zorya-classifier 0.0.0-stage → 0.1.0

package/dist/shared/scope.js

@@ -0,0 +1,29 @@
+import { ClassifierError, assertActive } from '../entities/errors.js';
+export class OperationScope {
+    parent;
+    controller = new AbortController();
+    signal = this.controller.signal;
+    startedAt = performance.now();
+    timer;
+    onAbort;
+    constructor(timeoutMs, parent) {
+        this.parent = parent;
+        this.onAbort = () => this.controller.abort(new ClassifierError('ABORTED', 'Operation cancelled'));
+        if (parent?.aborted)
+            this.onAbort();
+        else
+            parent?.addEventListener('abort', this.onAbort, { once: true });
+        this.timer = setTimeout(() => this.controller.abort(new ClassifierError('TIMEOUT', 'Operation deadline exceeded')), timeoutMs);
+        this.timer.unref();
+    }
+    guard() {
+        assertActive(this.signal);
+    }
+    abort() {
+        this.onAbort();
+    }
+    dispose() {
+        clearTimeout(this.timer);
+        this.parent?.removeEventListener('abort', this.onAbort);
+    }
+}

package/docs/README.ru.md

@@ -0,0 +1,245 @@
+# Zorya Classifier: руководство
+
+Zorya Classifier — библиотека для Node.js и TypeScript, которая помогает приложению принимать решения по тексту и изображениям. Вы задаёте допустимые классы или описываете искомый объект, библиотека передаёт их выбранной модели решений или языковой модели и проверяет структурированный ответ. Основной вариант — decision-модель, в примерах Luna Decisions. Обычные vision-модели без нативной классификации тоже поддерживаются через чат-адаптер. Код распространяется по MIT; веса модели в поставку не входят, запросы удалённых моделей оплачиваются отдельно; можно подключить и свой локальный сервер. Любая vision-модель, которая понимает изображения и выполняет контракт ответа, может использоваться через готовый OpenAI-совместимый адаптер или собственный `DecisionPort`. Точная проверенная совместимость и результаты перечислены в [таблице моделей](vision-results.md).
+
+Это самостоятельная библиотека: ей не нужны Zorya Games, Electron, база данных или игровой процесс. Её можно встроить в сервер, бота, инструмент обработки фотографий или собственный HTTP-сервис. Готовый постоянно работающий HTTP-сервер в пакет не входит.
+
+## Что умеет
+
+| Задача                                                     | API                                 | Результат                                                                         |
+| ---------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------- |
+| Распределить обращения по отделам, определить намерение    | `classify` с текстом                | Один из заданных классов и ранжирование вариантов                                 |
+| Проверить наличие объекта или выбрать категорию фотографии | `classify` с изображением           | Один из заданных классов                                                          |
+| Оценить изображение с текстовым условием                   | `classify` с текстом и изображением | Класс с учётом обоих входов                                                       |
+| Найти примерную область предмета, значка или указателя     | `locate`                            | Ячейка в координатах исходного изображения либо явная неопределённость/отсутствие |
+
+`classify` делает один запрос к выбранному API модели. `locate` делает до трёх последовательных запросов: крупная сетка → уточнение в четырёх выбранных областях → сравнение четырёх увеличенных кандидатов. Проверки присутствия входят в те же запросы. Модель выбирает варианты, а координаты вычисляет код.
+
+Библиотека не генерирует описание сцены и не ищет все экземпляры предмета: если подходящих объектов несколько, `locate` возвращает один кандидат. Выбранная ячейка может содержать только часть объекта; это не маска сегментации, не точная рамка и не доказанный центр. Дополнительный алгоритм уточнения можно подключить через `RefinementPort`.
+
+## Установка и ключ
+
+Нужен Node.js 22.12 или новее. Windows и Linux проверены; macOS отдельно не проверялась. Зависимости исполнения — Zod и Sharp, включая подходящий платформе нативный модуль Sharp.
+
+Исходники: [zoomplus/zorya-classifier](https://github.com/zoomplus/zorya-classifier). Пакет: [zorya-classifier в npm](https://www.npmjs.com/package/zorya-classifier). Установка из реестра:
+
+```sh
+npm install zorya-classifier
+```
+
+Для локального/релизного архива также работает `npm install ./zorya-classifier-0.1.0.tgz`.
+
+Скопируйте пример конфигурации в локальный `.env` и заполните значение `OPENROUTER_API_KEY` своим ключом. В репозитории `.env` исключён из Git; в своём проекте тоже добавьте это исключение. Не помещайте ключ в браузерный React-код, приложение клиента или публичный репозиторий. Вызовы модели выполняйте на доверенном сервере.
+
+Создайте `example.mjs` и запустите:
+
+```sh
+node --env-file=.env example.mjs
+```
+
+Эта команда работает и в PowerShell, и в Linux shell. Вместо файла можно передать переменную окружения средствами вашего сервера/менеджера секретов. Библиотека сама `.env` не читает; флаг обрабатывает Node.js. Ключ требуется только реальному адаптеру; обычные тесты работают без него.
+
+## Первый пример: классификация текста
+
+Полный файл `example.mjs`:
+
+```js
+import { createClassifier } from 'zorya-classifier'
+import { createOpenRouterDecisions } from 'zorya-classifier/openrouter'
+
+const apiKey = process.env.OPENROUTER_API_KEY
+if (!apiKey) throw new Error('Заполните OPENROUTER_API_KEY')
+
+const client = createClassifier({
+  decision: createOpenRouterDecisions({
+    apiKey,
+    model: 'openai/gpt-6-luna-decisions',
+    provider: 'openai',
+  }),
+})
+
+try {
+  const result = await client.classify({
+    input: 'Заказ ещё не приехал. Где посмотреть доставку?',
+    classes: [
+      { id: 'delivery', description: 'Вопрос о доставке или отслеживании заказа' },
+      { id: 'refund', description: 'Просьба вернуть деньги или товар' },
+      { id: 'other', description: 'Любое другое обращение, не относящееся к доставке и возврату' },
+    ],
+  })
+  console.log(result.choice)
+  console.log(result.probabilities)
+  console.log(result.metadata)
+} finally {
+  await client.dispose()
+}
+```
+
+Передавайте от 2 до 255 классов с уникальными `id`. Описывайте различия между ними явно. Если ни один предметный класс может не подойти, добавьте `other` или `none` с точным условием выбора: скрытого универсального класса «не знаю» здесь нет.
+
+`choice` — выбранный класс. В основном native-режиме возвращается настоящее распределение `probabilities` провайдера: выбирается максимум, при равенстве — первый заданный класс, без общего порога0.8. Для обычной языковой модели `probabilities` и `nativeChoice` равны `null`: баллы не выдумываются из порядка вариантов. Ответ обязан содержать только допустимые уникальные ID; некорректный JSON, лишние вопросы, отказ и обрезанный ответ считаются ошибкой. Правильная форма JSON ещё не доказывает фактическую правильность классификации.
+
+Для обычных языковых моделей используйте `createOpenRouterVision` с явными `model`/`provider`, например `openai/gpt-6-luna` и `openai`. Он работает через chat completions. Для классификации нужен один ID, для двух пространственных этапов — четыре упорядоченных кандидата. Нативный Jev-адаптер сохранён отдельно для совместимости и исторических сравнений; автоматического перехода на него нет.
+
+## Классификация изображения
+
+Внутри того же `try` можно передать изображение и дополнительный текст. Добавьте `readFile` к импортам:
+
+```js
+import { readFile } from 'node:fs/promises'
+
+const result = await client.classify({
+  input: {
+    image: await readFile('photo.jpg'),
+    text: 'Есть ли на фотографии велосипед, включая частично видимый?',
+  },
+  classes: [
+    { id: 'present', description: 'На изображении виден хотя бы один велосипед' },
+    { id: 'absent', description: 'На изображении нет видимого велосипеда' },
+  ],
+})
+```
+
+Для одной картинки поле `text` можно опустить. Принимаются `Uint8Array` и `Buffer` с одним PNG/JPEG/WebP: до 16 MiB и 16 777 216 декодированных пикселей. Ссылки на изображения публичный API не загружает — скачивание, права доступа и ограничения внешних URL остаются у вызывающего приложения.
+
+## Поиск объекта и координаты
+
+Также внутри `try`:
+
+```js
+const result = await client.locate({
+  image: await readFile('photo.jpg'),
+  target: 'красный рюкзак на стуле',
+  exclusions: ['сумка на полу'],
+})
+
+if (result.status === 'located') {
+  console.log(result.region) // left, top, width, height: пиксели
+  console.log(result.normalizedRegion) // те же поля в долях размеров изображения
+  console.log(result.metadata.image) // размеры и система координат
+} else {
+  console.log(result.status, result.reason)
+}
+```
+
+Начало координат — левый верхний угол изображения после применения его EXIF-ориентации. X растёт вправо, Y вниз. `region` включает левую/верхнюю границы и не включает правую/нижнюю. Для экранного оверлея сначала учитывайте ориентацию, масштаб отображения и возможные поля вокруг картинки. Не переносите координаты на следующий кадр без проверки: библиотека не отслеживает объект во времени.
+
+`roi: { left, top, width, height }` ограничивает поиск прямоугольником в целых пикселях того же ориентированного исходника. Координаты ответа остаются относительно всего исходника, а не относительно обрезанного фрагмента. Указывайте ROI только если он находится внутри реальных размеров изображения.
+
+| Статус                       | Что означает                                                                        | Как обрабатывать                                                                            |
+| ---------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `located`                    | Выбран кандидат в сетке                                                             | Показать область с учётом вероятностного характера результата                               |
+| `not-found`                  | Проверка присутствия отвергла объект в анализируемой области                        | Не переносить этот вывод на область за пределами ROI                                        |
+| `unknown`                    | Неуверенность, противоречие, отсутствие цели среди кандидатов или невозможная сетка | Уточнить цель, взять более подходящее изображение или вернуть пользователю неопределённость |
+| Исключение `ClassifierError` | Ошибка входа, сети, протокола, бюджета или жизненного цикла                         | Обработать код ошибки; не показывать её как отсутствие объекта                              |
+
+Небольшие значки, перекрытия, похожие предметы и сложные карты требуют собственной проверки на ваших данных. Предметные фотографии не доказывают точность на игровых мини-картах. Если нужен центр объекта или маска, это отдельный этап уточнения.
+
+## Отмена, нагрузка и ошибки
+
+Переиспользуйте один `client` на жизненный цикл сервиса. По умолчанию одновременно выполняются две операции, в очереди допускается 16, общий тайм-аут — 45 секунд, включая ожидание очереди и обработку картинки. Параметры можно задать в `createClassifier`; максимумы — 4 операции, 32 ожидающих и 120 секунд. При переполнении возвращается `CAPACITY`, вместо неограниченного накопления задач.
+
+Для отмены передайте `signal`. Например, этот вызов завершается не позднее тайм-аута сигнала с учётом физического освобождения нативных ресурсов:
+
+```js
+const result = await client.classify({
+  input: 'Нужна помощь со входом',
+  classes: [
+    { id: 'support', description: 'Техническая проблема' },
+    { id: 'other', description: 'Другая тема' },
+  ],
+  signal: AbortSignal.timeout(10_000),
+})
+```
+
+Для ручной отмены создайте `AbortController`, передайте `controller.signal`, вызовите `controller.abort()` при закрытии запроса пользователя. `await client.dispose()` отменяет активные/ожидающие операции и ждёт фактического завершения принадлежащих клиенту работ. Отмена уже отправленного HTTP-запроса не гарантирует отмену тарификации у провайдера.
+
+Обрабатывайте `ClassifierError` через экспорт библиотеки:
+
+```js
+import { ClassifierError } from 'zorya-classifier'
+
+try {
+  // await client.classify(...) или await client.locate(...)
+} catch (error) {
+  if (error instanceof ClassifierError) {
+    console.error(error.code, error.message)
+  } else {
+    throw error
+  }
+}
+```
+
+Коды включают `INVALID_INPUT`, `INVALID_RESPONSE`, `TIMEOUT`, `ABORTED`, `CAPACITY`, `DISPOSED`, `PROVIDER`, `AUTHENTICATION`, `UNSUPPORTED`, `RESOURCE_LIMIT`. Автоматических повторов, замены модели и провайдера нет. Собственный повтор учитывайте как новый платный запрос; `locate` к моменту ошибки уже мог выполнить предыдущие стадии.
+
+## Командная строка
+
+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:
+
+```sh
+export ZORYA_MODE=decisions
+export ZORYA_MODEL=openai/gpt-6-luna-decisions
+export ZORYA_PROVIDER=openai
+npx --no-install zorya-classifier --help
+npx --no-install zorya-classifier classify-text "Где мой заказ?" classes.json
+npx --no-install zorya-classifier classify-image photo.jpg classes.json
+npx --no-install zorya-classifier locate photo.jpg "красный рюкзак"
+```
+
+`classes.json` — обычный массив:
+
+```json
+[
+  { "id": "delivery", "description": "Вопрос о доставке" },
+  { "id": "other", "description": "Другая тема" }
+]
+```
+
+Для загрузки `.env` без дополнительных зависимостей:
+
+```sh
+node --env-file=.env node_modules/zorya-classifier/dist/cli.js locate photo.jpg "красный рюкзак"
+```
+
+CLI выводит JSON и обращается к реальному платному провайдеру. `--help` запросов не делает.
+
+## Провайдеры и проверенные модели
+
+OpenRouter — один из способов подключения. Для прямого провайдера или локального сервера:
+
+```js
+import { createOpenAICompatibleVision } from 'zorya-classifier/openai-compatible'
+
+const decision = createOpenAICompatibleVision({
+  endpoint: 'http://localhost:8000/v1/chat/completions',
+  model: 'your-deployed-vision-model',
+})
+const client = createClassifier({ decision })
+```
+
+Укажите настоящий ID развёрнутой модели и полный URL доверенного сервера. Для облачного API можно передать `apiKey`, а для другого способа авторизации — `headers`. Для API с другим протоколом реализуйте экспортируемый `DecisionPort`. Ключ OpenRouter не подставляется автоматически в запрос к вашему серверу. Локальный пример показывает настройку подключения; он не означает, что конкретная модель или сервер были проверены в реальном прогоне.
+
+Для `classify` с одной картинкой достаточно поддержки одной картинки. Для трёхэтапного `locate` модель/сервер должны принимать несколько изображений в одном запросе, максимум девять. Поддержка JSON Schema и JSON-object опциональна: по умолчанию схема описывается в промпте, а ответ проверяется кодом. Модель без нативной классификации подходит; модель, которая не выполняет контракт ответа, вернёт явную ошибку.
+
+[Таблица проверенных моделей](vision-results.md) содержит названия, провайдеров, число примеров, ошибки, точность, задержки и цену. Там отдельно указаны полноценная проверка на корпусе, короткий screening и тесты адаптера с искусственным сервером. Необозначенная модель не считается автоматически проверенной.
+
+Исторический Jev-прогон дал 55/60 на фото и 30/30 на авторских текстовых примерах. Это baseline прежнего адаптера, а не доказательство качества другой модели. Подробности и исходные ошибки сохранены в [исторических результатах](results.md). Локализация остаётся экспериментальной; ячейка не является точной маской или центром объекта.
+
+## Разработка и следующие документы
+
+```sh
+npm ci --ignore-scripts
+npm run prepare
+npm run check
+npm run pack:check
+npm run format:check
+```
+
+`check` включает секреты, TypeScript, ESLint, границы слоёв, неиспользуемый код, тесты и сборку. Husky проверяет добавленные в Git версии файлов. `pack:check` устанавливает архив в независимый проект, проверяет его файлы и API. Эти проверки не вызывают реальную модель.
+
+- [Полный контракт API](api.md): типы, лимиты, формат метаданных, округление баллов.
+- [Архитектура](architecture.md): слои, порты, отмена и владение ресурсами.
+- [Эксплуатация](operations.md): интеграция в сервис, расходы и завершение работы.
+- [Воспроизведение benchmark](benchmarks.md): лицензированные фотографии и отдельный запуск платных проверок.
+- [Безопасность](../SECURITY.md): ключи, Git, npm-архивы и ограничения сканирования.
+- [Подготовка публикации](publishing.md): GitHub/npm и необходимая авторизация владельца.

package/docs/acceptance.md

@@ -0,0 +1,31 @@
+# Acceptance: standalone0.1.0 preview
+
+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.
+
+## Executed checks and release gates
+
+| Check                 | Evidence                                                                                                                                                                                                                                                          |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Linux source quality  | Secret scan, TypeScript, strict ESLint, boundaries, dead-code,187 offline tests and build pass. Current local receipts are preserved with the release.                                                                                                            |
+| Installed archive     | Independent consumer compiles exported declarations and exercises native Sharp, fixture classification/three-stage localization, native Decisions adapter and ordinary direct adapter. Actual installed bytes are compared with the reviewed archive and scanned. |
+| Hosted Windows/Linux  | The [CI matrix](https://github.com/zoomplus/zorya-classifier/actions) runs Node22/24 on both operating systems. Publication requires all four jobs green for the release source; the external release manifest records the exact run/commit and results.          |
+| Native classifier     | 60 licensed photos:55 correct;40 heldout:39 correct;30 authored texts:30 correct; zero classification transport/protocol errors. [Exact model evidence](vision-results.md).                                                                                       |
+| Other ordinary models | Full Luna and Qwen comparisons, Nex development screening and stopped Haiku photo batch are preserved, including errors and unstarted cases.                                                                                                                      |
+| Lifecycle             | Offline regressions cover input ownership, deadlines, queue saturation, late completion, cancellation/reader cleanup,1000 operation/disposal cycles and strict rank/probability interpretation.                                                                   |
+| Credentials/archive   | Staged-blob/worktree scans, independent redacted Gitleaks and actual archive checks run before publication. Results and artifact hashes belong to the external release manifest.                                                                                  |
+
+The [first hosted CI run](https://github.com/zoomplus/zorya-classifier/actions/runs/39074647509) is retained as a failure: Linux passed; Windows exposed an8.3 temporary-directory alias mismatch in the declaration-isolation check. The check now canonicalizes with native filesystem realpaths; allowed declaration roots are unchanged. The final hosted run, rather than that failed run or historical local results, determines release eligibility.
+
+Historical native Windows/source and secret-scan receipts remain under docs/evidence; they describe the older runtime. Current hosted Windows exercises the new adapters and full source gates without Wine. macOS and live desktop/game integration remain unverified.
+
+## Quality limits
+
+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.
+
+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.
+
+## Traceability
+
+Live manifests pin corpus/source snapshots. The clean source archive derives from the standalone Git commit; the external release manifest pins that commit, source-file manifest, all archive SHA256 values, CI results and final secret scans. It remains outside the archives to avoid self-reference. Credentials, personal media, private history, dependencies and corpus photo pixels are excluded. See [publishing](publishing.md) and the actual GitHub/npm destinations for publication status.

package/docs/api.md

@@ -0,0 +1,45 @@
+# 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.
+
+`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`.
+
+`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.
+
+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.
+
+`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)
+
+`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.
+
+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.
+
+Other native protocols can implement `DecisionPort`. No native-to-chat or model/provider fallback occurs automatically.
+
+## Ordinary vision chat adapters
+
+`createOpenAICompatibleVision({ endpoint, model, apiKey?, headers?, responseFormat?, maxOutputTokens?, reasoningEffort?, responseModelIds?, fetch?, maxRequestBytes?, maxResponseBytes? })` is exported from `zorya-classifier/openai-compatible`. The full HTTP(S) chat-completions URL is explicit and trusted; URL user/password credentials are rejected. Anonymous local servers can omit authentication. Custom headers support other server authentication. Supply either `apiKey` or a custom Authorization header, not both. No OpenRouter routing fields are sent by this adapter.
+
+`createOpenRouterVision({ apiKey, model, provider, providerName?, ... })` is exported from `zorya-classifier/openrouter`. It wraps the same ordinary chat transport with a fixed OpenRouter chat-completions endpoint and explicit `provider.only`, no fallback, and required parameter support. `providerName` identifies a returned display name differing from the requested slug. Additional explicitly allowed response model snapshot IDs can be listed in `responseModelIds`; these are identity aliases, not alternative routes. Date-stamped snapshots of the requested model are accepted and preserved in metadata.
+
+`responseFormat` is `prompt` by default, requiring only ordinary instruction-following JSON output, not provider-native structured outputs. `json-object` and `json-schema` are explicit opt-ins when the model/server supports them. `maxOutputTokens` defaults to1024, maximum4096. `reasoningEffort` is optional; do not request unsupported parameters from a custom model. No temperature or reasoning option is silently imposed by the generic adapter.
+
+The model is given the exact class descriptions and required JSON shape. It returns one ranked ID for classification/final candidate selection and exactly `min(4, option count)` unique ranked IDs for each spatial beam question (`rankingSize: 1 | 4`; omitted defaults to4 on direct port calls) and an explicit present/absent/unknown for each presence question. The adapter checks all questions, IDs, types, finish state and byte limits. It rejects unknown IDs, duplicate/incomplete ranks, numeric probabilities invented in a ranking response, extra answers, malformed/fenced JSON, refusals, tool output and truncated generations. There are no hidden corrective retries. Factual correctness still depends on the model.
+
+The public `DecisionPort` supports another SDK/protocol. For a ranked answer, return `{ type: 'ranked-choice', ranking: [...] }`; for presence return `{ type: 'presence', presence: 'present' | 'absent' | 'unknown' }`, with truthful route/cost metadata. The caller's deadline-bound AbortSignal must be honored. Optional legacy probability answers remain supported. `classify` needs at most one image; `locate` requires up to nine images per request. A server supporting only a single image is not claimed to support the locator.
+
+`createOpenRouterJev({ apiKey, fetch?, maxRequestBytes?, maxResponseBytes? })` is an optional legacy Jev integration, never the required backend or an automatic fallback: fixed endpoint/model/provider, no automatic fallback/retry. Lower request/response caps can be supplied; response defaults1MiB. Direct port calls require the caller to supply a deadline-bound signal. The top-level client supplies it. The port accepts only top-level inline image parts, not remote URLs.
+
+## Optional legacy native adapter and quantization
+
+The legacy Jev adapter observed Jev 1.14 rounding scores to a 0.01 lattice: a real 153-option response sums to 0.99. Such values remain raw; they are never renormalized. For non-unit mass the adapter accepts only finite [0,1] values on that lattice whose clipped half-step intervals jointly admit total probability 1, and adds `probabilityRoundingStep: 0.01`. Complete option keys and the native maximum remain mandatory.
+
+A custom probability-valued `DecisionPort` answer without this explicit annotation must provide unit mass within floating-point tolerance. The annotation describes transport quantization, not calibration or confidence; many tied zeros can be compatible with rounding at high class counts and convey no ranking information. Stable input-order tie selection still applies. The result preserves both the native choice and our deterministic choice.

package/docs/architecture.md

@@ -0,0 +1,32 @@
+# 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.
+
+```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]
+```
+
+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.
+
+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.
+
+Extraction differences from the gaming service: the public result is an area; multiple objects are allowed with one selected; no session/epoch/database/process host remains; the caller owns freshness of supplied bytes; generic image operations have an explicit45s library timeout instead of borrowing the gaming background8s budget. Stable ties use supplied class/grid order. Prompt wording and compact grid labels are documented source changes and require new quality evidence; old game-map results do not qualify this library.
+
+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.
+
+## 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.

package/docs/benchmarks.md

@@ -0,0 +1,53 @@
+# Reproducible benchmarks
+
+Current native Luna Decisions and ordinary vision comparisons are summarized in [tested models](vision-results.md). The fixed native-Jev runner below remains a historical/reproducibility tool, not the primary model configuration. New model-selection snapshots and budget continuations are retained separately; never label the Jev runner's output as evidence for Luna or another backend.
+
+The optional corpus contains 60 licensed Open Images photographs and 30 authored text fixtures. Photographs cover 25 requested classes with ten each of baseline, absent target, small target, edge truncation, occlusion and repeated instances.20 photos/10 texts are development data;40/20 are reserved evaluation data. Public heldout does not guarantee exclusion from provider training.
+
+Photo licenses and hashes are in benchmarks/corpus/ATTRIBUTION.md, licenses and manifests. Photo pixels and bulk CSVs are not shipped in npm or the source archive. Run the pinned fetch_photos.py script from benchmarks/corpus to obtain them; fetch_metadata.py acquires source CSVs for the independent audit. Image manifests use explicit human-verified negatives. Authored text cases are fixtures, not real customer traffic.
+
+The benchmark is opt-in and must bound requests/costs before dispatch. Production library calls have no benchmark logger; a benchmark DecisionPort wrapper explicitly records input images, answers, errors and timing into an isolated run directory. The harness validates label files at startup; labels are used only by scoring and overlays after the corresponding producer results are recorded. They are never included in provider state, prompts, options or image filenames. Native classify uses a second call with the identical request; this tests wrapper parity and variance, not an expected accuracy gain. One/two-stage locate baselines reuse the exact successful prefix responses and are labeled correlated prefix ablations.
+
+Metrics include classification accuracy/macro-F 1/confusion, errors in the denominator, any-instance point-in-reference-box, selected-region area, distance to reference boxes, negative false positives, p 50/p 95 and physical call/known/unknown costs. The point is the center of the selected cell for evaluation only, not a claimed object centroid. Bbox membership is a proxy and can include background; overlays and region sizes remain necessary. No all-instance recall is claimed.
+
+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.
+
+## 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:
+
+```sh
+node --import tsx benchmarks/model-selection.ts --allow-paid --fresh-native --out .run/luna-native-example
+```
+
+This caps admission at93 calls and$0.50:60 photos+30 texts, then at most three calls for one fixed positive locator smoke if classification meets the recorded target. It starts a new budget rather than importing the owner's historical runs. No retries/fallback or hidden key loading occur. The source-pinned snapshots in docs/evidence describe their original versions; future results can vary. Extension/completion flags in that script are historical budget-continuation tools and require the exact local earlier-run receipts; they are not needed for a fresh run.
+
+## Historical Jev fixed-corpus runner
+
+From the repository root, install development dependencies with `npm ci --ignore-scripts`. Fetch only the pinned public photo bytes, then run fixture mechanics:
+
+```sh
+python3 benchmarks/corpus/fetch_photos.py
+node -e "require('node:fs').mkdirSync('.run',{recursive:true})"
+node --import tsx benchmarks/run.ts --mode offline --split dev --limit 2 --out .run/offline-example
+```
+
+For a real run, set `OPENROUTER_API_KEY` in your shell/secret manager and explicitly opt in:
+
+```sh
+node --import tsx benchmarks/run.ts --mode live --allow-paid --max-calls 360 --max-cost-usd 1 --out .run/live-example
+```
+
+Each output directory must be new. The maximum is 60 × (two independent classifications + three locator calls) + 30 × two text calls = 360 provider calls; early absence can reduce it. No retries or resumes silently repeat paid requests. The runner stops further admission on budget exhaustion or evidence-write failure, keeps incomplete results, and exits unsuccessfully for an incomplete run. A completed run may still contain provider/model failures; those remain in accuracy denominators.
+
+The budget reserves $0.02 before each request and retains that reservation for missing/invalid cost metadata. Current combined-context pricing gives a maximum input envelope of 262,144 × $0.000000042 = $0.011010048 per request; output tokens are free. See the [dated pricing snapshot](evidence/jev-pricing-2026-10-18.json), [provider context/pricing documentation](https://docs.typesafe.ai/models) and [OpenRouter image billing](https://openrouter.ai/docs/guides/community/multimodal-decisions). Recheck pricing before a future run. This is a local admission budget derived from published limits; it does not change the shared account's billing limits.
+
+`manifest.json` pins source/corpus hashes and configuration. Per-case requests include public image data; receipts record validated answers or sanitized errors. A malformed answer rejected by the adapter is represented by its error, not silently repaired. `report.json` contains confusion matrices, failures, latency, known/unknown costs and all joined sample scores. Overlays show reference boxes and one/two/three-stage selected cells. Preserve raw evidence locally; share only reviewed public-corpus evidence.
+
+The corpus README and validation report describe its frozen **pre-inference preparation**; measured model results live in this release's acceptance/report, not in that historical manifest.
+
+## Protocol correction found during v1
+
+The first live process is pinned to a pre-correction source snapshot: it rejected any probability sum farther than 1e-6 from 1. Two separate diagnostic replays captured an actual Jev 153-option response with sum 0.99 and a five-option response with unit mass. The release supports explicitly annotated quantization as described in the API; the exact 153-option response is covered by offline replay. The original live failures are retained and its metrics are not recomputed as successes. This correction changes response acceptance, not prompts, crops, argmax, geometry or model route. The release's complete future quality estimate still needs another frozen run; current figures describe the recorded v1 snapshot. The two diagnostic calls count toward the total call/cost accounting but not accuracy metrics.
+
+The final corrected runtime smoke used `--mode live --allow-paid --max-calls 14 --max-cost-usd 0.1 --split dev --limit 2 --out .run/live-release-smoke`. Its 14 calls and the two diagnostic probes are accounted separately from the full run; neither is pooled into the original accuracy metrics.

package/docs/evidence/current-linux-check.json

@@ -0,0 +1,15 @@
+{
+  "status": "PASS",
+  "platform": "linux",
+  "node": "v24.12.0",
+  "checks": ["secrets:check", "typecheck", "lint", "boundaries", "dead-code:ci", "test", "build"],
+  "tests": {
+    "pass": 187,
+    "fail": 0,
+    "skipped": 0
+  },
+  "runtimeDistFiles": 44,
+  "runtimeDistSha256": "3c9317d9c6945eb00a3c043cfe5e6be4e12541db7fefa30398d177b955f01fbd",
+  "sourceLogSha256": "8f78477d719c1cb813b74230cc246e3645d6dfd0c96b92806b3e89bc89d5fcce",
+  "note": "Source gates passed; documentation evidence subsequently added. Final release/CI checks inspect the committed source snapshot."
+}

package/docs/evidence/decisions-completion-v1-manifest.json

@@ -0,0 +1,96 @@
+{
+  "startedAt": "2026-10-17T22:59:39.495Z",
+  "authorization": "User authorized up to1000 aggregate test requests, keeping the existing $0.50 ceiling; prior288 calls and reconciled unknown costs included",
+  "routes": [
+    {
+      "id": "luna-decisions",
+      "model": "openai/gpt-6-luna-decisions",
+      "provider": "openai",
+      "providerName": "OpenAI",
+      "inputPerMillion": 0.1,
+      "outputPerMillion": 0
+    }
+  ],
+  "prior": {
+    "sha256": "25c463dc9b005c2702dd94e78b12cee861e5f27827c5093cda857771837b19c7",
+    "physicalCalls": 288,
+    "budget": {
+      "admittedProviderCalls": 288,
+      "maxCalls": 1000,
+      "maxCostUsd": 0.5,
+      "knownCostUsd": 0.029322660000000056,
+      "unknownCostCalls": 3,
+      "inFlightCalls": 0,
+      "reservationPerUnknownUsd": 0.05,
+      "accountedExposureUsd": 0.17932266000000008,
+      "exceededByReportedCost": false
+    }
+  },
+  "protocol": "native-choice-v1: exact criteria and raw distributions; no chat rank protocol",
+  "policy": "Complete the missing20 development photos and20 heldout texts for the same frozen Luna Decisions classifier; earlier40 heldout photos and10 development texts are retained, never replayed or repaired. No inference/prompt changes. At most40 new classification calls under expanded1000 aggregate request limit and unchanged $0.50 cap. No retries. Preserve previous locator provider error.",
+  "screen": [
+    "photo-dev-01",
+    "photo-dev-02",
+    "photo-dev-03",
+    "photo-dev-04",
+    "photo-dev-05",
+    "photo-dev-06",
+    "photo-dev-07",
+    "photo-dev-08",
+    "photo-dev-09",
+    "photo-dev-10"
+  ],
+  "sourceHashes": {
+    "src/app/cli-route.ts": "769b0f2e8fa6d1fabbf2e7bd000fec724c1b94a3c6233eea7b93d55503052aad",
+    "src/app/create-classifier.ts": "55bfcf78b8c12c616d1144371541ec4eb1e56a6a4790700b366e41dbdf896491",
+    "src/cli.ts": "b47f83c9470de5fbba10bb7c38241ef1ba67dfd59e976fe1d73d19db2748b99e",
+    "src/entities/contracts.ts": "6dc59ce64331d748f57d2f192aeb693ec4c5ff9e021e62dd56f534b94aa67efe",
+    "src/entities/errors.ts": "1c92c94c9ed6917953ac5192bfd2d8896cdb6fe13b7d05593573b7f2103330b0",
+    "src/features/choice-beam-layout.ts": "8f61d6f784e0e6273467cea01315f17bbfa4fffa695dd7a7bb9cd5cac5354e1a",
+    "src/features/choice.ts": "ff972121520a339b82895914242bf40f7b8dcd198b4305fd57e51b204b13952d",
+    "src/features/prompts.ts": "b808ed8f42e8c92daf08060d2805da618f2b140f99b6a9b07df49622d57b62aa",
+    "src/features/uniform-grid.ts": "8cee38aee52ba2c4ac2eaed909d5f53cc0e5aa2c04fe87585c66b29573e21c4d",
+    "src/index.ts": "1cd73c74a874adf1a4a3b6edb48e230f54c671098b9a3d51bb3a01a0ad2866db",
+    "src/infrastructure/openrouter-common.ts": "415462c42da7a3748c6bfe942ee99085fba71bc1f4158d369edda8269efeb124",
+    "src/infrastructure/openrouter-vision.ts": "d95f1be71f8011d32ec6dfbe15c3ad93d12fe1aaf88799f8dfb06156353e1915",
+    "src/infrastructure/openrouter.ts": "486a919853949e6789dd4035b7699fd89b9682cb3e928632c77b216656f44c55",
+    "src/infrastructure/raster.ts": "8217346f671b957540f3c01a7eb3d8ef7d0bfb6a5e18a47c96f0ccb08f4bcb08",
+    "src/infrastructure/vision-chat.ts": "9df3aeda2a2cb15d068055bca70e1bacc7ec682d70a3fc1b5f91be529753c790",
+    "src/openai-compatible.ts": "ff9096393ecb437d9c917c5da716553a5a887a810e65c9815dd791b772895fc3",
+    "src/openrouter.ts": "7272441f86f6d143aab867231f617dfd806c802b2147f95e640ace65cdee3ced",
+    "src/processes/classify.ts": "e9dd25f86e28264f2d6f1b409879514cb443194b8efdd638e42867869f7136ff",
+    "src/processes/locate.ts": "a64d2d3c4120a4ff5389a8a9b4620ecff1132dd5c3b46e69efe04208c97f39b4",
+    "src/shared/choice-mass.ts": "7f645998d9cd2688ca425b4765ec0bf7d125e932f085f9e84599b4c3b97743a3",
+    "src/shared/gate.ts": "97e4e32749dc9d3a9def6faaea2566b5d0ed831ba4451999740c719fafa8e576",
+    "src/shared/scope.ts": "cc557e9fd83a838f5366c64d026859db119491d927dfb3a84ef4320b2f0b0beb"
+  },
+  "harnessHashes": {
+    "benchmarks/ablations.ts": "d4450a1c962bd96f89af3499fd0d5da52bb20eb2c6fdf8c79d2e6057d0d6325b",
+    "benchmarks/budget.ts": "c8ac95573a79900e82583a11fe43b631c2959d15bf1bd5c49f1e4e6deb875564",
+    "benchmarks/corpus.ts": "0af52e2f896e74e8e9ab0937e34862cea5396ac0649f896299631160314848b4",
+    "benchmarks/metrics.ts": "024e2461104df77add39ef8fa1c501863b11ca126079d1ab28d512dbbee98d37",
+    "benchmarks/model-selection.ts": "123b2bdbedc72e31b365625b2f06920238da2da0416a3e3c12767a621ff11875",
+    "benchmarks/overlay.ts": "9eced23935c5428d657df747d0f239c6fc8a61ef2f1582d88a86e08f71ddfbf5",
+    "benchmarks/recording.ts": "142f271e6fce60580ff273aa3b0e64de52bd6b74e838bb75c925ac90099c8159",
+    "benchmarks/run.ts": "5ff28c02fd9bc6dc03aaf5934e7e28300f958696a2fb1fffca44edabf748ebfa",
+    "benchmarks/runner.ts": "fd95d5b720e11f4f22bd39e5044b456fcd3c42fffd6b4f308ee98bd99695558f"
+  },
+  "corpus": {
+    "corpus-manifest.json": "00f4459996db0f61a38235adaf512e1bfc52e02e1d599bb590b62a98217e4cdb",
+    "photo-manifest.json": "a99f47d4e1c064581c6cc9123b58a5c81b196d15227963bf015041544f713aa3",
+    "text/text-manifest.json": "5e74c8c13cd1f1f8a2e2ecc22e90e6c0c83ebf5f9407dfed5b87204d3b8831ac",
+    "text/inputs/policy.json": "9db3010c97fa056fbb4a43ea51a5c973bd75b9d21f8d07f2c15d6d176e712b8a",
+    "inputs/dev.json": "0c443231956e9578afa43d4bf884cc9741594ae69ac5f957657b9c5a24422bb6",
+    "ground-truth/dev.json": "c618e1a950ae89e0c9ced0c2b1ca249ea7adc891f61c0579468c479613ea4b26",
+    "text/inputs/dev.json": "e7d2bc07559cba70494d6e4672cc3e1113c070aba8b2694ee45e76ebcbc04fcc",
+    "text/ground-truth/dev.json": "4827650b560f20b32b0366dea14947681d29ef9fefb5a059301ba5abf5c031f0",
+    "inputs/heldout.json": "2ce42723824900de9a8eca60b58220567b938a88855ec41a5a882bb410d3b1e4",
+    "ground-truth/heldout.json": "737ee884b8bbf557191d5848b56f17ac056fd01793cd8fb738c5624ea119c7d2",
+    "text/inputs/heldout.json": "e33beeeb011c55992d955ce66397717875c0084bcc21be29ecd123bd29ccce4a",
+    "text/ground-truth/heldout.json": "d29cf2fb7b980d138fd7c8e712708fa9730aa6637f350468ae15651bf9f5c4b0"
+  },
+  "perCallReservationUsd": 0.05,
+  "reasoningEffort": null,
+  "responseFormat": null,
+  "timeoutMs": 45000
+}