zorya-classifier 0.1.0 → 0.2.0

package/NOTICE.md

@@ -6,6 +6,8 @@ Models, hosted APIs, Jev and OpenRouter are third-party services; each selected
 
 Direct runtime dependencies: Zod 3.25.76 (MIT), Sharp 0.34.5 (Apache-2.0). Sharp's separately installed native packages contain libvips and other libraries with their own notices, including LGPL terms; preserve the notices shipped with those packages when redistributing them. npm resolves and installs them separately; this archive does not bundle their binaries.
 
+The 0.2 optional MobileSAM adapter requires separately installed ONNX Runtime Node 1.23.2 (MIT) and separately obtained pinned Acly/MobileSAM ONNX assets. The archived MobileSAM model license is Apache-2.0. The explicit GrabCut adapter uses the separately obtained OpenCV 4.13.0 JS asset under its archived Apache-2.0 license. These assets and native binaries are not bundled or downloaded on import. See docs/evidence/v02/segmentation/provenance for license texts, source revision and artifact hashes. The library's MIT license does not replace these third-party licenses.
+
 Optional benchmark photographs are CC BY 2.0, Open Images annotations CC BY 4.0, and newly authored text fixtures MIT. Preserve benchmarks/corpus/ATTRIBUTION.md and each asset's attribution. Photographs and bulk upstream annotation CSVs are downloaded separately and excluded from the npm archive and source release archive.
 
 The public result JSON under docs/evidence also includes derived Open Images bounding-box annotations. These annotations remain CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); source: Open Images V7, https://storage.googleapis.com/openimages/web/index.html. Reference coordinates were normalized/joined for evaluation. Photo pixels are not included there.

package/README.md

@@ -1,11 +1,19 @@
 # Zorya Classifier
 
-Provider-independent text/image classification and coarse-to-fine object localization for Node.js and TypeScript. MIT application code. **Native decision models are the primary integration**, with Luna Decisions as the main example; ordinary vision language models are also supported without a native classification API.
+[![npm version](https://img.shields.io/npm/v/zorya-classifier)](https://www.npmjs.com/package/zorya-classifier)
 
-Use any image-capable instruction-following model through an OpenAI-compatible API, or implement the small `DecisionPort` for another protocol. OpenRouter is an optional adapter, not a mandatory service. Model compatibility and accuracy vary; see the exact [tested models/results](docs/vision-results.md), [acceptance](docs/acceptance.md), and historical [Jev baseline](docs/results.md).
+Provider-independent text/image classification and coarse-to-fine object localization for Node.js and TypeScript. MIT application code. The library never selects or connects a model for you: create a client with an explicit `DecisionPort`, either injected by your application or built with an adapter you configure. The model and provider shown in examples are examples, not defaults. Ordinary vision language models and native decision APIs are both supported.
+
+Use an explicitly configured image-capable model through a supported adapter, or implement the small `DecisionPort` for another protocol. OpenRouter is an optional adapter, not a mandatory service. A more capable model may help on a task, but model strength does not guarantee a monotonic accuracy improvement. Compatibility and quality vary; see the exact [tested models/results](docs/vision-results.md), [acceptance](docs/acceptance.md), and historical [Jev baseline](docs/results.md).
 
 [Русское руководство](docs/README.ru.md) · [API](docs/api.md) · [Architecture](docs/architecture.md) · [Benchmarks](docs/benchmarks.md)
 
+Version 0.2 adds region-seeded segmentation, mask-derived bounds and optional transparent cutouts, with a closed completeness check and one bounded mask expansion. See the [usage guide](docs/v02-usage.md) for contracts, backend ownership and CLI.
+
+The [frozen 80-case evaluation](docs/evidence/v02/region-seeded-heldout-v3/README.md) passed its predeclared admission criteria, but localization remains limited: 26/60 positive seed hits and 8/60 complete object boxes; no false seeds or cutouts on 20 negatives. Eight of 30 reference masks reached IoU 0.8, three failed and 19 had no predicted mask. These results describe one explicit caller-configured Luna/OpenAI + MobileSAM recipe, not every model or game.
+
+Six experimental encodings for text-only models were also tested on fresh photos and real UI captures. None qualified for image localization; see the [measured comparison](docs/evidence/v02/fresh-text/README.md). They remain research code rather than an advertised replacement for a vision model.
+
 ## Install
 
 Node.js 22.12+ is required. Source: [zoomplus/zorya-classifier](https://github.com/zoomplus/zorya-classifier). Package: [zorya-classifier](https://www.npmjs.com/package/zorya-classifier).
@@ -14,11 +22,11 @@ Node.js 22.12+ is required. Source: [zoomplus/zorya-classifier](https://github.c
 npm install zorya-classifier
 ```
 
-The release archive also installs with `npm install ./zorya-classifier-0.1.0.tgz`. Runtime dependencies are Zod and Sharp; model weights, Electron, a database and background services are not included.
+The release archive also installs with `npm install ./zorya-classifier-0.1.0.tgz`. Runtime dependencies are Zod and Sharp; model weights, Electron, a database and background services are not included. Optional local segmentation backends and their model assets are a separate responsibility of the caller; the library does not download or choose them.
 
-## Quickstart: Luna Decisions
+## Example: Luna Decisions
 
-This example uses the typed **Decisions API** with genuine Choice probabilities. Model and provider are explicit; there are no automatic retries or fallbacks. Jev is optional and is not used by this example.
+This example uses the typed **Decisions API** with genuine Choice probabilities. Model and provider are explicit; there are no automatic retries or fallbacks. It illustrates one integration and is not a library default. Jev is optional and is not used by this example.
 
 ```ts
 import { createClassifier } from 'zorya-classifier'
@@ -109,6 +117,10 @@ if (result.status === 'located') console.log(result.region)
 
 The locator uses up to three sequential calls: coarse 4×4 regions, fine grids in four padded regions, then four enlarged candidates. Coordinates come from code, never free-form model coordinates. Ordinary-model rankings select candidates; independent present/absent/unknown answers govern abstention. Multiple matching physical instances are allowed; one candidate is returned. Localization requires the model/endpoint to accept multiple images per call (up to nine); single-image-only endpoints can still support `classify`.
 
+## Extract a mask-derived object
+
+For a visible object box, center, or transparent cutout, use `extract` with an explicitly configured caller-owned segmenter. The existing region locator supplies a seed; the segmenter receives that seed while processing the full oriented source image. The library derives the returned box and center from actual mask pixels. After segmentation, the caller's decision port checks the original image with the mask-derived box and seed anchor. An incomplete box permits one enclosing-mask correction and one recheck; unresolved results remain unknown. This adds one or two closed checks to the normal region requests, without model-generated coordinates or an extent search. See the [0.2 usage guide](docs/v02-usage.md) and runnable [`extract-object.ts`](examples/extract-object.ts). The classifier and segmenter are separately caller-owned and both must be disposed.
+
 ## Development and limits
 
 ```sh
@@ -123,6 +135,6 @@ CLI uses explicit `ZORYA_MODEL` and defaults to `ZORYA_MODE=decisions`. OpenRout
 
 Tests are offline. Examples, CLI and explicitly authorized model benchmarks make paid calls. Default operation limits: 45-second absolute timeout, two active operations, sixteen waiters, bounded image/request/response sizes. Honor cancellation and call `dispose` on shutdown. The library has no import-time network request, hidden model switching or automatic retry.
 
-A model must understand the input, follow instructions and produce the checked answer shape. JSON Schema/JSON-object modes are opt-in when the chosen endpoint supports them; prompt-only mode does not require structured-output support. No universal accuracy, calibration or sub-second guarantee is asserted. Optional segmentation/refinement is a caller-owned `RefinementPort`.
+A model must understand the input, follow instructions and produce the checked answer shape. JSON Schema/JSON-object modes are opt-in when the chosen endpoint supports them; prompt-only mode does not require structured-output support. No universal accuracy, calibration or sub-second guarantee is asserted. Legacy region refinement uses `RefinementPort`; the 0.2 explicit `extract` workflow uses a caller-owned `SegmentationPort`.
 
 See [CONTRIBUTING](CONTRIBUTING.md), [SECURITY](SECURITY.md), [NOTICE](NOTICE.md), and [LICENSE](LICENSE).

package/dist/app/cli-arguments.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+declare const schema: z.ZodObject<{
+    command: z.ZodEnum<["classify-text", "classify-image", "locate", "extract"]>;
+    value: z.ZodString;
+    target: z.ZodString;
+    mode: z.ZodOptional<z.ZodEnum<["region", "whole-object"]>>;
+    output: z.ZodOptional<z.ZodString>;
+    backend: z.ZodOptional<z.ZodEnum<["mobile-sam", "grabcut"]>>;
+    encoder: z.ZodOptional<z.ZodString>;
+    decoder: z.ZodOptional<z.ZodString>;
+    opencv: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodEnum<["cpu", "dml"]>>;
+}, "strict", z.ZodTypeAny, {
+    value: string;
+    target: string;
+    command: "classify-text" | "classify-image" | "locate" | "extract";
+    mode?: "region" | "whole-object" | undefined;
+    provider?: "cpu" | "dml" | undefined;
+    output?: string | undefined;
+    backend?: "mobile-sam" | "grabcut" | undefined;
+    encoder?: string | undefined;
+    decoder?: string | undefined;
+    opencv?: string | undefined;
+}, {
+    value: string;
+    target: string;
+    command: "classify-text" | "classify-image" | "locate" | "extract";
+    mode?: "region" | "whole-object" | undefined;
+    provider?: "cpu" | "dml" | undefined;
+    output?: string | undefined;
+    backend?: "mobile-sam" | "grabcut" | undefined;
+    encoder?: string | undefined;
+    decoder?: string | undefined;
+    opencv?: string | undefined;
+}>;
+type CliArguments = z.infer<typeof schema>;
+export declare function parseCliArguments(args: string[]): CliArguments | {
+    command: 'help';
+};
+export {};

package/dist/app/cli-arguments.js

@@ -0,0 +1,67 @@
+import { parseArgs } from 'node:util';
+import { z } from 'zod';
+import { parse } from '../entities/contracts.js';
+import { ClassifierError } from '../entities/errors.js';
+const schema = z
+    .object({
+    command: z.enum(['classify-text', 'classify-image', 'locate', 'extract']),
+    value: z.string().min(1),
+    target: z.string().min(1),
+    mode: z.enum(['region', 'whole-object']).optional(),
+    output: z.string().min(1).optional(),
+    backend: z.enum(['mobile-sam', 'grabcut']).optional(),
+    encoder: z.string().min(1).optional(),
+    decoder: z.string().min(1).optional(),
+    opencv: z.string().min(1).optional(),
+    provider: z.enum(['cpu', 'dml']).optional(),
+})
+    .strict();
+export function parseCliArguments(args) {
+    let raw;
+    try {
+        raw = parseArgs({
+            args,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                mode: { type: 'string' },
+                output: { type: 'string' },
+                backend: { type: 'string' },
+                encoder: { type: 'string' },
+                decoder: { type: 'string' },
+                opencv: { type: 'string' },
+                provider: { type: 'string' },
+            },
+        });
+    }
+    catch {
+        throw new ClassifierError('INVALID_INPUT', 'Invalid CLI arguments; use --help');
+    }
+    if (raw.values['help'] || raw.positionals.length === 0)
+        return { command: 'help' };
+    if (raw.positionals.length !== 3)
+        throw new ClassifierError('INVALID_INPUT', 'Expected command, input and target/classes; use --help');
+    const { help: _help, ...values } = raw.values;
+    const parsed = parse(schema, {
+        ...values,
+        command: raw.positionals[0],
+        value: raw.positionals[1],
+        target: raw.positionals[2],
+    });
+    const nativeFlags = ['backend', 'encoder', 'decoder', 'opencv', 'provider', 'output'];
+    if (parsed.command !== 'extract' && nativeFlags.some((key) => parsed[key] !== undefined))
+        throw new ClassifierError('INVALID_INPUT', 'Native/output flags apply only to extract');
+    if (parsed.mode !== undefined && !['locate', 'extract'].includes(parsed.command))
+        throw new ClassifierError('INVALID_INPUT', 'Mode applies only to image localization');
+    if (parsed.command === 'extract') {
+        if (!parsed.output || !parsed.backend || parsed.mode === 'region')
+            throw new ClassifierError('INVALID_INPUT', 'extract requires --output and explicit --backend, and uses whole-object mode');
+        if (parsed.backend === 'mobile-sam' && (!parsed.encoder || !parsed.decoder || parsed.opencv))
+            throw new ClassifierError('INVALID_INPUT', 'mobile-sam requires --encoder and --decoder');
+        if (parsed.backend === 'grabcut' &&
+            (!parsed.opencv || parsed.encoder || parsed.decoder || parsed.provider))
+            throw new ClassifierError('INVALID_INPUT', 'grabcut requires --opencv; model/provider flags do not apply');
+    }
+    return parsed;
+}

package/dist/app/create-classifier.d.ts

@@ -1,14 +1,33 @@
 import type { ClassificationResult, ClassifyInput, DecisionPort, LocalizationResult, LocateInput, RefinementPort } from '../entities/contracts.js';
+import type { AnyLocateInput, WholeObjectLocateInput, WholeObjectLocalizationResult } from '../entities/whole-object.js';
+import type { WholeObjectIntervalPolicy } from '../processes/whole-object.js';
+import type { ImageRepresentationPort } from '../entities/representation.js';
+import type { ExtractInput, ExtractionResult, SegmentationPort } from '../entities/segmentation.js';
+import type { BoundaryViewPort } from '../entities/boundary-view.js';
+import type { ObjectProposalPort } from '../entities/object-proposals.js';
+import type { SegmentationBoxCheckPort } from '../entities/segmentation-verification.js';
 export interface ClassifierOptions {
     decision: DecisionPort;
     timeoutMs?: number;
     concurrency?: number;
     maxQueue?: number;
+    maxInputBytes?: number;
     refinement?: RefinementPort;
+    /** Caller-owned; classifier disposal never disposes a shared segmenter. */
+    segmentation?: SegmentationPort;
+    /** Optional caller-owned containment checker; by default reuses the injected decision port. */
+    segmentationBoxCheck?: SegmentationBoxCheckPort;
+    /** Explicit, caller-owned pixel-mask proposal strategy for whole-object operations. */
+    objectProposals?: ObjectProposalPort;
 }
 export interface Classifier {
     classify(input: ClassifyInput): Promise<ClassificationResult>;
+    locate(input: WholeObjectLocateInput): Promise<WholeObjectLocalizationResult>;
     locate(input: LocateInput): Promise<LocalizationResult>;
+    locate(input: AnyLocateInput): Promise<LocalizationResult | WholeObjectLocalizationResult>;
+    extract(input: ExtractInput): Promise<ExtractionResult>;
     dispose(): Promise<void>;
 }
 export declare function createClassifier(options: ClassifierOptions): Classifier;
+/** Internal benchmark composition. No research codec is exported by the npm entry points. */
+export declare function createResearchClassifier(options: ClassifierOptions, experimental?: ImageRepresentationPort, boundaryView?: BoundaryViewPort, intervalPolicy?: WholeObjectIntervalPolicy): Classifier;

package/dist/app/create-classifier.js

@@ -6,10 +6,28 @@ import { classifyInput } from '../processes/classify.js';
 import { locateInput } from '../processes/locate.js';
 import { OperationGate } from '../shared/gate.js';
 import { OperationScope } from '../shared/scope.js';
+import { InputBudget } from '../shared/input-budget.js';
+import { wholeObjectSchema } from '../entities/whole-object.js';
+import { locateWholeObjectInput } from '../processes/whole-object.js';
+import { preparedTextSchema, representationLimits } from '../entities/representation.js';
+import { extractSchema } from '../entities/segmentation.js';
+import { extractObject } from '../processes/extract.js';
+import { extractFromRegion } from '../processes/extract-from-region.js';
+import { createSharpCutoutRaster } from '../infrastructure/segmentation/cutout-raster.js';
+import { locateFromProposals } from '../processes/proposal-location.js';
+import { createSharpObjectProposalPresentation } from '../infrastructure/segmentation/proposal-presentation.js';
+import { createSegmentationBoxCheck } from '../features/segmentation/box-check.js';
+import { createSharpSegmentationBoxPresentation } from '../infrastructure/segmentation/box-presentation.js';
 const configSchema = z.object({
     timeoutMs: z.number().int().min(1).max(120000).default(45000),
     concurrency: z.number().int().min(1).max(4).default(2),
     maxQueue: z.number().int().min(0).max(32).default(16),
+    maxInputBytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(256 * 1024 * 1024)
+        .default(64 * 1024 * 1024),
 });
 function signalOf(value) {
     if (value === undefined)
@@ -19,17 +37,123 @@ function signalOf(value) {
     return value;
 }
 export function createClassifier(options) {
+    return composeClassifier(options);
+}
+/** Internal benchmark composition. No research codec is exported by the npm entry points. */
+export function createResearchClassifier(options, experimental, boundaryView, intervalPolicy) {
+    return composeClassifier(options, experimental, boundaryView, intervalPolicy);
+}
+function composeClassifier(options, experimental, boundaryView, intervalPolicy) {
     if (!options || typeof options.decision?.decide !== 'function')
         throw new ClassifierError('INVALID_INPUT', 'A DecisionPort is required');
+    const segmenter = options.segmentation;
+    const objectProposals = options.objectProposals;
+    if (segmenter !== undefined &&
+        (!segmenter ||
+            typeof segmenter.segment !== 'function' ||
+            (segmenter.expand !== undefined && typeof segmenter.expand !== 'function') ||
+            typeof segmenter.settle !== 'function' ||
+            typeof segmenter.dispose !== 'function'))
+        throw new ClassifierError('INVALID_INPUT', 'segmentation must implement SegmentationPort');
+    if (options.segmentationBoxCheck !== undefined &&
+        (!options.segmentationBoxCheck || typeof options.segmentationBoxCheck.check !== 'function'))
+        throw new ClassifierError('INVALID_INPUT', 'segmentationBoxCheck must implement its check port');
+    if (objectProposals !== undefined &&
+        (!objectProposals ||
+            typeof objectProposals.propose !== 'function' ||
+            typeof objectProposals.settle !== 'function' ||
+            typeof objectProposals.dispose !== 'function'))
+        throw new ClassifierError('INVALID_INPUT', 'objectProposals must implement ObjectProposalPort');
     const config = parse(configSchema, {
         timeoutMs: options.timeoutMs,
         concurrency: options.concurrency,
         maxQueue: options.maxQueue,
+        maxInputBytes: options.maxInputBytes,
     });
     const gate = new OperationGate(config.concurrency, config.maxQueue);
+    const inputBudget = new InputBudget(config.maxInputBytes);
     const raster = createSharpRaster();
+    const cutoutRaster = createSharpCutoutRaster();
+    const boxCheck = segmenter
+        ? (options.segmentationBoxCheck ??
+            createSegmentationBoxCheck({
+                decision: options.decision,
+                presentation: createSharpSegmentationBoxPresentation(),
+                imageState: raster.imageState,
+            }))
+        : undefined;
+    const proposalDependencies = objectProposals
+        ? {
+            decision: options.decision,
+            raster,
+            image: cutoutRaster,
+            proposals: objectProposals,
+            presentation: createSharpObjectProposalPresentation(),
+        }
+        : undefined;
     const owned = new Map();
     let disposed = false;
+    const textRepresentation = experimental
+        ? {
+            async prepare(input) {
+                const result = parse(preparedTextSchema, await experimental.prepare(input), 'INVALID_RESPONSE');
+                const bytes = result.state.reduce((sum, part) => sum + Buffer.byteLength(part, 'utf8'), 0);
+                if (bytes > representationLimits.totalBytes || bytes !== result.metadata.bytes)
+                    throw new ClassifierError('INVALID_RESPONSE', 'Representation byte accounting is inconsistent');
+                return {
+                    state: result.state,
+                    metadata: {
+                        ...result.metadata,
+                        views: result.metadata.views.map(({ content, ...view }) => ({
+                            ...view,
+                            ...(content === undefined ? {} : { content }),
+                        })),
+                    },
+                };
+            },
+        }
+        : undefined;
+    function representationFor(value) {
+        if (value?.type !== 'experimental-text')
+            return undefined;
+        if (!textRepresentation)
+            throw new ClassifierError('UNSUPPORTED', 'No text-image profile has passed release qualification yet');
+        return textRepresentation;
+    }
+    async function locateWhole(input, signal, representation) {
+        if (segmenter) {
+            const result = await extractRegion(input, signal, representation);
+            if (result.status === 'extracted')
+                return result.location;
+            if (result.status === 'unknown' && result.reason === 'segmentation-uncertain')
+                return {
+                    status: 'unknown',
+                    reason: 'segmentation-uncertain',
+                    metadata: 'metadata' in result ? result.metadata : result.location.metadata,
+                    ...(result.verification ? { verification: result.verification } : {}),
+                };
+            return result;
+        }
+        if (proposalDependencies) {
+            if (representation)
+                throw new ClassifierError('UNSUPPORTED', 'Mask proposal selection requires vision input');
+            return (await locateFromProposals(input, proposalDependencies, signal)).location;
+        }
+        return locateWholeObjectInput(input, options.decision, raster, signal, representation, boundaryView, intervalPolicy);
+    }
+    function extractRegion(input, signal, representation) {
+        if (!segmenter || !boxCheck)
+            throw new ClassifierError('UNSUPPORTED', 'Region extraction requires a SegmentationPort');
+        if (representation)
+            throw new ClassifierError('UNSUPPORTED', 'Checked segmentation requires vision input');
+        return extractFromRegion({ ...input, signal }, {
+            raster,
+            image: cutoutRaster,
+            segmenter,
+            boxCheck,
+            locateRegion: (source, { signal: operationSignal, ...request }) => locateInput({ ...request, image: source.bytes }, options.decision, raster, operationSignal, undefined, representation),
+        });
+    }
     async function run(signal, task) {
         if (disposed)
             throw new ClassifierError('DISPOSED', 'Classifier has been disposed');
@@ -58,6 +182,37 @@ export function createClassifier(options) {
         owned.set(scope, job);
         return job;
     }
+    async function locate(input) {
+        if (disposed)
+            throw new ClassifierError('DISPOSED', 'Classifier has been disposed');
+        gate.assertAvailable();
+        if (!input || typeof input !== 'object')
+            throw new ClassifierError('INVALID_INPUT', 'Expected locate input object');
+        const { signal, ...rest } = input;
+        const parent = signalOf(signal);
+        if (rest.mode === 'whole-object') {
+            const parsed = parse(wholeObjectSchema, rest);
+            const representation = representationFor(parsed.representation);
+            const release = inputBudget.reserve(parsed.image.byteLength);
+            try {
+                const snapshot = { ...parsed, image: new Uint8Array(parsed.image) };
+                return await run(parent, (s) => locateWhole(snapshot, s, representation));
+            }
+            finally {
+                release();
+            }
+        }
+        const parsed = parse(locateSchema, rest);
+        const representation = representationFor(parsed.representation);
+        const release = inputBudget.reserve(parsed.image.byteLength);
+        try {
+            const snapshot = { ...parsed, image: new Uint8Array(parsed.image) };
+            return await run(parent, (s) => locateInput(snapshot, options.decision, raster, s, options.refinement, representation));
+        }
+        finally {
+            release();
+        }
+    }
     return {
         async classify(input) {
             if (disposed)
@@ -68,27 +223,84 @@ export function createClassifier(options) {
             const { signal, ...rest } = input;
             const parent = signalOf(signal);
             const parsed = parse(classifySchema, rest);
-            const media = typeof parsed.input === 'string'
-                ? parsed.input
-                : {
-                    ...parsed.input,
-                    ...(parsed.input.image === undefined
-                        ? {}
-                        : { image: new Uint8Array(parsed.input.image) }),
-                };
-            return run(parent, (s) => classifyInput({ ...parsed, input: media }, options.decision, raster, s));
+            const hasImage = typeof parsed.input !== 'string' && parsed.input.image !== undefined;
+            const representation = hasImage ? representationFor(parsed.representation) : undefined;
+            const byteCount = typeof parsed.input === 'string'
+                ? Buffer.byteLength(parsed.input)
+                : (parsed.input.image?.byteLength ?? 0) + Buffer.byteLength(parsed.input.text ?? '');
+            const release = inputBudget.reserve(byteCount);
+            try {
+                const media = typeof parsed.input === 'string'
+                    ? parsed.input
+                    : {
+                        ...parsed.input,
+                        ...(parsed.input.image === undefined
+                            ? {}
+                            : { image: new Uint8Array(parsed.input.image) }),
+                    };
+                return await run(parent, (s) => classifyInput({ ...parsed, input: media }, options.decision, raster, s, representation));
+            }
+            finally {
+                release();
+            }
         },
-        async locate(input) {
+        locate,
+        async extract(input) {
             if (disposed)
                 throw new ClassifierError('DISPOSED', 'Classifier has been disposed');
             gate.assertAvailable();
             if (!input || typeof input !== 'object')
-                throw new ClassifierError('INVALID_INPUT', 'Expected locate input object');
+                throw new ClassifierError('INVALID_INPUT', 'Expected extract input object');
             const { signal, ...rest } = input;
             const parent = signalOf(signal);
-            const parsed = parse(locateSchema, rest);
-            const snapshot = { ...parsed, image: new Uint8Array(parsed.image) };
-            return run(parent, (s) => locateInput(snapshot, options.decision, raster, s, options.refinement));
+            const parsed = parse(extractSchema, rest);
+            if (!segmenter && !proposalDependencies)
+                throw new ClassifierError('UNSUPPORTED', 'extract requires an explicit SegmentationPort or ObjectProposalPort');
+            const representation = representationFor(parsed.representation);
+            const release = inputBudget.reserve(parsed.image.byteLength);
+            try {
+                const snapshot = { ...parsed, image: new Uint8Array(parsed.image) };
+                return await run(parent, (s) => {
+                    if (segmenter)
+                        return extractRegion(snapshot, s, representation);
+                    let prepared;
+                    // Per-operation ownership: no global selected-mask cache or second native inference.
+                    const selectedMask = {
+                        async segment() {
+                            if (!prepared?.mask || !prepared.segmentation)
+                                throw new ClassifierError('INVALID_RESPONSE', 'Proposal selection omitted its mask');
+                            return {
+                                status: 'segmented',
+                                mask: prepared.mask,
+                                metadata: prepared.segmentation,
+                            };
+                        },
+                        async settle() { },
+                        async dispose() { },
+                    };
+                    return extractObject({ ...snapshot, mode: 'whole-object', signal: s }, {
+                        raster,
+                        image: cutoutRaster,
+                        segmenter: selectedMask,
+                        locateWhole: async (source, { signal: requestSignal, ...request }) => {
+                            const wholeInput = {
+                                ...request,
+                                mode: 'whole-object',
+                                image: source.bytes,
+                            };
+                            if (!proposalDependencies)
+                                throw new ClassifierError('UNSUPPORTED', 'ObjectProposalPort is required');
+                            if (representation)
+                                throw new ClassifierError('UNSUPPORTED', 'Mask proposal selection requires vision input');
+                            prepared = await locateFromProposals(wholeInput, proposalDependencies, requestSignal);
+                            return prepared.location;
+                        },
+                    });
+                });
+            }
+            finally {
+                release();
+            }
         },
         async dispose() {
             disposed = true;

package/dist/app/extraction-files.d.ts

@@ -0,0 +1,9 @@
+import type { ExtractionResult } from '../entities/segmentation.js';
+/** Reserve every destination exclusively before writing; never overwrite an existing artifact. */
+export declare function writeExtractionFiles(prefix: string, result: Extract<ExtractionResult, {
+    status: 'extracted';
+}>): Promise<{
+    png: string;
+    mask: string;
+    descriptor: string;
+}>;

package/dist/app/extraction-files.js

@@ -0,0 +1,28 @@
+import { open, unlink } from 'node:fs/promises';
+/** Reserve every destination exclusively before writing; never overwrite an existing artifact. */
+export async function writeExtractionFiles(prefix, result) {
+    const files = { png: `${prefix}.png`, mask: `${prefix}.mask.u8`, descriptor: `${prefix}.json` };
+    const { png, mask, ...description } = result;
+    const descriptor = JSON.stringify({
+        ...description,
+        mask: { width: mask.width, height: mask.height, format: mask.format },
+        files,
+    }, null, 2);
+    const owned = [];
+    try {
+        for (const path of Object.values(files))
+            owned.push({ path, handle: await open(path, 'wx') });
+        for (const [index, bytes] of [png, mask.data, descriptor].entries())
+            await owned[index].handle.writeFile(bytes);
+        await Promise.all(owned.map(({ handle }) => handle.close()));
+        return files;
+    }
+    catch (error) {
+        const closed = await Promise.allSettled(owned.map(({ handle }) => handle.close()));
+        const removed = await Promise.allSettled(owned.map(({ path }) => unlink(path)));
+        const cleanupErrors = [...closed, ...removed].flatMap((outcome) => outcome.status === 'rejected' ? [outcome.reason] : []);
+        if (cleanupErrors.length)
+            throw new AggregateError([error, ...cleanupErrors], 'Extraction output and cleanup failed');
+        throw error;
+    }
+}

package/dist/cli.js

@@ -2,29 +2,73 @@
 import { readFile } from 'node:fs/promises';
 import { createClassifier } from './index.js';
 import { createCliDecision } from './app/cli-route.js';
+import { parseCliArguments } from './app/cli-arguments.js';
+import { writeExtractionFiles } from './app/extraction-files.js';
+import { createMobileSamSegmenter, createGrabCutSegmenter } from './segmentation.js';
 async function main() {
-    const [command, value, target] = process.argv.slice(2);
-    if (command === '--help' || !command) {
-        console.log('zorya-classifier classify-text <text> <classes.json>\nzorya-classifier classify-image <image> <classes.json>\nzorya-classifier locate <image> <target>\nSet ZORYA_MODEL. Default ZORYA_MODE=decisions; use chat for ordinary vision models/custom chat endpoints. OpenRouter: OPENROUTER_API_KEY + ZORYA_PROVIDER. Direct: ZORYA_ENDPOINT + optional ZORYA_API_KEY. Optional ZORYA_REASONING_EFFORT and ZORYA_RESPONSE_FORMAT. One classify request; up to three locate requests.');
+    const args = parseCliArguments(process.argv.slice(2));
+    if (args.command === 'help') {
+        console.log('zorya-classifier classify-text <text> <classes.json>\nzorya-classifier classify-image <image> <classes.json>\nzorya-classifier locate <image> <target> [--mode region|whole-object]\nzorya-classifier extract <image> <target> --output <prefix> --backend mobile-sam --encoder <path> --decoder <path> [--provider cpu|dml]\nzorya-classifier extract <image> <target> --output <prefix> --backend grabcut --opencv <path>\nSet ZORYA_MODEL. Default ZORYA_MODE=decisions; use chat for ordinary vision models/custom chat endpoints. OpenRouter: OPENROUTER_API_KEY + ZORYA_PROVIDER. Direct: ZORYA_ENDPOINT + optional ZORYA_API_KEY. Optional ZORYA_REASONING_EFFORT and ZORYA_RESPONSE_FORMAT. One classify request; up to three region or six whole-object requests. Extraction additionally runs the explicit local backend. Output files are never overwritten; native assets are never downloaded automatically.');
         return;
     }
-    if (!['classify-text', 'classify-image', 'locate'].includes(command) || !value || !target)
-        throw new Error('Invalid arguments; use --help');
-    const client = createClassifier({ decision: createCliDecision(process.env) });
+    const { command, value, target } = args;
+    const decision = createCliDecision(process.env);
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    process.once('SIGINT', abort);
+    process.once('SIGTERM', abort);
+    let segmenter;
+    let client;
     try {
-        if (command === 'locate')
-            console.log(JSON.stringify(await client.locate({ image: await readFile(value), target }), null, 2));
-        else {
+        // Validate local data before creating a native worker or dispatching any model request.
+        const image = command === 'classify-text' ? undefined : await readFile(value);
+        let classes;
+        if (command === 'classify-text' || command === 'classify-image') {
             const { z } = await import('zod');
-            const { classSchema } = await import('./entities/contracts.js');
+            const { classSchema, limits } = await import('./entities/contracts.js');
             const unknownClasses = JSON.parse(await readFile(target, 'utf8'));
-            const classes = z.array(classSchema).parse(unknownClasses);
-            const input = command === 'classify-text' ? value : { image: await readFile(value) };
-            console.log(JSON.stringify(await client.classify({ input, classes }), null, 2));
+            classes = z.array(classSchema).min(2).max(limits.maxClasses).parse(unknownClasses);
+        }
+        controller.signal.throwIfAborted();
+        if (command === 'extract')
+            segmenter =
+                args.backend === 'mobile-sam'
+                    ? await createMobileSamSegmenter({
+                        encoderPath: args.encoder,
+                        decoderPath: args.decoder,
+                        executionProvider: args.provider ?? 'cpu',
+                    })
+                    : await createGrabCutSegmenter({ assetPath: args.opencv });
+        client = createClassifier({ decision, ...(segmenter ? { segmentation: segmenter } : {}) });
+        controller.signal.throwIfAborted();
+        if (command === 'locate') {
+            console.log(JSON.stringify(await client.locate({
+                image: image,
+                target,
+                ...(args.mode ? { mode: args.mode } : {}),
+                signal: controller.signal,
+            }), null, 2));
+        }
+        else if (command === 'extract') {
+            const result = await client.extract({ image: image, target, signal: controller.signal });
+            console.log(JSON.stringify(result.status === 'extracted'
+                ? { status: result.status, files: await writeExtractionFiles(args.output, result) }
+                : result, null, 2));
+        }
+        else {
+            const input = command === 'classify-text' ? value : { image: image };
+            console.log(JSON.stringify(await client.classify({ input, classes: classes, signal: controller.signal }), null, 2));
         }
     }
     finally {
-        await client.dispose();
+        process.removeListener('SIGINT', abort);
+        process.removeListener('SIGTERM', abort);
+        try {
+            await client?.dispose();
+        }
+        finally {
+            await segmenter?.dispose();
+        }
     }
 }
 main().catch((error) => {