zorya-classifier 0.2.1 → 0.2.3

package/docs/README.ru.md

@@ -1,42 +1,56 @@
 # Zorya Classifier: руководство
 
-Версия 0.2 добавляет прозрачный PNG, бинарную маску, её рамку и центр. Прежний поиск области служит подсказкой для сегментации всего исходного изображения. Затем decision проверяет рамку; допускаются одно расширение маски и повторная проверка. [Руководство](v02-usage.md) описывает API, CLI и владение ресурсами.
+> **В этом пилоте H8a дал более полные рамки без дообучения: 7/9 против 3/9 у встроенного Jev 1.14**
+>
+> Это один открытый пилот DEV12: 12 задач на 9 исходных изображениях (четыре цели интерфейса используют один скриншот), 9 задач с объектом и 3 без. Сравниваются исторический результат H8a и один новый прогон Jev. Конвейер сегментации формирует маски-кандидаты, а явно настроенная модель OpenAI **gpt-6-luna** выбирает одну из них; рамка строится по пикселям выбранной маски. Дополнительного обучения для этого сравнения не было. Встроенный Jev 1.14 использует Box+Noul и возвращает рамку, а не маску. Для строгого зачёта одна и та же рамка-кандидат должна иметь IoU ≥0,5 с рамкой эталонного объекта и покрывать не менее 90% этой эталонной рамки. Это не проверка на отложенной выборке и не квалификация точности.
+>
+> | Показатель                                               | H8a              | Jev 1.14      |
+> | -------------------------------------------------------- | ---------------- | ------------- |
+> | Строгий критерий рамки                                   | 7/9              | 3/9           |
+> | IoU ≥0,5 без проверки покрытия (вспомогательная метрика) | 7/9              | 8/9           |
+> | Ложные обнаружения, когда объекта нет (меньше — лучше)   | 2/3 (Bowl, Undo) | 1/3 (Fighter) |
+>
+> [Полный отчёт](https://github.com/zoomplus/zorya-classifier/blob/v0.2.3/docs/research/v03-jev-native-box-results.ru.md) · [JSON-доказательная база](https://github.com/zoomplus/zorya-classifier/blob/v0.2.3/docs/evidence/v03/jev-native-box-dev12-20261025.json) · [Скачать визуальное сравнение ZIP](https://github.com/zoomplus/zorya-classifier/releases/download/v0.2.3/jev-native-box-dev12-comparison.zip)
+>
+> H8a здесь — только исследовательский рецепт: он не является стандартным путём `locate`/`extract` и не поставляется в npm как стратегия H8. Эти результаты не доказывают общую точность.
+
+Версия 0.2 добавляет прозрачный PNG, бинарную маску, её рамку и центр. Прежний поиск области служит подсказкой для сегментации всего исходного изображения. Затем порт решений проверяет рамку; допускаются одно расширение маски и повторная проверка. [Руководство](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`.
+Сравнение шести способов передачи изображения текстом завершено на свежих фотографиях и реальном интерфейсе: ни один не прошёл требования локализации. [Результаты и ограничения](evidence/v02/fresh-text/README.md) сохранены; публичный селектор IMAGE-AS-TEXT удалён — запросы с ним отклоняются на этапе валидации (`INVALID_INPUT`). Кодеки остаются только в `benchmarks/experiments/`.
 
-Zorya Classifier — библиотека для Node.js и TypeScript с поддерживаемой классификацией по тексту и изображениям и экспериментальной, не квалифицированной для общего применения пространственной локализацией и извлечением объектов. Библиотека не выбирает и не подключает модель за приложение: клиент получает явно переданный `DecisionPort` — готовый адаптер с выбранными настройками или собственную реализацию. Модель и провайдер в примерах — лишь варианты интеграции, не значения по умолчанию. Код распространяется по MIT; веса модели в поставку не входят, запросы удалённых моделей оплачиваются отдельно; можно подключить и свой локальный сервер. Совместимость и качество зависят от выбранного маршрута. Более мощная модель может помочь, но улучшение точности не гарантировано. Проверенные комбинации и результаты перечислены в [таблице моделей](vision-results.md).
+Zorya Classifier — библиотека для Node.js и TypeScript с поддерживаемой классификацией по тексту и изображениям и реализованными API пространственной локализации и извлечения объектов (модель, провайдер и нативные ресурсы — на стороне вызывающего). Библиотека не выбирает и не подключает модель за приложение: клиент получает явно переданный `DecisionPort` — готовый адаптер с выбранными настройками или собственную реализацию. Модель и провайдер в примерах — лишь варианты интеграции, не значения по умолчанию. Код распространяется по MIT; веса модели в поставку не входят, запросы удалённых моделей оплачиваются отдельно; можно подключить и свой локальный сервер. Совместимость и качество зависят от выбранного маршрута. Более мощная модель может помочь, но улучшение точности не гарантировано. Проверенные комбинации и результаты перечислены в [таблице моделей](vision-results.md).
 
 Это самостоятельная библиотека: ей не нужны Zorya Games, Electron, база данных или игровой процесс. Её можно встроить в сервер, бота, инструмент обработки фотографий или собственный HTTP-сервис. Готовый постоянно работающий HTTP-сервер в пакет не входит.
 
 ## Статус возможностей
 
-Дальнейшие эксперименты по точности пространственных сценариев остановлены; ни одна стратегия локализации, извлечения или предложений масок не продвигается для общего использования. Исторические метрики в `docs/evidence/**` сохранены без переинтерпретации.
+Пространственные API реализованы и документированы; сравнение рамок [H8a vs Jev на DEV12](https://github.com/zoomplus/zorya-classifier/blob/v0.2.3/docs/research/v03-jev-native-box-results.ru.md) — один исследовательский рецепт, не default библиотеки. Исторические метрики в `docs/evidence/**` сохранены без переинтерпретации. Сквозной ordinary-vision профиль H8a на DEV12 также описан в [базовом отчёте](https://github.com/zoomplus/zorya-classifier/blob/v0.2.3/docs/research/v03-h8a-development-baseline.ru.md).
 
-| Возможность                                   | Статус           | Примечание                                                                     |
-| --------------------------------------------- | ---------------- | ------------------------------------------------------------------------------ |
-| `classify` с явным `DecisionPort`             | Поддерживается   | Один закрытый ID класса; без заявления об универсальной точности модели        |
-| `locate` (сетка регионов)                     | Экспериментально | Гипотеза по ячейке, не геометрия целого объекта и не доказательство отсутствия |
-| `RefinementPort`                              | Экспериментально | Без общей квалификации качества                                                |
-| `locate({ mode: 'whole-object' })`            | Экспериментально | Интервалы или сегментация вызывающего; без квалификации                        |
-| `extract`, `SegmentationPort`, проверка рамки | Экспериментально | Структурный успех ≠ семантическая точность маски                               |
-| `objectProposals`, нативные фабрики           | Экспериментально | На стороне вызывающего; без квалификации                                       |
-| `experimental-text`                           | Отклонено        | `UNSUPPORTED`, пока профиль не пройдёт отбор                                   |
+| Возможность                                   | Статус         | Примечание                                                                     |
+| --------------------------------------------- | -------------- | ------------------------------------------------------------------------------ |
+| `classify` с явным `DecisionPort`             | Поддерживается | Один закрытый ID класса; без заявления об универсальной точности модели        |
+| `locate` (сетка регионов)                     | Доступно       | Гипотеза по ячейке, не геометрия целого объекта и не доказательство отсутствия |
+| `RefinementPort`                              | Доступно       | Опциональный legacy-хук на стороне вызывающего                                 |
+| `locate({ mode: 'whole-object' })`            | Доступно       | Интервалы или сегментация вызывающего                                          |
+| `extract`, `SegmentationPort`, проверка рамки | Доступно       | Структурный успех ≠ семантическая точность маски                               |
+| `objectProposals`, нативные фабрики           | Доступно       | На стороне вызывающего; ресурсы модели/runtime не поставляются библиотекой     |
+| `experimental-text`                           | Удалено из API | `INVALID_INPUT`; исследовательские кодеки только в benchmarks                  |
 
 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`                            | Ячейка в координатах исходного изображения либо явная неопределённость/отсутствие |
-| Получить маску, рамку, центр и прозрачный вырез предмета   | Экспериментально | `extract` с явным сегментатором     | Геометрия и вырез, выведенные из пикселей маски                                   |
+| Задача                                                     | Статус         | API                                 | Результат                                                                         |
+| ---------------------------------------------------------- | -------------- | ----------------------------------- | --------------------------------------------------------------------------------- |
+| Распределить обращения по отделам, определить намерение    | Поддерживается | `classify` с текстом                | Один из заданных классов и ранжирование вариантов                                 |
+| Проверить наличие объекта или выбрать категорию фотографии | Поддерживается | `classify` с изображением           | Один из заданных классов                                                          |
+| Оценить изображение с текстовым условием                   | Поддерживается | `classify` с текстом и изображением | Класс с учётом обоих входов                                                       |
+| Найти примерную область предмета, значка или указателя     | Доступно       | `locate`                            | Ячейка в координатах исходного изображения либо явная неопределённость/отсутствие |
+| Получить маску, рамку, центр и прозрачный вырез предмета   | Доступно       | `extract` с явным сегментатором     | Геометрия и вырез, выведенные из пикселей маски                                   |
 
-Для `extract` после сегментации модель получает исходную картинку с рамкой маски и отметкой прежней найденной области. Она выбирает один ответ: весь видимый объект внутри, нужно расширение или определить не удалось. При необходимости сегментатор один раз ищет внешнюю маску, содержащую прежние пиксели; её рамка проверяется повторно. Максимум получается пять модельных запросов: три на поиск области и два на проверку. Если подтверждения нет, библиотека возвращает неопределённость без частичного выреза. `verification` сохраняет проверки и результат расширения. Рамка и центр всегда вычисляются из маски; проверка рамки не гарантирует точности каждого пикселя. Своя модель подключается через `DecisionPort`, отдельная проверка — через `segmentationBoxCheck`.
+Для `extract` после сегментации порт решений получает полный исходник с рамкой из маски и исходной подсказкой `seed`. Ответ закрыт: `complete` (можно вернуть результат и опциональный вырез), `needs-expansion` (не более одного расширения охватывающей маски и одной финальной проверки; повторный `complete` после финальной проверки тоже допускает результат) или `unknown` (неразрешённая проверка, нет поддержки расширения, нет действительной охватывающей маски или провал финальной проверки — второго расширения нет). Внутри одного `extract` со встроенным `locate` — до трёх запросов на поиск области и до двух закрытых проверок рамки. Без подтверждения библиотека возвращает неопределённость и не публикует частичный вырез. Рамка и центр только из пикселей маски; успешная проверка рамки не доказывает идеальную сегментацию по пикселям. Порт решений подключается через `DecisionPort`; сегментатор остаётся на стороне вызывающего.
 
 Сконфигурированный `DecisionPort` выполняет запросы по контракту библиотеки. `classify` делает один запрос, а `locate` — до трёх последовательных запросов: крупная сетка → уточнение в четырёх выбранных областях → сравнение четырёх увеличенных кандидатов. Проверки присутствия входят в те же запросы. Порт отвечает за ответы, координаты вычисляет код.
 
@@ -44,7 +58,7 @@ Heldout region-seeded (один задокументированный реце
 
 ## Установка и ключ
 
-Нужен Node.js 22.12 или новее. Windows и Linux проверены; macOS отдельно не проверялась. Зависимости исполнения — Zod и Sharp, включая подходящий платформе нативный модуль Sharp.
+Нужен Node.js 22.12 или новее. Сводка измеренных контрольных точек рефакторинга (Linux Node 22/24, Windows, интерпретатор Python) и статус волн 1–9 — в [плане рефакторинга](refactoring-plan.ru.md); здесь не дублируется. Зависимости среды выполнения — Zod и Sharp, включая платформенный нативный модуль Sharp.
 
 Исходники: [zoomplus/zorya-classifier](https://github.com/zoomplus/zorya-classifier). Пакет: [zorya-classifier в npm](https://www.npmjs.com/package/zorya-classifier). Установка из реестра:
 
@@ -52,7 +66,7 @@ Heldout region-seeded (один задокументированный реце
 npm install zorya-classifier
 ```
 
-Для локального/релизного архива также работает `npm install ./zorya-classifier-0.1.0.tgz`.
+Для локального/релизного архива также работает `npm install ./zorya-classifier-0.2.3.tgz` (имя архива соответствует версии в `package.json`).
 
 Скопируйте пример конфигурации в локальный `.env` и заполните значение `OPENROUTER_API_KEY` своим ключом. В репозитории `.env` исключён из Git; в своём проекте тоже добавьте это исключение. Не помещайте ключ в браузерный React-код, приложение клиента или публичный репозиторий. Вызовы модели выполняйте на доверенном сервере.
 
@@ -127,9 +141,9 @@ const result = await client.classify({
 
 Для одной картинки поле `text` можно опустить. Принимаются `Uint8Array` и `Buffer` с одним PNG/JPEG/WebP: до 16 MiB и 16 777 216 декодированных пикселей. Ссылки на изображения публичный API не загружает — скачивание, права доступа и ограничения внешних URL остаются у вызывающего приложения.
 
-## Поиск объекта и координаты (экспериментально)
+## Поиск объекта и координаты
 
-Обычный `locate` экспериментален и не квалифицирован для общего применения. Также внутри `try`:
+Локализация и обычный `locate` доступны в публичном API. Региональный `locate` по умолчанию возвращает гипотетическую ячейку сетки, а не точную рамку объекта, маску, центр, доказательство отсутствия или универсальную точность. Пример внутри `try`:
 
 ```js
 const result = await client.locate({
@@ -158,9 +172,9 @@ if (result.status === 'located') {
 | `unknown`                    | Неуверенность, противоречие, отсутствие цели среди кандидатов или невозможная сетка | Уточнить цель, взять более подходящее изображение или вернуть пользователю неопределённость |
 | Исключение `ClassifierError` | Ошибка входа, сети, протокола, бюджета или жизненного цикла                         | Обработать код ошибки; не показывать её как отсутствие объекта                              |
 
-Если нужны маска, рамка или центр объекта, используйте `extract` с явно созданным сегментатором. Обычный `locate` сначала находит регион-кандидат; затем сегментатор получает seed-подсказку на всём ориентированном исходном изображении. Рамка и центр вычисляются по реальным пикселям маски, без отдельного поиска границ или подтверждения рамки языковой моделью. Пример и детали владения ресурсами приведены в [руководстве 0.2](v02-usage.md). Это технический путь обработки, а не гарантия точности на всех фото.
+Если нужны маска, рамка или центр объекта, используйте `extract` с явно созданным сегментатором. Обычный `locate` сначала находит регион-кандидат; затем сегментатор получает подсказку `seed` на всём ориентированном исходном изображении. Рамка и центр вычисляются по реальным пикселям маски. После сегментации **текущий** основной поток выполняет до **двух** закрытых проверок рамки на полном исходнике (`complete` / `needs-expansion` / `unknown`) через `DecisionPort`, с не более чем одним расширением маски и финальной проверкой; обрезка, масштаб и поля вокруг изображения сохраняют соответствие исходника и маски, а подготовка вида для проверки идёт через `RasterPort.imageState` на полном холсте. Пример и владение ресурсами — [руководство 0.2](v02-usage.md), [architecture.ru.md](architecture.ru.md). Это технический путь, а не гарантия точности на всех фото.
 
-В проверенном сценарии v2 приложение сначала вызывает `classify` для наличия цели и запускает `extract` только после ответа `present`. Это явная композиция приложения: один запрос классификации плюс до трёх запросов поиска. Сам `extract` дополнительную классификацию не вставляет. Ошибку классификации нельзя выдавать за отсутствие цели; обе операции должны использовать общий сигнал отмены и абсолютный срок выполнения.
+В типичной композиции приложение сначала вызывает `classify` для наличия цели и запускает `extract` только после ответа `present`. Это **явная** композиция: **1** запрос классификации + до **3** запросов `locate` + до **2** запросов проверки рамки внутри `extract` — **до 6** запросов порта решений суммарно. Сам `extract` отдельную классификацию не подставляет. Ошибку классификации нельзя выдавать за отсутствие цели. Вызывающий **может** передать один `AbortSignal` или общий предельный срок на **несколько** вызовов в своём сценарии, но библиотека держит **один абсолютный предельный срок на каждую отдельную операцию**, включая ожидание в очереди; **два** отдельных вызова **не** делят один предельный срок автоматически.
 
 Встроенный MobileSAM получает точку в центре найденной области и обрабатывает весь исходник; текст названия предмета он не понимает. Поэтому иногда он выделяет деталь, например фару вместо автомобиля. Успешный `extracted` подтверждает корректность маски и файлов, а точность распознавания оценивается отдельно. На полном DEV40 для v2 было 18/30 попаданий области в рамку цели, 5/30 совпадений рамки маски и 0 ложных вырезок на 10 отрицательных примерах. Это разные метрики. [Независимый отчёт](evidence/v02/region-seeded-dev-v2/README.md) сохраняет ошибки и ограничения; другой сегментатор подключается через тот же `SegmentationPort`.
 
@@ -168,7 +182,7 @@ if (result.status === 'located') {
 
 Переиспользуйте один `client` на жизненный цикл сервиса. По умолчанию одновременно выполняются две операции, в очереди допускается 16, общий тайм-аут — 45 секунд, включая ожидание очереди и обработку картинки. Параметры можно задать в `createClassifier`; максимумы — 4 операции, 32 ожидающих и 120 секунд. При переполнении возвращается `CAPACITY`, вместо неограниченного накопления задач.
 
-Для отмены передайте `signal`. Например, этот вызов завершается не позднее тайм-аута сигнала с учётом физического освобождения нативных ресурсов:
+Для отмены передайте `signal`. Операция перестаёт принимать результат после отмены или тайм-аута, но **может** удерживать слот и завершать физическую работу (HTTP, Sharp, принадлежащий нативный дочерний процесс) до фактического завершения — момент возврата из вызова по календарному времени **не** обещает мгновенного освобождения всех нативных ресурсов. Пример:
 
 ```js
 const result = await client.classify({
@@ -252,7 +266,7 @@ const client = createClassifier({ decision })
 
 [Таблица проверенных моделей](vision-results.md) содержит названия, провайдеров, число примеров, ошибки, точность, задержки и цену. Там отдельно указаны полноценная проверка на корпусе, короткий screening и тесты адаптера с искусственным сервером. Необозначенная модель не считается автоматически проверенной.
 
-Исторический Jev-прогон дал 55/60 на фото и 30/30 на авторских текстовых примерах. Это baseline прежнего адаптера, а не доказательство качества или превосходства другой модели. Результаты не позволяют предполагать, что более мощная модель обязательно повысит точность. Подробности и исходные ошибки сохранены в [исторических результатах](results.md). Локализация остаётся экспериментальной; ячейка не является точной маской или центром объекта.
+Исторический Jev-прогон дал 55/60 на фото и 30/30 на авторских текстовых примерах. Это исходный эталон прежнего адаптера, а не доказательство качества или превосходства другой модели. Результаты не позволяют предполагать, что более мощная модель обязательно повысит точность. Подробности и исходные ошибки сохранены в [исторических результатах](results.md). Локализация доступна; выбранная ячейка не является точной маской, центром объекта, сегментацией или гарантией универсальной точности карты.
 
 ## Разработка и следующие документы
 
@@ -264,11 +278,14 @@ npm run pack:check
 npm run format:check
 ```
 
-`check` включает секреты, TypeScript, ESLint, границы слоёв, неиспользуемый код, тесты и сборку. Husky проверяет добавленные в Git версии файлов. `pack:check` устанавливает архив в независимый проект, проверяет его файлы и API. Эти проверки не вызывают реальную модель.
+`check` включает секреты, TypeScript, ESLint, границы слоёв, неиспользуемый код, тесты и сборку. Husky проверяет добавленные в Git версии файлов. `pack:check` устанавливает архив в независимый проект-потребитель, проверяет его файлы и API. Эти проверки не вызывают реальную модель.
 
 - [Полный контракт API](api.md): типы, лимиты, формат метаданных, округление баллов.
-- [Архитектура](architecture.md): слои, порты, отмена и владение ресурсами.
+- [Архитектура](architecture.md) / [architecture.ru.md](architecture.ru.md): слои, порты, согласованность координат изображения и маски, жизненный цикл.
+- [Разработка](development.ru.md): установка, каталог тестов (`H5`, `H10` и группа `local-evidence`), секреты, архив пакета.
+- [Агенты и Composer](agents.ru.md): роли главного оркестратора, координатора и исполнителя Composer; видимость волн рефакторинга.
+- [План рефакторинга](refactoring-plan.ru.md): волны 1–9 и платформенные журналы/отчёты.
 - [Эксплуатация](operations.md): интеграция в сервис, расходы и завершение работы.
-- [Воспроизведение benchmark](benchmarks.md): лицензированные фотографии и отдельный запуск платных проверок.
+- [Воспроизведение каталога `benchmarks`](benchmarks.md): лицензированные фотографии и отдельный запуск платных проверок.
 - [Безопасность](https://github.com/zoomplus/zorya-classifier/blob/main/SECURITY.md): ключи, Git, npm-архивы и ограничения сканирования.
-- [Подготовка публикации](publishing.md): GitHub/npm и необходимая авторизация владельца.
+- [Подготовка публикации](publishing.md): реестры `GitHub` и `npm` и необходимая авторизация владельца.

package/docs/acceptance.md

@@ -1,6 +1,8 @@
 # Acceptance: standalone library
 
-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.
+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 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 implemented public APIs. A region cell is a search hypothesis, not a whole-object box; box checks and pixel-mask quality are separate measurements. One exposed DEV12 pilot compared historical H8a output with a single native Jev 1.14 run: H8a passed the strict same-instance box criterion on 7/9 positive tasks, Jev on 3/9. This is a research result, not a default `locate`/`extract` strategy or a general accuracy claim. See the [full comparison](research/v03-jev-native-box-results.ru.md) and [evidence](evidence/v03/jev-native-box-dev12-20261025.json). Jev remains optional historical compatibility.
 
 ## Current 0.2 acceptance
 
@@ -75,7 +77,7 @@ A separate [reconstructed C03 diagnostic](evidence/v02/reconstructed-c03-box.jso
 | 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`                      |
+| Text-only encoders                   | None qualified; public experimental image selector removed (`INVALID_INPUT` on strict parse)  |
 | Publication                          | Pending all mandatory gates                                                                   |
 
 ## 0.2 development snapshot, 2026-10-20
@@ -103,7 +105,7 @@ Hosted CI for source `32aa90d` passed every Windows/Linux × Node 22/24 job, inc
 
 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.
+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 was removed; strict input validation rejects it with `INVALID_INPUT`. 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.
 
@@ -135,7 +137,7 @@ Historical native Windows/source and secret-scan receipts remain under docs/evid
 
 Luna Decisions matches the historical Jev photo/text counts on this corpus; this is not proof of statistical non-inferiority, calibration or universal superiority. Two disjoint native sessions cover the full90 classification cases without replay or prompt changes. Public photographs may overlap training; text cases are authored fixtures, not customer traffic. No independent annotation/duplicate audit was performed.
 
-Localization is experimental. The first native smoke failed at its195-option/nine-image fine request; an explicit replay returned HTTP502 with provider refusal. The original error and diagnostic remain preserved. A separate fixed flower-image smoke completed all three native stages in4.75s; its reviewed receipt is in docs/evidence, and it does not replace a full localization evaluation. A selected cell is not segmentation, an exact object center, tracking or a universal map/minimap guarantee. Offline fixtures are not real-model quality evidence.
+Region `locate` is an implemented public API. By default it returns a hypothesized grid cell, not an exact object box, mask, center or proof of absence. It makes no universal accuracy guarantee. This section also records an older native-model smoke: its first attempt failed on a fine-grained request with 195 options and nine images; a separate replay returned HTTP 502 with a provider refusal. The original error and diagnostic remain preserved. A fixed flower-image smoke completed all three native stages in 4.75 seconds, but it is not a full localization evaluation and does not qualify general `locate` quality. A selected cell is not segmentation, an exact object center, tracking or a universal map/minimap guarantee. Offline fixtures are not real-model quality evidence.
 
 Paid comparison accounting is separate from the historical337-call Jev work. The owner expanded the comparison limit to1000 calls while retaining the$0.50 ceiling. Reported costs are reconciled only from retained numeric receipts; failed classifications remain failures, unknown charges retain conservative reservations. Local admission accounting is not a provider-side account cap or a verified invoice. The comparison finished at332 calls, known cost$0.03456876 and four unknown costs; conservative accounted exposure is$0.23456876. Exact receipts are in the model evidence/release manifest.
 

package/docs/agents.ru.md

@@ -0,0 +1,97 @@
+# Правила для агентов (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 по запросу; **не** для внутреннего рефакторинга и документации репозитория         |
+| `text-authorship.mdc` (`/root/.cursor/rules/text-authorship.mdc`)               | Постоянный пользовательский текст пишет `gpt-6-luna` / `high` / `fork_turns=none`, если владелец явно не разрешил иное |
+
+**Координатор** **включает** применимые пункты глобальных правил и [контракт участников](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, а прозу — автору Luna согласно отдельному правилу                   |
+| **Автор текста Luna**    | **`gpt-6-luna`**, рассуждение **`high`**, **`fork_turns=none`**                                            | Пишет пользовательский и постоянный текст: документацию, описания, сообщения CLI/интерфейса и прозу в комментариях. Может править только текст; не меняет исполняемую логику, тесты или конфигурацию времени выполнения. В смешанной задаче передаёт точную формулировку Composer |
+| **Координатор**          | **`gpt-6-luna`**, рассуждение **`high`**, **`fork_turns=none`** (иначе — только явная инструкция человека) | Владелец **каждого** процесса Cursor CLI; предварительная проверка CLI перед первым запуском; постановка задач Composer; проверка фактических изменений и журналов; передача владения — только явно                                                                               |
+| **Исполнитель Composer** | **`composer-2.5-fast`**                                                                                    | Выполняет технические изменения в исходниках, тестах и конфигурации; в смешанной задаче вставляет предоставленный Luna текст без переписывания. **Не** запускает `cursor-agent`, не делегирует и не запускает вложенных агентов                                                   |
+
+**Каждый** подагент Codex любой роли (включая координацию, автора текста и явно запрошенные исследование или проверку изменений) порождается как **`gpt-6-luna` / `high` / `fork_turns=none`**, если человек не указал иное. Владелец уже дал постоянное разрешение на такую роль, поэтому не нужно спрашивать отдельно для каждой задачи. Если главный оркестратор сам работает на Luna, он может написать текст напрямую; не нужно менять выбранную человеком модель или создавать дублирующую роль.
+
+Отдельные подагенты для исследования или проверки изменений — **только по явному запросу** человека и остаются **только для чтения**. Иначе исследование и проверку изменений выполняет главный оркестратор.
+
+Координатор **не обязан** работать в том же 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; публичный селектор IMAGE-AS-TEXT удалён (`INVALID_INPUT`); benchmark-only композиция через `createResearchClassifier`.
+
+## Тесты
+
+| Набор                   | Команда                                                                                                    |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Переносимый каталог     | `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/api.md

@@ -1,22 +1,22 @@
 # Public API
 
-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.
+Spatial localization, whole-object location, extraction, `RefinementPort`, caller-owned segmentation/box-check composition, `objectProposals`, and native segmentation factories are implemented public APIs. Grid cells from default `locate` are not whole-object boxes; mask-derived geometry and box-check verdicts measure different things; model, provider and native assets remain caller-supplied. Closed `classify` and explicitly configured `DecisionPort`/transport adapters remain supported; they do not imply universal model accuracy. The [H8a vs Jev DEV12 box comparison](research/v03-jev-native-box-results.ru.md) is a research recipe, not a library default.
 
 `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.
+The [0.2 guide](v02-usage.md) documents `extract`, mask-derived `locate({ mode: 'whole-object', ... })`, optional native adapters and public `representation: { type: 'vision' }` compatibility. The former experimental text-image selector was removed from public input. 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? })` (**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`.
+`locate({ image, target, exclusions?, roi?, signal? })` (available): 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` 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 })` (**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.
+`RefinementPort.refine({ image, target, region, signal })` (available) 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.
 

package/docs/architecture.md

@@ -1,12 +1,36 @@
 # Architecture and lifecycle
 
-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.
+Russian guide with layer map, SOLID notes and current paths: [architecture.ru.md](architecture.ru.md). Development onboarding: [development.ru.md](development.ru.md).
 
-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.
+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 implemented public APIs (grid cells ≠ whole-object boxes; masks and box checks differ). Evidence under `docs/evidence/**` remains historical; the DEV12 H8a vs Jev box comparison is documented separately as research, not a shipped default strategy.
+
+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.
+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; the former experimental text-image selector was removed from public input (strict `INVALID_INPUT`). Research encoders remain benchmark-only.
+
+```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
@@ -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.