zorya-classifier 0.0.0-stage → 0.2.0

package/docs/evidence/windows-native.json

@@ -0,0 +1,73 @@
+{
+  "status": "PASS",
+  "scope": "Final explicit-rounding runtime native Windows source/package offline qualification; no inference, game, app or installer",
+  "createdAt": "2026-10-17T21:47:43.642962+00:00",
+  "rawReceiptSha256": "86f9d51e043883e7e8f7c804f6ef64037d84adb548fedc8b121be8a79298df49",
+  "platform": {
+    "platform": "win32",
+    "node": "v24.19.0",
+    "arch": "x64",
+    "osType": "Windows_NT",
+    "osRelease": "10.0.26200",
+    "osVersion": "Windows 11 Pro"
+  },
+  "npm": "11.17.0",
+  "steps": [
+    {
+      "step": "check-final",
+      "durationMs": 11737.6716,
+      "exitCode": 0,
+      "timedOut": false,
+      "physicalCloseObserved": true,
+      "stdoutSha256": "1a02d2081e7b52e7d16c252627caa7d2427aaf93c5defc2aea541b18c86487e7",
+      "stderrSha256": "bdd8e52cff96a1a2de65f7c89c275f8eb847c4cb3c4e80298775e92dc8853ba8"
+    },
+    {
+      "step": "pack-check-final",
+      "durationMs": 6953.8477,
+      "exitCode": 0,
+      "timedOut": false,
+      "physicalCloseObserved": true,
+      "stdoutSha256": "975c81cf847d6360b2199e518f17f84e2570210a46e4759409f8ec319f57fdcc",
+      "stderrSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    }
+  ],
+  "tests": {
+    "tests": 142,
+    "pass": 142,
+    "fail": 0,
+    "cancelled": 0,
+    "skipped": 0
+  },
+  "consumer": {
+    "independentConsumer": "passed",
+    "declarations": "compiled",
+    "sharp": "0.34.5",
+    "vips": "8.17.3",
+    "classification": "yes",
+    "localization": "located",
+    "controlledDecisionCalls": 4,
+    "providerHttpCalls": 0
+  },
+  "testedSnapshotPackage": {
+    "files": 47,
+    "unpackedSize": 109715,
+    "sha256": "9029ed25c0c5f2ecc638d87d69d0dbefe1024181ccbe19bfe6f5513e85da0426",
+    "runtimeDistFiles": 34,
+    "runtimeDistSha256": "62d5a0075e5ccca6627ba81f8ca8be427f499ded7508570171c00520bcf369ca",
+    "consumerDeclarationFiles": 184,
+    "npmTransport": "node npm-cli.js; shell:false"
+  },
+  "runtimeDistEqualLinuxWindows": true,
+  "sourceMismatchCounts": {
+    "immutable": 0,
+    "staged": 0
+  },
+  "limitations": [
+    "Offline fake-fetch/DecisionPort checks do not qualify live Jev accuracy or performance",
+    "No Windows app/installer/game executed",
+    "Source docs may evolve after this immutable runtime snapshot",
+    "No OS-wide process/network trace claimed"
+  ],
+  "note": "Host-specific temporary paths removed from this public summary; original receipt retained locally. Final release docs/evidence can change archive SHA without changing tested dist."
+}

package/docs/evidence/windows-secrets.json

@@ -0,0 +1,46 @@
+{
+  "status": "PASS",
+  "scope": "Native Windows offline secrets guard qualification only; not a repeat of runtime suite",
+  "createdAt": "2026-10-17T22:05:25.617601+00:00",
+  "probe": {
+    "node": "v24.19.0",
+    "arch": "x64",
+    "platform": "win32",
+    "osRelease": "10.0.26200",
+    "osVersion": "Windows 11 Pro"
+  },
+  "gitVersion": "git version 2.52.0.windows.1",
+  "tests": {
+    "tests": 16,
+    "pass": 15,
+    "fail": 0,
+    "cancelled": 0,
+    "skipped": 1
+  },
+  "expectedSkipped": "POSIX FIFO creation regression; unavailable on Win32; Linux passed this case",
+  "worktreeScan": {
+    "status": "PASS",
+    "mode": "--worktree",
+    "scanned": 5,
+    "skippedBinary": 0,
+    "totalBytes": 154472
+  },
+  "stagedScan": {
+    "status": "PASS",
+    "mode": "--staged",
+    "scanned": 5,
+    "skippedBinary": 0,
+    "totalBytes": 154472
+  },
+  "sourceGuardPinsUnchanged": true,
+  "stagedPinsUnchanged": true,
+  "otherSourceChanges": [],
+  "limitations": [
+    "Heuristic text scanner does not guarantee detection of all credentials",
+    "Binary contents skipped explicitly after filename checks",
+    "Parent-directory replacement is not an atomic filesystem sandbox boundary",
+    "No model HTTP, private-key modification, application or installer execution",
+    "Npm registry installation used pinned lock and --ignore-scripts; no OS-wide network trace"
+  ],
+  "rawReceiptSha256": "271c48e4f6f149b195fd6e8c6d385d69f11bd41764cfa4ff52ce2a0b0ff9eaea"
+}

package/docs/operations.md

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

package/docs/plan.md

@@ -0,0 +1,27 @@
+# Accepted open-source extraction plan
+
+Current implementation: [accepted 0.2 plan](0.2.0-plan.md), whole-object bounds, extraction and comparative text-only image experiments. The first-release plan below is retained as history.
+
+First deliver an independent MIT Node.js/TypeScript library with classify(text/image/both) and locate(image,target), powered by Jev 1.14/TypeSafe. Preserve three Choice stages for localization, stable maxima/ties and source coordinates; no implicit model/provider fallback or retries. Classification is one native Choice. Separate heavy optional refinement and game/application dependencies.
+
+Prepare public contracts, strict schemas, source rules, architecture/API/operations documentation, examples/CLI, offline regressions and Windows/Linux CI. Package into a clean npm archive and test installation outside the repository. Scan release contents for secrets, private paths and unwanted assets. Prepare a clean source repository; public GitHub/npm publishing is a separate action.
+
+Evaluate 60 licensed real photographs (20 development/40 heldout) and 30 authored text fixtures (10/20). Separate raw producer inputs from ground truth. Compare classification against an independently called identical native Choice; evaluate one/two-stage locator prefix ablations from the three-stage run. Record mistakes, errors, latency, costs, true unknowns and visual overlays. No universal superiority claim without evidence.
+
+Acceptance requires executed source checks, clean independent consumer install, an honest real-provider report and complete release documentation. Configured CI is not evidence of execution. Historical gaming/microphone checks and installer work remain separate.
+
+## Owner revision: universal vision classification before first npm publication
+
+The owner replaced the Jev-centered release design after initial GitHub creation and before npm publication. Ordinary image-capable language models must work without a native classification/Decisions API. Implement an OpenRouter chat-completions adapter that requests closed ranked IDs and explicit present/absent/unknown predicates, validates all outputs and rejects invented IDs, extra questions, truncation, refusals and malformed JSON. Do not manufacture probabilities from ranks. Keep the original native adapter only as an optional compatibility/benchmark integration, never an implicit dependency/fallback.
+
+Preserve the three grid stages, source-pixel geometry, input ownership, bounded queues, cancellation, byte caps, no retries/model fallback and route accountability. Extend the internal/public result contract with explicit rank-only evidence. The selected class is the first ranked ID; only genuine provider probability distributions remain probability-valued. Update examples, CLI, docs and rules to the generic adapter.
+
+Compare cheap general vision candidates under a newly authorized bounded paid run before recommending the cheapest tested route that meets the recorded baseline. Preserve historical Jev reports as historical evidence, not a qualification for a different backend. A pending separate paid-run request does not authorize dispatch until approved. npm publication waits for updated code, independent archive checks, Windows/Linux CI and honest current-model evidence.
+
+The first hosted Windows CI exposed a temporary-directory alias problem in the declaration-isolation check. Resolve Windows 8.3 aliases with the native filesystem canonicalizer; do not broaden allowed declaration roots or skip archive verification. Preserve the failed run and verify the corrected check in hosted Windows CI.
+
+Additional owner requirement: provide a direct OpenAI-compatible endpoint adapter (including anonymous local servers/custom authentication) and a public custom port. OpenRouter is optional. README must explicitly distinguish configurable vision-model support from models/routes actually tested, with per-model accuracy, error, latency and price data.
+
+## Latest owner priority: native decision models except Jev
+
+Prioritize Luna Decisions through the typed Decisions API. Keep model/provider explicit and implement a generic native adapter; retain ordinary vision-chat support as an alternative, and Jev only as an optional historical integration. Do not silently fall back between protocols. Native probabilities remain genuine values; quantization assumptions require explicit model-specific evidence/configuration. Reallocate the remaining approved comparison budget without exceeding290 total calls/$0.50. Current ordinary runs and their failures remain preserved.

package/docs/provenance.json

@@ -0,0 +1,32 @@
+{
+  "upstreamCommit": "97fca38ef027f0c83c63bd069248e6299619abd2",
+  "algorithm": "coarse4x4 -> four padded regions/fine<=49 each -> four enlarged candidate Choice",
+  "copiedOrAdaptedFiles": [
+    {
+      "source": "packages/screen-locator-service/src/features/grid/uniform-grid.ts",
+      "sourceSha256": "c4ed5506218e93a79eade528942fdc35f9197b2ea5f1af2027cba21b6e18b847",
+      "destination": "src/features/uniform-grid.ts"
+    },
+    {
+      "source": "packages/screen-locator-service/src/features/grid/choice-beam-layout.ts",
+      "sourceSha256": "4a2a22efc43ef69313da5cacb41425c336186e8602fb168dfdef5572586ee6c8",
+      "destination": "src/features/choice-beam-layout.ts"
+    },
+    {
+      "source": "tools/eslint-plugin-element-guard/no-discarded-interval.js",
+      "sourceSha256": "321c43b61b673515571c969ba4ff75e307c0eefaccad308c414c5736174d260e",
+      "destination": "tools/no-discarded-interval.mjs"
+    }
+  ],
+  "changes": [
+    "Standalone ports and lifecycle; no game/application dependencies",
+    "Multiple targets allowed, returning one candidate",
+    "Stable supplied-order tie selection",
+    "Compact grid rendering and generic prompts require independent new quality evidence",
+    "45-second default for standalone operations; original gaming deadline unchanged",
+    "Provider-independent ordinary vision chat protocol with closed ranks and separate presence; no invented probabilities",
+    "Direct OpenAI-compatible endpoint and optional OpenRouter wrapper; native Jev retained as optional historical integration",
+    "One winner for single-label/final selection; four ranks only for coarse/fine beam stages"
+  ],
+  "originalRepositoryModified": false
+}

package/docs/publishing.md

@@ -0,0 +1,30 @@
+# Publishing handoff
+
+The owner has authorized publication under GitHub account `zoomplus` and npm account `zoomplus`. The selected destinations are the public repository `zoomplus/zorya-classifier` and public package `zorya-classifier`. These names were available at the preflight check. Check the actual repository/registry and release receipt for completion; this document describes the release process rather than asserting remote state.
+
+## Owner and authentication
+
+The supplied account profiles are https://github.com/zoomplus and https://www.npmjs.com/~zoomplus. The owner requested creation of the repository and publication without manually preparing either destination. MIT was already selected for the extracted code. No private email address is added to package metadata. A local package name is not a registry reservation; recheck availability and identity before dispatch.
+
+Send account names and URLs, not passwords, API keys, recovery codes or authentication files. GitHub can be authenticated locally with `gh auth login --web`; the owner completes the browser flow. npm can use local `npm login` followed by the required browser/2FA publication confirmation. See [GitHub CLI authentication](https://cli.github.com/manual/gh_auth_login) and [npm publication authentication](https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification/).
+
+For later CI releases, configure [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) with the actual GitHub repository/workflow. It uses OIDC rather than a long-lived npm token. Configure this after the package ownership and repository are known; a generic workflow would otherwise name an invented owner. Do not place tokens in a workflow or issue.
+
+## Maintainer release sequence
+
+1. Recheck package-name availability, author rights, MIT/third-party notices, acceptance limits and the desired public destination.
+2. Set the final package name/scope and repository/homepage/bugs metadata. Update imports/examples if the name changes, then rerun source and installed-archive checks. Existing archive hashes apply only to the original name/content.
+3. Run `npm run check`, `npm run pack:check`, `npm run format:check` and a redacted independent secret scan. Inspect actual staged blobs and the produced archive, not only `.gitignore`.
+4. Create/push only the clean standalone history, enable secret scanning/push protection and inspect the CI matrix. Raw runs, environment files, personal media and upstream history stay local. Public corpus downloads retain source licenses.
+5. Pack the reviewed version, verify its SHA256, then publish with the authorized account. Require the owner's authentication confirmation when prompted. Record registry integrity, Git tag/commit and release evidence.
+6. Verify the published version and `latest` dist-tag with the registry. Add the matching version tag and GitHub release notes. Keep the package's `repository`, `homepage` and `bugs` links correct, link npm prominently from GitHub, and update npm keywords plus GitHub Topics for the capabilities actually shipped. Examples include classification, object localization, whole-object bounding boxes, optional segmentation/cutouts, TypeScript and provider-independent model integration. Do not advertise an unqualified text-image research profile as supported.
+
+Both GitHub and npm publication are authorized for this project. A local archive remains useful for pre-release installation, but does not complete the requested release.
+
+## 0.2 release evidence
+
+Use the original-region/full-source-segmentation workflow in the current usage guide. Older interval/proposal experiments and their failed reports remain historical evidence; do not relabel them as measurements of the new flow. Record region hits separately from mask-derived object boxes and pixel-mask quality. The image-free control produces regions only.
+
+Before release, match every runtime file in the final archive to the bytes covered by native/resource acceptance, and require green Windows/Linux × Node 22/24 CI for the release source. A later documentation-only archive can have a different package SHA while retaining the tested runtime; record both complete archive hashes and the explicit runtime-file parity proof. Keep a final independently installed consumer check for the actual release archive.
+
+Keep the final release manifest outside its own archives to avoid self-reference. It records the clean source commit, archive hashes/integrities, model recipe and corpus seals, preserved failures, native/resource receipts, CI run and redacted secret scan. Publish those exact archive bytes, verify the registry response and dist-tag, then attach the matching source and npm artifact to the GitHub release. Do not replace failed accuracy or resource gates with an offline test count.

package/docs/research/text-transport-audit.md

@@ -0,0 +1,66 @@
+# Text-only transport audit for 0.2
+
+Audited on 2026-10-20 against baseline `b6e562d`. This is a protocol audit, not a paid model evaluation or a claim that text-encoded photographs can be reliably recognized.
+
+## Existing behavior to retain
+
+`src/infrastructure/vision-chat.ts` already implements a generic non-streaming Chat Completions transport. Images are optional: strings become text content parts, the final `CLASSIFICATION_TASK` follows all data, and a single strict output parser handles categorical rankings and independent presence answers. It does not require a native classifier API.
+
+The transport owns a bounded JSON snapshot before the first await. It forwards the caller's cancellation signal, disables redirects, reads a bounded response, and releases/cancels its reader through `readResponse`. There is one physical request and no transport retry or provider/model fallback. Model aliases in responses are accepted only through explicit identities or validated date snapshots. Missing `usage.cost` remains `null`; a response with ranking IDs never acquires invented probabilities.
+
+`src/infrastructure/openrouter-vision.ts` pins the Chat Completions endpoint and requires an explicit provider. Its request contains `provider.only`, `allow_fallbacks: false`, and `require_parameters: true`. `src/openai-compatible.ts` accepts an explicit trusted HTTP(S) endpoint and optional credentials, with no OpenRouter dependency.
+
+## Minimal additive implementation
+
+1. Factor the existing implementation into an internal chat factory with an explicit modality argument, `vision` or `text`. Retain `createVisionChat` as a compatible wrapper. Add `createTextChat` with the same transport/parser/options. No caller-controlled or extra wire field is necessary.
+2. In text mode, inspect the validated, owned request before fetch and reject every non-string state part with `UNSUPPORTED`. Do not silently strip images, stringify them, or accept their URLs as an alternative protocol. This check happens after plain-value snapshot validation, so accessors/proxies do not execute during modality validation.
+3. Select an accurate system introduction for text mode: a closed-set classifier interpreting supplied text representations, rather than a visual evidence ranker. Keep the untrusted-data warning, final closed task schema, independent presence semantics, and exact rank cardinality unchanged.
+4. Add `createOpenAICompatibleText` beside the existing direct vision wrapper and `createOpenRouterText` beside the OpenRouter vision wrapper. Public exports/types are coordinated by A0. Text and vision wrappers share schemas and transport implementation, rather than maintaining a second response parser.
+5. Keep existing per-part validation intact. The representation layer, rather than this transport, owns normalization, view de-duplication, grid geometry, and the stricter aggregate representation budget. The transport should not infer an image codec or select models.
+
+These changes do not depend on new whole-object or segmentation contracts and need no runtime dependency. The old vision code path must produce the same request body for the same input/options.
+
+## Existing limits and integration implications
+
+| Boundary             | Current limit                          | Consequence                                                                                                    |
+| -------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| State parts          | 1–64                                   | Account for codec grammar, metadata, and all views together.                                                   |
+| Each state string    | 1–64,000 UTF-16 code units             | A single 64 KiB ASCII payload may exceed this; split on meaningful complete view boundaries within this limit. |
+| Prepared image parts | At most 9                              | A library policy, not the provider's universal maximum. Text mode allows zero.                                 |
+| Decision questions   | 1–16                                   | Four extent questions fit in one call.                                                                         |
+| Choice options       | 2–255                                  | Closed interval IDs and `unknown` fit.                                                                         |
+| Request body         | At most 32 MiB                         | Includes task schema, escaping, headers excluded; text representation has its own tighter 64 KiB budget.       |
+| Response body        | At most 1 MiB                          | Bounded reading also applies to error responses.                                                               |
+| Ranking size         | Exactly 1 or 4, capped at option count | Whole-object sides need rank 1; spatial beam needs rank 4.                                                     |
+
+The 64 KiB representation budget is a UTF-8 byte budget and includes all textual image views, not arbitrary task text. It must not be confused with the current 64,000-code-unit individual string schema. No byte truncation should attempt to repair an over-budget view: reduce and declare its resolution before serialization, or return a representation-limit result.
+
+## Required offline regressions
+
+- A real local HTTP server receives text parts only from the new direct adapter, without any key or OpenRouter route.
+- Both new factories reject a valid prepared `image_url` part before fetch; test images appearing at the beginning, middle, and end of mixed state.
+- Malformed, proxy, and accessor inputs remain rejected before transport. Raw image-like strings stay ordinary untrusted strings, not decoded images.
+- Input mutation after invocation cannot change the emitted payload. A rejected image cannot be replaced with a text-only request through silent filtering.
+- Text factory preserves explicit model/provider routing and all response-format options, body/response caps, cancellation, abort cleanup, route identity checks, closed ID/cardinality checks, and unknown cost semantics.
+- Existing vision payload snapshots and behavior remain unchanged. Rank-only output still produces `probabilities: null` through the classifier.
+- The textual codec grammar precedes its encoded views, and the final `CLASSIFICATION_TASK` stays last. No ground truth or model-specific expected answer enters either part.
+- Experimental request preparation has a negative assertion over the serialized payload: no `image_url`, `input_image`, binary/base64 media, or media URL part. This assertion belongs to tests/benchmark capture, not a heuristic transport scan of all ordinary strings.
+
+## Public metadata availability check
+
+The following requests were unauthenticated metadata reads, with no inference dispatch and no key access. Retrieved at 2026-10-20 07:20 UTC:
+
+- `GET https://openrouter.ai/api/v1/models?output_modalities=decisions&input_modalities=image` returned `openai/gpt-6-luna-decisions`, input text/image, output decisions, context 1,050,000. Catalog pricing was $0.10 per million prompt tokens and zero completion charge. This does not verify its current inference route or success rate.
+- `GET https://openrouter.ai/api/v1/models` returned `deepseek/deepseek-v4.1-flash`, input text/image, output text. The benchmark may intentionally send text only even when the selected model also supports images; report payload modality separately from model capability.
+- `GET https://openrouter.ai/api/v1/models/deepseek/deepseek-v4.1-flash/endpoints` contained the exact `together` tag, display name `Together`, status `0`, and supported parameters including `response_format`, `structured_outputs`, and `reasoning_effort`. That endpoint advertised $0.30 per million prompt tokens and $1.20 per million completion tokens. The cheaper model-level aggregate price belongs to other endpoints and must not be used to price the pinned Together route.
+
+Default model catalog queries do not list all Decisions output models. An omitted Luna entry in the unfiltered text-output list is not evidence of removal. The guessed `/api/alpha/decisions/models` path returned 404 and must not be used as a catalog.
+
+## Primary references
+
+- [OpenRouter provider routing](https://openrouter.ai/docs/guides/routing/provider-selection): explicit provider allow-list, disabling fallback, and parameter support.
+- [OpenRouter structured outputs](https://openrouter.ai/docs/guides/features/structured-outputs): strict JSON schema support is endpoint-specific; `require_parameters` is required when relying on it.
+- [OpenRouter multimodal Decisions](https://openrouter.ai/docs/guides/community/multimodal-decisions): image parts go directly in `state`; text items are strings; filter the Models API by output modality.
+- [OpenRouter API overview](https://openrouter.ai/docs/api_reference/overview): Chat Completions text content and response envelopes.
+
+The official documentation allows considerably more images on Luna than this library's conservative nine-image bound. Raising that bound is unnecessary for this extension. Documentation also lists model-specific truncation behavior for other routes; do not add them as automatic text-encoding fallbacks.

package/docs/results.md

@@ -0,0 +1,69 @@
+# Recorded model results
+
+This report is historical evidence for the optional Jev integration. Current native Luna Decisions and ordinary vision model comparisons are in [tested models](vision-results.md); these figures do not qualify a different backend.
+
+These are measured outcomes, including mistakes and failures. They are not a claim that the wrapper improves Jev's classification accuracy, that photographic accuracy transfers to games, or that a selected cell is a segmented object.
+
+## Full corpus: live-v1
+
+The run completed on 2026-10-17 UTC with the source hashes in the [manifest](evidence/live-v1-manifest.json). It used the original strict probability-sum validator. The [complete report](evidence/live-v1-report.json) retains every sample, split, error, timing and joined ground-truth result. Corpus preparation and attribution are described in [benchmarks](benchmarks.md).
+
+The corpus contains 60 licensed photographs (20 dev / 40 heldout; 25 requested object classes) and 30 authored text-intent fixtures (10 dev / 20 heldout). The text fixtures are not real customer conversations. Public heldout can overlap provider training; it was only held out from local development. There was no independent human re-annotation or perceptual duplicate audit.
+
+| Classification        | Library         | Independent native Jev Choice |
+| --------------------- | --------------- | ----------------------------- |
+| Photographs correct   | 55/60 (91.67%)  | 55/60 (91.67%)                |
+| Photograph macro-F1   | 0.84367         | 0.84367                       |
+| Text fixtures correct | 30/30           | 30/30                         |
+| Photograph p50 / p95  | 2.835 / 4.287 s | 2.615 / 3.804 s               |
+| Text p50 / p95        | 0.283 / 0.323 s | 0.293 / 0.333 s               |
+
+Photo presence classification: TP 48, FN 2, TN 7, FP 3. Dev 18/20, heldout 37/40. Text dev 10/10, heldout 20/20. The chosen class agreed across all 90 library/native pairs. The native baseline makes a separate provider call with an identical request; it is not a copied answer. Values can vary between calls.
+
+## Locator and stage trade-off
+
+A positive hit means the **selected cell's center** lies in at least one annotated bounding box. This evaluates an area hypothesis, not the object's center or segmentation; a source bounding box can include background. Multiple matching instances are allowed. Prefix results reuse the same stage answers and are correlated ablations without the final candidate check.
+
+| Metric                                  | First-stage prefix | Two-stage prefix  | Full three stages |
+| --------------------------------------- | ------------------ | ----------------- | ----------------- |
+| Successful, including correct negatives | 46/60              | 31/60             | 27/60             |
+| Hits over all positive photos           | 39/50              | 24/50             | 20/50             |
+| Protocol failures                       | 1                  | 22                | 23                |
+| Unknown outcomes                        | 0                  | 0                 | 7                 |
+| False coordinates on absent targets     | 3/10               | 2/10              | 1/10              |
+| p50 / p95                               | 5.189 / 7.437 s    | 11.654 / 18.930 s | 13.642 / 22.229 s |
+| Median selected image-area fraction     | 6.25%              | 0.418%            | 0.513%            |
+
+For the full locator, 20 of 21 returned regions on positive photos hit a reference box. That conditional 95.24% excludes failures and abstentions; the result over **all 50 positives is 20/50**. Do not market the conditional percentage as overall accuracy. A larger first-stage region can achieve easier containment and does not offer the same spatial granularity.
+
+| Stratum (10 photos each) | Classification correct | First stage success | Two stages | Three stages |
+| ------------------------ | ---------------------- | ------------------- | ---------- | ------------ |
+| Baseline                 | 9                      | 10                  | 4          | 2            |
+| Repeated instances       | 9                      | 9                   | 6          | 5            |
+| Edge truncation          | 10                     | 9                   | 8          | 7            |
+| Absent target            | 7                      | 7                   | 7          | 7            |
+| Occlusion                | 10                     | 8                   | 4          | 3            |
+| Small target             | 10                     | 3                   | 2          | 3            |
+
+## Protocol correction and final smoke
+
+All 321 full-run HTTP responses were 200, with no timeouts. The strict adapter rejected 23 answers (`INVALID_RESPONSE`: stage 1 = 1, stage 2 = 21, stage 3 = 1). Their original raw rejected bodies were not saved. Therefore the cause of every rejection cannot be established retrospectively.
+
+Two later diagnostic calls on saved request inputs produced one 153-option response whose 0.01-rounded values sum to 0.99, and one valid five-option response. They are new independent responses, not recovered original failures. The final adapter preserves raw scores and accepts only explicitly annotated quantization whose half-step intervals admit unit probability mass. No prompts, crops, rankings or geometry were changed. The exact 153-option response is covered by a regression. See [API](api.md) and [probe evidence](evidence/protocol-probes.json).
+
+The final corrected runtime then completed a separate [smoke run](evidence/live-release-smoke-report.json): 2 dev photos + 2 dev texts, 14 HTTP calls, zero protocol failures. Photo classification was 1/2 for both library/native, texts 2/2 for both; localization returned one valid box hit and one `unknown`. This checks the corrected integration, **not a new full-corpus accuracy estimate**. The old failures remain unchanged. A full final-version quality benchmark remains future work within an explicitly funded run.
+
+## Calls, route and cost
+
+| Run               | HTTP calls | Known reported cost | Calls with unknown cost |
+| ----------------- | ---------- | ------------------- | ----------------------- |
+| Full live-v1      | 321        | $0.073546662        | 23                      |
+| Diagnostic probes | 2          | $0.001420734        | 0                       |
+| Final smoke       | 14         | $0.004080510        | 0                       |
+| Total             | 337        | $0.079047906        | 23                      |
+
+Adding the local $0.02 reservation for each unknown-cost call gives accounted exposure **$0.539047906**, not the actual final provider bill. The aggregate remains within the authorized 360-call / $1 diagnostic envelope. Local reservations do not enforce an account-wide spending cap.
+
+The 298 accepted full-run responses and all 14 smoke responses report `typesafe/jev-1.14-20261014` / TypeSafe; the adapter requests `typesafe/jev-1.14`, only TypeSafe, without fallback/retry. The two probes also used the fixed route. Missing metadata is never silently assumed to prove routing or zero cost. Pricing was checked against the [dated primary-source snapshot](evidence/jev-pricing-2026-10-18.json).
+
+Latencies include image preparation and benchmark artifact writes; measurements of the HTTP response headers alone are stored separately. They are not a service-level guarantee or evidence of sub-second localization.

package/docs/v02-usage.md

@@ -0,0 +1,162 @@
+# Region-seeded masks and extraction (0.2)
+
+The [accepted plan](0.2.0-plan.md) and [acceptance status](acceptance.md) distinguish implementation, offline checks, live quality and platform qualification. The frozen caller recipe passed admission with only 8/60 complete positive object boxes; 19/30 mask references had no prediction. Configure and test the model and segmenter for your own data. No text-image encoder qualified.
+
+The library does not select or connect a model. Supply a `DecisionPort` to `createClassifier`, either by implementing the port or explicitly constructing a provider adapter. The Luna examples below are reproducible integration recipes, not defaults or a claim that one model is always more accurate; stronger model capability does not guarantee monotonic accuracy gains. Optional local segmenters and proposal generators are configured separately, and their runtime packages and model assets remain the caller's responsibility.
+
+## Choose the operation
+
+| Operation                                               | Result                                                                       | Model requests                                 |
+| ------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------- |
+| `classify`                                              | One supplied class                                                           | One                                            |
+| `locate` (default / `mode: 'region'`)                   | A grid cell that may contain an object fragment                              | Up to three                                    |
+| `locate` with `mode: 'whole-object'` and `segmentation` | Visible bounds and center derived from a mask                                | Up to five, plus local segmentation/correction |
+| `extract` with `segmentation`                           | Mask-derived bounds, center, transparent PNG, cropped mask and source offset | Up to five, plus local segmentation/correction |
+
+The primary object workflow is the unchanged region locator followed by an explicitly configured segmenter. Segmentation receives the locator's seed prompt on the full EXIF-oriented source image; it does not receive a seed crop or treat the seed as an object box. Bounds and center come from actual foreground mask pixels. After the initial mask, a closed decision checks the original image with the actual mask box and original seed anchor: `complete`, `needs-expansion`, or `unknown`. It reuses the caller-supplied `DecisionPort`. An incomplete box permits one actual enclosing-mask correction and one final check; there is no separate extent search or generated model geometry. Default `locate` behavior remains compatible.
+
+## Primary workflow: region seed to mask-derived result
+
+Configure the caller's `DecisionPort` and local segmenter, then call `extract`:
+
+```ts
+const client = createClassifier({ decision, segmentation: segmenter })
+try {
+  const result = await client.extract({ image, target: 'the backpack' })
+  if (result.status === 'extracted') {
+    console.log(result.region, result.center, result.offset)
+    // result.png is transparent; result.mask contains the matching cropped binary mask.
+  } else {
+    console.log(result.status, result.reason)
+  }
+} finally {
+  try {
+    await client.dispose()
+  } finally {
+    await segmenter.dispose()
+  }
+}
+```
+
+`result.region` is the mask-derived half-open rectangle in source coordinates. `result.center` is its pixel center, and `result.offset` maps the cropped mask and PNG back to the source. Empty or seed-ungrounded masks return `unknown/segmentation-uncertain`; a locator rectangle is never substituted. The same unknown is returned when containment cannot be confirmed, expansion is unavailable, or the corrected mask still fails its check. Successful primary results use `method: 'region-checked-segmentation-v1'`. `verification.checks` retains the one or two closed decisions with raw scores/ranks and actual request metadata; `verification.expansion` reports `not-needed`, `unsupported`, `no-enclosing-mask`, `rejected-mask`, or `expanded`. Verification decision costs are included in `location.metadata`. A confirmed box is separate from pixel-perfect mask quality. Native and resource errors remain typed failures. `locate({ mode: 'whole-object' })` uses the same mask path when a segmenter is explicitly configured.
+
+The decision port, optional custom `segmentationBoxCheck`, and segmenter remain caller-owned. The classifier cancels and joins its operations but does not dispose an injected segmenter. Dispose both resources when the application owns both. Model/provider selection is also explicit; examples below show one caller-configured route, not a library default or accuracy guarantee.
+
+### Optional caller presence guard
+
+The tested v3 caller composition first classifies the target as `present` or `absent`, then calls `extract` only for `present`. This is caller logic: direct `extract` uses up to three region requests plus one or two containment checks; the guard adds one classification request. The [complete heldout comparison](evidence/v02/region-seeded-heldout-v3/README.md) preserves all errors and unknown outputs. Earlier v2 results predate containment checks and remain historical. A classification error remains an error; it must not be converted to absence. Keep both calls under one caller-owned absolute deadline and abort signal.
+
+```ts
+// image, target and signal are owned by this application's operation.
+const presence = await client.classify({
+  input: { image, text: target },
+  classes: [
+    { id: 'present', description: 'The target is visible in this image.' },
+    { id: 'absent', description: 'The target is not visible in this image.' },
+  ],
+  signal,
+})
+if (presence.choice === 'present') {
+  const result = await client.extract({ image, target, signal })
+  // Handle the actual result; do not substitute the seed for a failed mask.
+  console.log(result.status)
+}
+```
+
+This illustrates caller composition rather than a new package default. Exact benchmark tasks, prompts, timeouts, route and preserved failures are pinned in the historical [v2 development evidence](evidence/v02/region-seeded-dev-v2/README.md) and current [checked-flow v3 comparison](evidence/v02/region-seeded-dev-v3-control-r2/README.md). The latter records 6/30 positive whole-object box matches and 1/7 passing exact-canvas masks; it does not guarantee accurate cutouts for every object. Changing the caller's model, segmenter or prompt requires its own quality measurement.
+
+A baseline Linux CPU wiring smoke with the pinned MobileSAM assets used a synthetic 192×128 image. A colored rectangle produced a 2,800-pixel mask with bounds `[70, 34, 120, 90]`; an all-transparent input produced a full-size empty mask. Three child starts matched three closes. This verifies adapter wiring only, not photo accuracy.
+
+## Legacy interval and proposal strategies
+
+The earlier boundary-interval `whole-object` strategy and `objectProposals` mask-choice strategy remain optional legacy/research paths. They are not required by the primary seed-region segmentation workflow and have their own model-confirmation steps and historical evidence. The interval strategy asks closed Choices over integer boundaries after the region seed. Each axis has at most sixteen intervals plus `unknown`; up to three passes refine the intervals. It returns interval-derived geometry, not a segmented mask.
+
+The optional `objectProposals` adapter computes packed MobileSAM masks from nine seed points, then asks the configured model to select a supplied candidate and confirm its rectangle. Its box checks and mask quality are separate from direct seed-prompt segmentation. Default region and classification operations are unchanged.
+
+## Extract with an explicit local backend
+
+Core runtime dependencies remain Sharp and Zod. MobileSAM requires the optional peer:
+
+```sh
+npm install onnxruntime-node@1.23.2
+```
+
+Obtain the exact licensed assets yourself; [pinned sizes, SHA256 and provenance](evidence/v02/segmentation/README.md) are recorded separately. Asset files, optional ONNX Runtime installation and backend availability are caller-owned prerequisites; importing or configuring the package does not fetch model weights. Imports never download models or start workers. CPU is the default provider within this explicitly constructed adapter; `executionProvider: 'dml'` is an opt-in Windows route and fails when unavailable. No CPU/model fallback is attempted.
+
+```ts
+import { readFile, writeFile } from 'node:fs/promises'
+import { createClassifier } from 'zorya-classifier'
+import { createOpenRouterDecisions } from 'zorya-classifier/openrouter'
+import { createMobileSamSegmenter } from 'zorya-classifier/segmentation'
+
+const apiKey = process.env.OPENROUTER_API_KEY
+const encoderPath = process.env.MOBILE_SAM_ENCODER
+const decoderPath = process.env.MOBILE_SAM_DECODER
+if (!apiKey || !encoderPath || !decoderPath)
+  throw new Error('Configure credentials and asset paths')
+const segmenter = await createMobileSamSegmenter({
+  encoderPath,
+  decoderPath,
+  executionProvider: 'cpu',
+  threads: 2,
+})
+const client = createClassifier({
+  decision: createOpenRouterDecisions({
+    apiKey,
+    model: 'openai/gpt-6-luna-decisions',
+    provider: 'openai',
+  }),
+  segmentation: segmenter,
+})
+try {
+  const result = await client.extract({
+    image: await readFile('photo.jpg'),
+    target: 'the backpack',
+  })
+  if (result.status === 'extracted') {
+    await writeFile('backpack.png', result.png, { flag: 'wx' })
+    await writeFile('backpack.mask.u8', result.mask.data, { flag: 'wx' })
+    console.log(result.region, result.offset, result.mask.width, result.mask.height)
+  } else console.log(result.status, result.reason)
+} finally {
+  try {
+    await client.dispose()
+  } finally {
+    await segmenter.dispose()
+  }
+}
+```
+
+The mask is cropped to its visible bounds, row-major, one byte per pixel (`0` or `1`), with its own width/height and `format: 'binary-u8'`. `offset` maps its origin back to the source. PNG pixels inside the mask preserve source RGBA; pixels outside have zero RGBA. Transparent source pixels cannot substantiate an object. Invalid dimensions, nonbinary values, hard-ROI escape and masks missing the visible seed fail validation. Empty or ungrounded masks return `unknown/segmentation-uncertain`; a rectangle is never substituted for a mask. Protocol, native and resource errors remain typed failures.
+
+`createGrabCutSegmenter({ assetPath })` selects the separately supplied pinned OpenCV 4.13.0 JS asset. It does not require ONNX Runtime. This is an explicit alternate algorithm. A custom `SegmentationPort` can integrate other backends with the same validation.
+
+The caller owns a segmenter and may share it between clients. `client.dispose()` cancels and joins that client's operations without disposing the segmenter. Each `segment()` promise must remain pending until its own physical work settles, including cancellation. `segmenter.settle()` joins admitted work; `segmenter.dispose()` closes its own resources. Dispose both when the application owns both.
+
+Built-in adapters probe the backend on explicit factory calls and run each admitted inference in a fresh owned child. They currently do not reuse sessions: measured inference includes cold child/model startup. One active task and two waiters bound native work. Cancellation retains the slot through child close, with 250 ms grace before owned-child termination; each task has a 10-second native limit inside the client's absolute deadline. Consult measured evidence for latency-sensitive deployment.
+
+MobileSAM uses the seed region's center as a positive point on the full source and selects the mask with the greatest finite native quality score, using stable ties. It is a geometric point-prompt model; it does not interpret the target's text. Its raw quality score estimates a mask, not target identity or completeness. In the exposed development set it sometimes selected a part, such as a car's headlight, rather than the whole car. `status: 'extracted'` means that the returned mask and artifacts passed structural/source validation; it is not a semantic correctness guarantee. The [independent quality report](evidence/v02/region-seeded-dev-v2/README.md) measures that distinction. A caller-owned `SegmentationPort` can supply a different or text-guided backend without changing region search or connecting a model inside the library.
+
+## CLI
+
+Set explicit model/provider variables as in the [main guide](../README.md). Arguments are validated before native composition or model dispatch.
+
+```sh
+# Optional legacy interval-boundary location without an explicit segmenter.
+zorya-classifier locate photo.jpg 'the backpack' --mode whole-object
+# Primary region-seeded segmentation and cutout flow.
+zorya-classifier extract photo.jpg 'the backpack' --output backpack \
+  --backend mobile-sam --encoder /models/encoder.onnx --decoder /models/decoder.onnx
+zorya-classifier extract photo.jpg 'the backpack' --output backpack \
+  --backend grabcut --opencv /models/opencv.js
+```
+
+Successful extraction writes `<prefix>.png`, `<prefix>.mask.u8` and `<prefix>.json`. Destinations are reserved exclusively before writing; existing files are preserved. JSON contains dimensions, source geometry, metadata and file paths rather than serialized binary arrays. Output failure removes only destinations created by that operation. Parent directories must exist. SIGINT/SIGTERM cancels work and disposes CLI-owned resources.
+
+## Experimental text-only images
+
+The reserved selector is `representation: { type: 'experimental-text', profile: 'text-image-v1' }`. Public composition currently rejects image operations with `UNSUPPORTED` before dispatch because no encoder is qualified. Ordinary text classification remains usable.
+
+Research candidates compare normalized luma ASCII, color palette grids, SVG color runs, strict pixel RLE, binary/edge ASCII, and layered ASCII + SVG. No OCR, semantic helper or hidden vision call supplies object facts. Text adapters reject image parts rather than silently dropping them. Complete encoded views and metadata have a 64 KiB UTF-8 budget, allocated before encoding; output is never truncated to fit. Indistinguishable geometry returns a named unknown.
+
+Only a candidate that passes development selection and frozen independent heldout qualification may be promoted. Other candidates, bulk images and model weights stay outside npm. A grammar roundtrip or syntactically valid LLM answer alone does not qualify photo localization.