zorya-classifier 0.0.0-stage → 0.1.0

package/dist/entities/contracts.d.ts

@@ -0,0 +1,395 @@
+import { z } from 'zod';
+export declare const limits: Readonly<{
+    imageBytes: number;
+    imagePixels: 16777216;
+    bodyBytes: number;
+    maxClasses: 255;
+    maxImages: 9;
+}>;
+export declare const pixelRectSchema: z.ZodObject<{
+    left: z.ZodNumber;
+    top: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}>;
+export type PixelRect = z.infer<typeof pixelRectSchema>;
+export interface GridCell {
+    id: string;
+    column: number;
+    row: number;
+    region: PixelRect;
+    xId?: string;
+    yId?: string;
+    kind?: 'cell';
+}
+export interface GridPanel {
+    id: string;
+    region: PixelRect;
+    cells: readonly GridCell[];
+}
+export declare const classSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    description: string;
+}, {
+    id: string;
+    description: string;
+}>;
+export type ClassDefinition = z.infer<typeof classSchema>;
+export declare const classifySchema: z.ZodObject<{
+    input: z.ZodUnion<[z.ZodString, z.ZodEffects<z.ZodObject<{
+        text: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodEffects<z.ZodType<Uint8Array<ArrayBufferLike>, z.ZodTypeDef, Uint8Array<ArrayBufferLike>>, Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>>;
+    }, "strict", z.ZodTypeAny, {
+        text?: string | undefined;
+        image?: Uint8Array<ArrayBufferLike> | undefined;
+    }, {
+        text?: string | undefined;
+        image?: Uint8Array<ArrayBufferLike> | undefined;
+    }>, {
+        text?: string | undefined;
+        image?: Uint8Array<ArrayBufferLike> | undefined;
+    }, {
+        text?: string | undefined;
+        image?: Uint8Array<ArrayBufferLike> | undefined;
+    }>]>;
+    classes: z.ZodEffects<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        description: string;
+    }, {
+        id: string;
+        description: string;
+    }>, "many">, {
+        id: string;
+        description: string;
+    }[], {
+        id: string;
+        description: string;
+    }[]>;
+    instructions: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    input: string | {
+        text?: string | undefined;
+        image?: Uint8Array<ArrayBufferLike> | undefined;
+    };
+    classes: {
+        id: string;
+        description: string;
+    }[];
+    instructions?: string | undefined;
+}, {
+    input: string | {
+        text?: string | undefined;
+        image?: Uint8Array<ArrayBufferLike> | undefined;
+    };
+    classes: {
+        id: string;
+        description: string;
+    }[];
+    instructions?: string | undefined;
+}>;
+export type ClassifyInput = z.input<typeof classifySchema> & {
+    signal?: AbortSignal;
+};
+export declare const locateSchema: z.ZodObject<{
+    image: z.ZodEffects<z.ZodType<Uint8Array<ArrayBufferLike>, z.ZodTypeDef, Uint8Array<ArrayBufferLike>>, Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>;
+    target: z.ZodString;
+    exclusions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    roi: z.ZodOptional<z.ZodObject<{
+        left: z.ZodNumber;
+        top: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }, {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    image: Uint8Array<ArrayBufferLike>;
+    target: string;
+    exclusions: string[];
+    roi?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    } | undefined;
+}, {
+    image: Uint8Array<ArrayBufferLike>;
+    target: string;
+    exclusions?: string[] | undefined;
+    roi?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    } | undefined;
+}>;
+export type LocateInput = z.input<typeof locateSchema> & {
+    signal?: AbortSignal;
+};
+export type ImagePart = {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail: 'high';
+    };
+};
+export type DecisionState = (string | ImagePart)[];
+export type ChoiceQuestion = {
+    type: 'choice';
+    rankingSize?: 1 | 4;
+    instructions: string;
+    criteria: Record<string, string>;
+};
+type NoulQuestion = {
+    type: 'noul';
+    instructions: string;
+};
+type DecisionQuestion = ChoiceQuestion | NoulQuestion;
+export type DecisionRequest = {
+    state: DecisionState;
+    questions: Record<string, DecisionQuestion>;
+};
+export interface DecisionMetadata {
+    model: string | null;
+    provider: string | null;
+    requestId: string | null;
+    durationMs: number;
+    costUsd: number | null;
+    attempts: number;
+}
+declare const choiceAnswerSchema: z.ZodObject<{
+    type: z.ZodLiteral<"choice">;
+    choice: z.ZodString;
+    probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    confidence: z.ZodOptional<z.ZodNumber>;
+    probabilityRoundingStep: z.ZodOptional<z.ZodLiteral<0.01>>;
+}, "strip", z.ZodTypeAny, {
+    type: "choice";
+    choice: string;
+    probabilities: Record<string, number>;
+    confidence?: number | undefined;
+    probabilityRoundingStep?: 0.01 | undefined;
+}, {
+    type: "choice";
+    choice: string;
+    probabilities: Record<string, number>;
+    confidence?: number | undefined;
+    probabilityRoundingStep?: 0.01 | undefined;
+}>;
+export type ChoiceAnswer = z.infer<typeof choiceAnswerSchema>;
+export declare const decisionResultSchema: z.ZodObject<{
+    answers: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"choice">;
+        choice: z.ZodString;
+        probabilities: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        confidence: z.ZodOptional<z.ZodNumber>;
+        probabilityRoundingStep: z.ZodOptional<z.ZodLiteral<0.01>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "choice";
+        choice: string;
+        probabilities: Record<string, number>;
+        confidence?: number | undefined;
+        probabilityRoundingStep?: 0.01 | undefined;
+    }, {
+        type: "choice";
+        choice: string;
+        probabilities: Record<string, number>;
+        confidence?: number | undefined;
+        probabilityRoundingStep?: 0.01 | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"ranked-choice">;
+        ranking: z.ZodArray<z.ZodString, "many">;
+    }, "strict", z.ZodTypeAny, {
+        type: "ranked-choice";
+        ranking: string[];
+    }, {
+        type: "ranked-choice";
+        ranking: string[];
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"presence">;
+        presence: z.ZodEnum<["present", "absent", "unknown"]>;
+    }, "strict", z.ZodTypeAny, {
+        type: "presence";
+        presence: "unknown" | "present" | "absent";
+    }, {
+        type: "presence";
+        presence: "unknown" | "present" | "absent";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"noul">;
+        noul: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        type: "noul";
+        noul: number;
+    }, {
+        type: "noul";
+        noul: number;
+    }>]>>;
+    metadata: z.ZodObject<{
+        model: z.ZodNullable<z.ZodString>;
+        provider: z.ZodNullable<z.ZodString>;
+        requestId: z.ZodNullable<z.ZodString>;
+        durationMs: z.ZodNumber;
+        costUsd: z.ZodNullable<z.ZodNumber>;
+        attempts: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        model: string | null;
+        provider: string | null;
+        requestId: string | null;
+        durationMs: number;
+        costUsd: number | null;
+        attempts: number;
+    }, {
+        model: string | null;
+        provider: string | null;
+        requestId: string | null;
+        durationMs: number;
+        costUsd: number | null;
+        attempts: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    answers: Record<string, {
+        type: "choice";
+        choice: string;
+        probabilities: Record<string, number>;
+        confidence?: number | undefined;
+        probabilityRoundingStep?: 0.01 | undefined;
+    } | {
+        type: "ranked-choice";
+        ranking: string[];
+    } | {
+        type: "presence";
+        presence: "unknown" | "present" | "absent";
+    } | {
+        type: "noul";
+        noul: number;
+    }>;
+    metadata: {
+        model: string | null;
+        provider: string | null;
+        requestId: string | null;
+        durationMs: number;
+        costUsd: number | null;
+        attempts: number;
+    };
+}, {
+    answers: Record<string, {
+        type: "choice";
+        choice: string;
+        probabilities: Record<string, number>;
+        confidence?: number | undefined;
+        probabilityRoundingStep?: 0.01 | undefined;
+    } | {
+        type: "ranked-choice";
+        ranking: string[];
+    } | {
+        type: "presence";
+        presence: "unknown" | "present" | "absent";
+    } | {
+        type: "noul";
+        noul: number;
+    }>;
+    metadata: {
+        model: string | null;
+        provider: string | null;
+        requestId: string | null;
+        durationMs: number;
+        costUsd: number | null;
+        attempts: number;
+    };
+}>;
+export type DecisionResult = z.infer<typeof decisionResultSchema>;
+export interface DecisionPort {
+    decide(request: DecisionRequest, signal: AbortSignal): Promise<DecisionResult>;
+}
+export interface ChoiceSelection {
+    choice: string;
+    nativeChoice: string | null;
+    probabilities: Record<string, number> | null;
+    ranking?: string[];
+    confidence?: number;
+    probabilityRoundingStep?: 0.01;
+    tied: string[];
+}
+export interface ClassificationResult extends ChoiceSelection {
+    metadata: DecisionMetadata;
+}
+interface LocalizationMetadata {
+    image: {
+        width: number;
+        height: number;
+        coordinateSpace: 'oriented-source-pixels';
+    };
+    stages: DecisionMetadata[];
+    durationMs: number;
+    knownCostUsd: number;
+    unknownCostCount: number;
+}
+export type LocalizationResult = ({
+    status: 'located';
+    region: PixelRect;
+    normalizedRegion: PixelRect;
+    selection: ChoiceSelection;
+    method: 'three-choice-grid-v1';
+    refinement?: RefinementResult;
+} | {
+    status: 'not-found';
+    reason: 'absent-in-evaluated-region';
+} | {
+    status: 'unknown';
+    reason: 'uncertain-presence' | 'candidate-union-empty' | 'contradictory-evidence' | 'layout-limit';
+}) & {
+    metadata: LocalizationMetadata;
+};
+export type RefinementResult = {
+    status: 'refined';
+    region: PixelRect;
+    method: string;
+} | {
+    status: 'unknown';
+    reason: string;
+};
+export interface RefinementPort {
+    refine(input: {
+        image: Uint8Array;
+        target: string;
+        region: PixelRect;
+        signal: AbortSignal;
+    }): Promise<RefinementResult>;
+}
+export declare function parse<T>(schema: z.ZodType<T, z.ZodTypeDef, unknown>, value: unknown, code?: 'INVALID_INPUT' | 'INVALID_RESPONSE'): T;
+export interface RasterImage {
+    bytes: Uint8Array;
+    width: number;
+    height: number;
+}
+export interface RasterPort {
+    normalize(bytes: Uint8Array, signal: AbortSignal): Promise<RasterImage>;
+    crop(image: RasterImage, region: PixelRect, signal: AbortSignal, scale?: number): Promise<RasterImage>;
+    imageState(image: RasterImage, signal: AbortSignal): Promise<DecisionState>;
+    grid(image: RasterImage, region: PixelRect, cells: readonly GridCell[], labels: ReadonlyMap<string, string>, signal: AbortSignal): Promise<RasterImage>;
+}
+export {};

package/dist/entities/contracts.js

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+import { ClassifierError } from './errors.js';
+export const limits = Object.freeze({
+    imageBytes: 16 * 1024 * 1024,
+    imagePixels: 16_777_216,
+    bodyBytes: 32 * 1024 * 1024,
+    maxClasses: 255,
+    maxImages: 9,
+});
+export const pixelRectSchema = z
+    .object({
+    left: z.number().int().nonnegative().safe(),
+    top: z.number().int().nonnegative().safe(),
+    width: z.number().int().positive().max(16384),
+    height: z.number().int().positive().max(16384),
+})
+    .strict();
+export const classSchema = z
+    .object({
+    id: z
+        .string()
+        .min(1)
+        .max(128)
+        .regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/),
+    description: z.string().trim().min(1).max(300),
+})
+    .strict();
+const imageSchema = z
+    .custom((value) => value instanceof Uint8Array)
+    .refine((v) => v.byteLength > 0 && v.byteLength <= limits.imageBytes, 'Expected 1..16MiB image bytes');
+const mediaInputSchema = z
+    .object({ text: z.string().trim().min(1).max(32000).optional(), image: imageSchema.optional() })
+    .strict()
+    .refine((v) => v.text !== undefined || v.image !== undefined, 'Provide text or image');
+export const classifySchema = z
+    .object({
+    input: z.union([z.string().trim().min(1).max(32000), mediaInputSchema]),
+    classes: z
+        .array(classSchema)
+        .min(2)
+        .max(limits.maxClasses)
+        .refine((v) => new Set(v.map((c) => c.id)).size === v.length, 'Class IDs must be unique'),
+    instructions: z.string().trim().min(1).max(4000).optional(),
+})
+    .strict();
+export const locateSchema = z
+    .object({
+    image: imageSchema,
+    target: z.string().trim().min(1).max(2000),
+    exclusions: z.array(z.string().trim().min(1).max(500)).max(16).default([]),
+    roi: pixelRectSchema.optional(),
+})
+    .strict();
+const choiceAnswerSchema = z.object({
+    type: z.literal('choice'),
+    choice: z.string(),
+    probabilities: z.record(z.number().finite().min(0).max(1)),
+    confidence: z.number().finite().min(0).max(1).optional(),
+    probabilityRoundingStep: z.literal(0.01).optional(),
+});
+const answersSchema = z.record(z.discriminatedUnion('type', [
+    choiceAnswerSchema,
+    z
+        .object({
+        type: z.literal('ranked-choice'),
+        ranking: z.array(z.string().min(1).max(128)).min(1).max(4),
+    })
+        .strict(),
+    z
+        .object({ type: z.literal('presence'), presence: z.enum(['present', 'absent', 'unknown']) })
+        .strict(),
+    z.object({ type: z.literal('noul'), noul: z.number().finite().min(0).max(1) }),
+]));
+const metadataSchema = z.object({
+    model: z.string().nullable(),
+    provider: z.string().nullable(),
+    requestId: z.string().nullable(),
+    durationMs: z.number().finite().nonnegative(),
+    costUsd: z.number().finite().nonnegative().nullable(),
+    attempts: z.number().int().positive(),
+});
+export const decisionResultSchema = z.object({ answers: answersSchema, metadata: metadataSchema });
+export function parse(schema, value, code = 'INVALID_INPUT') {
+    const result = schema.safeParse(value);
+    if (!result.success)
+        throw new ClassifierError(code, 'Schema validation failed', {
+            paths: result.error.issues.map((v) => v.path.join('.')),
+        });
+    return result.data;
+}

package/dist/entities/errors.d.ts

@@ -0,0 +1,7 @@
+export type ErrorCode = 'INVALID_INPUT' | 'INVALID_RESPONSE' | 'TIMEOUT' | 'ABORTED' | 'CAPACITY' | 'DISPOSED' | 'PROVIDER' | 'AUTHENTICATION' | 'UNSUPPORTED' | 'RESOURCE_LIMIT';
+export declare class ClassifierError extends Error {
+    readonly code: ErrorCode;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: ErrorCode, message: string, details?: Readonly<Record<string, unknown>>);
+}
+export declare function assertActive(signal: AbortSignal): void;

package/dist/entities/errors.js

@@ -0,0 +1,16 @@
+export class ClassifierError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'ClassifierError';
+    }
+}
+export function assertActive(signal) {
+    if (signal.aborted)
+        throw signal.reason instanceof ClassifierError
+            ? signal.reason
+            : new ClassifierError('ABORTED', 'Operation cancelled');
+}

package/dist/features/choice-beam-layout.d.ts

@@ -0,0 +1,18 @@
+import type { PixelRect } from '../entities/contracts.js';
+import type { ChoiceAnswer as CategoricalAnswer, GridCell, GridPanel as GridDecisionPanel } from '../entities/contracts.js';
+type ChoiceMap = Pick<CategoricalAnswer, 'choice' | 'probabilities'> | {
+    choice: string;
+    ranking: readonly string[];
+};
+type PanelGeometry = Pick<GridDecisionPanel, 'id' | 'region' | 'cells'>;
+type RankedCell = {
+    cell: GridCell;
+    probability: number | null;
+};
+/** Native Choice is validated by its consumer; this helper never normalizes raw probabilities. */
+export declare function rankChoiceBeamCells(cells: readonly GridCell[], answer: ChoiceMap): RankedCell[];
+/** S7 coarse first pass owns every requested source pixel once, including tiny or narrow ROIs. */
+export declare function choiceBeamFirstCells(region: PixelRect): GridCell[];
+/** Four independent padded source ROIs; an impossible bounded layout returns no panels. */
+export declare function choiceBeamPanels(region: PixelRect, coarseCells: readonly GridCell[], answer: ChoiceMap, accuracyPx: number): PanelGeometry[];
+export {};

package/dist/features/choice-beam-layout.js

@@ -0,0 +1,136 @@
+import { pixelRectSchema } from '../entities/contracts.js';
+import { uniformCoordinateCells } from './uniform-grid.js';
+const sourceKey = (region) => `${region.left}:${region.top}:${region.width}:${region.height}`;
+function assertRegion(region) {
+    if (!pixelRectSchema.safeParse(region).success ||
+        !Number.isSafeInteger(region.left + region.width) ||
+        !Number.isSafeInteger(region.top + region.height))
+        throw new RangeError('Choice beam requires safe positive source-pixel rectangles');
+}
+function contains(outer, inner) {
+    return (inner.left >= outer.left &&
+        inner.top >= outer.top &&
+        inner.left + inner.width <= outer.left + outer.width &&
+        inner.top + inner.height <= outer.top + outer.height);
+}
+/** Native Choice is validated by its consumer; this helper never normalizes raw probabilities. */
+export function rankChoiceBeamCells(cells, answer) {
+    if (cells.length > 196)
+        throw new RangeError('Choice beam exceeds its distinct-cell budget');
+    if (!cells.length)
+        return [];
+    if ('ranking' in answer) {
+        if (answer.ranking.length !== Math.min(4, cells.length) ||
+            new Set(answer.ranking).size !== answer.ranking.length ||
+            answer.ranking[0] !== answer.choice)
+            throw new RangeError('Choice beam needs a complete top-four closed ranking');
+        const meanings = new Map();
+        for (const cell of cells) {
+            assertRegion(cell.region);
+            const key = sourceKey(cell.region);
+            if (!cell.id || (meanings.has(cell.id) && meanings.get(cell.id) !== key))
+                throw new RangeError('Conflicting cell IDs');
+            meanings.set(cell.id, key);
+        }
+        const seen = new Set(), ranked = [];
+        for (const id of answer.ranking) {
+            const cell = cells.find((value) => value.id === id);
+            if (!cell)
+                throw new RangeError('Ranking contains an unknown cell');
+            const key = sourceKey(cell.region);
+            if (!seen.has(key)) {
+                seen.add(key);
+                ranked.push({ cell, probability: null });
+            }
+        }
+        return ranked;
+    }
+    const meanings = new Map();
+    const ranked = cells.map((cell, order) => {
+        assertRegion(cell.region);
+        const probability = answer.probabilities[cell.id], key = sourceKey(cell.region);
+        if (!cell.id ||
+            !Object.hasOwn(answer.probabilities, cell.id) ||
+            probability === undefined ||
+            !Number.isFinite(probability) ||
+            probability < 0 ||
+            probability > 1 ||
+            (meanings.has(cell.id) && meanings.get(cell.id) !== key))
+            throw new RangeError('Choice beam needs complete finite probabilities and canonical cell IDs');
+        meanings.set(cell.id, key);
+        return { cell, probability, order };
+    });
+    const selected = ranked.find((item) => item.cell.id === answer.choice), maximum = Math.max(...ranked.map((item) => item.probability));
+    if (!selected || selected.probability !== maximum)
+        throw new RangeError('Choice beam requires a native spatial maximum');
+    ranked.sort((a, b) => b.probability - a.probability || a.order - b.order);
+    const seen = new Set(), result = [];
+    for (const item of ranked) {
+        const key = sourceKey(item.cell.region);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push({ cell: item.cell, probability: item.probability });
+        if (result.length === 4)
+            break;
+    }
+    return result;
+}
+/** S7 coarse first pass owns every requested source pixel once, including tiny or narrow ROIs. */
+export function choiceBeamFirstCells(region) {
+    assertRegion(region);
+    return uniformCoordinateCells(region, 4, 4);
+}
+function contextRegion(region, cell) {
+    const padX = Math.ceil(cell.width / 2), padY = Math.ceil(cell.height / 2), left = Math.max(region.left, cell.left - padX), top = Math.max(region.top, cell.top - padY);
+    return {
+        left,
+        top,
+        width: Math.min(region.left + region.width, cell.left + cell.width + padX) - left,
+        height: Math.min(region.top + region.height, cell.top + cell.height + padY) - top,
+    };
+}
+function panelLayout(region, accuracy) {
+    const desiredColumns = Math.ceil(region.width / accuracy), desiredRows = Math.ceil(region.height / accuracy);
+    let best;
+    for (let columns = 1; columns <= Math.min(49, desiredColumns); columns++) {
+        for (let rows = 1; rows <= Math.min(Math.floor(49 / columns), desiredRows); rows++) {
+            const side = Math.max(Math.ceil(region.width / columns), Math.ceil(region.height / rows));
+            if (side > 256)
+                continue;
+            const imbalance = Math.abs(region.width / columns - region.height / rows), count = columns * rows;
+            if (!best ||
+                side < best.side ||
+                (side === best.side && imbalance < best.imbalance) ||
+                (side === best.side && imbalance === best.imbalance && count > best.count))
+                best = { columns, rows, side, imbalance, count };
+        }
+    }
+    return best;
+}
+/** Four independent padded source ROIs; an impossible bounded layout returns no panels. */
+export function choiceBeamPanels(region, coarseCells, answer, accuracyPx) {
+    assertRegion(region);
+    if (!Number.isSafeInteger(accuracyPx) || accuracyPx < 1 || accuracyPx > 64)
+        throw new RangeError('Choice beam accuracy must be a bounded positive integer');
+    if (coarseCells.length > 16)
+        throw new RangeError('Choice beam first pass exceeds16 cells');
+    for (const cell of coarseCells) {
+        assertRegion(cell.region);
+        if (!contains(region, cell.region))
+            throw new RangeError('Choice beam coarse cells must fit the requested source ROI');
+    }
+    const canonical = new Map(), panels = [];
+    for (const { cell } of rankChoiceBeamCells(coarseCells, answer)) {
+        const roi = contextRegion(region, cell.region), layout = panelLayout(roi, accuracyPx);
+        if (!layout)
+            return [];
+        const id = `p${panels.length}`, cells = uniformCoordinateCells(roi, layout.columns, layout.rows).map((fine) => {
+            const key = sourceKey(fine.region), canonicalId = canonical.get(key) ?? `${id}:${fine.id}`;
+            canonical.set(key, canonicalId);
+            return { ...fine, id: canonicalId };
+        });
+        panels.push({ id, region: roi, cells });
+    }
+    return panels;
+}

package/dist/features/choice.d.ts

@@ -0,0 +1,4 @@
+import type { ChoiceSelection, DecisionRequest, DecisionResult } from '../entities/contracts.js';
+export declare function validateDecision(request: DecisionRequest, value: unknown): DecisionResult;
+export declare function selection(result: DecisionResult, keys: readonly string[], rankingSize?: number): ChoiceSelection;
+export declare function presence(result: DecisionResult): number;