zorya-classifier 0.2.1 → 0.2.3

package/docs/architecture.ru.md

@@ -0,0 +1,146 @@
+# Архитектура Zorya Classifier
+
+Описание фактической структуры репозитория на ветке рефакторинга. Краткий обзор жизненного цикла на английском: [architecture.md](architecture.md). Инварианты для участников разработки и агентов: [AGENTS.md](https://github.com/zoomplus/zorya-classifier/blob/main/AGENTS.md).
+
+## Назначение
+
+Zorya Classifier — MIT-библиотека для Node.js 22.12+. **Поддерживается** закрытая классификация текста и изображений: приложение передаёт явно настроенный `DecisionPort` или собирает адаптер самостоятельно. Библиотека не выбирает модель, провайдера или конечную точку API.
+
+**Реализованные пространственные API** (модель, провайдер и нативные ресурсы — на стороне вызывающего; ячейка сетки ≠ рамка целого объекта):
+
+- сеточный `locate`, режим «целый объект» (`whole-object`), `RefinementPort`;
+- `extract` с сегментатором на стороне вызывающего, проверка рамки и связанная композиция;
+- `ObjectProposalPort` и явные нативные фабрики сегментации;
+- селектор IMAGE-AS-TEXT (`experimental-text`) удалён из публичного runtime; запросы с ним дают `INVALID_INPUT`. Кодеки — только `benchmarks/experiments/`.
+
+Исследовательский код в `benchmarks/experiments/` и текстовые эксперименты без частей изображения **не входят** в дистрибутив npm. Отдельные скрипты в каталогах `benchmarks/v02/`, `benchmarks/v03/` и в корне `benchmarks/`: они используют вспомогательные модули из `experiments/`, но не сводятся к одной папке. Метрики в `docs/evidence/**` исторические; универсальное качество или «продвижение» стратегии из них не следует.
+
+## Публичная поверхность пакета
+
+Ровно **четыре** точки экспорта библиотеки в `package.json`: `.`, `./openrouter`, `./openai-compatible`, `./segmentation` (исходники: `index.ts`, `openrouter.ts`, `openai-compatible.ts`, `segmentation.ts` в `src/`). Исполняемый CLI (`zorya-classifier`, `cli.ts` → `dist/cli.js`, маршрутизация в `app/cli-route.ts`) — отдельная команда `bin`, **не** пятая точка входа библиотеки.
+
+## Слои и пути
+
+Правило зависимостей проверяет `npm run boundaries`: слои `entities` и `shared` не импортируют `infrastructure`; процессы не импортируют адаптеры напрямую — только контракты портов.
+
+| Слой             | Роль                                             | Примеры путей                                                                                                                                                   |
+| ---------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `app`            | Сборка классификатора, CLI, конфигурация         | `create-classifier.ts`, `classifier-contracts.ts`, `classifier-config.ts`, `classifier-runtime.ts`, `classifier-spatial.ts`, `cli-route.ts` в `src/app/`        |
+| `processes`      | Оркестрация операций                             | `classify.ts`, `locate.ts`, `extract.ts`, `extract-from-region.ts`, `whole-object.ts`, `proposal-location.ts`, `boundary-state.ts` в `src/processes/`           |
+| `features`       | Чистая логика: Choice, сетка, промпты, маски     | `choice.ts`, `uniform-grid.ts`, `choice-beam-layout.ts`, `prompts.ts`, `src/features/segmentation/*`, `src/features/proposals/*`                                |
+| `entities`       | Контракты, Zod, геометрия                        | `contracts.ts`, `classification.ts`, `decision.ts`, `geometry.ts`, `image.ts`, `localization.ts`, `validation.ts`, `segmentation-metadata.ts` в `src/entities/` |
+| `infrastructure` | Реализации портов: HTTP, растр, фоновые процессы | `decision-transport/*`, `vision-chat/*`, `openrouter.ts`, `raster.ts`, `segmentation/mobile-sam/*`, `segmentation/grabcut/*` в `src/infrastructure/`            |
+| `shared`         | Утилиты без слоя `infrastructure`                | `gate.ts`, `scope.ts`, `input-budget.ts`, `choice-mass.ts` в `src/shared/`                                                                                      |
+
+**Порт** — контракт (интерфейс и схемы), через который процесс вызывает внешнюю работу. **Кто владеет ресурсом:** вызывающее приложение **настраивает** `DecisionPort` (у порта **нет** контракта `dispose`); при завершении работы вызывающий вызывает `dispose()` классификатора и сам освобождает переданные `SegmentationPort` / `ObjectProposalPort`. Фабрика `createClassifier` владеет очередью операций и встроенным `RasterPort` на базе Sharp, переданным в процессы. Явно созданный нативный адаптер **владеет** своим дочерним процессом и закрывает его при `dispose` адаптера. Пакеты среды выполнения (ONNX и т. п.) и файлы моделей — **предварительные условия вызывающего**; библиотека их не скачивает и не освобождает автоматически.
+
+## Диаграмма зависимостей импортов
+
+Схема отражает **направление импортов**, а не порядок сетевых вызовов во время операции. Слой `app` собирает процессы и адаптеры; процессы опираются на нижние слои и контракты портов; слой `infrastructure` реализует порты и **не** импортируется из процессов. Во время выполнения работа идёт только через **внедрённые** экземпляры портов.
+
+```mermaid
+flowchart TB
+  subgraph app [app — композиция]
+    CC[create-classifier.ts]
+  end
+  subgraph processes [processes]
+    P[classify / locate / extract …]
+  end
+  subgraph features [features]
+    F[choice / grid / segmentation / proposals]
+  end
+  subgraph entities [entities + shared]
+    E[contracts / schemas / gate / scope]
+  end
+  subgraph infra [infrastructure]
+    I[decision-transport / vision-chat / raster / native segmentation]
+  end
+  Caller[Приложение] -->|порты и байты| CC
+  CC --> P
+  CC --> I
+  P --> F
+  P --> E
+  F --> E
+  I --> F
+  I --> E
+```
+
+Прямого ребра «processes → infrastructure» в коде нет.
+
+## Поток операции extract (`v0.2`)
+
+Сначала локатор области находит подсказку `seed` на полном ориентированном исходном изображении. Сегментатор вызывающего получает **полное** изображение и `seed`; границы, центр и вырез считаются **только** по действительным пикселям маски. Закрытая проверка рамки на полном исходнике возвращает `complete`, `needs-expansion` или `unknown`:
+
+- **`complete`** — можно сформировать результат (опциональный прозрачный вырез).
+- **`needs-expansion`** — не более **одного** расширения охватывающей маски и **одной** финальной проверки; если финальная проверка снова **`complete`**, результат допустим.
+- **`unknown`** — неразрешённая проверка, отсутствие поддержки расширения, нет действительной охватывающей маски или провал финальной проверки; **второго** расширения нет. Координаты от модели и «растянутая» рамка не используются.
+
+```mermaid
+flowchart LR
+  Q[Очередь и предельный срок] --> L[Локатор области: до 3 запросов]
+  L --> S[Сегментатор вызывающего: полный исходник + seed]
+  S --> M[Валидация маски, bounds из пикселей]
+  M --> B[Закрытая проверка рамки на полном исходнике]
+  B -->|complete| C[Результат / опциональный вырез]
+  B -->|needs-expansion| E[Не более одного расширения маски]
+  E -->|успех| P[Сохранение всех видимых пикселей маски]
+  E -->|нет expand / нет охватывающей маски| U[Явная неопределённость]
+  P --> B2[Финальная проверка]
+  B2 -->|complete| C
+  B2 -->|unknown / needs-expansion| U
+  B -->|unknown| U
+```
+
+## Ответственность по путям
+
+| Задача                                     | Путь                                                                                                      |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| Фабрика, очередь, освобождение (`dispose`) | `src/app/create-classifier.ts`, `classifier-runtime.ts`                                                   |
+| Пространственная сборка, проверка рамки    | `src/app/classifier-spatial.ts`                                                                           |
+| Классификация                              | `src/processes/classify.ts`                                                                               |
+| Трёхстадийный locate                       | `src/processes/locate.ts`                                                                                 |
+| Извлечение                                 | `src/processes/extract-from-region.ts`, `extract.ts`                                                      |
+| Валидация маски, правила проверки рамки    | `src/features/segmentation/validation.ts`, `source-mask.ts`, `region-result.ts`, `box-check.ts`           |
+| HTTP-транспорт решений                     | `src/infrastructure/decision-transport/*`, `vision-chat/*`                                                |
+| MobileSAM / GrabCut                        | `src/infrastructure/segmentation/mobile-sam/*`, `src/infrastructure/segmentation/grabcut/*`               |
+| Исследования (вне дистрибутива npm)        | `benchmarks/experiments/create-research-classifier.ts`, `text-representation.ts`, `boundary-view.ts`      |
+| Журналы / учётные данные                   | `benchmarks/runtime-source-files.ts`, `benchmarks/v03/integrity-receipts.ts`, `benchmarks/credentials.ts` |
+
+## SOLID без лишних сервисов
+
+Композиция отделена от оркестрации и от ввода-вывода: новый провайдер добавляется адаптером `DecisionPort`, геометрия и процессы не переписываются под каждый SDK. Процессы зависят от **малых** портов, а не от монолита. Отдельный сетевой микросервис классификации в репозитории не предусмотрен — изоляция модулей нужна для тестов, секретов и жизненного цикла.
+
+## Состояние, байты и завершение работы
+
+1. **Владение входом:** байты изображения и маски валидируются и фиксируются **до первого** `await`; последующая мутация буфера вызывающего не должна менять результат.
+2. **Один абсолютный предельный срок** на операцию, включая ожидание в очереди; `AbortSignal` проходит через все границы.
+3. **Ограниченная очередь:** при переполнении — `CAPACITY`.
+4. **Слоты:** после отмены или тайм-аута результат операции не принимается, но слот удерживается, пока не завершится физическая работа (Sharp, HTTP, дочерний процесс, созданный адаптером). Это не обещание мгновенного возврата по календарному времени.
+5. **`dispose()`** классификатора отменяет ожидающие и активные операции и дожидается завершения своих операций; общий `SegmentationPort` / `ObjectProposalPort` вызывающий освобождает сам.
+6. **Нативные адаптеры:** только явный вызов фабрики; закреплённые байты через один дескриптор; без автоматической загрузки весов.
+
+## Координаты исходника и маски
+
+Обрезка, масштабирование и вписывание с сохранением пропорций и полями должны применяться **согласованно**: чистый слой, наложение и вырез строятся в одной системе координат исходника; панель с полями нельзя отображать на исходнике как растянутый прямоугольник. Для проверки рамки сначала рендерится полный холст исходника, затем внедрённый `RasterPort.imageState` готовит вид для транспорта (стороны 280–1568, сохранение пропорций и исходных координат маски). Регрессии публичных адаптеров проверяют и малые, и большие входы; заглушка `DecisionPort` не заменяет проверку подготовки транспорта.
+
+## Пространственный контракт `v0.2`
+
+Основной `extract`: локатор → сегментатор на полном ориентированном исходнике → границы, центр и вырез только из действительных пикселей маски → закрытая проверка (`complete` / `needs-expansion` / `unknown`) с ветвлением выше. Нет координат от модели, поиска по охвату и «растянутой» рамки при неразрешённом исходе. Верная рамка не доказывает идеальную сегментацию по каждому пикселю.
+
+**Запросы порта решений:** внутри одного `extract` с `locate` — до 3 (locate) + 2 (проверки); отдельный сценарий «`classify` + `extract`» — до 6 запросов решений суммарно (см. [README.ru.md](README.ru.md)).
+
+## Ранги, оценки Native Choice, пространственный луч, Noul
+
+- Финальный выбор класса — **один** закрытый ID; лишние альтернативы для одной метки не требуются.
+- Пространственные стадии луча — **четыре** упорядоченных кандидата; один финальный ID **не** равен четырём кандидатам луча.
+- Обычный маршрут `vision-chat`: только ранг, без выдуманных `probabilities`; ранг **не** означает вероятность.
+- Native Choice (Decisions API): сохраняются **исходные** оценки провайдера; при равенстве — **исходный порядок** входных классов; **без** автоматической нормализации. Любая интервальная квантовка требует явной аннотации адаптера и соответствующего теста на массу, отличную от единицы.
+- **Noul** — **отдельное** двоичное решение о **наличии цели** (target-presence), не смешивается с выбором максимума по классам.
+- Оценка качества у `ObjectProposalPort` — **некалиброванная** диагностика, может быть вне [0, 1]; **не** вероятность, **не** основание для семантического выбора и **не** отправляется модели как доказательство качества.
+
+## Связанные документы
+
+- [Разработка](development.ru.md) — установка, тесты, секреты.
+- [v02-usage.md](v02-usage.md) — extract, CLI, сегментатор.
+- [Эталонные прогоны](benchmarks.md) — платные CLI каталога `benchmarks` (не офлайн-каталог `npm test`).
+- [План рефакторинга](refactoring-plan.ru.md) — измеренные контрольные точки платформ.

package/docs/benchmarks.md

@@ -1,5 +1,7 @@
 # Reproducible benchmarks
 
+Credential policy for paid runners: `OPENROUTER_API_KEY` from the process environment by default (`benchmarks/credentials.ts`). Among the changed paid CLIs, only `benchmarks/v02/run-region-seeded-dev.ts` and `benchmarks/v03/run-quality-pilot.ts` accept an explicit `--env-file`; other modified runners read the process environment. Missing or invalid explicit files do not fall back to other env sources or upstream project `.env` files. See [development.ru.md](development.ru.md).
+
 Current native Luna Decisions and ordinary vision comparisons are summarized in [tested models](vision-results.md). The fixed native-Jev runner below remains a historical/reproducibility tool, not the primary model configuration. New model-selection snapshots and budget continuations are retained separately; never label the Jev runner's output as evidence for Luna or another backend.
 
 The optional corpus contains 60 licensed Open Images photographs and 30 authored text fixtures. Photographs cover 25 requested classes with ten each of baseline, absent target, small target, edge truncation, occlusion and repeated instances.20 photos/10 texts are development data;40/20 are reserved evaluation data. Public heldout does not guarantee exclusion from provider training.
@@ -18,7 +20,7 @@ The [region-seeded runner](https://github.com/zoomplus/zorya-classifier/blob/mai
 
 The historical hash helper serializes JSON in insertion order; it does not sort every object's keys. Freeze the exact producer-shaped object for each variant, including its distinct prompt policy. Reordering a spread can change its digest even when the values look equivalent. Keep failed pre-dispatch drafts rather than changing the historical hash algorithm. The [all-attempt ledger](evidence/v02/region-seeded-dev-v3-control-r2/attempt-accounting.json) includes charges from the original unscored control as well as the valid pair.
 
-These research runners preserve host-specific historical default paths. In another checkout, pass explicit `--image-root`, `--photo-inputs`, `--ui-inputs`, `--map-inputs`, `--encoder` and `--decoder` paths; use `--env-file` for the explicitly authorized paid run. Keep the corresponding input SHA-256 flags and phase freeze consistent. Core library clients take explicit ports and do not read these benchmark configuration files.
+These research runners preserve host-specific historical default paths. In another checkout, pass explicit `--image-root`, `--photo-inputs`, `--ui-inputs`, `--map-inputs`, `--encoder` and `--decoder` paths; for paid dispatch set `OPENROUTER_API_KEY` in the process or pass `--env-file` on `benchmarks/v02/run-region-seeded-dev.ts` (and `benchmarks/v03/run-quality-pilot.ts` for the v03 pilot). Keep the corresponding input SHA-256 flags and phase freeze consistent. Core library clients take explicit ports and do not read these benchmark configuration files.
 
 Region-fragment hits, mask-derived box matches and exact-canvas mask IoU are different measurements. The image-free control has no segmenter and cannot produce an object mask. The current comparison uses all 40 cases per profile, including unknowns/errors, and reports native quality separately from semantic model decisions. Its 20 photos, ten controlled UI captures and ten controlled map captures do not establish broad game or UI coverage. The [conditional selection](evidence/v02/region-seeded-method-selection-20261021-v3.json) precedes any new blind pixels or truth; the [acceptance record](acceptance.md) determines current release eligibility.
 

package/docs/development.ru.md

@@ -0,0 +1,141 @@
+# Разработка Zorya Classifier
+
+Руководство для участников разработки и исполнителей Composer. Контракт: [AGENTS.md](https://github.com/zoomplus/zorya-classifier/blob/main/AGENTS.md). Слои и порты: [architecture.ru.md](architecture.ru.md). Порядок работы агентов: [agents.ru.md](agents.ru.md). **Измеренные контрольные точки** (Linux Node 22/24, Windows, интерпретатор Python) — в [плане рефакторинга](refactoring-plan.ru.md#платформы-и-ci).
+
+## Быстрый старт
+
+```sh
+npm ci --ignore-scripts
+npm run prepare    # по желанию: локальный Husky
+npm run check
+npm run pack:check
+npm run format:check
+```
+
+`npm test` по умолчанию — офлайн-каталог переносимых тестов (без живого провайдера). Импорт пакета не запускает фоновые процессы и не скачивает веса.
+
+## Порядок чтения
+
+1. [README.ru.md](README.ru.md) — возможности, примеры, статус без универсальных заявлений о качестве.
+2. [Контракт участников](https://github.com/zoomplus/zorya-classifier/blob/main/AGENTS.md) — предметная область, жизненный цикл, каталог `benchmarks`, секреты.
+3. [Архитектура](architecture.ru.md) — зависимости слоёв, пространственный поток `extract`.
+4. [api.md](api.md) — публичные типы и лимиты.
+5. [CONTRIBUTING.md](https://github.com/zoomplus/zorya-classifier/blob/main/CONTRIBUTING.md) — ожидания запроса на слияние.
+6. Пространственные сценарии v0.2: [v02-usage.md](v02-usage.md), [0.2.0-plan.md](0.2.0-plan.md).
+7. Итерация качества: [план 0.3.0](https://github.com/zoomplus/zorya-classifier/blob/main/docs/0.3.0-quality-plan.md).
+
+## Скрипты
+
+| Команда                                    | Назначение                                                                                                     |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `npm test`                                 | Переносимый каталог: `node --import tsx scripts/run-classified-tests.mjs portable`                             |
+| `npm run test:local-evidence`              | Три файла, **7** тестов воспроизведения с локальными/замороженными артефактами (нужны предварительные условия) |
+| `npm run test:python-native`               | Тесты с предварительными условиями Python и нативной среды                                                     |
+| `npm run check`                            | секреты, проверка типов, ESLint, границы слоёв, Knip, тесты, сборка                                            |
+| `npm run pack:check`                       | Установка архива пакета в изолированный проект-потребитель, проверка байтов и API                              |
+| `npm run secrets:check` / `secrets:staged` | Сканирование рабочего дерева и версий файлов, добавленных в индекс Git                                         |
+| `npm run boundaries`                       | Слои и циклы                                                                                                   |
+| `npm run dead-code:ci`                     | Knip (явные точки входа; исключение — необязательный `onnxruntime-node`)                                       |
+
+Единый раннер: `scripts/run-classified-tests.mjs` и Zod-каталог `scripts/test-catalog.ts` / `scripts/test-catalog.json`.
+
+## Три группы тестов
+
+| Группа               | Команда                       | Состав                                                                                                                                                                                                                                                                  |
+| -------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`portable`**       | `npm test`                    | Заглушки, фикстуры, границы слоёв, большинство `test/*.test.ts`, часть `benchmarks/v03/*.test.ts`; необязательные нативные и артефактные тесты **видны здесь** и могут **пропускаться** без предварительных условий (в том числе `H6`, `H8`)                            |
+| **`local-evidence`** | `npm run test:local-evidence` | Ровно **три файла**, **7** тестов: мок-воспроизведение H5 (`benchmarks/v03/h5-replay-local.test.ts`), мок-воспроизведение `grounded-mask` (`grounded-mask-replay-local.test.ts`), минимальный замороженный манифест H10 (`evaluate-h10-clipseg-local-evidence.test.ts`) |
+| **`python-native`**  | `npm run test:python-native`  | `h10-clipseg-runner.test.ts`, `h11-sa2va-runner.test.ts`                                                                                                                                                                                                                |
+
+`H6`/`H8` и другие необязательные нативные проверки **не** входят в группу `local-evidence`; они остаются в переносимом каталоге. Новый тест добавляют в `*.test.ts` и **ровно одну** группу каталога; `test/test-catalog.test.ts` проверяет классификацию.
+
+### Предварительные условия `local-evidence`
+
+Тесты воспроизведения ожидают **заранее подготовленное** дерево данных и журналы, а не только исходники репозитория:
+
+- Воспроизведение `grounded-mask` ищет **соседний** архив модели/данных и Python-журнал относительно **родителя** каталога, заданного корнем данных (переменная `ZORYA_V03_DATA_ROOT` и связанные пути в секции предварительных условий каталога). Нужна корректная структура архивного каталога и квитанции модели/окружения.
+- Указать `ZORYA_V03_DATA_ROOT` только на каталог с исходниками репозитория **не создаёт** эти артефакты автоматически.
+
+При **правильной** раскладке данных на Linux Node 22 зафиксирован успешный прогон **7/7** — журнал `final-local-evidence-node22-configured.log`. Ранний прогон с неверной конфигурацией — `final-local-evidence-node22.log` (три падения `grounded-mask`) — сохранён как исторический, его не скрывают.
+
+Не коммитьте пути к частным корпусам и абсолютные адреса конкретного хоста в документацию.
+
+## Добавить адаптер, операцию или тест
+
+1. **Контракт** — Zod и типы в `src/entities/*`; правила в `features` или оркестрация в `processes`; HTTP- и нативная реализация — в `infrastructure`, без импорта `infrastructure` из `entities`/`features`/`processes`.
+2. **Публичный адаптер** — транспорт в `infrastructure/decision-transport` + `vision-chat`; фасад в `src/openrouter.ts` / `openai-compatible.ts` (одна из четырёх точек входа библиотеки).
+3. **Тесты смысла:** отмена после постановки в очередь, поздний результат после отмены, `CAPACITY`, мутация входа после старта, ожидание завершения в `dispose`, реальные публичные адаптеры и лимиты подготовленного изображения 280–1568 (не только заглушка `DecisionPort`).
+4. После новых импортов — `npm run boundaries`; при смене состава `dist` и экспортов — `npm run pack:check`.
+5. Только исследования — под `benchmarks/experiments/`; не расширять npm `files` без отдельного продуктового решения.
+
+Не добавляйте сетевые микросервисы и абстракции «ради архитектуры».
+
+## Учётные данные каталога `benchmarks`
+
+`benchmarks/credentials.ts`: по умолчанию `process.env.OPENROUTER_API_KEY`. Явный **`--env-file`** поддерживают **только** `benchmarks/v02/run-region-seeded-dev.ts` и `benchmarks/v03/run-quality-pilot.ts` среди изменённых платных CLI каталога `benchmarks`; остальные читают переменные окружения процесса. `readOpenRouterKeyFromEnvFile(path)` при отсутствии или невалидности файла **не** откатывается к окружению процесса. Чужие `.env` других проектов не загружаются.
+
+Тесты группы `portable` и библиотека ключа в окружении не требуют.
+
+## Секреты, архив пакета, зависимости
+
+- **Husky:** сканирование **версий файлов, добавленных в индекс Git**, затем проверки и форматирование.
+- **`secrets:check`:** отслеживаемые и неигнорируемые неиндексированные файлы **рабочего дерева**.
+- **`pack:check`:** байты **установленного** архива, компиляция потребителя; пути исследований отклоняются.
+- Единственный шаблон переменных окружения — **пустой** `.env.example` (тоже проверяется на содержимое).
+- Зависимости среды выполнения (Zod, Sharp и др.) в этой волне рефакторинга **не менялись**; необязательный ONNX — только явный путь фонового процесса.
+
+Платные CLI каталога `benchmarks` не заменяют `npm test` / `npm run check`.
+
+## Python, Windows и нативные предварительные условия
+
+### `python-native` (вызывающий, изолированный офлайн Python)
+
+Набор `npm run test:python-native` требует задать обе переменные окружения: `H10_PYTHON_EXECUTABLE` и `H11_PYTHON_EXECUTABLE`. Библиотека не устанавливает Python и не скачивает веса.
+
+Проверенный прогон 44/44, 0 пропусков на ревизии `4877d05` использовал один изолированный интерпретатор CPU (без CUDA) для обеих переменных и следующий замороженный стек:
+
+| Компонент    | Версия         |
+| ------------ | -------------- |
+| Python       | **3.12.3**     |
+| NumPy        | **2.5.2**      |
+| PyTorch      | **2.6.0+cpu**  |
+| torchvision  | **0.21.0+cpu** |
+| transformers | **4.57.3**     |
+| Pillow       | **12.3.0**     |
+
+Перед прогоном задайте `HF_HUB_OFFLINE=1` и `TRANSFORMERS_OFFLINE=1`. H10 CLIPSeg использует уже существующие закреплённые локальные файлы модели на стороне вызывающего и корень каталога по предварительным условиям тестов (не создаются репозиторием). В двух тестах H11 на CPU создаются фикстуры FakeTensor только с метаданными (в том числе синтетические метаданные CUDA-устройства для отдельных случаев валидации и загрузчика); проверяется логика валидации и загрузчика рабочего кода и негативные случаи. Такой офлайн-прогон не проверяет реальный CUDA, GPU, выделение физической видеопамяти или живой инференс модели H11.
+
+Воспроизводимый рецепт для Linux, проверенный на этой платформе. В наборе `python-native` есть проверка завершения дочернего процесса при завершении родительского процесса на Linux; этот набор на Windows не проверялся. Без привязки к частному хосту: создать venv на Python 3.12.3, установить пакеты из таблицы с CPU-колёсами PyTorch/torchvision, задать корень локальных файлов модели H10 по каталогу тестов (например `H10_CLIPSEG_ASSETS`, если файлы не берутся из закреплённого контракта в репозитории), затем явно задать обе переменные и офлайн-флаги:
+
+```bash
+export H10_PYTHON_EXECUTABLE=/path/to/venv/bin/python
+export H11_PYTHON_EXECUTABLE=/path/to/venv/bin/python
+export HF_HUB_OFFLINE=1
+export TRANSFORMERS_OFFLINE=1
+npm run test:python-native
+```
+
+Первый сбой офлайн-настройки сохранён как `python-native.log`; принятый прогон — `python-native-rerun.log` (каталог артефактов `zorya-classifier-completion-20261023`).
+
+Контрольные тесты геометрии на Python (**6/6**, `controlled-oracles-current.log`) — **отдельно** от `python-native`.
+
+### Windows (разработка и локальная матрица)
+
+На свежей Windows Server 2025 для полного `npm run check` (этап Knip / native binding oxc-resolver 11.24.2) может понадобиться установленный на машине разработчика [Microsoft Visual C++ Redistributable для x64](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist/) — см. официальное руководство Microsoft. Репозиторий не ставит runtime автоматически и не менял зависимости; проверки установленного архива (`pack:check`) проходили и без этой установки. В одноразовой оценочной VM runtime ставился вручную с дистрибутива Microsoft (Authenticode OK); первая проба загрузки через Node `-e` с пустым stdout не принята, принята отдельная проверка загрузки модуля через CJS-файл с точным маркером stdout и exit 0 (`windows/vc-runtime-verified-smoke.json`).
+
+Принятая локальная матрица (ревизия `4877d05`): Windows Server 2025 build 26100, Node 22.23.4 и 24.22.1 — все проверки с exit 0, 765/772 с 7 заранее существовавшими пропусками (POSIX FIFO, симлинк без привилегий, две маски H3b/H4e, два H6, один H8); байты архива совпадают с Linux. Удалённый GitHub Actions CI не запускался.
+
+В WSL перед проверками проверьте `process.platform` и явные пути к `node`/`npm` ([контракт участников](https://github.com/zoomplus/zorya-classifier/blob/main/AGENTS.md)).
+
+**Финальная верификация (волна 9):** полная матрица Linux + Windows + `python-native` на **`4877d05`** — [план рефакторинга](refactoring-plan.ru.md#волна-9--финальная-верификация-завершено). Исторический снимок только Linux на **`7a74226`** там же сохранён отдельно.
+
+## Перед запросом на слияние
+
+```sh
+npm ci --ignore-scripts
+npm run check
+npm run pack:check
+npm run format:check
+```
+
+Платные прогоны каталога `benchmarks` в CI для запроса на слияние не обязательны.

package/docs/migrations/experimental-text-image-removal.ru.md

@@ -0,0 +1,9 @@
+# Удаление публичного селектора IMAGE-AS-TEXT
+
+Публичный runtime больше не принимает `representation: { type: 'experimental-text', profile: 'text-image-v1' }`. Любая попытка передать этот селектор (или неизвестные ключи в `representation`) завершается `ClassifierError` с кодом `INVALID_INPUT` **до** вызова `DecisionPort` или сетевого fetch.
+
+Обычная **текстовая** классификация (`classify` со строкой или `{ text }`) и **vision**-адаптеры/запросы без экспериментального селектора не изменились.
+
+Исследовательские text-image кодеки остаются только в `benchmarks/experiments/` и не входят в npm `dist`. Они не ожидают публичной квалификации; исторические замеры v0.2/v0.3 и отчёты сохранены без переклассификации.
+
+Для офлайн-бенчмарков используйте `createResearchClassifier` с явным research-портом и benchmark-only схемами (`researchRepresentationSchema`).