zorya-classifier 0.0.0-stage → 0.2.0

package/dist/processes/whole-object.d.ts

@@ -0,0 +1,7 @@
+import type { DecisionPort, RasterPort } from '../entities/contracts.js';
+import type { ImageRepresentationPort } from '../entities/representation.js';
+import type { BoundaryViewPort } from '../entities/boundary-view.js';
+import type { WholeObjectLocateInput, WholeObjectLocalizationResult } from '../entities/whole-object.js';
+export type WholeObjectIntervalPolicy = 'fixed-16-v1' | 'tolerance-aware-v1';
+/** Seed a physical instance, then narrow its four visible source-space boundaries with closed interval Choices. */
+export declare function locateWholeObjectInput(input: Omit<WholeObjectLocateInput, 'signal'>, decision: DecisionPort, raster: RasterPort, signal: AbortSignal, representation?: ImageRepresentationPort, boundaryView?: BoundaryViewPort, intervalPolicy?: WholeObjectIntervalPolicy): Promise<WholeObjectLocalizationResult>;

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/choice-mass.d.ts

@@ -0,0 +1,2 @@
+/** Checks wire consistency, not informativeness or calibrated confidence. */
+export declare function acceptsChoiceMass(scores: readonly number[], step?: 0.01): boolean;

package/dist/shared/choice-mass.js

@@ -0,0 +1,19 @@
+/** Checks wire consistency, not informativeness or calibrated confidence. */
+export function acceptsChoiceMass(scores, step) {
+    if (scores.some((score) => !Number.isFinite(score) || score < 0 || score > 1))
+        return false;
+    const mass = scores.reduce((sum, score) => sum + score, 0);
+    if (Math.abs(mass - 1) <= 1e-6)
+        return true;
+    if (step !== 0.01)
+        return false;
+    let lower = 0;
+    let upper = 0;
+    for (const score of scores) {
+        if (Math.abs(score - Math.round(score / step) * step) > 1e-12)
+            return false;
+        lower += Math.max(0, score - step / 2);
+        upper += Math.min(1, score + step / 2);
+    }
+    return lower <= 1 + 1e-12 && upper >= 1 - 1e-12;
+}

package/dist/shared/gate.d.ts

@@ -0,0 +1,11 @@
+/** A slot is retained until the physical job's finally block calls release. */
+export declare class OperationGate {
+    private readonly capacity;
+    private readonly maxQueue;
+    private active;
+    private readonly queue;
+    constructor(capacity: number, maxQueue: number);
+    assertAvailable(): void;
+    acquire(signal: AbortSignal): Promise<void>;
+    release(): void;
+}

package/dist/shared/gate.js

@@ -0,0 +1,52 @@
+import { ClassifierError, assertActive } from '../entities/errors.js';
+/** A slot is retained until the physical job's finally block calls release. */
+export class OperationGate {
+    capacity;
+    maxQueue;
+    active = 0;
+    queue = [];
+    constructor(capacity, maxQueue) {
+        this.capacity = capacity;
+        this.maxQueue = maxQueue;
+    }
+    assertAvailable() {
+        if (this.active >= this.capacity && this.queue.length >= this.maxQueue)
+            throw new ClassifierError('CAPACITY', 'Operation queue is full');
+    }
+    async acquire(signal) {
+        assertActive(signal);
+        this.assertAvailable();
+        if (this.active < this.capacity) {
+            this.active++;
+            return;
+        }
+        await new Promise((resolve, reject) => {
+            const entry = {
+                signal,
+                resolve,
+                reject,
+                onAbort: () => {
+                    const index = this.queue.indexOf(entry);
+                    if (index < 0)
+                        return;
+                    this.queue.splice(index, 1);
+                    signal.removeEventListener('abort', entry.onAbort);
+                    reject(signal.reason);
+                },
+            };
+            this.queue.push(entry);
+            signal.addEventListener('abort', entry.onAbort, { once: true });
+            if (signal.aborted)
+                entry.onAbort();
+        });
+    }
+    release() {
+        this.active--;
+        const entry = this.queue.shift();
+        if (!entry)
+            return;
+        entry.signal.removeEventListener('abort', entry.onAbort);
+        this.active++;
+        entry.resolve();
+    }
+}

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/dist/shared/scope.d.ts

@@ -0,0 +1,12 @@
+export declare class OperationScope {
+    private readonly parent?;
+    readonly controller: AbortController;
+    readonly signal: AbortSignal;
+    readonly startedAt: number;
+    private readonly timer;
+    private readonly onAbort;
+    constructor(timeoutMs: number, parent?: AbortSignal | undefined);
+    guard(): void;
+    abort(): void;
+    dispose(): void;
+}

package/dist/shared/scope.js

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