zorya-classifier 0.1.0 → 0.2.1

package/docs/evidence/v02/wesnoth-proof-root-review-20261020-v1.json

@@ -0,0 +1,76 @@
+{
+  "schema": "independent-wesnoth-excluded-proof-review-v1",
+  "sourceMapSha256": "41d2b65d3098c77c68d560832938c9e38bf2a549496e338cb158835ebbdff417",
+  "imageSha256": {
+    "a": "560f6f6fa5b69e0ff30f5416457f537ede44c2d023cd9096785ad98865d19c86",
+    "b": "cc7763407c1084802c3ab5e78c538ce7da6c7c1186d396c4daae6304bfabd569",
+    "a2": "0a89337c48966476368131328402d056940da7fefc67071e6883b825a5b27917"
+  },
+  "roiRawSha256": {
+    "a": "49416ea53f982154205b2a0e6c04deea74c5a34db6d3eddfa6e706793e14927a",
+    "b": "440809bfeff0badb16815394f64ee40b62d1c3ee904c3670e97bf927d40546e1",
+    "a2": "49416ea53f982154205b2a0e6c04deea74c5a34db6d3eddfa6e706793e14927a"
+  },
+  "captureSize": {
+    "width": 1024,
+    "height": 768
+  },
+  "contentRect": {
+    "left": 856,
+    "top": 11,
+    "width": 160,
+    "height": 212
+  },
+  "bitmapRoi": {
+    "left": 856,
+    "top": 11,
+    "width": 159,
+    "height": 212
+  },
+  "sameStateRoiByteIdentical": true,
+  "markerCount": 51,
+  "changedPixels": 1297,
+  "float32RepeatedSampler": {
+    "projectedPixels": 1363,
+    "deltaInside": 1297,
+    "outside": [],
+    "projectedUnchanged": 66,
+    "allMarkerProjectionsIntersectDelta": true,
+    "sampledSourceYAtRow53": 215,
+    "cursorAtRow53": 215.9999237060547
+  },
+  "idealRationalSampler": {
+    "projectedPixels": 1363,
+    "deltaInside": 1294,
+    "outside": [
+      [923, 64],
+      [924, 64],
+      [925, 64]
+    ],
+    "projectedUnchanged": 69,
+    "allMarkerProjectionsIntersectDelta": true,
+    "sampledSourceYAtRow53": 216
+  },
+  "providerCalls": 0,
+  "freshCohortImagesRead": false,
+  "freshCohortTruthRead": false,
+  "scope": "Excluded proof only. Projection is an upper bound, not an exact foreground mask; painter overdraw leaves projected pixels unchanged. Full-frame A/A2 stability is not claimed.",
+  "operatorSha256": "b37bfea4abeeb2b25c4fb630129bd1da483b798f5df8bba2846ca4e15c171a1f",
+  "rawReviewSha256": "c0e359dd2811ee90d1a356b7ac8357fd50d3bf2182f68380f249c40230c4928d",
+  "sourceTransform": {
+    "map": "Wesnoth 1.16.11 official 4p_Siege_Castles.map",
+    "rawGrid": [38, 38],
+    "defaultBorderSize": 1,
+    "unscaledBitmap": [648, 864],
+    "markerRect": "L=18*x-6; T=24*y+(odd(x)?0:-12); width=18; height=24; half-open",
+    "sampling": "float32(source/destination); float32 accumulator initialized0; truncation before each float32 addition",
+    "sourceAudit": "wesnoth-1.16.11-minimap-projection-source-audit.md"
+  },
+  "limits": [
+    "This proof is excluded from the new blind cohort.",
+    "Same-state stability is established only for the minimap bitmap ROI.",
+    "Whole-source projection covers markers, including pixels hidden by later terrain painting. It is not an exact foreground mask.",
+    "Controlled Wesnoth rendering is one source family; this is not a diverse natural-game accuracy benchmark.",
+    "No model request or localization accuracy was measured by this proof."
+  ]
+}

package/docs/operations.md

@@ -2,7 +2,7 @@
 
 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.
+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 and classify-image are supported; locate and extract are experimental and unqualified (see README capability table). 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.
 
@@ -10,6 +10,12 @@ Unknown cost remains unknown. Budget your own calls or use the benchmark's conse
 
 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.
+Owner handoff and authentication steps are in [publishing](publishing.md). Secret scanning commands and their limits are in [SECURITY](https://github.com/zoomplus/zorya-classifier/blob/main/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 experimental and 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](https://github.com/zoomplus/zorya-classifier/blob/main/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

@@ -1,5 +1,7 @@
 # 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.

package/docs/publishing.md

@@ -17,5 +17,20 @@ For later CI releases, configure [npm trusted publishing](https://docs.npmjs.com
 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.
 
-GitHub is sufficient to share source and accept contributions. npm is optional, but makes installation and versioned dependency management easier. The existing local archive can already be installed without either publication.
+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.
+
+## 0.2.1 release-candidate handoff
+
+This branch prepares a local **0.2.1 release candidate** from the published **0.2.0** package baseline. Only experimental status documentation, JSDoc, CLI help, the package description, and a test-only Git fixture isolation fix in `test/secrets.test.ts` changed. There are no model, default, or algorithm/runtime behavior changes relative to 0.2.0. At local 0.2.1 release-candidate preparation time, npm and GitHub publication for 0.2.1 had not yet been recorded in this handoff; check the repository releases, npm registry entry, and external release receipt for the current publication state.
+
+A failed pre-commit attempt during local release preparation is preserved in the maintainer’s local release-preparation logs. That failure led to the narrow test-only isolation fix so hook-provided `GIT_*` variables cannot redirect fixture repositories or mutate unrelated sentinel indexes during secret scans.

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/v02-usage.md

@@ -0,0 +1,164 @@
+# Region-seeded masks and extraction (0.2)
+
+Everything in this guide—default region `locate`, `locate({ mode: 'whole-object' })`, `extract`, optional `RefinementPort`, `SegmentationPort`, box-check composition, `objectProposals`, and exported native factories—is **experimental and unqualified** for general use. Passing structural or lifecycle checks does not establish semantic object accuracy or mask quality. Further accuracy experiments on these paths are stopped; no spatial or extraction strategy is promoted. Historical metrics in `docs/evidence/**` are unchanged.
+
+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                                               | Status       | Result                                                                       | Model requests                                 |
+| ------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------- | ---------------------------------------------- |
+| `classify`                                              | Supported    | One supplied class                                                           | One                                            |
+| `locate` (default / `mode: 'region'`)                   | Experimental | A grid cell that may contain an object fragment                              | Up to three                                    |
+| `locate` with `mode: 'whole-object'` and `segmentation` | Experimental | Visible bounds and center derived from a mask                                | Up to five, plus local segmentation/correction |
+| `extract` with `segmentation`                           | Experimental | 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.

package/docs/vision-results.md

@@ -1,6 +1,35 @@
 # Tested models and results
 
-Native decision models other than Jev are the primary integration. **Luna Decisions is the selected route:** it matched the historical photo/text counts on this corpus, while ordinary vision chat models remain configurable alternatives. This is an observed result on a small public corpus, not a statistical non-inferiority or universal-accuracy guarantee.
+## Current 0.2 region and extraction evidence
+
+Region `locate`, whole-object location, `extract`, proposal/refinement strategies, and native segmentation adapters are **experimental and unqualified** for general use; figures below are historical evidence for one documented recipe, not a promotion or universal accuracy claim. Further spatial accuracy experiments are stopped. H8 DEV recorded 7/9 positives with 2/3 false outputs and did not qualify.
+
+The final [frozen v3 heldout report](evidence/v02/region-seeded-heldout-v3/README.md) evaluates all 80 cases per profile. Classification is 65/80; positive seed hits 26/60; complete object boxes 8/60; false seeds and extractions 0/20 negatives. Of 30 exact-canvas mask references, eight pass IoU 0.8, three fail and 19 have no prediction. Both positive-photo paired seed intervals are [0.500, 0.833]. These are separate metrics; a successful seed or containment decision does not guarantee a tight mask. Candidate accounting includes 266 physical calls, two HTTP 502 failures and two unknown charges. The control made 80 image-free calls. This one controlled corpus admission and the resource/native checks qualify the documented recipe only; model choice stays with the caller. Development and failed historical evidence below is preserved.
+
+The primary 0.2 flow retains the original three-Choice region search and uses its seed to segment the full oriented source. Only actual mask pixels determine the cutout, bounds and center. The caller's decision port then sees the full image with the actual box and seed anchor, choosing `complete`, `needs-expansion`, or `unknown`. One actual enclosing-mask correction and one final check are allowed. Unresolved results remain unknown. The caller chooses both ports; no model-generated coordinates or separate extent search are added.
+
+The [checked-flow DEV v3 comparison](evidence/v02/region-seeded-dev-v3-control-r2/README.md) uses explicit Luna Decisions/OpenAI, CPU MobileSAM and a caller-side presence guard. The complete 40-case candidate and 40-case image-free control R2 use the same tasks. The first control's erroneous freeze identity is preserved separately and was not scored.
+
+| Measure                                         | Candidate                               | Image-free control R2               |
+| ----------------------------------------------- | --------------------------------------- | ----------------------------------- |
+| Classification                                  | 35/40                                   | 10/40                               |
+| Coarse positive seed-box intersections          | 18/30                                   | 0/30                                |
+| Whole-object box matches                        | 6/30                                    | Not produced                        |
+| False seeds / extractions on verified negatives | 0/10                                    | 0/10 seeds; no segmentation         |
+| Exact-canvas mask IoU ≥ 0.8                     | 1/7 references; 4 scored, 3 unavailable | Not produced                        |
+| Physical requests / known cost                  | 162 / $0.0645113; six unknown charges   | 40 / $0.0008353; no unknown charges |
+
+The positive-photo seed comparison is +0.625 with a fixed-bootstrap 95% interval [0.375, 0.875]. The exact-foreground comparison is available on only five photo pairs, with interval [0.4, 1.0]. These are seed-search metrics, not whole-object or mask accuracy. All failures and unavailable predictions remain in their stated denominators. The 16 extracted results include only six correct whole-object boxes; a containment decision is not proof of a tight or pixel-perfect mask. Timings under concurrent resource stress are not ranked. The [conditional method selection](evidence/v02/region-seeded-method-selection-20261021-v3.json) freezes this recipe for a new blind evaluation, not release qualification.
+
+The earlier [DEV v1](evidence/v02/region-seeded-dev-v1/README.md) failed its negative-case gate: 18/30 coarse seed-box intersections, 5/30 mask-derived box matches, one false seed/extraction on ten negatives and 1/7 exact-canvas masks reaching IoU 0.8. Its presence-first v2 successor passed development admission before the owner's containment-check revision. These earlier results remain distinct from v3.
+
+The same-seed native component comparison favored MobileSAM over GrabCut on the exposed v1 set: 5 versus 0 box matches among the 22 positive cases with predicted seeds, and 1 versus 0 passing mask references. This supplies development evidence for an explicitly configured backend, not universal superiority or end-to-end qualification. Current blind, native/resource and publication gates are tracked in [acceptance](acceptance.md). The historical 0.1 classification results below remain unchanged.
+
+## Historical 0.1 classification comparison
+
+The routes in this report are explicit benchmark configurations, not library defaults. The caller selects and connects every model through an injected `DecisionPort` or an adapter they configure. **Luna Decisions was the selected 0.1 classification recipe:** it matched the historical photo/text counts on this corpus, while ordinary vision chat models remain configurable alternatives. This is an observed result on a small public corpus, not a statistical non-inferiority or universal-accuracy guarantee.
+
+These classification results do not qualify the new 0.2 whole-object or extraction workflows. Their [current acceptance state](acceptance.md) records the failed first blind localization run and the remaining checks independently.
 
 The fixed corpus has60 licensed photos (20 development/40 heldout) and30 authored text fixtures (10/20). Ground truth never enters model requests. Errors stay in the accuracy denominator; unstarted cases remain unverified. Public images may overlap model training. Exact [summaries/source pins](evidence/vision-model-summary.json) and individual run reports below retain failures.
 
@@ -36,7 +65,7 @@ Native Luna was evaluated in two disjoint sessions:40 heldout photos+10 developm
 
 [Chat v1](evidence/vision-selection-v1-report.json) · [Chat v2](evidence/vision-selection-v2-report.json) · [Native first session](evidence/decisions-selection-v1-report.json) · [Native completion](evidence/decisions-completion-v1-report.json).
 
-## Localization remains experimental
+## Historical 0.1 localization smokes
 
 The first native locator smoke reached its fine stage but received a provider error. An explicit diagnostic replay of that exact195-option/nine-image fine request returned HTTP502: `OpenAI refused to answer question "selection"`. The [diagnostic receipt](evidence/luna-decisions-fine-probe.json) is preserved. This does not establish a documented universal option/image limit or authorize silently changing geometry; model refusal stays an error. A subsequent fixed flower-image smoke completed all three native stages in4.75s and returned a region; its [report](evidence/luna-decisions-locator-smoke-report.json) includes the reference-box metric. This one success does not erase the failed request or qualify the whole locator corpus. A valid classification result does not guarantee locator compatibility.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zorya-classifier",
-  "version": "0.1.0",
-  "description": "Provider-independent text/image classification and coarse-to-fine object localization for Node.js",
+  "version": "0.2.1",
+  "description": "Provider-independent classification with experimental localization and object extraction for Node.js",
   "type": "module",
   "license": "MIT",
   "engines": {
@@ -19,6 +19,10 @@
     "./openai-compatible": {
       "types": "./dist/openai-compatible.d.ts",
       "import": "./dist/openai-compatible.js"
+    },
+    "./segmentation": {
+      "types": "./dist/segmentation.d.ts",
+      "import": "./dist/segmentation.js"
     }
   },
   "bin": {
@@ -33,7 +37,7 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "lint": "eslint . --max-warnings 0",
     "format": "prettier --write .",
@@ -46,7 +50,7 @@
     "prepare": "husky",
     "secrets:check": "node scripts/secrets.mjs --worktree",
     "secrets:staged": "node scripts/secrets.mjs --staged",
-    "prepublishOnly": "npm run check && npm run pack:check"
+    "prepublishOnly": "npm run check && npm run pack:check && npm run format:check"
   },
   "dependencies": {
     "sharp": "0.34.5",
@@ -60,6 +64,7 @@
     "eslint-plugin-unicorn": "59.0.1",
     "husky": "9.1.7",
     "knip": "5.62.0",
+    "onnxruntime-node": "1.23.2",
     "prettier": "3.6.2",
     "tsx": "4.20.5",
     "typescript": "5.9.2",
@@ -78,14 +83,34 @@
     "classification",
     "image-classification",
     "object-localization",
+    "image-localization",
+    "bounding-box",
+    "object-extraction",
+    "image-segmentation",
+    "background-removal",
+    "decision-models",
+    "computer-vision",
+    "nodejs",
+    "llm",
     "openrouter",
     "typescript",
     "vision",
     "openai-compatible",
-    "multimodal"
+    "multimodal",
+    "mobile-sam",
+    "segment-anything",
+    "binary-mask"
   ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
+  },
+  "peerDependencies": {
+    "onnxruntime-node": "1.23.2"
+  },
+  "peerDependenciesMeta": {
+    "onnxruntime-node": {
+      "optional": true
+    }
   }
 }