docs(architecture): согласовано владение выполнением транскрипции

docs/specs/2026-09-21-transcription-execution.md

@@ -0,0 +1,162 @@
+# Владение выполнением транскрипции
+
+**Статус:** согласовано для постановки задач. Реализация не начата.
+
+## Зачем
+
+Основное направление развития — поддерживаемые модели и движки распознавания,
+прежде всего ONNX. В перспективе нужны аппаратные варианты исполнения на Mac
+и через Windows ML, но их внедрение не входит в этот рефакторинг.
+
+Сейчас CLI хранит модель, backend, путь к модели и фактическое устройство,
+передаёт их в `_transcribe_file` и обновляет после fallback. Для ONNX часть
+согласованного состояния находится в adapter, а загруженная модель передаётся
+отдельно. Это увеличивает interface: caller должен знать порядок вызовов
+и поддерживать согласованность значений.
+
+`device` одновременно обозначает движок и аппаратное исполнение. Значение
+`onnx` выбирает adapter, но не закрепляет CPU: установленный `onnx-asr 0.12.0`
+по умолчанию использует доступные execution providers. При этом CLI безусловно
+пишет `ONNX (CPU)`. Параметр `cpu_threads` принимается ONNX adapter, но не
+используется при загрузке ASR и VAD.
+
+## Согласованные ограничения
+
+- Сохраняются ONNX-ASR, OpenVINO и FasterWhisper. Удаление CUDA-библиотек из
+  обязательной установки не означает удаление FasterWhisper или его CPU-пути.
+- Приоритет — подключение моделей и вариантов исполнения. Промежуточное
+  сохранение и возобновление обработки совещаний не нужны для этой работы.
+- Автоматически выбираются только проверенные сочетания модели и исполнения.
+  Новое аппаратное исполнение сначала подключается явно и проверяется отдельно.
+- CUDA-зависимости устанавливаются по желанию пользователя. Способ установки
+  и включения должен быть описан в документации.
+- Наличие драйвера NVIDIA не доказывает совместимость железа с runtime.
+  Ноутбук владельца с установленным драйвером и несовместимым старым GPU —
+  обязательный сценарий для проверки нового поведения.
+- Диаризация остаётся необязательным последующим проходом. Сбой «два
+  собеседника на чёткой записи, найден один говорящий» требует отдельного
+  исследования качества; этот рефакторинг его не исправляет.
+
+## Форма module
+
+External seam проходит между caller и выполнением распознавания. Caller
+создаёт один module для согласованных настроек запуска и последовательно
+передаёт ему файлы. Module владеет загруженной моделью, связанным adapter,
+фактическими настройками и допустимыми переходами исполнения. Caller получает
+результат распознавания и сведения о выполнении, а не внутреннее состояние,
+которое нужно передать обратно при следующем файле.
+
+Module создаётся после prescan, когда есть работа. Загрузка и проверка
+возможностей завершаются до распознавания первого файла: это сохраняет
+проверку пословного контракта перед включённой диаризацией. Один и тот же
+interface используется для одного файла и для батча. События прогресса остаются
+доступны CLI. Публичная функция `transcribe` сохраняется как путь одного файла
+через тот же module; конкретные имена новых типов здесь не закрепляются.
+
+Внутри различаются поддерживаемая модель, движок распознавания и способ
+исполнения. Существующие значения CLI и TOML преобразуются в этот выбор при
+подготовке запуска. Backend остаётся internal seam с реальными adapters;
+каталог ONNX, VAD, квантизация и перевод результата библиотеки в сегменты
+распознавания и слова с временной привязкой остаются в ONNX adapter.
+Отдельная иерархия adapters для каждого execution provider пока не нужна.
+
+CLI сохраняет выбор файлов, prescan, пользовательский вывод и итоговый статус.
+Форматирование, запись Markdown и правила диаризации не поглощаются новым
+module. Это ограничивает первый шаг владением ASR и его настройками.
+
+Depth оценивается по обязанностям caller: ему больше не нужно согласовывать
+model/backend/path/device. Locality — изменения загрузки и исполнения
+сосредоточены в module и соответствующем adapter. Leverage — один interface
+покрывает одиночный запуск, батч и их тесты.
+
+## Выбор исполнения и ошибки
+
+Ручное включение CUDA состоит из двух явных действий: установки зависимостей
+и выбора CUDA через CLI либо TOML. CUDA не участвует
+в `auto`, даже если найден `nvidia-smi` или установлены её библиотеки.
+Так установка драйвера не меняет движок и модель по умолчанию.
+
+Начальный автоматический путь — ONNX с CPU и существующей моделью по умолчанию.
+Для ONNX список providers задаётся явно; наличие CoreML в macOS wheel не
+включает его автоматически. Это делает политику проекта определённой, но
+не заменяет проверку работы на настоящем Mac.
+
+Явный аппаратный выбор не подменяется молча другим исполнением. При отсутствии
+CUDA-библиотек выводится инструкция подключения; при несовместимости железа
+объясняется отказ выбранного пути. Установка библиотек не предлагается как
+универсальное исправление аппаратной несовместимости. Остальные существующие
+правила ошибок и разрешённых fallback сохраняются внутри module; состояние
+после перехода остаётся согласованным для следующего файла.
+
+Сведения о выполнении различают запрошенное и выбранное исполнение, модель,
+квантизацию и настройки потоков. Они не раскрывают model handle. Для ONNX
+наличие или регистрация provider не выдаётся за доказательство выполнения
+всего графа на GPU/NPU. Отладочный вывод должен помогать выяснить конфигурацию
+на чужой машине, включая версии runtime и providers, без доступа к записи.
+
+## Проверка результата
+
+Основные сценарии проверяются через external interface с подменой внешних
+движков, при работающей оркестрации проекта:
+
+- Пустой prescan не загружает модели; два файла переиспользуют одну модель.
+- Добавление каталожной ONNX-модели не требует изменений в CLI.
+- Выбранная квантизация и бюджет потоков действительно передаются ASR и VAD;
+  нулевой бюджет сохраняет настройки потоков библиотек.
+- Наличие `nvidia-smi` при обычной установке не запускает CUDA и не ведёт
+  через ошибку GPU к FasterWhisper CPU.
+- Явная CUDA с отсутствующими библиотеками и с несовместимым GPU даёт разные
+  содержательные ошибки. Автоматическая смена модели не маскирует отказ.
+- Случайно доступный непроверенный ONNX provider не меняет автоматический путь.
+- Разрешённый fallback не требует переноса состояния в CLI; обычная ошибка
+  файла не повреждает состояние для последующих файлов батча.
+- Сохраняются явные CPU/OpenVINO-пути, порядок слов, пословный контракт,
+  прогресс, прерывание и существующее поведение необязательной диаризации.
+
+Тесты ручного переноса внутренних полей заменяются проверками этих сценариев.
+Тесты преобразования результатов adapters сохраняются на их internal seams.
+Mock-тесты не подтверждают ускорение или совместимость на Mac/Windows ML;
+для признания сочетания проверенным нужен реальный прогон с оценкой результата.
+
+## Документация и прежние решения
+
+README должен различать обычную установку и подключение CUDA: дополнительные
+зависимости Linux/WSL, требования Windows, явный запуск, настройку TOML
+и диагностику отсутствующих библиотек или несовместимого железа. Команды
+установки из клона и через `uv tool` проверяются при реализации. CUDA extra
+оформляется отдельным изменением, чтобы поставку можно было проверить
+независимо от рефакторинга выполнения.
+
+При реализации нужно отразить пересмотр прежних решений:
+
+- [ADR-001](../adr/001-cuda-bootstrap.md): обязательная cuBLAS ради готовности
+  CUDA сразу после установки сменяется подключением по желанию пользователя.
+- [ADR-002](../adr/002-batch-and-config.md): состояние модели больше не
+  возвращается caller для переноса между файлами. Prescan-first сохраняется.
+- [ADR-003](../adr/003-pluggable-backends.md): движок и аппаратное исполнение
+  различаются внутри module; device больше не считается полным описанием
+  исполнения. Сохраняются adapters, ленивые imports и единый владелец загрузки.
+- [ADR-006](../adr/006-onnx-asr-backend.md): автоматический выбор CUDA по
+  `nvidia-smi` заменяется явным включением; модель ONNX по умолчанию сохраняется.
+- [ADR-007](../adr/007-word-level-speaker-diarization.md): правила пословного
+  результата и диаризации этим решением не пересматриваются.
+
+Основания для будущих аппаратных вариантов уже собраны в
+[исследовании runtime](../research/2026-08-12-onnx-runtime-openvino-lifecycle.md).
+Актуальные описания механизмов: [CoreML EP](https://onnxruntime.ai/docs/execution-providers/CoreML-ExecutionProvider.html)
+и [Windows ML](https://learn.microsoft.com/en-us/windows/ai/new-windows-ml/overview).
+Их наличие не является подтверждением выбранных моделей на этих платформах.
+
+## Объём задач
+
+Для основного рефакторинга достаточно одной задачи с несколькими коммитами:
+владение моделью, перевод callers, настройки ONNX и проверка поведения входят
+в один принимаемый результат. Отдельных задач на каждый файл или коммит нет.
+
+Существующая [задача #2](https://git.dementev.space/ddmitry/local-transcriber/issues/2)
+получает принятое решение об optional CUDA вместо дальнейшего исследования:
+зависимости, ручное включение, автоматический ONNX CPU, диагностика CUDA
+и документация. Она выполняется первой и даёт основному рефакторингу
+определённые правила выбора. Фиксация CPU providers ASR/VAD относится к #2;
+бюджет потоков, владение состоянием и общая диагностика исполнения — к основной
+задаче. Работа над CoreML, Windows ML и качеством диаризации сюда не входит.