zorya-classifier 0.2.1 → 0.2.2

package/dist/infrastructure/segmentation/mobile-sam/model-assets.d.ts

@@ -0,0 +1,8 @@
+export declare const encoderIdentity: Readonly<{
+    readonly bytes: 28157093;
+    readonly sha256: "580f5fb648ea1062c0aabc26217aed56921985f03f0cbbd852bba81d760cc749";
+}>;
+export declare const decoderIdentity: Readonly<{
+    readonly bytes: 16496559;
+    readonly sha256: "8976b90a87ba50a6a72217a5ff994f7d25ce16f2229fcc1ed259e1294c622ffe";
+}>;

package/dist/infrastructure/segmentation/mobile-sam/model-assets.js

@@ -0,0 +1,8 @@
+export const encoderIdentity = Object.freeze({
+    bytes: 28_157_093,
+    sha256: '580f5fb648ea1062c0aabc26217aed56921985f03f0cbbd852bba81d760cc749',
+});
+export const decoderIdentity = Object.freeze({
+    bytes: 16_496_559,
+    sha256: '8976b90a87ba50a6a72217a5ff994f7d25ce16f2229fcc1ed259e1294c622ffe',
+});

package/dist/infrastructure/segmentation/mobile-sam/object-proposals.d.ts

@@ -0,0 +1,7 @@
+import type { ObjectProposalPort } from '../../../entities/object-proposals.js';
+import { type MobileSamObjectProposalsOptions } from './options.js';
+/**
+ * Explicit CPU-only proposals: historical 3x3/36 default or opt-in seed-center/four.
+ * @experimental Native proposal adapter; unqualified for general spatial or mask accuracy.
+ */
+export declare function createMobileSamObjectProposals(options: MobileSamObjectProposalsOptions): Promise<ObjectProposalPort>;

package/dist/infrastructure/segmentation/mobile-sam/object-proposals.js

@@ -0,0 +1,124 @@
+import { performance } from 'node:perf_hooks';
+import { ClassifierError, assertActive } from '../../../entities/errors.js';
+import { objectProposalLimits } from '../../../entities/object-proposals.js';
+import { NativeChildPool } from '../native-child.js';
+import { verifyPinnedAsset } from '../verify-asset.js';
+import { probeBackend } from '../probe-backend.js';
+import { nativeErrorReplySchema, nativeObjectProposalReplySchema, } from '../native-protocol.js';
+import { decoderIdentity, encoderIdentity } from './model-assets.js';
+import { proposalOptionsSchema } from './options.js';
+import { snapshotProposalInput } from './input.js';
+/**
+ * Explicit CPU-only proposals: historical 3x3/36 default or opt-in seed-center/four.
+ * @experimental Native proposal adapter; unqualified for general spatial or mask accuracy.
+ */
+export async function createMobileSamObjectProposals(options) {
+    const checked = proposalOptionsSchema.safeParse(options);
+    if (!checked.success)
+        throw new ClassifierError('INVALID_INPUT', 'Invalid MobileSAM proposal options');
+    const parsed = checked.data;
+    try {
+        import.meta.resolve('onnxruntime-node');
+    }
+    catch {
+        throw new ClassifierError('UNSUPPORTED', 'onnxruntime-node is not installed');
+    }
+    await verifyPinnedAsset(parsed.encoderPath, encoderIdentity, 'MobileSAM encoder');
+    await verifyPinnedAsset(parsed.decoderPath, decoderIdentity, 'MobileSAM decoder');
+    const sourceWorker = import.meta.url.endsWith('.ts');
+    const workerUrl = new URL(sourceWorker ? '../native-worker.ts' : '../native-worker.js', import.meta.url);
+    // Probe the explicitly requested CPU provider in an owned child, disposing it before return.
+    const modelOptions = {
+        encoderPath: parsed.encoderPath,
+        decoderPath: parsed.decoderPath,
+        executionProvider: 'cpu',
+        threads: parsed.threads,
+    };
+    await probeBackend(workerUrl, 'mobile-sam', { options: modelOptions });
+    const pool = new NativeChildPool({
+        workerUrl,
+        maxActive: 1,
+        maxWaiting: 2,
+        jobTimeoutMs: 10_000,
+        abortGraceMs: 250,
+        encode: (job) => Buffer.from(JSON.stringify({ id: job.id, ...job.payload })),
+        decode: (raw, id) => {
+            const error = nativeErrorReplySchema.safeParse(raw);
+            if (error.success) {
+                if (error.data.id !== id)
+                    throw new ClassifierError('INVALID_RESPONSE', 'Native child error ID mismatch');
+                throw new ClassifierError(error.data.code, error.data.message);
+            }
+            const reply = nativeObjectProposalReplySchema.safeParse(raw);
+            if (!reply.success || reply.data.id !== id)
+                throw new ClassifierError('INVALID_RESPONSE', 'Native child returned invalid proposals');
+            return reply.data;
+        },
+    });
+    return {
+        async propose(input) {
+            const started = performance.now();
+            assertActive(input.signal);
+            let image;
+            const raw = await pool.runLazy(input.signal, () => {
+                const snapshot = snapshotProposalInput(input);
+                image = snapshot.image;
+                return {
+                    kind: 'mobile-sam-proposals',
+                    width: image.width,
+                    height: image.height,
+                    rgba: Buffer.from(image.data).toString('base64'),
+                    seedRegion: snapshot.seedRegion,
+                    roi: snapshot.roi,
+                    sampling: parsed.sampling,
+                    options: modelOptions,
+                };
+            });
+            const reply = nativeObjectProposalReplySchema.parse(raw);
+            const expectedCount = parsed.sampling === 'seed-center' ? 4 : 36;
+            if (reply.width !== image.width ||
+                reply.height !== image.height ||
+                reply.proposals.length !== expectedCount)
+                throw new ClassifierError('INVALID_RESPONSE', 'Proposal dimensions or candidate count do not match the request');
+            const expectedBytes = Math.ceil((image.width * image.height) / 8);
+            let aggregateBytes = 0;
+            const proposals = reply.proposals.map((proposal, index) => {
+                const expectedId = `C${String(index).padStart(2, '0')}`;
+                const bytes = Buffer.from(proposal.mask, 'base64');
+                aggregateBytes += bytes.byteLength;
+                if (proposal.id !== expectedId ||
+                    bytes.byteLength !== expectedBytes ||
+                    bytes.toString('base64') !== proposal.mask ||
+                    aggregateBytes > objectProposalLimits.packedBytes)
+                    throw new ClassifierError('INVALID_RESPONSE', 'Proposal masks are malformed or oversized');
+                const unusedBits = expectedBytes * 8 - image.width * image.height;
+                const allowed = unusedBits ? (1 << (8 - unusedBits)) - 1 : 255;
+                if ((bytes[expectedBytes - 1] & ~allowed) !== 0)
+                    throw new ClassifierError('INVALID_RESPONSE', 'Proposal mask has nonzero padding bits');
+                return {
+                    id: proposal.id,
+                    mask: {
+                        data: new Uint8Array(bytes),
+                        width: image.width,
+                        height: image.height,
+                        format: 'binary-lsb0',
+                    },
+                    qualityScore: proposal.qualityScore,
+                };
+            });
+            return {
+                proposals,
+                metadata: {
+                    method: parsed.sampling === 'seed-center'
+                        ? 'mobile-sam-seed-center-proposals-v1'
+                        : 'mobile-sam-nine-point-proposals-v1',
+                    backend: 'mobile-sam',
+                    durationMs: Math.max(0, performance.now() - started),
+                    input: { width: image.width, height: image.height },
+                },
+            };
+        },
+        settle: () => pool.settle(),
+        dispose: () => pool.dispose(),
+    };
+}

package/dist/infrastructure/segmentation/mobile-sam/options.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+export declare const optionsSchema: z.ZodObject<{
+    encoderPath: z.ZodString;
+    decoderPath: z.ZodString;
+    executionProvider: z.ZodDefault<z.ZodEnum<["cpu", "dml"]>>;
+    deviceId: z.ZodOptional<z.ZodNumber>;
+    threads: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    encoderPath: string;
+    decoderPath: string;
+    executionProvider: "cpu" | "dml";
+    threads: number;
+    deviceId?: number | undefined;
+}, {
+    encoderPath: string;
+    decoderPath: string;
+    executionProvider?: "cpu" | "dml" | undefined;
+    deviceId?: number | undefined;
+    threads?: number | undefined;
+}>;
+/** @experimental Options for the unqualified MobileSAM segmentation factory. */
+export type MobileSamSegmenterOptions = z.input<typeof optionsSchema>;
+export declare const proposalOptionsSchema: z.ZodObject<{
+    encoderPath: z.ZodString;
+    decoderPath: z.ZodString;
+    executionProvider: z.ZodDefault<z.ZodLiteral<"cpu">>;
+    threads: z.ZodDefault<z.ZodNumber>;
+    sampling: z.ZodDefault<z.ZodEnum<["seed-grid", "seed-center"]>>;
+}, "strict", z.ZodTypeAny, {
+    encoderPath: string;
+    decoderPath: string;
+    executionProvider: "cpu";
+    threads: number;
+    sampling: "seed-grid" | "seed-center";
+}, {
+    encoderPath: string;
+    decoderPath: string;
+    executionProvider?: "cpu" | undefined;
+    threads?: number | undefined;
+    sampling?: "seed-grid" | "seed-center" | undefined;
+}>;
+/** @experimental Options for the unqualified MobileSAM object-proposal factory. */
+export type MobileSamObjectProposalsOptions = z.input<typeof proposalOptionsSchema>;

package/dist/infrastructure/segmentation/mobile-sam/options.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+export const optionsSchema = z
+    .object({
+    encoderPath: z.string().min(1).max(4096),
+    decoderPath: z.string().min(1).max(4096),
+    executionProvider: z.enum(['cpu', 'dml']).default('cpu'),
+    deviceId: z.number().int().min(0).max(32).optional(),
+    threads: z.number().int().min(1).max(8).default(2),
+})
+    .strict();
+export const proposalOptionsSchema = z
+    .object({
+    encoderPath: z.string().min(1).max(4096),
+    decoderPath: z.string().min(1).max(4096),
+    executionProvider: z.literal('cpu').default('cpu'),
+    threads: z.number().int().min(1).max(8).default(2),
+    sampling: z.enum(['seed-grid', 'seed-center']).default('seed-grid'),
+})
+    .strict();

package/dist/infrastructure/segmentation/mobile-sam/proposal-masks.d.ts

@@ -0,0 +1,26 @@
+import type { NativeObjectProposalReply } from '../native-protocol.js';
+/** Produce either the historical 3x3 grid or one geometric-center prompt. */
+export declare function mobileSamProposalPoints(rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, sampling?: 'seed-grid' | 'seed-center'): Array<{
+    x: number;
+    y: number;
+}>;
+/** Turn one decoder response into four owned packed candidates immediately. */
+export declare function packMobileSamProposalCandidates(input: {
+    width: number;
+    height: number;
+    rgba: Uint8Array;
+    roi: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    pointIndex: number;
+    logits: Float32Array;
+    scores: Float32Array;
+}): NativeObjectProposalReply['proposals'];

package/dist/infrastructure/segmentation/mobile-sam/proposal-masks.js

@@ -0,0 +1,71 @@
+import { packBinaryMask } from '../../../features/segmentation/packed-mask.js';
+import { inside } from './segmentation-masks.js';
+/** Produce either the historical 3x3 grid or one geometric-center prompt. */
+export function mobileSamProposalPoints(rect, sampling = 'seed-grid') {
+    if (!Number.isSafeInteger(rect.left) ||
+        !Number.isSafeInteger(rect.top) ||
+        !Number.isSafeInteger(rect.width) ||
+        !Number.isSafeInteger(rect.height) ||
+        rect.left < 0 ||
+        rect.top < 0 ||
+        rect.width < 1 ||
+        rect.height < 1)
+        throw new Error('Invalid MobileSAM seed rectangle');
+    if (sampling !== 'seed-grid' && sampling !== 'seed-center')
+        throw new Error('Invalid MobileSAM proposal sampling profile');
+    if (sampling === 'seed-center')
+        return [{ x: rect.left + (rect.width - 1) / 2, y: rect.top + (rect.height - 1) / 2 }];
+    return Array.from({ length: 9 }, (_, index) => {
+        const row = Math.floor(index / 3);
+        const column = index % 3;
+        return {
+            x: rect.left + Math.round(((rect.width - 1) * column) / 2),
+            y: rect.top + Math.round(((rect.height - 1) * row) / 2),
+        };
+    });
+}
+/** Turn one decoder response into four owned packed candidates immediately. */
+export function packMobileSamProposalCandidates(input) {
+    const pixels = input.width * input.height;
+    if (!Number.isSafeInteger(input.width) ||
+        !Number.isSafeInteger(input.height) ||
+        input.width < 1 ||
+        input.height < 1 ||
+        pixels > 2_097_152 ||
+        input.rgba.length !== pixels * 4 ||
+        input.logits.length !== pixels * 4 ||
+        input.scores.length !== 4 ||
+        !Number.isInteger(input.pointIndex) ||
+        input.pointIndex < 0 ||
+        input.pointIndex > 8 ||
+        input.roi.left < 0 ||
+        input.roi.top < 0 ||
+        input.roi.width < 1 ||
+        input.roi.height < 1 ||
+        input.roi.left + input.roi.width > input.width ||
+        input.roi.top + input.roi.height > input.height)
+        throw new Error('Invalid MobileSAM proposal response dimensions');
+    const proposals = [];
+    for (let token = 0; token < 4; token++) {
+        const qualityScore = input.scores[token];
+        if (qualityScore === undefined || !Number.isFinite(qualityScore))
+            throw new Error('Invalid MobileSAM proposal quality score');
+        const mask = new Uint8Array(pixels);
+        const base = token * pixels;
+        for (let index = 0; index < pixels; index++) {
+            const value = input.logits[base + index];
+            if (value === undefined || !Number.isFinite(value))
+                throw new Error('Non-finite MobileSAM proposal logit');
+            if (value <= 0 || input.rgba[index * 4 + 3] === 0)
+                continue;
+            const x = index % input.width;
+            const y = Math.floor(index / input.width);
+            if (inside(input.roi, x, y))
+                mask[index] = 1;
+        }
+        const id = `C${String(input.pointIndex * 4 + token).padStart(2, '0')}`;
+        const packed = packBinaryMask(mask, input.width, input.height);
+        proposals.push({ id, mask: Buffer.from(packed.data).toString('base64'), qualityScore });
+    }
+    return proposals;
+}

package/dist/infrastructure/segmentation/mobile-sam/segmentation-masks.d.ts

@@ -0,0 +1,112 @@
+export declare function inside(rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, x: number, y: number): boolean;
+interface MaskCandidate {
+    token: number;
+    score: number;
+    mask: Uint8Array;
+}
+/** Sort by model quality and use decoder token order as a deterministic tie break. */
+export declare function selectBestMaskCandidate<T extends MaskCandidate>(candidates: readonly T[]): T | undefined;
+export declare function mobileSamSegmentationPrompt(input: {
+    prompt: 'whole-region' | 'seed-region';
+    seedRegion: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    wholeRegion: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    xScale: number;
+    yScale: number;
+}): {
+    coordinates: Float32Array<ArrayBuffer>;
+    labels: Float32Array<ArrayBuffer>;
+};
+export declare function collectMobileSamSegmentationCandidates(input: {
+    width: number;
+    height: number;
+    rgba: Uint8Array;
+    logits: Float32Array;
+    scores: Float32Array;
+    roi: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    seedRegion: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    prompt: 'whole-region' | 'seed-region';
+}): MaskCandidate[];
+export declare function selectMobileSamSegmentationMask(input: {
+    candidates: readonly MaskCandidate[];
+    width: number;
+    height: number;
+    prompt: 'whole-region' | 'seed-region';
+}): Uint8Array;
+interface EnclosingMobileSamCandidate {
+    token: number;
+    score: number;
+    mask: Uint8Array;
+    area: number;
+    bounds: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+}
+/** Full-source segmentation masks use the segmentation pixel cap, not the proposal cap. */
+export declare function packFullSourceBinaryMask(mask: Uint8Array, width: number, height: number): Uint8Array;
+/** Strictly decode the LSB-first full-source mask representation used by expansion IPC. */
+export declare function unpackFullSourceBinaryMask(data: Uint8Array, width: number, height: number): Uint8Array;
+/** Validate a prior full-source mask and return its foreground area and bounds. */
+export declare function validateMobileSamPreviousMask(input: {
+    width: number;
+    height: number;
+    rgba: Uint8Array;
+    previousMask: Uint8Array;
+    roi: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+}): {
+    area: number;
+    bounds: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+};
+/** Select the smallest actual decoder mask that strictly encloses prior foreground. */
+export declare function selectEnclosingMobileSamCandidate(input: {
+    width: number;
+    height: number;
+    rgba: Uint8Array;
+    logits: Float32Array;
+    scores: Float32Array;
+    previousMask: Uint8Array;
+    roi: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+}): EnclosingMobileSamCandidate | undefined;
+export {};

package/dist/infrastructure/segmentation/mobile-sam/segmentation-masks.js

@@ -0,0 +1,230 @@
+export function inside(rect, x, y) {
+    return x >= rect.left && y >= rect.top && x < rect.left + rect.width && y < rect.top + rect.height;
+}
+/** Sort by model quality and use decoder token order as a deterministic tie break. */
+export function selectBestMaskCandidate(candidates) {
+    return [...candidates].sort((a, b) => b.score - a.score || a.token - b.token)[0];
+}
+export function mobileSamSegmentationPrompt(input) {
+    if (input.prompt === 'whole-region')
+        return {
+            coordinates: Float32Array.of(input.wholeRegion.left * input.xScale, input.wholeRegion.top * input.yScale, (input.wholeRegion.left + input.wholeRegion.width) * input.xScale, (input.wholeRegion.top + input.wholeRegion.height) * input.yScale),
+            labels: Float32Array.of(2, 3),
+        };
+    const centerX = input.seedRegion.left + (input.seedRegion.width - 1) / 2;
+    const centerY = input.seedRegion.top + (input.seedRegion.height - 1) / 2;
+    const pointX = centerX * input.xScale;
+    const pointY = centerY * input.yScale;
+    return {
+        coordinates: Float32Array.of(pointX, pointY, pointX, pointY),
+        labels: Float32Array.of(1, -1),
+    };
+}
+export function collectMobileSamSegmentationCandidates(input) {
+    const pixels = input.width * input.height;
+    if (input.rgba.length !== pixels * 4 ||
+        input.logits.length !== pixels * 4 ||
+        input.scores.length !== 4)
+        throw new Error('Invalid MobileSAM decoder output dimensions');
+    const candidates = [];
+    for (let token = 0; token < 4; token++) {
+        const mask = new Uint8Array(pixels);
+        let seedHit = false;
+        for (let index = 0; index < pixels; index++) {
+            const value = input.logits[token * pixels + index];
+            if (value === undefined || !Number.isFinite(value))
+                throw new Error('Non-finite mask logit');
+            if (value <= 0)
+                continue;
+            const x = index % input.width;
+            const y = Math.floor(index / input.width);
+            if (!inside(input.roi, x, y))
+                continue;
+            if (input.prompt === 'seed-region' && input.rgba[index * 4 + 3] === 0)
+                continue;
+            mask[index] = 1;
+            if (inside(input.seedRegion, x, y))
+                seedHit = true;
+        }
+        const score = input.scores[token];
+        if (score === undefined || !Number.isFinite(score))
+            throw new Error('Non-finite MobileSAM quality diagnostic');
+        if (seedHit)
+            candidates.push({ token, score, mask });
+    }
+    return candidates;
+}
+export function selectMobileSamSegmentationMask(input) {
+    const best = selectBestMaskCandidate(input.candidates);
+    if (best)
+        return best.mask;
+    if (input.prompt === 'seed-region')
+        return new Uint8Array(input.width * input.height);
+    throw new Error('MobileSAM produced no seed-grounded mask');
+}
+/** Full-source segmentation masks use the segmentation pixel cap, not the proposal cap. */
+export function packFullSourceBinaryMask(mask, width, height) {
+    const pixels = Number.isSafeInteger(width) && Number.isSafeInteger(height) ? width * height : NaN;
+    if (!Number.isSafeInteger(width) ||
+        !Number.isSafeInteger(height) ||
+        width < 1 ||
+        height < 1 ||
+        !Number.isSafeInteger(pixels) ||
+        pixels > 16_777_216 ||
+        mask.length !== pixels)
+        throw new Error('Invalid full-source mask dimensions');
+    const packed = new Uint8Array(Math.ceil(pixels / 8));
+    for (let index = 0; index < pixels; index++) {
+        const value = mask[index];
+        if (value !== 0 && value !== 1)
+            throw new Error('Full-source mask is not binary');
+        if (value === 1)
+            packed[index >> 3] = (packed[index >> 3] ?? 0) | (1 << (index & 7));
+    }
+    return packed;
+}
+/** Strictly decode the LSB-first full-source mask representation used by expansion IPC. */
+export function unpackFullSourceBinaryMask(data, width, height) {
+    const pixels = Number.isSafeInteger(width) && Number.isSafeInteger(height) ? width * height : NaN;
+    const expectedBytes = Number.isSafeInteger(pixels) ? Math.ceil(pixels / 8) : NaN;
+    if (!Number.isSafeInteger(width) ||
+        !Number.isSafeInteger(height) ||
+        width < 1 ||
+        height < 1 ||
+        !Number.isSafeInteger(pixels) ||
+        pixels > 16_777_216 ||
+        data.length !== expectedBytes)
+        throw new Error('Invalid packed full-source mask dimensions');
+    const unusedBits = expectedBytes * 8 - pixels;
+    if (unusedBits > 0) {
+        const allowed = (1 << (8 - unusedBits)) - 1;
+        if (((data[expectedBytes - 1] ?? 0) & ~allowed) !== 0)
+            throw new Error('Packed full-source mask has nonzero padding bits');
+    }
+    const output = new Uint8Array(pixels);
+    for (let index = 0; index < pixels; index++)
+        output[index] = ((data[index >> 3] ?? 0) >> (index & 7)) & 1;
+    return output;
+}
+/** Validate a prior full-source mask and return its foreground area and bounds. */
+export function validateMobileSamPreviousMask(input) {
+    const pixels = Number.isSafeInteger(input.width) && Number.isSafeInteger(input.height)
+        ? input.width * input.height
+        : NaN;
+    if (!Number.isSafeInteger(input.width) ||
+        !Number.isSafeInteger(input.height) ||
+        input.width < 1 ||
+        input.height < 1 ||
+        !Number.isSafeInteger(pixels) ||
+        pixels > 16_777_216 ||
+        input.rgba.length !== pixels * 4 ||
+        input.previousMask.length !== pixels ||
+        !Number.isSafeInteger(input.roi.left) ||
+        !Number.isSafeInteger(input.roi.top) ||
+        !Number.isSafeInteger(input.roi.width) ||
+        !Number.isSafeInteger(input.roi.height) ||
+        input.roi.left < 0 ||
+        input.roi.top < 0 ||
+        input.roi.width < 1 ||
+        input.roi.height < 1 ||
+        input.roi.left + input.roi.width > input.width ||
+        input.roi.top + input.roi.height > input.height)
+        throw new Error('Invalid previous mask dimensions or ROI');
+    let area = 0;
+    let left = input.width;
+    let top = input.height;
+    let right = -1;
+    let bottom = -1;
+    for (let index = 0; index < pixels; index++) {
+        const value = input.previousMask[index];
+        if (value !== 0 && value !== 1)
+            throw new Error('Previous mask is not binary');
+        if (value === 0)
+            continue;
+        const x = index % input.width;
+        const y = Math.floor(index / input.width);
+        if (!inside(input.roi, x, y) || input.rgba[index * 4 + 3] === 0)
+            throw new Error('Previous mask foreground is outside visible ROI pixels');
+        area++;
+        left = Math.min(left, x);
+        top = Math.min(top, y);
+        right = Math.max(right, x);
+        bottom = Math.max(bottom, y);
+    }
+    if (area === 0)
+        throw new Error('Previous mask has no foreground');
+    return { area, bounds: { left, top, right, bottom } };
+}
+/** Select the smallest actual decoder mask that strictly encloses prior foreground. */
+export function selectEnclosingMobileSamCandidate(input) {
+    const pixels = input.width * input.height;
+    const previous = validateMobileSamPreviousMask(input);
+    if (input.logits.length !== pixels * 4 || input.scores.length !== 4)
+        throw new Error('Invalid MobileSAM decoder output dimensions');
+    let best;
+    let currentMask;
+    try {
+        for (let token = 0; token < 4; token++) {
+            const score = input.scores[token];
+            if (score === undefined || !Number.isFinite(score))
+                throw new Error('Non-finite MobileSAM quality diagnostic');
+            const mask = new Uint8Array(pixels);
+            currentMask = mask;
+            let area = 0;
+            let left = input.width;
+            let top = input.height;
+            let right = -1;
+            let bottom = -1;
+            let containsPrevious = true;
+            const base = token * pixels;
+            for (let index = 0; index < pixels; index++) {
+                const value = input.logits[base + index];
+                if (value === undefined || !Number.isFinite(value))
+                    throw new Error('Non-finite MobileSAM mask logit');
+                const x = index % input.width;
+                const y = Math.floor(index / input.width);
+                const foreground = value > 0 && input.rgba[index * 4 + 3] !== 0 && inside(input.roi, x, y);
+                if (input.previousMask[index] === 1 && !foreground)
+                    containsPrevious = false;
+                if (!foreground)
+                    continue;
+                mask[index] = 1;
+                area++;
+                left = Math.min(left, x);
+                top = Math.min(top, y);
+                right = Math.max(right, x);
+                bottom = Math.max(bottom, y);
+            }
+            const strictBoundsGrowth = left <= previous.bounds.left &&
+                top <= previous.bounds.top &&
+                right >= previous.bounds.right &&
+                bottom >= previous.bounds.bottom &&
+                (left < previous.bounds.left ||
+                    top < previous.bounds.top ||
+                    right > previous.bounds.right ||
+                    bottom > previous.bounds.bottom);
+            if (!containsPrevious || area <= previous.area || !strictBoundsGrowth) {
+                mask.fill(0);
+                continue;
+            }
+            const candidate = { token, score, mask, area, bounds: { left, top, right, bottom } };
+            if (!best ||
+                candidate.area < best.area ||
+                (candidate.area === best.area && candidate.score > best.score) ||
+                (candidate.area === best.area &&
+                    candidate.score === best.score &&
+                    candidate.token < best.token)) {
+                best?.mask.fill(0);
+                best = candidate;
+            }
+            else
+                mask.fill(0);
+        }
+        return best;
+    }
+    catch (error) {
+        currentMask?.fill(0);
+        best?.mask.fill(0);
+        throw error;
+    }
+}

package/dist/infrastructure/segmentation/mobile-sam/segmenter.d.ts

@@ -0,0 +1,22 @@
+import type { z } from 'zod';
+import type { SegmentationPort } from '../../../entities/segmentation.js';
+import { NativeChildPool } from '../native-child.js';
+import { type NativeSegmentationRequest } from '../native-protocol.js';
+import { optionsSchema, type MobileSamSegmenterOptions } from './options.js';
+type SerializedTask = (Omit<Extract<NativeSegmentationRequest, {
+    kind: 'mobile-sam';
+}>, 'id' | 'rgba'> & {
+    rgba: string;
+}) | (Omit<Extract<NativeSegmentationRequest, {
+    kind: 'mobile-sam-expand';
+}>, 'id' | 'rgba'> & {
+    rgba: string;
+});
+/**
+ * Explicit pinned MobileSAM inference in a separately owned Node child process.
+ * @experimental Native segmentation adapter; unqualified for general mask or object accuracy.
+ */
+export declare function createMobileSamSegmenter(options: MobileSamSegmenterOptions): Promise<SegmentationPort>;
+/** Internal adapter seam: pool ownership stays with the caller. */
+export declare function createMobileSamPortForPool(pool: Pick<NativeChildPool<SerializedTask>, 'runLazy' | 'settle' | 'dispose'>, parsed: z.output<typeof optionsSchema>): SegmentationPort & Required<Pick<SegmentationPort, 'expand'>>;
+export {};