zorya-classifier 0.1.0 → 0.2.1

package/docs/README.ru.md

@@ -1,19 +1,44 @@
 # Zorya Classifier: руководство
 
-Zorya Classifier — библиотека для Node.js и TypeScript, которая помогает приложению принимать решения по тексту и изображениям. Вы задаёте допустимые классы или описываете искомый объект, библиотека передаёт их выбранной модели решений или языковой модели и проверяет структурированный ответ. Основной вариант — decision-модель, в примерах Luna Decisions. Обычные vision-модели без нативной классификации тоже поддерживаются через чат-адаптер. Код распространяется по MIT; веса модели в поставку не входят, запросы удалённых моделей оплачиваются отдельно; можно подключить и свой локальный сервер. Любая vision-модель, которая понимает изображения и выполняет контракт ответа, может использоваться через готовый OpenAI-совместимый адаптер или собственный `DecisionPort`. Точная проверенная совместимость и результаты перечислены в [таблице моделей](vision-results.md).
+Версия 0.2 добавляет прозрачный PNG, бинарную маску, её рамку и центр. Прежний поиск области служит подсказкой для сегментации всего исходного изображения. Затем decision проверяет рамку; допускаются одно расширение маски и повторная проверка. [Руководство](v02-usage.md) описывает API, CLI и владение ресурсами.
+
+[Независимый тест 80 случаев](evidence/v02/region-seeded-heldout-v3/README.md) прошёл согласованные критерии, но показал ограниченную полноту: 26/60 попаданий в область объекта и 8/60 полных рамок, без ложных выделений на 20 отрицательных случаях. Из 30 эталонных масок восемь достигли IoU 0,8, три не достигли, для 19 предсказание отсутствовало. Это результаты одной явно настроенной комбинации Luna/OpenAI и MobileSAM, а не гарантия для любой модели или игры.
+
+Сравнение шести способов передачи изображения текстом завершено на свежих фотографиях и реальном интерфейсе: ни один не прошёл требования локализации. [Результаты и ограничения](evidence/v02/fresh-text/README.md) сохранены, публичный экспериментальный режим явно возвращает `UNSUPPORTED`.
+
+Zorya Classifier — библиотека для Node.js и TypeScript с поддерживаемой классификацией по тексту и изображениям и экспериментальной, не квалифицированной для общего применения пространственной локализацией и извлечением объектов. Библиотека не выбирает и не подключает модель за приложение: клиент получает явно переданный `DecisionPort` — готовый адаптер с выбранными настройками или собственную реализацию. Модель и провайдер в примерах — лишь варианты интеграции, не значения по умолчанию. Код распространяется по MIT; веса модели в поставку не входят, запросы удалённых моделей оплачиваются отдельно; можно подключить и свой локальный сервер. Совместимость и качество зависят от выбранного маршрута. Более мощная модель может помочь, но улучшение точности не гарантировано. Проверенные комбинации и результаты перечислены в [таблице моделей](vision-results.md).
 
 Это самостоятельная библиотека: ей не нужны Zorya Games, Electron, база данных или игровой процесс. Её можно встроить в сервер, бота, инструмент обработки фотографий или собственный HTTP-сервис. Готовый постоянно работающий HTTP-сервер в пакет не входит.
 
+## Статус возможностей
+
+Дальнейшие эксперименты по точности пространственных сценариев остановлены; ни одна стратегия локализации, извлечения или предложений масок не продвигается для общего использования. Исторические метрики в `docs/evidence/**` сохранены без переинтерпретации.
+
+| Возможность                                   | Статус           | Примечание                                                                     |
+| --------------------------------------------- | ---------------- | ------------------------------------------------------------------------------ |
+| `classify` с явным `DecisionPort`             | Поддерживается   | Один закрытый ID класса; без заявления об универсальной точности модели        |
+| `locate` (сетка регионов)                     | Экспериментально | Гипотеза по ячейке, не геометрия целого объекта и не доказательство отсутствия |
+| `RefinementPort`                              | Экспериментально | Без общей квалификации качества                                                |
+| `locate({ mode: 'whole-object' })`            | Экспериментально | Интервалы или сегментация вызывающего; без квалификации                        |
+| `extract`, `SegmentationPort`, проверка рамки | Экспериментально | Структурный успех ≠ семантическая точность маски                               |
+| `objectProposals`, нативные фабрики           | Экспериментально | На стороне вызывающего; без квалификации                                       |
+| `experimental-text`                           | Отклонено        | `UNSUPPORTED`, пока профиль не пройдёт отбор                                   |
+
+Heldout region-seeded (один задокументированный рецепт): 26/60 попаданий seed на позитивах; 8/60 полных рамок объекта; на 30 эталонных масках — 8 с IoU 0,8, 3 неудачи, 19 без предсказания. H8 DEV: 7/9 позитивов и 2/3 ложных выхода, без квалификации. Узкий исторический admission — не общая пространственная квалификация.
+
 ## Что умеет
 
-| Задача                                                     | API                                 | Результат                                                                         |
-| ---------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------- |
-| Распределить обращения по отделам, определить намерение    | `classify` с текстом                | Один из заданных классов и ранжирование вариантов                                 |
-| Проверить наличие объекта или выбрать категорию фотографии | `classify` с изображением           | Один из заданных классов                                                          |
-| Оценить изображение с текстовым условием                   | `classify` с текстом и изображением | Класс с учётом обоих входов                                                       |
-| Найти примерную область предмета, значка или указателя     | `locate`                            | Ячейка в координатах исходного изображения либо явная неопределённость/отсутствие |
+| Задача                                                     | Статус           | API                                 | Результат                                                                         |
+| ---------------------------------------------------------- | ---------------- | ----------------------------------- | --------------------------------------------------------------------------------- |
+| Распределить обращения по отделам, определить намерение    | Поддерживается   | `classify` с текстом                | Один из заданных классов и ранжирование вариантов                                 |
+| Проверить наличие объекта или выбрать категорию фотографии | Поддерживается   | `classify` с изображением           | Один из заданных классов                                                          |
+| Оценить изображение с текстовым условием                   | Поддерживается   | `classify` с текстом и изображением | Класс с учётом обоих входов                                                       |
+| Найти примерную область предмета, значка или указателя     | Экспериментально | `locate`                            | Ячейка в координатах исходного изображения либо явная неопределённость/отсутствие |
+| Получить маску, рамку, центр и прозрачный вырез предмета   | Экспериментально | `extract` с явным сегментатором     | Геометрия и вырез, выведенные из пикселей маски                                   |
+
+Для `extract` после сегментации модель получает исходную картинку с рамкой маски и отметкой прежней найденной области. Она выбирает один ответ: весь видимый объект внутри, нужно расширение или определить не удалось. При необходимости сегментатор один раз ищет внешнюю маску, содержащую прежние пиксели; её рамка проверяется повторно. Максимум получается пять модельных запросов: три на поиск области и два на проверку. Если подтверждения нет, библиотека возвращает неопределённость без частичного выреза. `verification` сохраняет проверки и результат расширения. Рамка и центр всегда вычисляются из маски; проверка рамки не гарантирует точности каждого пикселя. Своя модель подключается через `DecisionPort`, отдельная проверка — через `segmentationBoxCheck`.
 
-`classify` делает один запрос к выбранному API модели. `locate` делает до трёх последовательных запросов: крупная сетка → уточнение в четырёх выбранных областях → сравнение четырёх увеличенных кандидатов. Проверки присутствия входят в те же запросы. Модель выбирает варианты, а координаты вычисляет код.
+Сконфигурированный `DecisionPort` выполняет запросы по контракту библиотеки. `classify` делает один запрос, а `locate` — до трёх последовательных запросов: крупная сетка → уточнение в четырёх выбранных областях → сравнение четырёх увеличенных кандидатов. Проверки присутствия входят в те же запросы. Порт отвечает за ответы, координаты вычисляет код.
 
 Библиотека не генерирует описание сцены и не ищет все экземпляры предмета: если подходящих объектов несколько, `locate` возвращает один кандидат. Выбранная ячейка может содержать только часть объекта; это не маска сегментации, не точная рамка и не доказанный центр. Дополнительный алгоритм уточнения можно подключить через `RefinementPort`.
 
@@ -102,9 +127,9 @@ const result = await client.classify({
 
 Для одной картинки поле `text` можно опустить. Принимаются `Uint8Array` и `Buffer` с одним PNG/JPEG/WebP: до 16 MiB и 16 777 216 декодированных пикселей. Ссылки на изображения публичный API не загружает — скачивание, права доступа и ограничения внешних URL остаются у вызывающего приложения.
 
-## Поиск объекта и координаты
+## Поиск объекта и координаты (экспериментально)
 
-Также внутри `try`:
+Обычный `locate` экспериментален и не квалифицирован для общего применения. Также внутри `try`:
 
 ```js
 const result = await client.locate({
@@ -133,7 +158,11 @@ if (result.status === 'located') {
 | `unknown`                    | Неуверенность, противоречие, отсутствие цели среди кандидатов или невозможная сетка | Уточнить цель, взять более подходящее изображение или вернуть пользователю неопределённость |
 | Исключение `ClassifierError` | Ошибка входа, сети, протокола, бюджета или жизненного цикла                         | Обработать код ошибки; не показывать её как отсутствие объекта                              |
 
-Небольшие значки, перекрытия, похожие предметы и сложные карты требуют собственной проверки на ваших данных. Предметные фотографии не доказывают точность на игровых мини-картах. Если нужен центр объекта или маска, это отдельный этап уточнения.
+Если нужны маска, рамка или центр объекта, используйте `extract` с явно созданным сегментатором. Обычный `locate` сначала находит регион-кандидат; затем сегментатор получает seed-подсказку на всём ориентированном исходном изображении. Рамка и центр вычисляются по реальным пикселям маски, без отдельного поиска границ или подтверждения рамки языковой моделью. Пример и детали владения ресурсами приведены в [руководстве 0.2](v02-usage.md). Это технический путь обработки, а не гарантия точности на всех фото.
+
+В проверенном сценарии v2 приложение сначала вызывает `classify` для наличия цели и запускает `extract` только после ответа `present`. Это явная композиция приложения: один запрос классификации плюс до трёх запросов поиска. Сам `extract` дополнительную классификацию не вставляет. Ошибку классификации нельзя выдавать за отсутствие цели; обе операции должны использовать общий сигнал отмены и абсолютный срок выполнения.
+
+Встроенный MobileSAM получает точку в центре найденной области и обрабатывает весь исходник; текст названия предмета он не понимает. Поэтому иногда он выделяет деталь, например фару вместо автомобиля. Успешный `extracted` подтверждает корректность маски и файлов, а точность распознавания оценивается отдельно. На полном DEV40 для v2 было 18/30 попаданий области в рамку цели, 5/30 совпадений рамки маски и 0 ложных вырезок на 10 отрицательных примерах. Это разные метрики. [Независимый отчёт](evidence/v02/region-seeded-dev-v2/README.md) сохраняет ошибки и ограничения; другой сегментатор подключается через тот же `SegmentationPort`.
 
 ## Отмена, нагрузка и ошибки
 
@@ -174,7 +203,7 @@ try {
 
 ## Командная строка
 
-CLI требует явный `ZORYA_MODEL`; по умолчанию используется `ZORYA_MODE=decisions`. Для обычной языковой модели или прямого чат-сервера установите `ZORYA_MODE=chat`. Для OpenRouter задайте также `OPENROUTER_API_KEY` и `ZORYA_PROVIDER`. Для прямого API или локального сервера задайте полный `ZORYA_ENDPOINT` и при необходимости отдельный `ZORYA_API_KEY`; ключ OpenRouter туда не передаётся. Необязательные `ZORYA_REASONING_EFFORT` и `ZORYA_RESPONSE_FORMAT` используйте только при поддержке сервером. Например, для основного маршрута Luna Decisions:
+CLI требует явный `ZORYA_MODEL`; режим CLI по умолчанию — `ZORYA_MODE=decisions`. Это настройка команды, а не выбор модели внутри библиотеки. Для обычной языковой модели или прямого чат-сервера установите `ZORYA_MODE=chat`. Для OpenRouter задайте также `OPENROUTER_API_KEY` и `ZORYA_PROVIDER`. Для прямого API или локального сервера задайте полный `ZORYA_ENDPOINT` и при необходимости отдельный `ZORYA_API_KEY`; ключ OpenRouter туда не передаётся. Необязательные `ZORYA_REASONING_EFFORT` и `ZORYA_RESPONSE_FORMAT` используйте только при поддержке сервером. Например, одна из конфигураций Luna Decisions:
 
 ```sh
 export ZORYA_MODE=decisions
@@ -223,7 +252,7 @@ const client = createClassifier({ decision })
 
 [Таблица проверенных моделей](vision-results.md) содержит названия, провайдеров, число примеров, ошибки, точность, задержки и цену. Там отдельно указаны полноценная проверка на корпусе, короткий screening и тесты адаптера с искусственным сервером. Необозначенная модель не считается автоматически проверенной.
 
-Исторический Jev-прогон дал 55/60 на фото и 30/30 на авторских текстовых примерах. Это baseline прежнего адаптера, а не доказательство качества другой модели. Подробности и исходные ошибки сохранены в [исторических результатах](results.md). Локализация остаётся экспериментальной; ячейка не является точной маской или центром объекта.
+Исторический Jev-прогон дал 55/60 на фото и 30/30 на авторских текстовых примерах. Это baseline прежнего адаптера, а не доказательство качества или превосходства другой модели. Результаты не позволяют предполагать, что более мощная модель обязательно повысит точность. Подробности и исходные ошибки сохранены в [исторических результатах](results.md). Локализация остаётся экспериментальной; ячейка не является точной маской или центром объекта.
 
 ## Разработка и следующие документы
 
@@ -241,5 +270,5 @@ npm run format:check
 - [Архитектура](architecture.md): слои, порты, отмена и владение ресурсами.
 - [Эксплуатация](operations.md): интеграция в сервис, расходы и завершение работы.
 - [Воспроизведение benchmark](benchmarks.md): лицензированные фотографии и отдельный запуск платных проверок.
-- [Безопасность](../SECURITY.md): ключи, Git, npm-архивы и ограничения сканирования.
+- [Безопасность](https://github.com/zoomplus/zorya-classifier/blob/main/SECURITY.md): ключи, Git, npm-архивы и ограничения сканирования.
 - [Подготовка публикации](publishing.md): GitHub/npm и необходимая авторизация владельца.

package/docs/acceptance.md

@@ -1,8 +1,121 @@
-# Acceptance: standalone0.1.0 preview
+# Acceptance: standalone library
 
-This acceptance concerns the extracted MIT Node.js library, not the Zorya desktop application, installer, microphone or game session. Native Luna Decisions is the primary documented route; ordinary vision chat, direct OpenAI-compatible servers and custom DecisionPort implementations remain alternatives. Jev is optional historical compatibility.
+This acceptance concerns the extracted MIT Node.js library, not the Zorya desktop application, installer, microphone or game session. The caller supplies a `DecisionPort` or explicitly configures an adapter; model/provider recipes below are examples, not library defaults. Closed `classify` and explicitly configured provider/transport adapters are supported integration paths. Region `locate`, whole-object location, extraction, `RefinementPort`, segmentation/box-check composition, `objectProposals`, and native segmentation factories are experimental and unqualified; public API symbols carry `@experimental`. Further spatial accuracy experiments are stopped; no strategy is promoted. Jev is optional historical compatibility.
 
-## Executed checks and release gates
+## Current 0.2 acceptance
+
+The original-region/full-source-segmentation workflow, closed box check and single enclosing-mask correction are implemented. The caller selects every decision model, provider and segmenter. Classification and the default region API remain compatible. All six text-only encoders failed their separate qualification and remain unsupported.
+
+The [independent frozen heldout evaluation](evidence/v02/region-seeded-heldout-v3/README.md) passed its predeclared criteria on all 80 candidate and 80 image-free control cases. Candidate classification was 65/80. Positive seed hits were 26/60, complete mask-derived boxes 8/60, and false seeds/extractions 0/20 negatives. Of 30 exact-canvas mask references, eight reached IoU 0.8, three did not and 19 had no predicted mask. Both paired positive-photo seed intervals were [0.500, 0.833]; neither measures whole-object quality. The corpus contains official photos and one controlled UI/game family each, not general game coverage. Two HTTP 502 failures and unknown charges remain counted.
+
+The [fresh checked-flow resource run](evidence/v02/checked-region-segmentation-resource-4df544c-receipt.json) passed every strict monotonic-duration guard after the harness-only deadline repair. It recorded 7,212.61 seconds, 3,295 successful operations and 4,942 matching child starts/closes with none left. [Independent root recomputation](evidence/v02/checked-region-segmentation-resource-4df544c-root-review.json) rehashed all 59 pinned sources and confirmed idle-median growth of 51.44 MiB RSS, 8.61 MiB heap and 5.57 MiB array buffers; external memory decreased. All fixed thresholds pass. This is bounded resource evidence, not proof of zero retained memory.
+
+[Native Windows installed-archive checks](evidence/v02/native-checked-region-windows-987ac32.json) cover the same 114 compiled runtime files. The [565-test hosted matrix](evidence/v02/ci-f9d4633.json) passed Windows/Linux × Node 22/24. The later evaluator-only missing-byte-count compatibility fix preserves pinned assets, bounded reads, hashes, canvas/pixel checks and every scoring criterion. Final source gates, exact installed archive, runtime parity, redacted security scans, final-source CI and registry publication are recorded separately in the external release manifest. Historical interrupted and rejected runs below remain preserved.
+
+## Implementation and development history
+
+The latest owner correction adds a closed post-segmentation containment check and at most one actual enclosing-mask repair. The original three-Choice region search stays compatible; coordinates and cutouts still come only from mask pixels. A default checker reuses the injected decision port, while an optional custom checker remains caller-owned. An unresolved check returns unknown without a partial cutout. The [updated plan](0.2.0-plan.md) records contracts, ownership, bounded calls and execution waves.
+
+A [three-call DEV component probe](evidence/v02/checked-region-component-v1/README.md) rejected the headlight-only Car box, accepted the Knife box, and accepted the actual enclosing Car box. This demonstrates the correction hypothesis on two exposed images; it does not qualify general accuracy. The old v2 blind freeze was [cancelled before dispatch](evidence/v02/region-seeded-heldout-cancelled-before-dispatch-20261021-v2.json); all 80 unused cases remain sealed.
+
+The corrected checked-flow runtime is integrated at `987ac32`. All 563 offline tests and strict source/build/format gates pass at `29357d7`, including a real public producer-to-evaluator fixture with controlled fetches and the per-variant freeze verifier. [All four hosted Windows/Linux × Node 22/24 jobs](evidence/v02/ci-29357d7.json) and their installed-archive checks passed. The [native Windows installed-archive check](evidence/v02/native-checked-region-windows-987ac32.json) passed actual segmentation, enclosing-mask expansion, cancellation, capacity and disposal on the unchanged compiled runtime: ten owned child starts matched ten closes, with none retained and zero provider HTTP calls. These are transport, wiring and lifecycle checks, not real-photo accuracy or game navigation.
+
+The first checked-flow resource attempt was [interrupted after a public-transport preparation defect was reproduced](evidence/v02/checked-region-resource-interrupted-2b0d09f.json). The corrected runtime prepares the full rendered source through the existing raster image-state port, preserving mask coordinates; real native and ordinary public adapters are covered on 64×48 and 1920×1080 sources. The [completed corrected-runtime run](evidence/v02/checked-region-segmentation-resource-987ac32-receipt.json) preserves 3,176 successful measured operations, 4,764 matching child starts/closes, no retained child and memory growth below the fixed thresholds. It is **not qualified**: one timer-based idle window measured 29,999.622479 ms instead of the required 30,000 ms, so the original strict duration guard failed despite more than 7,211 monotonic process seconds. No rounding or retrospective waiver is applied. A harness-only absolute-deadline wait fix and a fresh full run are required; runtime bytes and the blind cohort remain unchanged.
+
+The [v3 candidate-only evaluation](evidence/v02/region-seeded-dev-v3-candidate-only/README.md) scored all 40 cases: 6/30 positive mask-derived boxes matched, with zero false locations on ten negatives; one of seven exact-canvas mask references reached IoU 0.8. It retains six failed provider calls and their unknown charges. The original [v3 development freeze](evidence/v02/region-seeded-development-freeze-20261021-v3.json) incorrectly reused the candidate prompt policy when calculating the control identity. The evaluator rejected that mismatch; the original control remains preserved and unscored. The [separate prospective control-R2 freeze](evidence/v02/region-seeded-development-control-r2-freeze-20261021.json) was verified before a new complete control40. Its [strict paired evaluation](evidence/v02/region-seeded-dev-v3-control-r2/README.md) reuses only the immutable correctly pinned candidate: coarse positive-photo seed difference +0.625, 95% interval [0.375, 0.875]; exact-mask foreground seed interval [0.4, 1.0] on five comparable photo pairs. These are seed metrics, not whole-object or mask accuracy. Development admission passes; the [conditional method selection](evidence/v02/region-seeded-method-selection-20261021-v3.json) freezes the unchanged recipe before any new blind data. The unused blind cohort remains undispatched. No text-only encoder qualified, and no 0.2 npm release is claimed.
+
+The new [v3 blind freeze](evidence/v02/region-seeded-heldout-run-freeze-20261021-v3.json) binds 80 unused cases, unchanged source/oracle pins, distinct ordered candidate/control identities and the original admission criteria. Both offline preflights verified all 80 images with zero provider calls after method selection. An [independent metadata audit](evidence/v02/region-seeded-heldout-readiness-audit-20261021-v3.json) preserves the rejected first draft's JSON property-order error and confirms the corrected identities. Actual dispatch remains disabled until the required checked-flow resource gate passes and a separate authorization is recorded.
+
+## Baseline before checked expansion
+
+The agreed primary flow is the original three-Choice region search followed by one caller-owned segmentation of the full oriented source. The selected cell is a prompt, not a crop limiting the object. Cutout pixels, bounding rectangle and centre come from the mask. The implementation was integrated at `c6b8069`; its 54 runtime source files remain unchanged. At `65c785f`, all 512 offline tests, strict TypeScript/ESLint, boundaries, dead-code checks, build and formatting pass. Caller-owned model/segmenter configuration and default region behavior are retained.
+
+The [native Windows installed-archive check](evidence/v02/native-region-windows-efc9318.json) passed with the new full-source point-prompt flow: the mask extended beyond its seed, PNG alpha and mask/bounds/center/offset agreed, transparent input produced a valid empty mask, and nine owned child starts matched nine closes. Physical cancellation, bounded queuing, caller ownership and cleanup passed with zero HTTP. This is wiring/lifecycle evidence, not photo accuracy. [All four hosted Windows/Linux × Node 22/24 jobs passed for `c5eddd8`](evidence/v02/ci-c5eddd8.json); final release-source CI and archive parity remain mandatory.
+
+The [first complete region-seeded DEV40](evidence/v02/region-seeded-dev-v1/README.md) failed: 5/30 positive mask-derived boxes matched, 1/10 verified negatives produced a false seed and cutout, and 1/7 exact-canvas mask references reached IoU 0.8. The separately recorded classification correctly rejected that false target. A [new presence-first caller recipe](evidence/v02/region-seeded-development-freeze-20261021-v2.json) reuses that existing classification to skip localization after absence or error, without changing the library or adding a request. Its complete candidate/control DEV40 rerun passed independent development admission: zero false seeds/extractions on ten negatives, 18/30 coarse seed-box intersections, 5/30 mask-derived box matches, and 1/7 exact-canvas masks reaching IoU 0.8. The paired positive-photo seed proxy is +0.625 with 95% interval [0.375, 0.875]; it does not measure whole-object accuracy. Six 502s and unknown charges remain counted. This new run, rather than the earlier post-hoc filter, is the development evidence; mask/box quality remains low. The old box-confirmation blind run was [cancelled before dispatch](evidence/v02/box-heldout-cancelled-before-dispatch-20261021-v1.json); its unused 80-case cohort remains sealed. No release or blind accuracy qualification is claimed.
+
+The [two-hour `450439c` proposal baseline](evidence/v02/proposal-resource-soak-450439c-receipt.md) terminated after 7,210.99 monotonic seconds and 3,022 successful measured operations, with 3,022 child starts/closes and none retained. Idle RSS grew 228.3 MiB, exceeding the investigation threshold; that research path remains unqualified for sustained resource use. This does not establish its cause. The later [original-region segmentation baseline](evidence/v02/region-segmentation-resource-0ba4c87-receipt.json) completed after 7,208.68 monotonic seconds, with an independent same-process age witness, 4,537 successful operations and 4,537 owned child starts/closes. Idle RSS rose 62.63 MiB and heap 5.74 MiB, below the fixed investigation thresholds; external/array-buffer growth was negligible. This is threshold evidence for the earlier flow, not proof of no retained memory or qualification of the later checked-containment runtime. Its separate two-hour run remains active.
+
+| Gate                               | Baseline workflow                                                                          |
+| ---------------------------------- | ------------------------------------------------------------------------------------------ |
+| Source checks                      | Pass: 512 tests and strict checks at `65c785f`; final release checks remain                |
+| Real image quality                 | DEV v1 failed; presence-first v2 passed development admission; blind qualification pending |
+| Installed archive / Windows native | Native new-flow wiring passed; final release archive and runtime parity still required     |
+| Two-hour resources                 | Original-region segmentation baseline passed; checked-containment run remains separate     |
+| Text-only encoders                 | None qualified; experimental public image selector rejects explicitly                      |
+| Publication                        | Pending mandatory gates                                                                    |
+
+## Historical gate state before the region-segmentation clarification
+
+The integrated executable passes 471 Linux offline tests, formatting, strict source checks and the installed-archive consumer at `9f85acc`. [All four Windows/Linux × Node 22/24 jobs passed for `9f85acc`](evidence/v02/ci-9f85acc.json), including the new HELDOUT profiles, evaluator metadata correction, explicit-thread resource harness, archive and formatting steps. [The `6f9cc15` run](evidence/v02/ci-6f9cc15.json), [the `e0c190b` run](evidence/v02/ci-e0c190b.json), [the `c35f67d` run](evidence/v02/ci-c35f67d.json) and [the earlier `450439c` run](evidence/v02/ci-450439c.json) remain preserved. [Native Windows installed-archive acceptance](evidence/v02/native-proposal-windows-450439c.json) passes on the changed runtime: eight child starts/closes, none left, physical cancellation and caller ownership. Its 107-file installed manifest matches the reviewed archive exactly. Independent Gitleaks scanned 104 commits / 8.58 MB with no findings. The evaluator-only metadata correction passes these source checks and does not change runtime or scoring. Earlier [c107 CI](evidence/v02/ci-c107ddf.json) and [integration evidence](evidence/v02/integration-25c19cd.json) remain preserved. Final release source still needs its own checks.
+
+The frozen runtime used for v4 had all 53 source files and 106 compiled runtime files byte-identical to `0c365cb`. The new box-confirmation development hypothesis changes the proposal process and presenter, so the historical native/resource receipts below do not automatically cover its new bytes. Fresh native Windows acceptance has passed; the new two-thread resource run remains active. The first proposal resource run completed its configured wall-clock phases, but its observed process lifetime and summed monotonic operation durations did not prove the required physical duration. It is retained as historical evidence. Replacement harness `261dc23` uses monotonic phase deadlines, enforces the full duration minima, and has a separate kernel-uptime observer. Its [fresh two-hour run passed](https://github.com/zoomplus/zorya-classifier/blob/36818582091bfd19951631f358183bdb9ffd1e11/docs/evidence/v02/proposal-resource-soak-261dc23.md): 7,212.6 monotonic seconds, an independent live process-age witness at 7,200.68 seconds, and 2,158 native starts/closes in the measurement window with none left. Idle heap, external and array-buffer growth pass the fixed limits; RSS grew 115.76 MiB, below the 128 MiB threshold. Root independently checked parity of all 55 pinned files. This fixture run establishes resource/lifecycle behavior; its shared-host timing does not qualify model quality or production latency.
+
+The [first frozen blind candidate](evidence/v02/heldout-evaluation-20261020.md) failed: 3/60 positive whole-object boxes matched, there were 2/20 false locations against a limit of one, and the paired photo bootstrap interval was [0, 0.20], whose lower bound must be positive. Four of six scored mask instances reached IoU 0.8; nineteen reference instances were unavailable. Mask and box metrics remain separate. The no-image control completed all 40 photos with no successful location. No alternative is selected from these revealed heldout results.
+
+The [six-case split Choice/NoUL pilot](evidence/v02/split-choice-noul-dev6.md) failed its predeclared positive gate: classification 4/6, positive whole-object matches 0/2, false locations 0/4 verified negatives, and one failed localization. The [split categorical-presence follow-up](evidence/v02/categorical-presence-dev6.md) also produced no locations. Neither failed split profile advanced to full DEV40.
+
+The distinct native categorical batch comparison completed both original DEV40 profiles: [preserving the neutral instruction](evidence/v02/categorical-dev40-preserve.json) reached 3/30 positive whole-object matches, while [target alone](evidence/v02/categorical-dev40-target-only.json) reached 0/30. Both classify 35/40 and have zero false locations on ten negatives. Preserving the instruction is [frozen as the development selection](evidence/v02/categorical-vision-method-selection.json), before new heldout pixels or per-case truth were opened. Its eight 502 failures and eight unknown charges remain counted. The second profile has four such failures. Timing is unranked under concurrent native stress; no latency tie-break was needed. This caller-owned recipe does not become a library default or qualify blind accuracy. The new 80-case cohort has independent photo, controlled Mousepad UI and controlled Minetest minimap source oracles. Its [first setup attempt failed before HTTP](evidence/v02/categorical-heldout-predispatch-20261020-v3.json); the separate [v4 freeze](evidence/v02/categorical-heldout-run-freeze-20261020-v4.json) binds the corrected common photo instruction, unchanged images/targets/truth and the exact executable producer closure. Both measurements completed before independent truth evaluation. The [v4 result failed qualification](https://github.com/zoomplus/zorya-classifier/blob/36818582091bfd19951631f358183bdb9ffd1e11/docs/evidence/v02/categorical-heldout-v4/README.md): 1/60 positive whole-object boxes, zero false locations on 20 negatives, and paired photo bootstrap interval [0, 0.10]. Classification is 69/80, including ten false positives; the no-image control has zero positive locations. All 456 physical calls, seven unknown charges and failures remain counted. The initial mask section has no joined references; the separate official index has 32 masks on 21 photos, with 30 masks using a different full-frame canvas. A separate exploratory normalized-canvas calculation records seven scored reference instances, three at IoU 0.8, and 25 unavailable predictions; exact alignment remains unqualified and cannot change the box/paired failure. These cases are now exposed regression data; a changed method requires new development and a fresh blind cohort.
+
+The [paired segmentation component comparison](evidence/v02/segmentation/component-comparison-summary.json) uses the same five public DEV photos and independent masks for both MobileSAM and GrabCut. Its corrected, oracle-assisted seed panel gives mean per-case mask IoU 0.859 versus 0.595; its 53-file runtime snapshot matches `c107ddf`, before the two later proposal prompt/presentation changes. The native backend implementations are unchanged. This supports a component comparison under supplied geometry, not end-to-end accuracy or a library-selected backend.
+
+The new proposal development hypothesis separates mask completeness from whole-box completeness. It selects the same seeded instance by its actual foreground-derived rectangle, renders that rectangle, and confirms only the chosen candidate at source resolution. It retains source/ROI/seed checks and the same failure thresholds; no ground-truth padding or coordinates enter production. This changes two runtime files and is not a qualified replacement. The named [box-confirmation DEV40](evidence/v02/box-confirmation-dev40/report.json) completed independently: classification 35/40, whole-object matches 5/30 (photo 4/16, controlled map 1/7, UI 0/7), and zero false locations on ten negatives. Eight provider failures and unknown costs remain counted. Only one mask-annotated case returned a mask; neither of its two reference instances reaches IoU 0.8. These development results do not qualify release or extraction. A new two-hour monotonic run is active against `450439c` with two native threads; its interrupted one-thread setup run is retained as a failure, and no terminal resource result is claimed yet. The separate [native-only refinement component](evidence/v02/box-confirmation-dev40/component-refinement.json) reuses all eight predicted boxes/seeds and has no passing mask reference; it does not demonstrate a refinement benefit and no additional refiner is promoted. The [development selection](evidence/v02/box-confirmation-method-selection-20261020-v1.json) freezes the current recipe for a new independent blind cohort. The [corrected source-exclusion audit](evidence/v02/box-heldout-exclusion-audit-20261020-v1.json) covers all 160 exposed photos and their source groups; new source JPEG and official mask canvases must match exactly before admission.
+
+The [new HELDOUT preparation](evidence/v02/box-heldout-source-review-20261020-v1.json) has separate strict candidate/control profiles and an 82-file source closure independently checked with the TypeScript parser. All 53 runtime sources still match the current resource/Windows-tested runtime. New synthetic normalization checks exercise both profiles successfully; no new blind request has been dispatched. The [photo cohort seal](evidence/v02/box-heldout-photo-seal-20261020-v1.json) records 30 positive/ten negative fresh photos with exact mask canvases, and the [independently reviewed Calculator proof](evidence/v02/calculator-proof-root-review-20261020-v1.json) supports [a sealed controlled UI20 cohort](evidence/v02/box-heldout-ui-seal-20261020-v1.json). The [controlled map20](evidence/v02/box-heldout-map-seal-20261021-v1.json) and [combined corpus/assets](evidence/v02/box-heldout-combined-seal-20261021-v1.json) are now sealed. The [new strict input/source freeze](evidence/v02/box-heldout-run-freeze-20261021-v1.json) binds the unchanged selection and 82-file producer; its SHA-256 is `31e6b96b485b1dccbbe10b2c5e222ca0c20f3adbe25ee027a682595a136d8650`. Resource completion, oracle-source integration and final source/CI review remain dispatch prerequisites.
+
+The [excluded Wesnoth proof](evidence/v02/wesnoth-proof-root-review-20261020-v1.json) now independently confirms the source-derived minimap placement across 51 villages and all 1,297 changed pixels. Exact float32 repeated sampling resolves the original three edge discrepancies without padding or fitting. The projected support is still an upper bound, not a mask; the sealed controlled map20 uses isolated A/B/A marker deltas to establish visible boxes, with its per-case provenance kept separately. No fresh cohort image or per-case truth was read by this independent proof review, and no model accuracy is claimed from it.
+
+A separate [reconstructed C03 diagnostic](evidence/v02/reconstructed-c03-box.json) finds box IoU 0.874 and reference-box coverage 0.986 against the original Dog annotation. The original producer rejected completeness and returned `unknown`; its mask was not saved. This replay does not repair that result, prove the original mask bytes, or measure mask IoU. A matching box alone cannot show that the mask-completeness verdict was wrong.
+
+| Gate                                 | Current status                                                                                |
+| ------------------------------------ | --------------------------------------------------------------------------------------------- |
+| Source checks and installed consumer | Pass: 471 Linux tests / installed consumer at `9f85acc`; final release checks remain required |
+| Hosted Windows/Linux × Node 22/24    | Pass at `9f85acc` on all four jobs; final release source CI remains required                  |
+| Windows native execution             | Pass for changed runtime in reviewed Windows archive; controlled input only                   |
+| Two-hour resource soak               | Old snapshot passed; fresh `450439c` two-thread run is active, no result yet                  |
+| First frozen blind vision candidate  | Failed both false-location and paired-bootstrap gates                                         |
+| Second frozen blind vision candidate | Failed: 1/60 whole boxes; paired lower bound zero; new development required                   |
+| Text-only encoders                   | None qualified; public experimental image selector returns `UNSUPPORTED`                      |
+| Publication                          | Pending all mandatory gates                                                                   |
+
+## 0.2 development snapshot, 2026-10-20
+
+The release is **not qualified or published yet**. The following table and paragraphs preserve earlier snapshots; the current gate state above takes precedence.
+
+| Gate                                | Current evidence and remaining work                                                                                                                                                                                                                                                                                                                                                 |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Runtime and installed archive       | [Repaired runtime snapshot `0c365cb`](evidence/v02/integration-0c365cb.json); its 55 runtime/harness files remain unchanged in `24f849f`. The latter passes 368 offline source tests.                                                                                                                                                                                               |
+| Windows native execution            | [Actual installed-archive CPU acceptance](evidence/v02/native-proposal-windows-0c365cb.json): public locate/extract, physical cancellation, capacity and caller ownership; eight child starts/closes and none left. This uses controlled input, not a real game.                                                                                                                    |
+| Hosted CI                           | [All four OS/Node jobs passed for `0c365cb`](evidence/v02/ci-0c365cb.json). [The later `24f849f` run](https://github.com/zoomplus/zorya-classifier/actions/runs/39431706865) passed source checks but rejected a machine-local path in documentation during archive inspection. That failure must be repaired without weakening the scanner, then the final source must pass again. |
+| Resource retention                  | The original wall-clock proposal run has ended and is retained, but does not prove the required physical duration. The replacement monotonic run is in progress; the earlier `8010aad` result does not cover this pipeline.                                                                                                                                                         |
+| Vision quality                      | [Complete repaired DEV2](evidence/v02/dev2-proposal-evaluation.md): 35/40 classifications correct, 1/30 positive whole-object matches, no false locations on ten negatives, and no mask reaching IoU 0.8. This is insufficient to qualify a winner.                                                                                                                                 |
+| Additional vision development       | A completed ordinary-Luna photo screen returned no whole-object locations, mostly because of its 45-second operation deadline. The paired Qwen screen stopped on an unsupported route/configuration; those failures are not a measure of Qwen's visual accuracy. Failed and incomplete records remain preserved. Supported routes require separate frozen runs.                     |
+| Text-only images                    | All six encoders remain unqualified and the public experimental selector rejects explicitly.                                                                                                                                                                                                                                                                                        |
+| Blind qualification and publication | The first frozen HELDOUT run completed and failed qualification. A new development method requires a fresh blind cohort. GitHub/npm publication follows qualification, final archive inspection and final CI.                                                                                                                                                                       |
+
+Whole-object location, explicit extraction, optional native adapters and CLI are implemented and integrated. [Snapshot evidence](evidence/v02/integration-8010aad.json) records source commit, actual installed-archive hash and check results. The 254-test snapshot passed source gates and the independent consumer tested the old and new APIs with zero provider HTTP calls. Subsequent diagnostic/corpus integration passed 256 tests; these counts are offline evidence, not model accuracy.
+
+The installed consumer imports core and segmentation entries and compiles declarations without ONNX Runtime. It exercises cutout/mask output with a controlled segmenter and proves caller ownership. The [native CPU smoke](https://github.com/zoomplus/zorya-classifier/blob/main/benchmarks/v02/native-smoke-evidence.md) separately exercised real MobileSAM on five licensed dev photographs with independent instance masks. These are distinct tests.
+
+The configured two-hour Linux CPU resource run completed against the frozen native sources of `8010aad`: ten minutes of warmup followed by two idle windows and the 6,540-second busy phase. Its [numeric report](evidence/v02/resource-soak-linux-8010aad.json) records 4,756 segmented operations, matching child starts/closes and no owned children left. Before/after idle-median growth was approximately 7.4 MiB heap, 11.2 MiB external, 6.2 MiB array buffers and 43.8 MiB RSS, within the plan's thresholds. Sampling was scheduled every five seconds; actual gaps are recorded. Native Windows CPU component acceptance passed against the pinned installed archive: imports/declarations, real inference, cancellation, queue capacity and disposal left zero owned children. The [hardened report](evidence/v02/native-windows-eea1790.json) separates those lifecycle checks from mask quality. These tests use oracle boxes, not end-to-end localization. Live whole-object qualification and the experimental encoder's independent development/heldout gates remain pending. Historical 0.1 results below do not qualify these additions.
+
+Hosted CI for source `32aa90d` passed every Windows/Linux × Node 22/24 job, including a clean installation, source checks, installed archive and formatting. [CI evidence](evidence/v02/ci-32aa90d.json) records the executed run; the final release still needs its own run. The earlier lockfile failure is retained separately. The [paired numeric/axis-ruler diagnostic](evidence/v02/presentation-paired-20261020.json) found no located positive target on the old exposed panel; neither vision presentation is qualified by that pilot.
+
+The subsequent [CI run for `9d00fe5`](evidence/v02/ci-9d00fe5.json) passed all four Windows/Linux × Node 22/24 jobs with 316 offline tests and the installed-archive checks. Earlier platform-path and formatting failures remain preserved. This verifies that source snapshot, not a later untested release or real-provider accuracy.
+
+All six text-image encoders remain research-only. The [fresh independent comparison](evidence/v02/fresh-text/README.md) is complete for photographs and real UI: every encoder has zero correct whole-object matches, and some violate the negative-case gate. None qualifies for heldout promotion. The initial classification harness defect and corrected classification-only follow-ups are preserved separately; they do not overwrite the localization runs. Failed protocol/rate-limit/truncated-generation diagnostics remain recorded. The public experimental image selector rejects explicitly. Historical controlled map/UI renders with model-assisted labels remain an exploratory supplement: their source licensing and split are recorded, but they do not close the independent-ground-truth gate.
+
+Subsequent [whole-object prompt/presentation experiments](evidence/v02/boundary-variants.md) found one correctly bounded Car example after removing the separate seed crop and outlining that seed on the original. Boat still returned unknown; this is development evidence, not qualification. A [controlled real-UI oracle](https://github.com/zoomplus/zorya-classifier/blob/main/benchmarks/v02/corpus/dev-independent-ui/README.md) now independently derives seven button boxes from GTK accessibility allocations and verifies all painted edges in the captured pixels. Its three negatives are scoped to the completely inventoried visible toolbar. It is one controlled source family, not a diverse natural-UI benchmark.
+
+The five-photo native reports also retain a subsequently discovered fixture limitation: the original Hat seed contains zero ground-truth foreground pixels, and the Cat seed center is background. Their historical results are preserved. These invalid or ambiguous grounding prompts must not be interpreted as a clean segmentation-quality comparison; corrected oracle prompts require a separate manifest and report. This does not change the physical lifecycle/resource scope of the original run.
+
+The corrected installed-archive [Windows GrabCut component run](evidence/v02/native-grabcut-windows-4c494a3-run3.json) passed actual inference and lifecycle checks: ten child starts and ten closes, cancellation joined the physical close, three queued operations completed and one exceeded capacity, and the coordinator removed its own temporary directory after worker exit. Its five photo masks all remain below IoU 0.8, so lifecycle acceptance does not qualify mask quality. The first two harness failures are retained alongside the successful run. MobileSAM's oracle-box comparison reaches the threshold on four of five photos; this remains a component intervention, not end-to-end localization.
+
+The [fresh independent 30-case development comparison](evidence/v02/fresh-development.md) is complete for numeric and outlined-axis vision variants: both classify 26/30, but whole-object localization reaches only 0/16 and 1/16 photographs respectively and no UI positives. These results remain unqualified. All provider failures, timeouts, unknowns and unknown charges are included. The new independent Freeciv map oracle is separately documented; its same-coordinate positives do not establish positional diversity. Heldout inputs and labels remain blind until a candidate is frozen.
+
+The optional pixel-mask proposal path is now integrated in source `4c9c09f`, with [353 passing offline tests and an installed consumer](evidence/v02/integration-4c9c09f.json). The consumer compiles declarations and exercises both whole-object and cutout output without ONNX Runtime. A separately pinned native Linux smoke exercises the real CPU proposal adapter, physical cancellation, queue capacity and parent loss. The [native Windows installed-archive run](evidence/v02/native-proposal-windows-4c9c09f-retry1.json) also passes actual public locate/extract, caller ownership and cleanup: eight child starts, eight closes and zero owned children. Its initial checksum-constant harness failure is retained. These synthetic checks establish wiring and lifecycle, not photo accuracy. End-to-end masks will be measured independently of whole-object boxes. The matching hosted CI source/pack steps passed on all four OS/Node jobs; a single test-formatting failure is [preserved](evidence/v02/ci-4c9c09f.json), and final release CI remains mandatory.
+
+## Historical 0.1 executed checks and release gates
 
 | Check                 | Evidence                                                                                                                                                                                                                                                          |
 | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

package/docs/api.md

@@ -1,24 +1,30 @@
 # Public API
 
-`createClassifier({ decision, timeoutMs?, concurrency?, maxQueue?, refinement? })` creates an owned client. Defaults: 45,000ms absolute budget including queue/image work/provider work; two active operations; sixteen waiters. Configured maxima: 120s, four active,32 queued. Input images are at most16MiB and16,777,216 decoded pixels; single PNG/JPEG/WebP only. The adapter accepts prepared PNG/JPEG with sides280..1568 and a32MiB total request cap. Byte inputs are copied before the first await, including Buffer views.
+Spatial localization, whole-object location, extraction, `RefinementPort`, caller-owned segmentation/box-check composition, `objectProposals`, and native segmentation factories are **experimental and unqualified** for general use (TypeScript `@experimental` on the corresponding public types and methods). Closed `classify` and explicitly configured `DecisionPort`/transport adapters remain supported; they do not imply universal model accuracy. Further spatial accuracy experiments are stopped; no strategy is promoted.
+
+`createClassifier({ decision, timeoutMs?, concurrency?, maxQueue?, maxInputBytes?, refinement?, segmentation?, objectProposals? })` creates an owned client. Defaults: 45,000ms absolute budget including queue/image work/provider work; two active operations; sixteen waiters; 64 MiB total admitted input bytes, reserved before copying. Configured maxima: 120s, four active,32 queued,256 MiB admitted input. Input images are at most16MiB and16,777,216 decoded pixels, with source sides at most16,384; single PNG/JPEG/WebP only. The vision adapter accepts prepared PNG/JPEG with sides280..1568 and a32MiB total request cap. Byte inputs are copied before the first await, including Buffer views.
+
+The caller supplies the `DecisionPort`; the library never chooses a model, provider or endpoint. You may inject a port directly or explicitly construct one of the adapters below. Their model/provider values are examples or benchmark recipes, not defaults, and stronger models do not guarantee higher accuracy. Optional segmentation adapters are configured separately and require caller-installed runtime packages and caller-supplied local assets.
+
+The [0.2 guide](v02-usage.md) documents `extract`, mask-derived `locate({ mode: 'whole-object', ... })`, optional native adapters and the reserved experimental representation selector. Default region behavior is unchanged. The primary object flow runs the original region locator, then prompts the caller-configured segmenter on the full oriented source image; the actual mask determines bounds, center and cutout. A closed containment check then sees the full source with the actual mask-derived box and seed anchor. An incomplete box can trigger one optional `SegmentationPort.expand(input, previousMask)` and one final check; missing support or unresolved verification returns `unknown/segmentation-uncertain`. The previous mask is full-source binary-u8. `segmentationBoxCheck` can inject a custom checker; otherwise the same caller-supplied `decision` is reused. `verification.checks` retains each closed decision and `verification.expansion` records the correction path; all decision receipts contribute to localization metadata. This checks box containment separately from pixel-mask quality, without an extent search. Native factories are exported from `zorya-classifier/segmentation`; the caller supplies and disposes the segmenter separately. `objectProposals` and interval-based whole-object location remain optional legacy strategies. The segmentation entry also exports `packBinaryMask`/`unpackBinaryMask` for custom adapters.
 
 `classify({ input, classes, instructions?, signal? })`: input is a string or `{ text?, image? }` with at least one field. Classes are2..255 distinct IDs plus descriptions. IDs match `[a-zA-Z][a-zA-Z0-9_-]*`; descriptions at most300 chars. Text is at most32,000 chars, custom instructions4,000. Define explicit none/other behavior in your classes. With ordinary vision models the result contains `choice` (first ranked ID), `ranking`, `probabilities: null`, `nativeChoice: null`, empty `tied`, and metadata. No rank is converted to a fabricated probability. Optional native integrations instead retain raw probabilities, stable maximum/ties, native choice/confidence and optional quantization annotation. Confidence is never a calibrated spatial guarantee.
 
-`locate({ image, target, exclusions?, roi?, signal? })`: target at most2,000 chars; up to16 exclusions of500 chars. ROI uses integer `left/top/width/height` in EXIF-oriented source pixels. Return coordinates reference that oriented image; metadata names this space and dimensions. Rectangles include left/top and exclude right/bottom. Normalized rectangle fields are divided by image dimensions. Tiny/impossible bounded grids return `unknown/layout-limit`.
+`locate({ image, target, exclusions?, roi?, signal? })` (**experimental**): target at most2,000 chars; up to16 exclusions of500 chars. ROI uses integer `left/top/width/height` in EXIF-oriented source pixels. Return coordinates reference that oriented image; metadata names this space and dimensions. Rectangles include left/top and exclude right/bottom. Normalized rectangle fields are divided by image dimensions. Tiny/impossible bounded grids return `unknown/layout-limit`.
 
-`located` returns a selected grid region, normalized region, third-stage selection evidence and optional refinement. `not-found/absent-in-evaluated-region` is based on the initial independent presence check. A target missing from later shortlisted cells yields `unknown/candidate-union-empty`, not global absence. Ordinary models return present/absent/unknown as an independent categorical predicate. Legacy Noul0.5 abstains; contradictory presence/selection returns unknown. Multiple physical matching objects are permitted; this is an any-instance locator.
+`located` from default region mode returns a selected grid region, normalized region, third-stage selection evidence and optional refinement. `not-found/absent-in-evaluated-region` is based on the initial independent presence check. A target missing from later shortlisted cells yields `unknown/candidate-union-empty`, not global absence. Ordinary models return present/absent/unknown as an independent categorical predicate. Legacy Noul0.5 abstains; contradictory presence/selection returns unknown. Multiple physical matching objects are permitted; this is an any-instance locator. With an explicit `segmentation` port, `locate({ mode: 'whole-object' })` and `extract` use the region seed plus full-source segmentation; reported bounds and center come from the valid mask.
 
 The algorithm searches4×4 coarse cells, keeps four source-distinct maxima, pads each by half a coarse cell within ROI, partitions each into at most49 fine cells (global≤196, side≤256), then compares the four best fine cells as enlarged A–D/none. Edges count as matches. Scores/rank hints are not sent to the final comparison. No cell-center correction is presented as object segmentation.
 
-`RefinementPort.refine({ image, target, region, signal })` is optional trusted code. It receives a private oriented-source byte copy. A returned refined rectangle must fit the source and intersect the selected cell. It does not replace the original area evidence. No built-in heavy refiner is downloaded.
+`RefinementPort.refine({ image, target, region, signal })` (**experimental**) is optional trusted code. It receives a private oriented-source byte copy. A returned refined rectangle must fit the source and intersect the selected cell. It does not replace the original area evidence. No built-in heavy refiner is downloaded.
 
 `dispose()` cancels current/queued work, rejects further calls and waits for physical settlement. Injected ports must honor cancellation. Native image work retains its concurrency slot until completion, even if cancellation has already been requested.
 
 `ClassifierError.code`: INVALID_INPUT, INVALID_RESPONSE, TIMEOUT, ABORTED, CAPACITY, DISPOSED, PROVIDER, AUTHENTICATION, UNSUPPORTED, RESOURCE_LIMIT. Transport failures throw; they are not successful negative classifications. Provider metadata uses null for unknown model/provider/request/cost. Localization adds knownCostUsd and unknownCostCount; knownCostUsd alone is not a complete bill when unknownCostCount>0.
 
-## Native decision models (primary integration)
+## Optional native decision adapter
 
-`createOpenRouterDecisions({ apiKey, model, provider, providerName?, responseModelIds?, probabilityRoundingStep?, fetch?, maxRequestBytes?, maxResponseBytes? })` uses the typed `/api/alpha/decisions` endpoint. The primary documented route is `openai/gpt-6-luna-decisions` / `openai`. Model and provider are required; `provider.only` disables fallback. Compatible native models can be supplied explicitly; vision support and factual quality must be checked per model. Jev is not required.
+`createOpenRouterDecisions({ apiKey, model, provider, providerName?, responseModelIds?, probabilityRoundingStep?, fetch?, maxRequestBytes?, maxResponseBytes? })` uses the typed `/api/alpha/decisions` endpoint. One documented example route is `openai/gpt-6-luna-decisions` / `openai`. Model and provider are required; `provider.only` disables fallback. Compatible native models can be supplied explicitly; vision support and factual quality must be checked per model. Jev is not required. The adapter is opt-in and is never selected by the library on its own.
 
 The adapter sends the exact Choice criteria and independent Noul questions, preserving genuine raw distributions and metadata. Internal chat-only `rankingSize` hints are stripped from the native wire request. Model/provider identity, question correspondence, complete finite probabilities and the categorical maximum are verified. Valid date-stamped model snapshots are accepted. `probabilityRoundingStep` is unset by default: a selected model does not inherit Jev's observed0.01 wire quantization. Set it explicitly only with supporting provider/wire evidence; values are still never normalized.
 

package/docs/architecture.md

@@ -1,20 +1,33 @@
 # Architecture and lifecycle
 
-The public factory composes a DecisionPort and a Sharp-backed RasterPort. 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.
+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 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 LR
   I[Owned input snapshot] --> G[Bounded operation queue]
   G --> C[Classify: closed class ranking]
-  G --> L[Locate: coarse ranking]
-  L --> F[Fine-grid ranking]
-  F --> V[Candidate comparison]
-  V --> R[Source region]
-  R --> O[Optional injected refinement]
+  G --> L[Original region locator: up to three requests]
+  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 -->|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]
+  R -->|complete| X
+  R -->|unresolved / no parent| 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.
 
+The box renderer preserves the full source canvas. The injected raster `imageState` then prepares the whole rendered image for the transport, preserving aspect ratio with explicit scale/padding metadata and prepared sides between 280 and 1568 pixels. This never crops to the selected box and never changes the mask's source-space coordinates. Public-adapter regressions exercise both 64×48 and 1920×1080 inputs; DecisionPort-only fixtures do not exercise transport size validation.
+
 Transport validates complete question/answer correspondence, probabilities, identity and byte limits. Errors omit credentials, provider bodies and raw user media. Raw images exist only for the active operation unless an explicit caller-owned diagnostic wrapper records requests. Scores are not mixed across Choice distributions or interpreted as pixel/pose confidence.
 
 Image handling normalizes EXIF orientation, validates bounded decode, crops in source pixels and prepares PNG presentations with recorded aspect-ratio/padding transforms. Labels map to exact canonical rectangles. Original and clean crops remain available alongside grid overlays. Final candidate pixels are source crops enlarged with integer nearest-neighbor scale.
@@ -23,10 +36,12 @@ Extraction differences from the gaming service: the public result is an area; mu
 
 ESLint catches common promise/race/interval errors and architectural checks reject private imports/cycles. These checks cannot prove native memory safety; tests additionally exercise cancellation, queue overload, late completion, input mutation and repeated lifecycle disposal.
 
+Knip checks the dynamically started native-worker entry. Its dependency allowlist contains only `onnxruntime-node`: Knip 5 flags referenced optional peers, while this package intentionally loads it only inside the explicit MobileSAM worker. The installed-archive check proves that core and segmentation entries import and their declarations compile without ONNX; requesting MobileSAM then fails explicitly. Other dependency/export checks remain enabled.
+
 ## Model and provider independence
 
 `createOpenAICompatibleVision` accepts a trusted direct chat-completions endpoint, model ID, optional key/custom headers, and the same bounded transport policies. `createOpenRouterVision` adds explicit OpenRouter-only routing around that transport. Neither requires a native classifier endpoint. The core knows only `DecisionPort`; a non-OpenAI-compatible SDK can implement that port without changing geometry or lifecycle.
 
 Ordinary language models receive images/text, closed option descriptions and a JSON answer schema. They return ranked IDs and independent categorical presence evidence. These are validated against the exact supplied questions/options; no ranks are converted to fake probabilities. The optional legacy native integration retains probability-valued answers for compatibility and historical benchmarking. A malformed/refused/truncated answer remains an error; it is never silently retried through another backend.
 
-The primary native integration is `createOpenRouterDecisions` with explicit model/provider, initially Luna Decisions. It shares bounded snapshots/HTTP cleanup with the optional Jev wrapper and strips internal rank-count hints from the typed wire request. Native probability checks remain separate from ordinary chat ranking. Jev-specific quantization is never silently applied to another model.
+`createOpenRouterDecisions` is one optional adapter for a caller-chosen native model/provider. Luna Decisions appears in examples and benchmark recipes; it is not a library default. The adapter shares bounded snapshots/HTTP cleanup with the optional Jev wrapper and strips internal rank-count hints from the typed wire request. Native probability checks remain separate from ordinary chat ranking. Jev-specific quantization is never silently applied to another model. Results from one route do not imply that a stronger model will improve every task.

package/docs/benchmarks.md

@@ -12,6 +12,16 @@ Metrics include classification accuracy/macro-F 1/confusion, errors in the denom
 
 Offline fixture tests validate mechanics only. Actual provider outcomes are recorded in [results](results.md), acceptance and the run reports. Keep failed and incomplete runs. Never silently retry errors, alter labels or discard difficult images to improve headline metrics.
 
+## 0.2 checked region and segmentation recipe
+
+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.
+
+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.
+
 ## Current native Luna Decisions reproduction
 
 For an independent fresh run of the selected non-Jev route, fetch the corpus, set your own `OPENROUTER_API_KEY`, then explicitly opt in:

package/docs/categorical-presence-port.md

@@ -0,0 +1,26 @@
+# Caller-owned categorical presence composition
+
+`examples/categorical-presence-port.ts` shows how to wrap an injected public `DecisionPort` for services that answer closed Choice questions. The wrapper sends the original Choice questions and translated presence questions together in one delegate call. The translated classes are `present`, `absent`, and `unknown`; their instructions retain the exact original proposition. Existing scored Choice answers are returned unchanged. For translated questions, a valid probability distribution is reduced to the first maximum in criteria order, while a rank-only answer remains categorical and does not acquire invented scores.
+
+The example is source code in this repository, not an npm subpath export. To adapt it in an application, install the public package and its direct Zod dependency, copy the example source into your project, and inject a `DecisionPort` you have configured:
+
+```sh
+npm install zorya-classifier zod@3.25.76
+```
+
+```ts
+import { createClassifier, type DecisionPort } from 'zorya-classifier'
+import { createCategoricalPresencePort } from './categorical-presence-port.js'
+
+declare const configuredDecision: DecisionPort // supplied by your application
+
+const classifier = createClassifier({
+  decision: createCategoricalPresencePort(configuredDecision),
+  timeoutMs: 120_000, // benchmark recipe limit; production callers should choose their own deadline
+})
+// After your operations finish, await classifier.dispose().
+```
+
+The caller owns the wrapped port and its delegate. Inject the returned port into `createClassifier({ decision: ... })`; choose and configure the actual service outside this example. The wrapper snapshots the request before awaiting, validates closed IDs and answer shape, passes through the caller's `AbortSignal`, and fails if cancellation arrives during the delegate call. To preserve auditability, record the delegate's raw response at the transport boundary before this wrapper converts it.
+
+This composition mirrors the categorical protocol selected in development. That profile still requires independent blind qualification; neither the source example nor fixture tests qualify a model or make this a default SDK behavior. The 120-second timeout is the benchmark recipe, not a recommended universal production setting. The offline tests exercise only local fixtures; they make no provider or native calls.