zorya-classifier 0.2.0 → 0.2.2

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 помечены `@experimental`):
+
+- сеточный `locate`, режим «целый объект» (`whole-object`), `RefinementPort`;
+- `extract` с сегментатором на стороне вызывающего, проверка рамки и связанная композиция;
+- `ObjectProposalPort` и явные нативные фабрики сегментации;
+- профиль `representation: { type: 'experimental-text', … }` — отклонён (`UNSUPPORTED`), пока профиль не пройдёт независимый отбор.
+
+Исследовательский код в `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`, `classifier-representation.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.
@@ -14,11 +16,11 @@ Offline fixture tests validate mechanics only. Actual provider outcomes are reco
 
 ## 0.2 checked region and segmentation recipe
 
-The [region-seeded runner](../benchmarks/v02/region-seeded-runner.md) records the original region search separately from full-source segmentation and up to two closed visible-box checks. The caller configures the model, native adapter and presence guard explicitly. Its [v3 development freeze](evidence/v02/region-seeded-development-freeze-20261021-v3.json), [prospective control-R2 correction](evidence/v02/region-seeded-development-control-r2-freeze-20261021.json) and [independent results](evidence/v02/region-seeded-dev-v3-control-r2/README.md) retain the original identity-authoring failure. A separate offline verifier rejects reuse of candidate prompt policies in the control identity before dispatch.
+The [region-seeded runner](https://github.com/zoomplus/zorya-classifier/blob/main/benchmarks/v02/region-seeded-runner.md) records the original region search separately from full-source segmentation and up to two closed visible-box checks. The caller configures the model, native adapter and presence guard explicitly. Its [v3 development freeze](evidence/v02/region-seeded-development-freeze-20261021-v3.json), [prospective control-R2 correction](evidence/v02/region-seeded-development-control-r2-freeze-20261021.json) and [independent results](evidence/v02/region-seeded-dev-v3-control-r2/README.md) retain the original identity-authoring failure. A separate offline verifier rejects reuse of candidate prompt policies in the control identity before dispatch.
 
 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/operations.md

@@ -2,7 +2,7 @@
 
 Configure a trusted model endpoint or the optional OpenRouter route. SDK factories receive endpoint/model/key explicitly; the core knows only DecisionPort. Keep server-specific credentials separate from OpenRouter credentials. Store keys in ignored local files or a secret manager. No startup request is made.
 
-CLI requires `ZORYA_MODEL` and defaults to `ZORYA_MODE=decisions`. For ordinary vision models/custom chat servers choose `ZORYA_MODE=chat`. OpenRouter mode requires `OPENROUTER_API_KEY` and `ZORYA_PROVIDER`; direct mode uses a full `ZORYA_ENDPOINT` with optional separate `ZORYA_API_KEY`, and never forwards the OpenRouter key. In chat mode, optional `ZORYA_REASONING_EFFORT` and `ZORYA_RESPONSE_FORMAT` must be supported by the chosen endpoint. Use `zorya-classifier --help`. Commands: classify-text text classes.json; classify-image image classes.json; locate image target. CLI calls real paid models. Native images are decoded locally through Sharp; external requests send prepared text/images to the configured route. The library neither writes nor logs media by default.
+CLI requires `ZORYA_MODEL` and defaults to `ZORYA_MODE=decisions`. For ordinary vision models/custom chat servers choose `ZORYA_MODE=chat`. OpenRouter mode requires `OPENROUTER_API_KEY` and `ZORYA_PROVIDER`; direct mode uses a full `ZORYA_ENDPOINT` with optional separate `ZORYA_API_KEY`, and never forwards the OpenRouter key. In chat mode, optional `ZORYA_REASONING_EFFORT` and `ZORYA_RESPONSE_FORMAT` must be supported by the chosen endpoint. Use `zorya-classifier --help`. Commands: classify-text and classify-image are supported; locate and extract are experimental and unqualified (see README capability table). CLI calls real paid models. Native images are decoded locally through Sharp; external requests send prepared text/images to the configured route. The library neither writes nor logs media by default.
 
 Choose a finite timeout based on your UI needs. Default 45s includes queue time; no latency SLA is asserted. Handle CAPACITY by applying upstream backpressure rather than creating more clients. Explicitly cancel superseded application requests and call dispose on shutdown. A cancelled native job may finish before its slot is released; this prevents unbounded physical concurrency.
 
@@ -10,12 +10,12 @@ Unknown cost remains unknown. Budget your own calls or use the benchmark's conse
 
 Build release locally with npm run check and npm run pack:check. Produce npm pack only after those gates. Review LICENSE/NOTICE/acceptance and archive contents before publishing. Publication destinations are GitHub `zoomplus/zorya-classifier` and npm `zorya-classifier` under owner `zoomplus`. Authentication stays outside the repository. Check the remote release/registry and external receipt for actual publication state.
 
-Owner handoff and authentication steps are in [publishing](publishing.md). Secret scanning commands and their limits are in [SECURITY](../SECURITY.md); they run in Husky, source checks and the archive check. Release manifests live next to the prepared archives, outside Git/npm contents.
+Owner handoff and authentication steps are in [publishing](publishing.md). Secret scanning commands and their limits are in [SECURITY](https://github.com/zoomplus/zorya-classifier/blob/main/SECURITY.md); they run in Husky, source checks and the archive check. Release manifests live next to the prepared archives, outside Git/npm contents.
 
 Compatibility with another image-capable model does not imply tested accuracy or support for all structured-output parameters. Choose prompt/JSON-object/JSON-schema mode according to server capabilities, inspect explicit failures and consult docs/vision-results.md. Never label generated ranks as calibrated probabilities.
 
 # 0.2 additions
 
-Whole-object location, explicit extraction backends, CLI artifacts and ownership are described in [the 0.2 guide](v02-usage.md). The core input reservation is bounded across active and queued work; native admission rejects before expensive snapshots/base64. Keep a shared segmenter or object-proposal adapter alive until all owning clients have disposed. The optional CPU proposal adapter rejects sources above 2,097,152 pixels and packs at most 36 masks into a 10 MiB batch; it does not silently resize. Proposal selection is currently an API composition; the CLI retains the explicit interval/segmenter path. Raw native scores are uncalibrated diagnostics, never probability thresholds. Native calls currently start a fresh owned child each time; session reuse is not implemented. Do not extrapolate cold synthetic smoke timings into production latency or photo quality.
+Whole-object location, explicit extraction backends, CLI artifacts and ownership are experimental and described in [the 0.2 guide](v02-usage.md). The core input reservation is bounded across active and queued work; native admission rejects before expensive snapshots/base64. Keep a shared segmenter or object-proposal adapter alive until all owning clients have disposed. The optional CPU proposal adapter rejects sources above 2,097,152 pixels and packs at most 36 masks into a 10 MiB batch; it does not silently resize. Proposal selection is currently an API composition; the CLI retains the explicit interval/segmenter path. Raw native scores are uncalibrated diagnostics, never probability thresholds. Native calls currently start a fresh owned child each time; session reuse is not implemented. Do not extrapolate cold synthetic smoke timings into production latency or photo quality.
 
-The [native resource harness](../benchmarks/v02/NATIVE-SMOKE.md) records independent parent samples, short-child memory, idle/busy phases, cancellation and child ownership without forcing garbage collection. A short harness verification is separate from the required two-hour resource run. Use an explicit corpus/asset manifest and preserve unsuccessful results.
+The [native resource harness](https://github.com/zoomplus/zorya-classifier/blob/main/benchmarks/v02/NATIVE-SMOKE.md) records independent parent samples, short-child memory, idle/busy phases, cancellation and child ownership without forcing garbage collection. A short harness verification is separate from the required two-hour resource run. Use an explicit corpus/asset manifest and preserve unsuccessful results.

package/docs/provenance.json

@@ -26,7 +26,11 @@
     "45-second default for standalone operations; original gaming deadline unchanged",
     "Provider-independent ordinary vision chat protocol with closed ranks and separate presence; no invented probabilities",
     "Direct OpenAI-compatible endpoint and optional OpenRouter wrapper; native Jev retained as optional historical integration",
-    "One winner for single-label/final selection; four ranks only for coarse/fine beam stages"
+    "One winner for single-label/final selection; four ranks only for coarse/fine beam stages",
+    "Refactor wave 8 (completed, branch work/classifier-refactor-20261023, commit 7a74226): Russian guides architecture.ru.md, development.ru.md, agents.ru.md, refactoring-plan.ru.md; English README/CONTRIBUTING/architecture navigation aligned to measured waves; documented app→processes/features/entities/infrastructure import direction, four package exports plus separate CLI bin, v0.2 extract branch complete→result/cutout and needs-expansion→single enclosing correction plus final check; benchmarks/credentials.ts env and limited --env-file; benchmarks/v03/integrity-receipts.ts path identity; benchmarks/experiments research tree with runtime-source-files.ts recording source dependencies and build/pack:check enforcing npm dist boundaries; agent roles and composer-2.5-fast dispatch rules in agents.ru.md; copied-file SHA-256 entries above unchanged",
+    "Refactor waves 1-8 (measured, Linux Node 22/24 at 7a74226): waves 1-7C as below plus wave 8 documentation and provenance closure; wave 9 verification on Linux Node 22.23.2 and bundled Node 24.22.1 — npm run check 772/772, pack:check 447/188/212, zero provider HTTP; public API four entries and 67 exported types (final-public-api.log); 407 protected baseline files unchanged plus package-lock.json, .env.example, src/index.ts (final-protected-evidence.json, code checkpoint 76d7ac6); local-evidence 7/7 configured (final-local-evidence-node22-configured.log); Python geometry oracles 6/6 (root-controlled-oracles.log); Windows checks not run on measured host; python-native suite not run; no publication or paid provider runs",
+    "Refactor waves 1-7C (measured): src/app classifier module split; processes/features/segmentation and proposals; infrastructure decision-transport, vision-chat, mobile-sam/grabcut facades; runtime-source-files.ts records benchmark source dependencies; npm dist isolation enforced by build and pack:check; benchmarks/credentials.ts explicit env and limited --env-file; benchmarks/v03/integrity-receipts.ts H5/H6 path identity; unified scripts/run-classified-tests.mjs and Zod test catalog; Wave 7C removed four unused functions and one unused type and privatized unused exports without algorithm changes; portable 772/772 Linux Node 22 at 76d7ac6; 407 protected baseline files byte-identical (wave7-final-protected-evidence.json); package-lock unchanged; Knip explicit entries with onnxruntime-node sole optional dependency exception",
+    "Refactor wave 9 completion (accepted, branch work/classifier-refactor-20261023, commit 4877d05): four-pair matrix Linux Node 22.23.2 and 24.22.1 plus Windows Server 2025 build 26100 Node 22.23.4 and 24.22.1 on local evaluation VM (remote GitHub Actions CI not run); npm run check portable 772 per run with Linux 772/772 zero skip and Windows 765 pass zero fail seven pre-existing optional/platform skips; pack:check 447/188/212 archive sha256 cb3e980854bb625380b594f5ac3f05d657bbeda4b42880bf8f57fe307645aa20 and runtime dist sha256 111c744ad406ff4645e2ff0f471610376a648aa81771eacf0a94bb61ea8d1131 identical across pairs zero provider HTTP requests/calls (not zero network traffic); public API four entries 67 types bidirectional value compatibility (public-api.log); 407 protected files unchanged plus package-lock.json .env.example src/index.ts (protected-evidence.json); isolated offline CPU Python 3.12.3 python-native 44/44 zero skip with H10 caller-owned pinned local model files HF_HUB_OFFLINE TRANSFORMERS_OFFLINE both H10_PYTHON_EXECUTABLE and H11_PYTHON_EXECUTABLE required verified run used one interpreter two H11 tests CPU FakeTensor metadata-only fixtures exercise loader/validation not GPU or live H11 inference; local-evidence 7/7 zero fail skip (local-evidence-current.log); Python geometry oracles 6/6 (controlled-oracles-current.log); native request-source bounds dedupe 420 equivalent inputs identical ordered Zod errors (native-protocol-equivalence.json); preserved failed receipts python-native.log initial offline setup failure wave7-root-local-evidence-baseline.log final-local-evidence-node22.log Windows win-4877d0535a04-node22 setup failure win-4877d0535a04-node22-r2 Knip VCRUNTIME before portable tests vc-runtime Node -e empty stdout probe not accepted accepted separate CJS module-load check exact stdout marker exit 0; Windows jobs win-4877d0535a04-node22-r3 and win-4877d0535a04-node24 accepted completion-code-verification.json local-verification.json; historical wave 9 Linux-only snapshot at 7a74226 retained in docs; no publication or paid provider runs; copied-file SHA-256 entries above unchanged"
   ],
   "originalRepositoryModified": false
 }

package/docs/publishing.md

@@ -28,3 +28,11 @@ Use the original-region/full-source-segmentation workflow in the current usage g
 Before release, match every runtime file in the final archive to the bytes covered by native/resource acceptance, and require green Windows/Linux × Node 22/24 CI for the release source. A later documentation-only archive can have a different package SHA while retaining the tested runtime; record both complete archive hashes and the explicit runtime-file parity proof. Keep a final independently installed consumer check for the actual release archive.
 
 Keep the final release manifest outside its own archives to avoid self-reference. It records the clean source commit, archive hashes/integrities, model recipe and corpus seals, preserved failures, native/resource receipts, CI run and redacted secret scan. Publish those exact archive bytes, verify the registry response and dist-tag, then attach the matching source and npm artifact to the GitHub release. Do not replace failed accuracy or resource gates with an offline test count.
+
+## Research and consumer archive
+
+The v0.3 research plans and evidence stay in Git history under `docs/research/v03-*` and `docs/evidence/v03/`. They can contain local artifact references needed for reproducibility and are excluded from the npm consumer archive through `docs/.npmignore`, together with the unfinished v0.3 quality plan. Preserve their original evidence bytes; do not rewrite historical receipts to make packaging pass. Public API and usage documentation remains packaged. `pack:check` rejects accidental inclusion of these internal paths and still scans the actual installed archive for credentials and private paths. Before a release, ensure every packaged documentation link has a packaged or public GitHub destination.
+
+## 0.2.2 merge release scope
+
+Version **0.2.2** integrates the refactor worktree with **0.2.1** documentation and packaging safeguards from `main`: experimental status/JSDoc, archive documentation links, `docs/.npmignore` sensitive-evidence exclusions, and isolated Git fixture handling in `test/secrets.test.ts`. Runtime defaults and the primary 0.2 extraction contract are unchanged relative to the published **0.2.0** baseline. This note does not assert npm/GitHub publication, CI completion, or release artifacts; check the registry, repository releases, and external release receipt for current state.