zorya-classifier 0.2.1 → 0.2.2

package/docs/agents.ru.md

@@ -0,0 +1,95 @@
+# Правила для агентов (Zorya Classifier)
+
+Независимая MIT-библиотека. Технический контракт на английском: [AGENTS.md](https://github.com/zoomplus/zorya-classifier/blob/main/AGENTS.md). Архитектура и разработка: [архитектура](architecture.ru.md), [разработка](development.ru.md). Статус волн: [план рефакторинга](refactoring-plan.ru.md).
+
+## Глобальные правила владельца
+
+Cursor **не** подгружает автоматически файлы из `/root/.cursor/rules/`. **Главный оркестратор** и **каждый** порождённый подагент Codex должны прочитать оба канонических файла:
+
+| Файл                                                                            | Назначение                                                                                                     |
+| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `repository-cleanliness.mdc` (`/root/.cursor/rules/repository-cleanliness.mdc`) | Уборка только артефактов текущей задачи; сохранять чужие ветки, блокировки и журналы проверок                  |
+| `context7.mdc` (`/root/.cursor/rules/context7.mdc`)                             | Внешняя документация SDK, API и CLI по запросу; **не** для внутреннего рефакторинга и документации репозитория |
+
+**Координатор** **включает** применимые пункты глобальных правил и [контракт участников](https://github.com/zoomplus/zorya-classifier/blob/main/AGENTS.md) в текст каждой задачи для исполнителя Composer. Не дублировать глобальные правила в [правила проекта](https://github.com/zoomplus/zorya-classifier/blob/main/.cursor/rules/zorya-classifier.mdc).
+
+## Роли
+
+| Роль                     | Модель / исполнитель                                                                                       | Обязанности                                                                                                                                                                                                                                                            |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Главный оркестратор**  | Выбирает **человек** (нет модели главного по умолчанию)                                                    | По умолчанию: анализ, исследование, проверка изменений, планирование, прогон тестов, интеграция в Git после проверки; **никогда** не запускает и не владеет Cursor CLI; **не** подменяет Composer при правках исходников, тестов и документации в разрешённых границах |
+| **Координатор**          | **`gpt-6-luna`**, рассуждение **`high`**, **`fork_turns=none`** (иначе — только явная инструкция человека) | Владелец **каждого** процесса Cursor CLI; предварительная проверка CLI перед первым запуском; постановка задач Composer; проверка фактических изменений и журналов; передача владения — только явно                                                                    |
+| **Исполнитель Composer** | **`composer-2.5-fast`**                                                                                    | Редактирует разрешённые пути **сам**; **не** запускает `cursor-agent`, не делегирует и не запускает вложенных агентов                                                                                                                                                  |
+
+**Каждый** подагент Codex любой роли (включая координацию и явно запрошенные исследование или проверку изменений) порождается как **`gpt-6-luna` / `high` / `fork_turns=none`**, если человек не указал иное.
+
+Отдельные подагенты для исследования или проверки изменений — **только по явному запросу** человека и остаются **только для чтения**. Иначе исследование и проверку изменений выполняет главный оркестратор.
+
+Координатор **не обязан** работать в том же OS-процессе, что и главный оркестратор; важно явное владение процессом Cursor и передача владения.
+
+## Видимость плана (не повторное согласование)
+
+Перед **любым** запуском реализации или перепланированием главный оркестратор **показывает пользователю** нумерованные волны в порядке зависимостей. Для каждой волны: роли (главный / координатор / Composer), идентификаторы моделей и `fork_turns`, конкретные пути в зоне ответственности, входы и предварительные условия, параллелизм (не более 3 процессов Composer глобально, отдельные рабочие деревья Git при параллели), артефакты (журналы в **корне артефактов вне репозитория**), проверки и критерии выхода; рядом — краткое русское «зачем».
+
+Уже данной в сессии авторизации достаточно для реализации, проверки изменений, исправлений, тестов и интеграции в разрешённых границах — не изобретать повторные циклы согласования. При реальной нехватке модели, доступа, аутентификации или квоты — сообщить фактически, **без** подстановки другой модели или режима Auto.
+
+Проверка изменений опирается на **фактические изменения в файлах и вывод тестов**, а не на пересказ модели.
+
+## Запуск Composer (координатор)
+
+Перед **первым** запуском:
+
+```sh
+cursor-agent --version
+cursor-agent status
+cursor-agent models
+```
+
+Запуск **только** с моделью **`composer-2.5-fast`**. Запрещены Auto и скрытая подстановка `composer-2.5` или других семейств — остановиться и сообщить блокер.
+
+**Один координатор на один процесс Cursor.** Глобально **не более 3** процессов Composer. Параллель: отдельные **рабочие деревья Git**, непересекающееся владение файлами; слияние после проверки изменений и тестов; общие файлы — явная координация.
+
+Пример из корня репозитория (без секретов в тексте задачи):
+
+```sh
+cursor-agent \
+  --workspace "$PWD" \
+  --print \
+  --force \
+  --output-format stream-json \
+  --model composer-2.5-fast \
+  "…текст задачи: пути в зоне ответственности, ограничения, запрет рекурсивного запуска agent…"
+```
+
+## Инварианты кода (кратко)
+
+Слои: [архитектура](architecture.ru.md), `npm run boundaries`.
+
+- Строгий TypeScript и Zod на границах; без подстановки провайдера.
+- Байты входа — до первого `await`; один абсолютный предельный срок с очередью; слоты до фактического завершения работы; `dispose` дожидается завершения.
+- v0.2 `extract`: геометрия из маски, закрытая проверка рамки, не более одного расширения маски и финальной проверки; без координат от модели.
+- Ранг не равен вероятности; один финальный ID против четырёх кандидатов пространственной стадии луча.
+- Каталог `benchmarks`: `hashCanonical` = `SHA-256`(`JSON.stringify`) с фиксированным порядком полей.
+- Исследования в `benchmarks/experiments/` — вне дистрибутива npm; публичный профиль `experimental-text` явно отклоняет не квалифицированные запросы.
+
+## Тесты
+
+| Набор                   | Команда                                                                                                    |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Переносимый каталог     | `npm test`                                                                                                 |
+| Локальные свидетельства | `npm run test:local-evidence` (H5, `grounded-mask`, минимальный H10 — см. [разработку](development.ru.md)) |
+| Группа `python-native`  | `npm run test:python-native` (см. [разработку](development.ru.md))                                         |
+
+Единый раннер: `scripts/run-classified-tests.mjs`. Не ссылаться на удалённый `run-portable-tests.mjs`.
+
+Измеренные счётчики переносимого каталога и платформы — [план рефакторинга](refactoring-plan.ru.md). На измеренном Linux-хосте Python **3.12.3**: установлены `PIL`/`Pillow`; **`numpy`**, **`torch`** и **`transformers`** **отсутствуют**; набор `python-native` **не запускался**. Переносимый каталог: **772** успешных, **0** пропущенных (необязательные тесты без ресурсов могут пропускаться). Узкие проверки исполнителя Composer под встроенным Linux Node 24 **не** равны полным проверкам главного оркестратора на Node 24.
+
+## Секреты, платные прогоны, публикация
+
+`npm run secrets:check`, сканирование **версий файлов, добавленных в индекс Git** (Husky), `npm run pack:check`. Ключ каталога `benchmarks`: `OPENROUTER_API_KEY` или явный `--env-file` **только** в `run-region-seeded-dev.ts` / `run-quality-pilot.ts` — [разработку](development.ru.md).
+
+Не коммитить `.env`, частные медиа, журналы чатов. Платные прогоны, GPU и публикация — явная область работ и бюджеты.
+
+## Уборка
+
+Только рабочие деревья, временные каталоги и кэш, созданные текущей задачей. Сохранять ранее существующие изменения, неудачные журналы проверок (артефакты **вне** репозитория), посторонние ветки. См. `repository-cleanliness.mdc`.

package/docs/architecture.md

@@ -1,13 +1,37 @@
 # Architecture and lifecycle
 
+Russian guide with layer map, SOLID notes and current paths: [architecture.ru.md](architecture.ru.md). Development onboarding: [development.ru.md](development.ru.md).
+
 Closed `classify` and injected `DecisionPort`/adapter transport are supported integration paths. Region `locate`, whole-object location, extraction, `RefinementPort`, caller-owned segmentation and box-check composition, `ObjectProposalPort`, and explicit native segmentation factories are experimental and unqualified; they are labeled `@experimental` on the public API. No spatial or extraction strategy is promoted; evidence under `docs/evidence/**` remains historical.
 
-The public factory composes the caller-supplied `DecisionPort` and a Sharp-backed `RasterPort`. The library does not select a model, provider or endpoint; applications either inject an existing port or explicitly build one with a supported adapter. Processes orchestrate classify/locate; features contain pure Choice interpretation, grid geometry and prompt construction; entities define validated public contracts; infrastructure owns provider HTTP and image processing. No application runtime, game-state schema or workspace import is required.
+The public factory composes the caller-supplied `DecisionPort` and a Sharp-backed `RasterPort`. The library exposes four package entries (`.`, `./openrouter`, `./openai-compatible`, `./segmentation`); the CLI is a separate bin, not a fifth library export. The library does not select a model, provider or endpoint; applications either inject an existing port or explicitly build one with a supported adapter. **Import layers:** `app` composes `processes` and `infrastructure`; `processes` depend on `features`, `entities`, and `shared` port contracts only (no direct `processes` → `infrastructure` imports); `infrastructure` implements ports and may use `features`/`entities`/`shared`. Runtime calls reach HTTP, raster, and native work through injected port instances wired in `app`. Processes orchestrate classify/locate; features contain pure Choice interpretation, grid geometry and prompt construction; entities define validated public contracts. Benchmark runners live under `benchmarks/v02/`, `benchmarks/v03/`, and the repo root as well as helpers in `benchmarks/experiments/`; not all runners are under `experiments/`. No application runtime, game-state schema or workspace import is required.
 
 The primary 0.2 object path preserves the original region locator. Its selected seed prompts an explicitly configured segmenter on the full oriented source image; actual mask pixels determine bounds, center and the optional cutout. A generic closed containment checker receives the full source with the mask-derived box and original seed anchor. It uses the injected decision port and a presentation port; the process allows at most one actual enclosing-mask correction and a final check. The segmenter can implement optional `expand`; corrected foreground must strictly contain the old visible foreground and grow the real box within the hard ROI. The process rejects unresolved checks without publishing a partial cutout. Its absolute deadline, cancellation and byte ownership cover every stage. No additional extent search or model-generated coordinates are used. `locate({ mode: 'whole-object' })` and `extract` use the same mask-derived geometry when a segmenter is configured. Boundary-interval location and `ObjectProposalPort` remain optional legacy strategies with their own request flows.
 
 Extraction composes the selected locator with a caller-owned `SegmentationPort` and a `CutoutRasterPort`; processes import neither Sharp nor native inference. Explicitly created native adapters own their workers and queues, while the caller supplies and manages their optional runtime packages and local model assets. No weights are selected, installed or downloaded by the library. [Operation and ownership details](v02-usage.md) are explicit; no experimental text-image profile is publicly qualified yet.
 
+```mermaid
+flowchart TB
+  subgraph appLayer [app]
+    APP[create-classifier]
+  end
+  subgraph procLayer [processes]
+    PROC[classify / locate / extract]
+  end
+  subgraph featLayer [features + entities + shared]
+    FEAT[choice / grid / contracts / gate]
+  end
+  subgraph infraLayer [infrastructure]
+    INF[decision-transport / raster / native segmentation]
+  end
+  APP --> PROC
+  APP --> INF
+  PROC --> FEAT
+  INF --> FEAT
+```
+
+Runtime orchestration (same primary extract semantics as below):
+
 ```mermaid
 flowchart LR
   I[Owned input snapshot] --> G[Bounded operation queue]
@@ -16,12 +40,14 @@ flowchart LR
   L --> S[Caller-owned segmenter on full source with seed prompt]
   S --> M[Validate mask and derive visible bounds / center]
   M --> B[Closed box check on full source and seed anchor]
-  B -->|complete| X[Optional transparent cutout]
+  B -->|complete| X[Result / optional transparent cutout]
   B -->|unknown| U[Explicit unresolved result]
-  B -->|needs expansion| E[At most one actual enclosing-mask correction]
-  E --> R[Validate foreground containment and recheck actual box]
+  B -->|needs-expansion| E[At most one actual enclosing-mask correction]
+  E -->|success| P[Preserve every prior visible foreground pixel]
+  E -->|no expand / no valid enclosing mask| U
+  P --> R[Final check on actual box]
   R -->|complete| X
-  R -->|unresolved / no parent| U
+  R -->|unknown / needs-expansion| U
 ```
 
 One deadline covers the whole operation, including queue time. AbortSignal passes through every boundary; guards after awaits reject late results. Physical Sharp/provider work retains its slot until its promise settles. Timers/listeners are cleared in finally. There is no import-time worker, automatic retry, persistent image cache, database or background polling loop.

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.
@@ -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/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

@@ -29,8 +29,10 @@ Before release, match every runtime file in the final archive to the bytes cover
 
 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.
 
-## 0.2.1 release-candidate handoff
+## Research and consumer archive
 
-This branch prepares a local **0.2.1 release candidate** from the published **0.2.0** package baseline. Only experimental status documentation, JSDoc, CLI help, the package description, and a test-only Git fixture isolation fix in `test/secrets.test.ts` changed. There are no model, default, or algorithm/runtime behavior changes relative to 0.2.0. At local 0.2.1 release-candidate preparation time, npm and GitHub publication for 0.2.1 had not yet been recorded in this handoff; check the repository releases, npm registry entry, and external release receipt for the current publication state.
+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.
 
-A failed pre-commit attempt during local release preparation is preserved in the maintainer’s local release-preparation logs. That failure led to the narrow test-only isolation fix so hook-provided `GIT_*` variables cannot redirect fixture repositories or mutate unrelated sentinel indexes during secret scans.
+## 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.