# ADR-002: Batch mode и config

**Статус**: Принято
**Дата**: 2026-03-18
**Обновлено**: 2026-09-21 — решения 2 и 4 пересмотрены (см. пометки)

## Контекст

После завершения MVP (шаги 1–7) пользователям не хватает:
- Обработки нескольких файлов за один вызов (batch mode)
- Конфигурационного файла для хранения дефолтов (модель, язык, устройство)

## Решения

### 1. Prescan-first: валидация до загрузки модели

Модель загружается **только если есть файлы для обработки**. Перед загрузкой модели выполняется полный prescan: валидация всех файлов и проверка существующих транскриптов.

**Почему**: загрузка модели (large-v3) занимает ~10 секунд и ~3 GB RAM/VRAM. Повторный запуск по уже обработанным файлам должен быть дешёвым no-op.

### 2. Состояние модели между файлами

**Пересмотрено 2026-09-21.** Исходное решение: `_transcribe_file()` возвращал
`TranscribeFileResult` с обновлёнными `model`, `backend`, `model_path`
и `actual_device`, а CLI переносил их в следующий файл после mid-stream
fallback. Это делало caller владельцем согласованности четырёх полей.

Теперь состояние не покидает module выполнения: `Transcriber` создаётся один
раз на запуск после prescan, загружает модель при первом файле и сам держит
загруженную модель, adapter и фактическое исполнение. Fallback меняет
состояние внутри module, и следующий файл батча идёт уже по нему. Caller
получает `TranscribeResult` и `ExecutionInfo` (запрошенное и выбранное
исполнение, движок, модель, квантизация, потоки, версии runtime).

**Альтернатива**: mutable-контейнер с моделью, передаваемый по ссылке, —
отклонена тогда же; owner-объект решает ту же задачу явно и тестируется
через свой interface.

### 3. Конфиг: CWD → глобальный, без мержа

Порядок поиска:
1. `.transcriber.toml` в текущей директории (проектный конфиг)
2. `~/.config/transcriber/config.toml` (глобальный конфиг)

Первый найденный побеждает, мержа между файлами нет.

**Почему**: CWD-конфиг удобен для per-project дефолтов (`language = "ru"` для русскоязычного проекта), глобальный — для машинных дефолтов (`device = "cpu"` на ноутбуке без GPU). Мерж усложняет предсказуемость.

**Приоритет значений**: CLI > конфиг > хардкод.

### 4. Публичный `transcribe()` — путь одного файла

**Пересмотрено 2026-09-21.** Внутренние helpers `load_model()`
и `_transcribe_file()` удалены. `transcribe()` сохранён и стал обёрткой над
тем же `Transcriber`: `model_name` и `compute_type` без значения берут
умолчания выбранного исполнения, `device="auto"` означает ONNX CPU, как в CLI.

## Последствия

- Обратная совместимость CLI: `transcribe file.mp4` работает как раньше
- Batch mode: модель загружается один раз для всех файлов; CLI не переносит
  состояние между файлами
- Fallback из CLI недостижим: явный device — strict, `auto` — ONNX CPU без
  переходов. Механизм сохранён для `transcribe(..., strict_device=False)`
- `--force` флаг для перезаписи существующих транскриптов в батч-режиме