zorya-classifier 0.1.0 → 0.2.1

package/dist/processes/whole-object.js

@@ -0,0 +1,272 @@
+import { z } from 'zod';
+import { parse } from '../entities/contracts.js';
+import { assertActive, ClassifierError } from '../entities/errors.js';
+import { wholeObjectSchema } from '../entities/whole-object.js';
+import { validateDecision } from '../features/choice.js';
+import { targetState } from '../features/prompts.js';
+import { prepareBoundaryState } from './boundary-state.js';
+import { locateInput } from './locate.js';
+const axisOrder = ['left', 'right', 'top', 'bottom'];
+const boundaryResponseSchema = z
+    .object({
+    status: z.literal('known'),
+    interval: z.object({ start: z.number().int(), endExclusive: z.number().int() }).strict(),
+})
+    .strict();
+function partition(interval, tolerancePx, policy) {
+    const length = interval.endExclusive - interval.start;
+    if (!Number.isSafeInteger(length) || length < 1)
+        return [];
+    const count = policy === 'tolerance-aware-v1'
+        ? Math.min(16, Math.max(1, Math.ceil(length / tolerancePx)))
+        : Math.min(16, length);
+    return Array.from({ length: count }, (_, i) => {
+        const start = interval.start + Math.floor((i * length) / count);
+        const endExclusive = interval.start + Math.floor(((i + 1) * length) / count);
+        return { start, endExclusive };
+    });
+}
+function boundsFor(region) {
+    return {
+        left: { start: region.left, endExclusive: region.left + region.width },
+        right: { start: region.left, endExclusive: region.left + region.width },
+        top: { start: region.top, endExclusive: region.top + region.height },
+        bottom: { start: region.top, endExclusive: region.top + region.height },
+    };
+}
+function boundaryInstruction(axis) {
+    const edge = axis === 'left' ? 'left' : axis === 'right' ? 'right' : axis === 'top' ? 'top' : 'bottom';
+    return `Select the interval containing the ${edge}most visible pixel coordinate INSIDE HARD_ROI of the SAME physical instance identified by SEED. If the object continues outside HARD_ROI, locate only the visible intersection with that ROI; do not infer hidden parts. Coordinates use the original oriented source pixels. Choose only a supplied interval or unknown; do not infer free coordinates. The interval limits are half-open integer coordinate ranges. Current boundary intervals are candidate ranges, not new ROI limits.`;
+}
+function choicesFor(axis, current, tolerancePx, policy, showBoundaryView = false) {
+    const intervals = partition(current, tolerancePx, policy);
+    const labels = intervals.map((_, i) => `${axis}${String(i).padStart(2, '0')}`);
+    return {
+        intervals,
+        labels,
+        question: {
+            type: 'choice',
+            rankingSize: 1,
+            instructions: showBoundaryView
+                ? `${boundaryInstruction(axis)} A separate boundary view uses X/Y display labels. Use the exact display-label-to-choice mapping in the request state; still select only one supplied closed interval or unknown.`
+                : boundaryInstruction(axis),
+            criteria: {
+                ...Object.fromEntries(intervals.map((range, i) => [
+                    labels[i],
+                    `Integer boundary coordinates in [${range.start}, ${range.endExclusive}).`,
+                ])),
+                unknown: 'The same seeded instance or its boundary cannot be identified reliably.',
+            },
+        },
+    };
+}
+function sameInstanceQuestion() {
+    return {
+        type: 'choice',
+        rankingSize: 1,
+        instructions: 'Using ORIGINAL and SEED, determine whether extent answers can track the same single visible physical instance represented by SEED. If multiple indistinguishable instances could be the seed, or identity cannot be resolved, choose ambiguous. Select only one supplied answer.',
+        criteria: {
+            same: 'The visible extent can be tracked to the exact same physical instance represented by SEED.',
+            different: 'The apparent extent may belong to a different matching instance than SEED.',
+            ambiguous: 'The seeded instance is not uniquely identifiable in the scene.',
+        },
+    };
+}
+async function prepareState(raster, image, seed, target, exclusions, signal, representation) {
+    const seedImage = await raster.crop(image, seed, signal);
+    if (!representation) {
+        const original = await raster.imageState(image, signal);
+        const seedState = await raster.imageState(seedImage, signal);
+        return [...targetState(target, exclusions), 'ORIGINAL', ...original, 'SEED', ...seedState];
+    }
+    const views = [
+        {
+            id: 'source',
+            role: 'source',
+            image,
+            sourceRegion: { left: 0, top: 0, width: image.width, height: image.height },
+        },
+        { id: 'seed', role: 'crop', image: seedImage, sourceRegion: seed },
+    ];
+    const prepared = await representation.prepare({ source: image, views, signal });
+    return [
+        ...targetState(target, exclusions),
+        'ORIGINAL AND SEED GEOMETRY',
+        JSON.stringify({ seedRegion: seed }),
+        ...prepared.state,
+    ];
+}
+function resultMetadata(image, stages, durationMs) {
+    return {
+        image: { width: image.width, height: image.height, coordinateSpace: 'oriented-source-pixels' },
+        stages,
+        durationMs,
+        knownCostUsd: stages.reduce((sum, stage) => sum + (stage.costUsd ?? 0), 0),
+        unknownCostCount: stages.filter((stage) => stage.costUsd === null).length,
+    };
+}
+function unknown(reason, metadata) {
+    return { status: 'unknown', reason, metadata };
+}
+function intervalWidth(interval) {
+    return interval.endExclusive - interval.start;
+}
+function selectedChoice(result, question, keys) {
+    const answer = result.answers[question];
+    if (!answer || (answer.type !== 'choice' && answer.type !== 'ranked-choice'))
+        throw new ClassifierError('INVALID_RESPONSE', `Missing closed Choice answer for ${question}`);
+    if (answer.type === 'ranked-choice') {
+        const choice = answer.ranking[0];
+        if (!choice || !keys.includes(choice))
+            throw new ClassifierError('INVALID_RESPONSE', 'Unknown ranked interval');
+        return choice;
+    }
+    const maximum = Math.max(...keys.map((key) => answer.probabilities[key] ?? -Infinity));
+    const choice = keys.find((key) => answer.probabilities[key] === maximum);
+    if (!choice)
+        throw new ClassifierError('INVALID_RESPONSE', 'Closed Choice has no winner');
+    return choice;
+}
+function finalRegion(bounds, roi, source, seed) {
+    const { left, right, top, bottom } = bounds;
+    const x1 = left.start, x2 = right.endExclusive;
+    const y1 = top.start, y2 = bottom.endExclusive;
+    if (x1 >= x2 || y1 >= y2)
+        return undefined;
+    const region = { left: x1, top: y1, width: x2 - x1, height: y2 - y1 };
+    if (x1 < roi.left ||
+        y1 < roi.top ||
+        x2 > roi.left + roi.width ||
+        y2 > roi.top + roi.height ||
+        x2 > source.width ||
+        y2 > source.height ||
+        x1 >= seed.left + seed.width ||
+        y1 >= seed.top + seed.height ||
+        x2 <= seed.left ||
+        y2 <= seed.top)
+        return undefined;
+    return region;
+}
+/** Seed a physical instance, then narrow its four visible source-space boundaries with closed interval Choices. */
+export async function locateWholeObjectInput(input, decision, raster, signal, representation, boundaryView, intervalPolicy = 'fixed-16-v1') {
+    const started = performance.now();
+    const args = parse(wholeObjectSchema, input);
+    const normalized = await raster.normalize(args.image, signal);
+    const roi = args.roi ?? { left: 0, top: 0, width: normalized.width, height: normalized.height };
+    const seedInput = {
+        image: args.image,
+        target: args.target,
+        exclusions: args.exclusions,
+        roi,
+        mode: 'region',
+        ...(args.representation === undefined ? {} : { representation: args.representation }),
+    };
+    const stages = [];
+    const trackedDecision = {
+        async decide(request, callSignal) {
+            const result = await decision.decide(request, callSignal);
+            stages.push(result.metadata);
+            return result;
+        },
+    };
+    const metadata = () => resultMetadata(normalized, stages, performance.now() - started);
+    try {
+        const seedResult = await locateInput(seedInput, trackedDecision, raster, signal, undefined, representation);
+        if (seedResult.status !== 'located')
+            return { ...seedResult, metadata: metadata() };
+        const seed = seedResult.region;
+        let current = boundsFor(roi);
+        for (let pass = 0; pass < args.maxExtentPasses; pass++) {
+            assertActive(signal);
+            const specs = Object.fromEntries(axisOrder.map((axis) => [
+                axis,
+                choicesFor(axis, current[axis], args.boxTolerancePx, intervalPolicy, !!boundaryView && !representation),
+            ]));
+            const state = boundaryView && !representation
+                ? await prepareBoundaryState(raster, normalized, seed, args.target, args.exclusions, signal, boundaryView, roi, current, specs)
+                : await prepareState(raster, normalized, seed, args.target, args.exclusions, signal, representation);
+            const questions = Object.fromEntries(axisOrder.map((axis) => [axis, specs[axis].question]));
+            if (pass === 0)
+                questions['instance'] = sameInstanceQuestion();
+            const request = {
+                state: [
+                    ...state,
+                    JSON.stringify({
+                        pass: pass + 1,
+                        hardRoi: roi,
+                        seedRegion: seed,
+                        currentBounds: current,
+                    }),
+                ],
+                questions,
+            };
+            const answer = validateDecision(request, await trackedDecision.decide(request, signal));
+            assertActive(signal);
+            if (pass === 0) {
+                const identity = selectedChoice(answer, 'instance', ['same', 'different', 'ambiguous']);
+                if (identity !== 'same')
+                    return unknown('instance-ambiguous', metadata());
+            }
+            const next = { ...current };
+            for (const axis of axisOrder) {
+                const spec = specs[axis];
+                const selected = selectedChoice(answer, axis, [...spec.labels, 'unknown']);
+                if (selected === 'unknown')
+                    return unknown('extent-uncertain', metadata());
+                const chosen = spec.intervals[spec.labels.indexOf(selected)];
+                if (!chosen)
+                    throw new ClassifierError('INVALID_RESPONSE', 'Selected boundary interval is missing');
+                next[axis] = parse(boundaryResponseSchema, { status: 'known', interval: chosen }, 'INVALID_RESPONSE').interval;
+            }
+            if (boundaryView && !representation) {
+                const x1 = next.left.start;
+                const x2 = next.right.endExclusive;
+                const y1 = next.top.start;
+                const y2 = next.bottom.endExclusive;
+                if (x1 >= x2 ||
+                    y1 >= y2 ||
+                    x1 >= seed.left + seed.width ||
+                    x2 <= seed.left ||
+                    y1 >= seed.top + seed.height ||
+                    y2 <= seed.top)
+                    return unknown('extent-inconsistent', metadata());
+            }
+            current = next;
+            if (axisOrder.every((axis) => intervalWidth(current[axis]) <= args.boxTolerancePx))
+                break;
+        }
+        if (axisOrder.some((axis) => intervalWidth(current[axis]) > args.boxTolerancePx))
+            return unknown('extent-uncertain', metadata());
+        const bounds = current;
+        const region = finalRegion(bounds, roi, normalized, seed);
+        if (!region)
+            return unknown('extent-inconsistent', metadata());
+        const edgeLimited = bounds.left.start === roi.left ||
+            bounds.top.start === roi.top ||
+            bounds.right.endExclusive === roi.left + roi.width ||
+            bounds.bottom.endExclusive === roi.top + roi.height;
+        return {
+            status: 'located',
+            kind: 'whole-object',
+            seedRegion: { ...seed },
+            region,
+            normalizedRegion: {
+                left: region.left / normalized.width,
+                top: region.top / normalized.height,
+                width: region.width / normalized.width,
+                height: region.height / normalized.height,
+            },
+            bounds,
+            completeness: edgeLimited ? 'boundary-limited' : 'visible-object',
+            method: 'grid-object-extent-v1',
+            metadata: metadata(),
+        };
+    }
+    catch (error) {
+        if (error instanceof ClassifierError &&
+            error.code === 'RESOURCE_LIMIT' &&
+            error.details['component'] === 'representation')
+            return unknown('representation-limit', metadata());
+        throw error;
+    }
+}

package/dist/segmentation.d.ts

@@ -0,0 +1,10 @@
+/** Optional native adapters are composed here; importing types never starts native work. */
+export type { BinaryMask, SegmentationInput, SegmentationMetadata, SegmentationResult, SegmentationPort, ExtractionResult, } from './entities/segmentation.js';
+export { createMobileSamSegmenter } from './infrastructure/segmentation/mobile-sam/index.js';
+export type { MobileSamSegmenterOptions } from './infrastructure/segmentation/mobile-sam/index.js';
+export { createMobileSamObjectProposals } from './infrastructure/segmentation/mobile-sam/index.js';
+export type { MobileSamObjectProposalsOptions } from './infrastructure/segmentation/mobile-sam/index.js';
+export type { PackedBinaryMask, ObjectProposal, ObjectProposalInput, ObjectProposalBatch, ObjectProposalPort, } from './entities/object-proposals.js';
+export { packBinaryMask, unpackBinaryMask } from './features/segmentation/packed-mask.js';
+export { createGrabCutSegmenter } from './infrastructure/segmentation/grabcut/index.js';
+export type { GrabCutSegmenterOptions } from './infrastructure/segmentation/grabcut/index.js';

package/dist/segmentation.js

@@ -0,0 +1,4 @@
+export { createMobileSamSegmenter } from './infrastructure/segmentation/mobile-sam/index.js';
+export { createMobileSamObjectProposals } from './infrastructure/segmentation/mobile-sam/index.js';
+export { packBinaryMask, unpackBinaryMask } from './features/segmentation/packed-mask.js';
+export { createGrabCutSegmenter } from './infrastructure/segmentation/grabcut/index.js';

package/dist/shared/input-budget.d.ts

@@ -0,0 +1,7 @@
+/** Reserves active plus queued snapshots before allocating any owned byte copy. */
+export declare class InputBudget {
+    private readonly limit;
+    private retained;
+    constructor(limit: number);
+    reserve(bytes: number): () => void;
+}

package/dist/shared/input-budget.js

@@ -0,0 +1,21 @@
+import { ClassifierError } from '../entities/errors.js';
+/** Reserves active plus queued snapshots before allocating any owned byte copy. */
+export class InputBudget {
+    limit;
+    retained = 0;
+    constructor(limit) {
+        this.limit = limit;
+    }
+    reserve(bytes) {
+        if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > this.limit - this.retained)
+            throw new ClassifierError('CAPACITY', 'Owned input byte budget is full');
+        this.retained += bytes;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.retained -= bytes;
+        };
+    }
+}

package/docs/0.2.0-plan.md

@@ -0,0 +1,190 @@
+# Accepted 0.2 implementation plan
+
+Latest owner clarification, 2026-10-21: preserve the original three-Choice region search. Use its selected region only as a segmentation prompt on the **full oriented source image**, never as a crop limiting the object. Derive the cutout, bounding rectangle and its centre from actual foreground mask pixels. Then send the original image with that rectangle and a seed anchor to the caller's decision model, asking whether the entire visible seeded object fits inside. If not, request one actual enclosing mask from the segmenter and check its derived rectangle once more. No model-generated coordinates or separate extent search. The prepared v2 blind run is [cancelled before dispatch](evidence/v02/region-seeded-heldout-cancelled-before-dispatch-20261021-v2.json); its immutable freeze and earlier failures remain historical evidence. The sealed, undispatched cohort stays blind and can evaluate the corrected workflow after separately named development selection.
+
+Status: implementation, the corrected checked-flow resource protocol and the frozen v3 heldout admission are complete. The [current acceptance](acceptance.md) records the measured limits: 8/60 positive complete boxes, eight passing mask references out of 30, and no false seeds/cutouts on 20 negatives. The qualified recipe remains caller-owned; no text-only encoder qualified. Final archive/security/source-CI and registry publication evidence belongs to the release manifest. This document preserves the execution history below. Publication requires the final gates, not merely a successful build. The library never chooses a model/provider: benchmark routes such as Luna are explicit recipes, not defaults, and greater model capability does not guarantee monotonic accuracy improvement.
+
+The fresh text-only development comparison is now complete for the primary photo and independent real-UI strata: all six encoders have zero correct whole-object matches. The [preserved comparison](evidence/v02/fresh-text/README.md) includes the original classification harness defect, separate corrected classification follow-ups, representation-limit failures and false locations. No text candidate proceeds to blind qualification or public promotion.
+
+## Active completion goal and vision selection
+
+The owner explicitly activated the completion goal on 2026-10-20: finish this plan, close its acceptance gates, and choose the best qualified vision approach. The goal covers the standalone library and its authorized GitHub/npm release. Vision localization and experimental text-only image encodings are separate comparisons; a result from one does not qualify the other.
+
+The earlier qualification preparation used the box-confirmation recipe documented below. That preparation is historical and is superseded by the region-segmentation implementation described in the next section. The earlier [categorical neutral-instruction recipe](evidence/v02/categorical-vision-method-selection.json) used the [v4 frozen 80-case input/source closure](evidence/v02/categorical-heldout-run-freeze-20261020-v4.json). Its [dispatch authorization](evidence/v02/categorical-heldout-dispatch-authorization-20261020-v4.json) records 451 passing local tests, all four Windows/Linux CI jobs, installed-archive checks and the completed monotonic resource gate for that snapshot. Candidate80 and photo-only no-image40 completed serially before independent evaluation. The [v4 heldout result failed](https://github.com/zoomplus/zorya-classifier/blob/36818582091bfd19951631f358183bdb9ffd1e11/docs/evidence/v02/categorical-heldout-v4/README.md): one correct whole-object box on 60 positives, zero false locations on 20 negatives, and paired-photo interval [0, 0.10], whose lower bound must be positive. Classification is 69/80 and does not qualify localization. Initial mask coverage omitted the separately indexed references; differing annotation canvases remain explicit and cannot repair the box/paired result. This cohort is now exposed regression data. A changed method requires a separately named development comparison and a fresh blind cohort. Earlier experimental branches below are preserved history, not instructions to select a runner-up from the failed heldout.
+
+## Current checked region-segmentation implementation
+
+The latest owner correction supersedes the earlier prohibition on a post-segmentation model confirmation. It does not restore interval searching. A closed `box_check` Choice uses the fixed ordered IDs `complete`, `needs-expansion`, `unknown`, selecting the categorical maximum with stable ties and preserving scores. The source presentation marks the actual mask-derived rectangle and the original seed, so a photograph containing several matching objects still refers to the same physical instance. The prompt asks about visible containment, not unseen geometry or pixel-mask purity. Caller-injected models/providers remain mandatory; no model is connected by the library.
+
+Contracts: `SegmentationBoxCheckPort.check` receives full-source RGBA, actual `region`, original `seedRegion`, hard `roi`, target/exclusions and the operation signal. It returns a validated verdict, selection and actual request metadata. `SegmentationBoxPresentationPort` renders the bounded full-source presentation. `SegmentationPort.expand?` receives the original full-source segmentation input plus a full-source binary previous mask. Existing custom segmenters remain compatible: an initial complete result needs no expansion; an incomplete result without expansion support returns an explicit unknown. `SegmentationVerification` records both checks and whether expansion was unnecessary, unsupported, unavailable, rejected or applied.
+
+Runtime: retain one absolute deadline across region search, segmentation, verification, optional expansion and final verification. Permit at most two containment checks and one expansion. A corrected mask must preserve all prior visible foreground, add foreground and grow at least one actual box edge while respecting source/ROI/alpha. MobileSAM selects the smallest eligible native enclosing mask, then native quality and token order for deterministic ties. Native quality is not semantic confidence. Missing or unresolved correction yields `segmentation-uncertain`; never stretch a box or publish a partial cutout as complete. Derive bounds, centre, mask and PNG only after a complete check. Record verification costs with the region stages. Region-only localization remains unchanged.
+
+Transport preparation is mandatory after full-source box rendering. Inject the existing `RasterPort.imageState`, preserving all source content and recording scale/padding rather than sending raw arbitrary-size PNGs. Built-in transports validate prepared sides 280..1568; keep that validation. The added native/ordinary public-adapter regression found the first implementation's missing preparation on 64×48 and 1920×1080 inputs. Preserve the interrupted checked-flow resource attempt; repeat affected gates on corrected runtime bytes. Mask geometry remains in the full oriented source coordinate space.
+
+Implementation wave: root first commits shared contracts, rules and cancellation receipt; A5 then owns native request/worker/adapter expansion and focused tests in its own worktree; A6 owns the generic closed checker, full-source box/seed presentation and their tests in another worktree; root implements process/factory integration and operation/ownership tests. A3 keeps the existing resource run untouched as historical baseline and prepares checked-flow native/resource coverage separately. Merge focused tested commits before global checks. New DEV recipes count up to five model calls for extraction (three region plus two checks), or six with the benchmark's caller presence guard. Freeze source, prompt, routes, scheduling and budget before a new complete DEV comparison; do not relabel the old v2 results or open the unused blind cohort before selection.
+
+The integrated checked-flow runtime at `987ac32` passed installed-archive checks and [native Windows execution](evidence/v02/native-checked-region-windows-987ac32.json), with all ten owned children closed. The merged producer/evaluator fixture and freeze guard bring the offline suite to 563 passing tests at `29357d7`, including [all four hosted Windows/Linux × Node 22/24 jobs](evidence/v02/ci-29357d7.json). The [v3 development freeze](evidence/v02/region-seeded-development-freeze-20261021-v3.json) pins all 68 producer sources, the explicit route, prompts, native assets and budgets before the complete candidate/control comparison. Corrected-runtime two-hour resources and independent quality qualification remain pending; these platform checks do not qualify accuracy or publication. The [completed checked resource attempt](evidence/v02/checked-region-segmentation-resource-987ac32-receipt.json) retains valid measurements but failed its strict idle-before deadline by 0.377521 ms. Preserve that failure, repair the harness to await an absolute monotonic deadline without tolerance, test early timer resolution and cancellation, then repeat the full resource protocol on unchanged runtime bytes before blind dispatch.
+
+The complete v3 candidate is [scored independently](evidence/v02/region-seeded-dev-v3-candidate-only/README.md). The original paired evaluation stopped because the freeze reused the candidate prompt text when calculating the control identity. Preserve that failure and the unscored original control. A new [prospective control-R2 freeze](evidence/v02/region-seeded-development-control-r2-freeze-20261021.json) is verified from explicit per-profile prompt policies before repeating the complete control40. Reuse only the already frozen immutable candidate; do not rerun candidates to choose a better outcome. This corrects freeze authoring without changing the 68-file producer, runtime, model prompts or the sealed blind cohort.
+
+The complete R2 [paired seed comparison](evidence/v02/region-seeded-dev-v3-control-r2/README.md) passes development admission. The [conditional v3 method selection](evidence/v02/region-seeded-method-selection-20261021-v3.json) freezes that exact recipe before new blind pixels or per-case truth are opened. All 40 candidate cases, 40 R2 controls, provider failures, unknown charges and the first failed control identity remain preserved. Whole-object box and mask quality remain separately reported and low; no universal accuracy or release qualification is inferred from the seed-search statistic.
+
+The [new v3 blind freeze](evidence/v02/region-seeded-heldout-run-freeze-20261021-v3.json) retains all 80 unused cases and the unchanged truth/source seals. Candidate and control have separately reconstructed ordered JSON identities; an [independent metadata audit](evidence/v02/region-seeded-heldout-readiness-audit-20261021-v3.json) confirms them and preserves the first rejected zero-request draft. Both offline preflights verify 80/80 images. Model dispatch remains disabled until checked-flow two-hour resource acceptance and a separately recorded integrator GO. Evaluate truth only after both producer profiles are terminal, preserving every failed, unknown and unavailable result.
+
+The previous unverified region-segmentation version below remains baseline evidence; its source/platform/resource checks cannot qualify newly changed runtime bytes.
+
+The previous primary flow used the original three-Choice region locator followed by one explicitly supplied full-source segmenter. `extract` returned a cutout, mask-derived bounding rectangle and its centre; `locate` with a configured segmenter obtained the same mask-derived geometry. No separate extent search or model confirmation ran in that baseline. Default region localization stayed compatible, and the caller selected its model and segmenter. All 486 integrated offline tests and strict source/build/format checks passed at `c6b8069`. These are baseline checks, not evidence for the latest correction.
+
+The old box-confirmation dispatch was [cancelled before any provider call](evidence/v02/box-heldout-cancelled-before-dispatch-20261021-v1.json). Its undispatched 80-case cohort remains sealed for qualification after new development selection. In the replacement benchmark, original region hits and mask-derived object geometry are separate metrics. A genuine image-free control can compare region localization without a native segmenter; it must never claim a cell is a whole-object box. All previous failed variants and their unchanged scoring remain historical evidence below. Earlier statements about preparing or selecting the box-confirmation flow are superseded by this section and the owner's clarification above.
+
+The [first complete region-seeded DEV40](evidence/v02/region-seeded-dev-v1/README.md) failed its negative-case admission gate: one absent target produced a seed and a cutout. Its separately recorded classification correctly rejected that target. The separately named [presence-first v2 caller recipe](evidence/v02/region-seeded-development-freeze-20261021-v2.json) reuses the existing classification result and starts the unchanged region/segmentation workflow only after a successful `present` result. Absence and classification errors remain explicit, with no localization calls. This adds no model call and does not change the library's public `extract` or model selection. It supersedes the earlier classification-independent benchmark policy only for these explicitly named v2 profiles. Repeat all DEV40 candidate/control cases before selection; do not qualify from a post-hoc filter. The same heldout executable is prepared but remains unauthorized until the new development gate and independent freeze pass.
+
+The [complete v2 rerun passed development admission](evidence/v02/region-seeded-dev-v2/README.md), while its mask-derived box score remained 5/30. The [conditional development selection](evidence/v02/region-seeded-method-selection-20261021-v2.json) freezes that exact caller composition before opening the unused blind cohort. Its [new run freeze](evidence/v02/region-seeded-heldout-run-freeze-20261021-v2.json) measures the owner's region-first workflow: actual foreground in a seed is distinct from a complete object mask. The paired positive-photo gate compares exact reference-mask seed hits and separately labeled coarse seed-box hits against the identical image-free seed task. Mask-derived boxes retain IoU >= 0.5 and coverage >= 0.9; exact masks retain IoU >= 0.8. Neither whole-object success nor pixel-mask quality can be inferred from the seed statistic. All unknowns/errors, verified negatives and available reference masks remain in their respective denominators. Source/CI/resource gates remain mandatory, and a frozen recipe is not publication qualification.
+
+## Historical box-confirmation hypothesis (superseded before dispatch)
+
+The failed v4 positive funnel motivates a new implementation, not selection of another recipe from its revealed answers. The explicit proposal workflow will judge the actual foreground-derived bounding rectangle separately from pixel-mask completeness, and final confirmation will receive the one selected candidate at source resolution. No inferred coordinates, padding to annotations, color heuristics, model default or lower scoring threshold are added. The compatible region/interval workflow is unchanged.
+
+The separately named `native-luna-box-confirmation-sam-target-plus-neutral-v1` development profile retains the full original 20-photo/10-UI/10-map inputs, target-plus-neutral policy, explicit Luna/OpenAI route, pinned CPU MobileSAM assets, 120-second operation deadline, two case workers, one active/two waiting native jobs, two native threads, 8-pixel tolerance, three extent passes, at most six physical calls per case, and 300 calls / $5 / $0.05 unknown-cost reservation. It has no retry or fallback. Freeze the actual executable closure before dispatch and preserve the new identity in its independent evaluator. The old two-profile comparison and old heldout identities are not relabeled.
+
+A successful DEV gate precedes a new source-group-disjoint blind freeze; exposed v4 cases remain regression data. The two changed runtime files also require fresh resource and native installed-archive acceptance. The `450439c` monotonic two-hour run is active with explicit two native threads and no terminal result. Its interrupted one-thread setup attempt is retained and is not a pass. Fresh native Windows installed-archive checks and all four hosted CI jobs have passed for the changed runtime; final source checks remain mandatory. The [complete new DEV40 report](evidence/v02/box-confirmation-dev40/report.json) records 5/30 positive whole-object matches, photo 4/16, classification 35/40 and zero false locations on ten negatives. Mask evidence remains insufficient: one annotated case returned a prediction, neither of its two references passes IoU 0.8. The native-only refinement component test preserved all eight actual model-predicted boxes/seeds and original outputs. Its one annotated returned case still has zero passing mask references; no additional refiner is promoted. The [new development selection](evidence/v02/box-confirmation-method-selection-20261020-v1.json) freezes the box-confirmation recipe before acquisition of a fresh source-group-disjoint blind cohort. The native resource gate and new blind qualification remain pending.
+
+The [separate HELDOUT runner review](evidence/v02/box-heldout-source-review-20261020-v1.json) pins the complete 82-file dispatcher closure, including its indirect encoder imports and three metadata files. An independent TypeScript AST traversal confirms coverage; all 53 runtime sources remain byte-identical to `b03210a`. New candidate/control profiles have strict, separate identities, freeze validation and successful synthetic normalization checks. Historical plans/evaluators remain unchanged. [The sealed photo acquisition](evidence/v02/box-heldout-photo-seal-20261020-v1.json) has 30 positives with exact-canvas official masks and ten verified negatives, disjoint from all 160 exposed photo/source groups. The [controlled Calculator proof](evidence/v02/calculator-proof-root-review-20261020-v1.json) has been independently checked, and [its sealed UI20 cohort](evidence/v02/box-heldout-ui-seal-20261020-v1.json) has 15 positives and five verified negatives. The [controlled map20 seal](evidence/v02/box-heldout-map-seal-20261021-v1.json) and [combined corpus/asset seal](evidence/v02/box-heldout-combined-seal-20261021-v1.json) now pin the complete cohort. The [strict input/source freeze](evidence/v02/box-heldout-run-freeze-20261021-v1.json), SHA-256 `31e6b96b485b1dccbbe10b2c5e222ca0c20f3adbe25ee027a682595a136d8650`, is validated against all 82 producer files and the unchanged development selection. Resource completion, source-oracle integration and final source/CI review still precede any blind dispatch.
+
+The [excluded Wesnoth minimap proof](evidence/v02/wesnoth-proof-root-review-20261020-v1.json) independently verifies the source-derived placement: all 1,297 changed pixels fall inside the projected support of 51 markers, and repeated same-state minimap pixels are identical. Source-faithful float32 accumulator sampling resolves the three edge pixels missed by ideal-rational scaling. The projection remains an upper bound because later terrain can overpaint it; per-marker visible boxes require isolated A/B evidence. The controlled map20 now contains 15 isolated A/B/A positives and five source-verified negatives across 20 official map sources; original and canonical input pins are sealed. Its per-case oracle remains the independent curator's evidence, separate from this excluded proof. This is one actual rendered game/editor family, not diverse natural-game validation.
+
+## Historical vision investigation
+
+The earlier vision development wave compared the existing numeric boundary-interval baseline with visually labeled axis bands using the same closed intervals, source coordinates, instance grounding and geometric validity rules. Consider splitting axis questions only if the band presentation remains insufficient. Preserve the failed baseline, add allowlisted decision/geometry traces for new runs, and freeze each presentation/prompt variant before dispatch. The Luna Decisions route is one explicitly pinned benchmark candidate, not a library default.
+
+The historical source snapshot `a6c2683` passed 376 tests and hosted CI. Later integration passed 393 Linux tests, source/format/installed-archive checks, and [2922caf passed every Windows/Linux × Node 22/24 job](evidence/v02/ci-2922caf.json). Earlier archive-path and Windows test-path failures remain in evidence; neither repair weakened a scanner or changed runtime behavior. At that historical snapshot, all 53 runtime source files were unchanged from frozen snapshot `0c`; the replacement resource harness is separately pinned below. The supported 20-photo [screen report](evidence/v02/supported-vision-screen-20261020.md) does not replace the full DEV40 evaluation or authorize a winner. Do not declare qualification or publication from a screen.
+
+The [fresh interval comparison](evidence/v02/fresh-development.md) remains unqualified. A subsequent private diagnostic freezes MobileSAM point proposals from actual model-selected seed regions, renders every actual mask as an alias-only candidate, and lets Luna make one closed Choice plus a separate whole-target binary check. Source pixels produce candidate boxes; a language model never supplies coordinates. Raw native quality is not semantic confidence. Producer requests contain no case identifiers, source filenames, native quality, split or truth; early identifier-labeled sheets were rejected before any paid use and retained. Candidate replay and oracle upper bounds do not qualify an end-to-end implementation. Any promoted alternative still requires the same source/ROI ownership, one absolute operation deadline, final method contract, independent metrics, blind freeze and lifecycle gates.
+
+The axis-band candidate is opt-in through the internal benchmark composition, not the public default. Its rendering port receives only oriented source pixels, a source rectangle and closed candidate intervals; it never identifies objects. First-pass left/right share one X view and top/bottom share one Y view. Later passes zoom each boundary interval independently with 25% surrounding context, clipped to the hard ROI, while retaining original and seed images (at most six images per extent request). Display labels `X0…XF` / `Y0…YF` map explicitly to exact Choice IDs. The process validates returned PNG metadata, source transforms and candidate identity before dispatch. Text-only encodings ignore this renderer and continue to send zero image parts. Allowlisted traces retain selected IDs, raw native scores, actual seed/boundary geometry and transforms without recording images, request text or credentials.
+
+Whole-object variants share the existing IoU/visible-coverage criteria, independent annotations, errors/unknown denominators and false-location checks. The default region mode retains its fragment-localization semantics and is reported separately; a cell is not compared as if it were an object box. Compare MobileSAM and GrabCut on the same independently labeled masks, distinguishing oracle-box component tests from end-to-end extraction.
+
+Select eligible vision approaches by whole-object accuracy and reliability first, then p95 latency, actual request count and cost. Timings from concurrent native stress are diagnostic only. Keep the public tolerance contract and quality thresholds; parameter experiments must be explicitly named and frozen during development. Select and freeze the winning implementation before heldout evaluation, without choosing a new winner from revealed heldout outcomes.
+
+The original native resource run used frozen native/extraction/raster code from `8010aad`; that run is historical. New diagnostics and resource work proceed in separate worktrees. Final completion requires the source/archive/platform/resource gates and documented benchmark evidence. A build or a short smoke run alone does not complete the goal.
+
+The `8010aad` resource report is historical coverage of the earlier pipeline. The optional public packed-proposal path requires a new frozen two-hour run. Its first complete 40-case DEV run exposed a native input-validation defect: a repeated-group base64 regular expression throws `RangeError` on the admitted 1280×800 RGBA payload. This is independent of decision-model accuracy. The [before](evidence/v02/native-base64-before.json) and [after](evidence/v02/native-base64-after.json) offline reproductions pin the protocol source, sizes and zero provider/native calls. Native protocol validation now uses a bounded linear canonical-base64 scan, with large-payload, malformed-padding and nonzero-pad-bit regressions across the request/reply schemas. Preserve the failed DEV run; repeat the complete DEV pass on the repaired source before winner freeze, rather than repairing individual outcome rows. Then perform the new resource, archive and platform gates on the final runtime bytes.
+
+The repaired [DEV2 run](evidence/v02/dev2-proposal-evaluation.md) completed without recurrence of the protocol overflow. Its complete 40-case recipe was frozen before blind evaluation. The [80-case heldout evaluation](evidence/v02/heldout-evaluation-20261020.md) failed: 3/60 positive boxes, 2/20 false locations, and a paired photo bootstrap lower bound of zero. Preserve that failure and its original source, truth and output hashes. Do not choose a runner-up from its revealed outcomes. All 53 runtime source files remain unchanged from `0c365cb`; native Windows installed-archive checks apply to those same runtime bytes.
+
+Additional ordinary-model screens must distinguish unsupported API configurations from visual errors. Preserve the incomplete JSON-Schema Qwen screen and the ordinary-Luna 45-second timeout results. Probe actual multi-image route compatibility before an expanded run, without automatic format/model/provider fallback. A differently configured deadline or response format is a separately named and frozen development recipe; it does not repair earlier rows. The public default deadline remains 45 seconds. Timings collected while native stress is running are diagnostic and cannot rank latency. Keep per-case native metadata and physical request accounting independent when overlapping operations.
+
+The first proposal resource report used wall-clock phase accounting and could not prove the full physical duration. Its measurements remain historical. The replacement resource harness is frozen at `261dc23`: monotonic deadlines, at least 600 seconds warmup, 6,540 busy seconds, two 30-second idle windows, five-second samples, and an independent process/kernel-uptime witness. The complete replacement run passed its monotonic-duration, memory and owned-child gates; see [the pinned receipt](https://github.com/zoomplus/zorya-classifier/blob/36818582091bfd19951631f358183bdb9ffd1e11/docs/evidence/v02/proposal-resource-soak-261dc23.md). The earlier incomplete duration proof remains preserved. The public runtime itself already uses monotonic operation durations and owned deadline timers.
+
+The first split-port vision experiment assigned closed spatial Choices and independent Noul predicates to separate caller-supplied adapters. Its [DEV6 pilot failed](evidence/v02/split-choice-noul-dev6.md): classification 4/6, positive whole-object matches 0/2, zero false locations on four negatives and one failed negative localization. It is ineligible for full DEV40 dispatch; preserve its source, outputs, failures and unknown cost.
+
+The next offline composition assigns each binary predicate to a native closed Choice over `present`, `absent`, and `unknown`, while spatial Choice uses its separately configured adapter. Validate native scores and select a maximum with existing stable-tie rules, then return categorical `presence`; never fabricate a NoUL score or probabilities. Preserve the exact predicate/state/images and journal the actual transformed Choice request before conversion. A mixed request awaits both physical branches under one absolute deadline; failures cancel and join the sibling branch. Each route has its own physical/logical recorder and truthful receipts under one hard budget. Composite metadata must not invent a single model identity or duplicate costs. Use no fallback, game/color heuristics, or free model coordinates.
+
+These split-port experiments belong to examples and benchmark composition, with no built-in model/provider or modification of the frozen 53-file runtime. Their frozen six-case pilot gate requires at least one correct positive whole-object result and no false locations on four verified negatives; failed split profiles do not proceed to full DEV40. Freeze every controller, model, prompt, deadline, scheduling policy and native limit before dispatch.
+
+The next, distinct comparison uses one injected native DecisionPort for both original spatial Choices and converted categorical binary Choices in the same request. It preserves original spatial answers, maps only converted binary answers to categorical presence, and preserves the single actual request's metadata and receipt. This reduces the physical upper bound to six calls per case, including classification. Predeclare two full DEV40 profiles: (A) the original target plus neutral instruction suffix, and (B) the manifest target alone. The only removable suffix is the exact neutral procedural instruction present on the 20 photo inputs; reject any other nonempty instruction rather than discard task constraints. UI/map descriptions stay unchanged. This paired ablation tests the complete original DEV corpus rather than filtering a new native batch method on two difficult photos. Each profile has 300 physical calls / $5 / $0.05 unknown reserve, a 120-second operation budget, two case workers and the same pinned native limits/assets. Profiles run serially; runtime defaults stay unchanged. This protocol is recorded before either profile dispatches.
+
+Mandatory full DEV40 eligibility remains unchanged: all cases and failures count, and no false locations are allowed on its ten verified negatives. Qualification additionally requires the unchanged positive-box/mask criteria and a new source-group-disjoint blind 80-case cohort; no revealed heldout case may become fresh evidence. Keep new heldout truth and pixels sealed from producers until a new DEV candidate is frozen. Before a larger run, derive its worst-case physical-call bound and freeze sufficient explicit admission caps without weakening legacy budget tiers. Preserve all failed variants and never replace a revealed heldout failure with a runner-up.
+
+Both native categorical DEV40 profiles have now completed on frozen producer `e4f55ba`. Preserving the neutral instruction reached 3/16 photo whole-object matches; target alone reached 0/16. Both classify 35/40, with zero false locations on ten negatives. All eight and four respective 502 failures and unknown charges remain counted. [The development method selection](evidence/v02/categorical-vision-method-selection.json) freezes the first profile before any new heldout pixels or per-case truth are opened; concurrent timings are not used. Carry its 120-second deadline, two case workers, one active/two waiting native jobs, CPU threads, prompts and source transforms unchanged into blind qualification. The new run freeze must additionally bind the canonical 80 input pins, this method-selection digest and the actual executable producer closure. Source/CI, monotonic resource acceptance and independent oracle integrity remain prerequisites to blind dispatch. Development selection does not authorize publication or install a model/provider default.
+
+## Results and compatibility
+
+1. Preserve the default three-Choice region locator and its result shape. A grid cell is evidence of a fragment, never an object mask.
+2. Add explicit `mode: 'whole-object'`: seed search followed by closed boundary interval selection for one visible physical instance.
+3. Add `extract`: transparent PNG, binary mask, source-space box and offset. Segmenters are optional, explicit, caller-owned adapters; no rectangle fallback.
+4. Compare six text-only image encodings. Promote exactly one tested winner as `experimental-text` / `text-image-v1`; do not expose losing research implementations in the published archive.
+5. Support custom ports and generic OpenAI-compatible text transports. No provider/model fallback, fabricated probabilities or automatic native asset downloads.
+
+## Frozen S1 contracts
+
+Contracts live in `src/entities/{contracts,whole-object,representation,segmentation}.ts`. Public operation bytes are snapshotted before the first await. Validation uses Zod. Default timeout is one absolute 45-second deadline including queue time; cancellation never releases a physical slot early. Default admitted input-byte budget is 64 MiB and is reserved before copying.
+
+Whole-object input adds `boxTolerancePx` (1–64, default 8), `maxExtentPasses` (1–3, default 3). Success contains `kind: 'whole-object'`, `seedRegion`, conservative `region`, normalized region, four half-open `bounds` intervals, completeness (`visible-object` or `boundary-limited`), method and all stage receipts. Unknowns distinguish instance ambiguity, uncertain extent, inconsistent extent and representation limits. Old failures retain their meaning.
+
+Each extent API request asks four closed Choices: leftmost, rightmost, topmost and bottommost visible pixel of the same seeded instance. Partition each axis into at most 16 actual integer intervals plus `unknown`; recursively partition the selected interval. Never generate free coordinates. Stop within three passes when interval widths meet tolerance. If l∈[aL,bL) and r∈[aR,bR), the conservative horizontal extent is [aL,bR). Left/right intervals may coincide for a small object. Validate existence, source/ROI containment and seed intersection; do not sort, clamp or average invalid answers. Hard ROI boundaries limit visible completeness. Multiple indistinguishable seeded instances yield unknown.
+
+`ImageRepresentationPort.prepare` receives all views for one decision request at once. Every view has source region, role and optional code-generated grid metadata. Text encoders operate on clean pixels; rendered grid labels are metadata, not extra encoded pixel views. Deduplicate identical clean/grid regions. Bound all encoded views together to 64 KiB UTF-8, each string to 64,000 UTF-16 units, and ASCII/RLE resolution to at most 64×64. Allocate resolution before encoding; never truncate a final encoded string. Record dimensions, transforms and bytes. If distinct candidate geometry collapses at that resolution, report unknown rather than fabricate precision.
+
+`SegmentationPort.segment` receives canonical RGBA8, seed region, whole bounds, hard ROI, target/exclusions and signal. It returns a source-size binary-u8 mask plus actual backend/method/time/input dimensions or a named unknown. `settle` joins physical work; `dispose` closes only the adapter's own resources. Classifier joins its segment tasks but does not close an externally shared segmenter. Extraction crops by the mask box, zeros RGBA outside the mask, preserves source color/alpha inside it, and reports source offset. Validate binary values, dimensions, pixel cap, ROI and seed intersection. No fictitious confidence from native quality scores.
+
+## Encoders and strict codec
+
+Research candidates: `ascii-luma-v1`, `palette-grid-v1`, `svg-contours-v1`, `pixel-rle-v1`, `ascii-contours-v1`, `ascii-svg-layered-v1`.
+
+RLE grammar is versioned and deterministic:
+
+```text
+PIXEL_RLE_V1
+width=8 height=2
+color=RGBA8 order=row-major
+
+y0: #FF0000FF*5 #000000FF*3
+y1: #FFFFFFFF*8
+```
+
+Uppercase eight-hex RGBA, positive decimal run count, no crossing rows, exact row widths, ascending unique row numbers and exact height. Validate caps before allocating; no eval, exponent/fraction counts, duplicate rows or overflow. Roundtrip equality applies to the normalized raster, not the original photo before lossy resizing. Compare raw/PNG/text bytes and tokens; do not claim RLE always compresses photographs. Prompt ablation: no grammar, grammar only, grammar plus two synthetic examples. Examples contain no benchmark ground truth.
+
+Contour candidate: luma → p1/p99 contrast stretch → Otsu binary; independently Sobel → gradient threshold. Export BINARY and EDGES ASCII planes. Constant images must not divide by zero or invent edges. Replicate borders; distinguish transparency. Do not assume dark pixels are the target, discard small components or add morphological fitting. SVG derives from the original color raster, not thresholded pixels: at most 512 contours/2,048 vertices, no scripts, external URLs or foreignObject. Exceeding representable limits is explicit. Layered candidate sends both representations in one call, with common source geometry. Compare ASCII, SVG and layered evidence independently.
+
+Text-only localization uses no OCR, semantic model, hidden segmentation or image input. Neural `extract` is a separate explicitly reported workflow. Text factories reject image parts before fetch; they do not silently discard them.
+
+## Native segmentation and ownership
+
+Port universal utilities and algorithms from the game repository without `@element` imports or game DTOs. Add optional peer `onnxruntime-node@1.23.2`; core and segmentation entry imports do not initialize native sessions. Explicit CPU required; DML only when requested and available, with no CPU fallback. Default one owned child, at most two waiting jobs. IDs fence late results; parent loss stops owned children. A job has a 10-second native limit; abort gives 250 ms grace before killing only the owned child. Capacity releases after confirmed exit/settlement; poison the adapter if exit cannot be confirmed.
+
+Pinned Acly/MobileSAM revision `0d3b403339b4674a82493d5e97964dd78089ddc8`:
+
+| Asset                         |    Bytes | SHA256                                                           |
+| ----------------------------- | -------: | ---------------------------------------------------------------- |
+| mobile_sam_image_encoder.onnx | 28157093 | 580f5fb648ea1062c0aabc26217aed56921985f03f0cbbd852bba81d760cc749 |
+| sam_mask_decoder_multi.onnx   | 16496559 | 8976b90a87ba50a6a72217a5ff994f7d25ce16f2229fcc1ed259e1294c622ffe |
+
+Encoder takes HWC RGB float32 values 0–255 and performs normalization/padding itself. Prompt the whole box, preserve the seed separately for grounding. Preserve model/asset license and graph validation. OpenCV 4.13.0 JS (10,964,323 bytes, SHA256 `63366510248adf3a7eddf3e793dd825404efb7df3749f4d6f8557c7fa4ca8aa0`) is an explicit alternate backend, never silent fallback.
+
+## Work ownership and waves
+
+Root orchestrator: GPT-6.1 Sol / max. New implementation agents: GPT-6 Luna / high. At most three executors plus root. Each executor uses its own worktree, commits focused changes, reports SHA/files/tests/evidence/limitations and removes only its own temporary files/processes. Root alone changes shared contracts, factory, public exports, CLI, package/lock/config and root documentation. Coordinate shared files before edits. Global checks run on a stable merged tree.
+
+| Wave | Root                                               | Parallel executors                                                                     | Gate                               |
+| ---- | -------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------- |
+| 0    | baseline, plan, S1 contracts                       | A3 native audit, A5 protocol audit, A6 independent acceptance/corpus                   | S1 SHA                             |
+| 1    | review/contracts/byte ownership                    | A1 canonical pixels/transforms/RLE; A2 whole-object intervals; A3 segmentation/extract | focused checks, merge A1→A2→A3     |
+| 2    | integrate M1                                       | A4 other encoders; A5 text transports/requests; A6 independent corpus/evaluation       | M2 SHA                             |
+| 3    | public composition, CLI, clean packaging           | A2 integration fixes; A3 native fixes; A6 independent API/archive audit                | BENCH SHA                          |
+| 4    | freeze routes/prompts/budgets                      | A5 sole paid dev runner; A6 evaluator; A3 native fixtures outside latency measurements | winner freeze                      |
+| 5    | promote only winner, byte-parity check, clean dist | scoped fixes only                                                                      | RC1 SHA                            |
+| 6A   | freeze implementation                              | A5 heldout API run; A6 blind evaluation; A3 light prep                                 | public experiment gate             |
+| 6B   | native/resource integration                        | A3 Windows/Linux native; A6 resource audit; A5 docs                                    | resource gate                      |
+| 7    | classify fixes and rerun affected gates            | relevant owners                                                                        | fresh holdout if algorithm changes |
+| 8    | documentation, archive, GitHub/npm release         | independent final review                                                               | all mandatory checks               |
+
+A1 owns canonical normalization, transforms, representation budgets/RLE and tests. A2 owns extent geometry, prompts, orchestration and tests, using frozen ports/fakes. A3 owns explicit native backend workers, mask/PNG and extraction process, injected whole-locator port (no dependency on an unmerged implementation). A4 owns other research encoders and normalization ablations. A5 owns text protocol and exactly one paid dispatcher. A6 owns independent annotated corpus, oracle/evaluator, no-image payload checks and installed-consumer acceptance. An audit role can finish before a new executor takes the same concurrency slot; old inherited-model agents do not silently become Luna.
+
+## Evaluation and selection
+
+Existing exposed images are regression/development evidence only. Acquire source-group-disjoint licensed dev40 and heldout80, with independent labels/masks. Dev: photos16 positive/4 negative, maps7/3, UI7/3. Heldout: photos30/10, maps15/5, UI15/5. Synthetic UI cannot be reported as real UI. A missing annotation is not a negative. Keep labels outside producer inputs and hash/freeze manifests before paid calls.
+
+The controlled UI source oracle uses JSONL and measured pixel allocations, whereas the shared evaluator consumes normalized JSON arrays. The evaluator-only `canonical-ui-truth.ts` converter validates source identities, painted-edge confirmation, allocation agreement and scoped negative inventory evidence before conversion. Its tests use synthetic records; the HELDOUT oracle itself must not be opened or converted until the vision recipe is frozen. Preserve original oracle hashes and record the derived evaluator array separately. Never import this converter into a producer.
+
+Primary whole-object match requires IoU≥0.5 AND visible GT coverage≥0.9 for the same GT instance. Mask IoU≥0.8. Include unknown/errors/timeouts in denominators. Photo classification is a separate closed-label request and cannot feed localization. Text control receives no image or encoding. Pin exact DeepSeek Flash/Together text and Luna Decisions/OpenAI vision control routes; unavailable routes are not auto-replaced.
+
+All offline/security/privacy/resource/protocol gates and zero false locations on ten dev negatives are eligibility conditions. Rank eligible candidates lexicographically by photo localization, photo classification, lower p95, lower cost, then representation bytes. Freeze winner before heldout. Heldout gate: all mandatory checks, at most one false location on twenty negatives, and positive lower 95% paired-bootstrap bound versus no-image control on photo localization (10,000 resamples, fixed seed). Do not choose a runner-up on revealed holdout. If none qualifies, retain research evidence and leave public experimental release unqualified.
+
+One dispatcher counts physical API admissions separately from receipts; failed/missing receipts retain unknown cost. Use explicit hard run budgets despite broad owner authorization. Preserve failed/incomplete runs. Never log keys, raw private media or user sessions.
+
+## Final acceptance and documentation
+
+Run `npm run check`, `npm run pack:check`, `npm run format:check`; installed archive tests cover old/default behavior and new modes. Source/pack secret scanning remains strict. Clean dist before build; losing candidates/research corpora/native weights are absent from npm. Core import works without ONNX. Compare public promoted encoder byte-for-byte with the frozen benchmark winner.
+
+Offline cases: large/tiny/thin/edge/transparent/negative/multiple-instance objects, ROI/EXIF transforms, invalid intervals, stable ties, malicious RLE, constant normalization, overflow and byte budgets, cancellation at awaits, queue pressure, duplicate/late worker messages, worker exit/parent loss and caller-owned segmenter reuse. Timers, listeners, ports and owned processes reach zero after dispose. No early native-slot reuse.
+
+Resource run: two hours, ten-minute warmup, five-second snapshots, no forced GC; compare corresponding idle windows. Heap/external/arrayBuffers increase ≤max(10%,16MiB), RSS >max(20%,128MiB) requires investigation and rerun. Record actual host limits and platforms. Configured CI is not execution. Windows user game/install checks remain owned by the user and separate from this library.
+
+Update README/Russian README, API, architecture, operations, provenance/licenses, examples/CLI, benchmark/results, contributor rules and publication checklist. Preserve old reports. Release 0.2 only after mandatory qualification, not as an alias for incomplete work.
+
+The owner reconfirmed npm publication and discoverability on 2026-10-20. At release, update npm keywords and GitHub repository topics to match the capabilities actually qualified and shipped, create the version tag and release notes, publish the reviewed archive, and verify the registry version/dist-tag and GitHub/npm links. Update usage examples and measured-results documentation before publication. Do not tag an unqualified research method as a supported public feature.
+
+The replacement monotonic resource gate completed on frozen source `261dc23`: [duration, memory and owned-process evidence](https://github.com/zoomplus/zorya-classifier/blob/36818582091bfd19951631f358183bdb9ffd1e11/docs/evidence/v02/proposal-resource-soak-261dc23.md). The repaired `d684259` CI run passed all four Windows/Linux × Node 22/24 jobs. The categorical heldout producers and independent evaluator use separate explicit profile identities; a new freeze must pin their actual executable source and canonical inputs before any dispatch.