@camstack/types 1.2.404 → 1.2.405

package/dist/interfaces/platform.d.ts

@@ -1,4 +1,5 @@
 import type { InferenceDeviceDescriptor } from '../inference/runtime-capabilities.js';
+import type { AcceleratorCompute } from '../pipeline/auto-tune/accelerator-compute.js';
 /** Hardware information detected at boot */
 export interface HardwareInfo {
     readonly platform: 'darwin' | 'linux' | 'win32';
@@ -9,6 +10,12 @@ export interface HardwareInfo {
     readonly availableRAM_MB: number;
     readonly gpu: GpuInfo | null;
     readonly npu: NpuInfo | null;
+    /**
+     * Per-accelerator compute the probe reported (D930). Absent when the probe
+     * did not run; an empty list means it ran and found no accelerator. A
+     * failed field inside an entry is null, never 0.
+     */
+    readonly accelerators?: readonly AcceleratorCompute[];
     /**
      * Coral Edge TPU hardware (USB and/or PCIe), when found. Optional so existing
      * HardwareInfo construction sites and older cross-node probe reports stay

package/dist/node-color.d.ts

@@ -1,7 +1,6 @@
 import { z } from 'zod';
 /** Fixed cluster node palette ids (maps to `--color-node-*` theme tokens). */
 export declare const NODE_COLOR_IDS: readonly ['node-a', 'node-b', 'node-c', 'node-d', 'node-e', 'node-f', 'node-g', 'node-h'];
-export type NodeColorId = (typeof NODE_COLOR_IDS)[number];
 export declare const NodeColorIdSchema: z.ZodEnum<{
     "node-a": "node-a";
     "node-b": "node-b";
@@ -12,4 +11,5 @@ export declare const NodeColorIdSchema: z.ZodEnum<{
     "node-g": "node-g";
     "node-h": "node-h";
 }>;
+export type NodeColorId = z.infer<typeof NodeColorIdSchema>;
 export declare function assignNodeColorId(nodeId: string): NodeColorId;

package/dist/pipeline/auto-tune/accelerator-compute.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Capacity of an accelerator we have not measured (D930).
+ *
+ * The latency table stays the measured columns. A device that reports compute
+ * (OpenVINO GOPS, or execution units × clock, or compute units, or TOPS) is
+ * estimated from the nearest measured column of the same accelerator kind,
+ * scaled by the compute ratio and clamped. A node benchmark still replaces
+ * the estimate. A device that reports neither compute nor a known class stays
+ * `unknown`.
+ *
+ * A failed probe field is `null`, never `0` (D393): zero would be a compute
+ * ratio of zero and would size the device as if it could not run.
+ */
+import { z } from 'zod';
+import type { AcceleratorKind, HardwareClassId } from './plan-schemas.js';
+import { type DetectorLatencyColumn, type DetectorPerfTable } from './detector-performance.js';
+/**
+ * An unmeasured device is never estimated outside this band of its reference.
+ *
+ * Peak GOPS and detector latency do not move together: a 640 model is memory
+ * bound, a 320 model less so, and the N100→N305 public EU×clock ratio is
+ * about 2.2×. 2× is the widest that spread justifies without a measurement
+ * on the device; 0.5× is the symmetric floor so a tiny iGPU is not told it
+ * is many times slower than the weakest column we measured. A node benchmark
+ * replaces the estimate and is not clamped.
+ */
+export declare const ESTIMATE_COMPUTE_RATIO_MIN = 0.5;
+export declare const ESTIMATE_COMPUTE_RATIO_MAX = 2;
+/**
+ * Within this of 1.0, a device whose class IS the reference is that measured
+ * machine (a probe clock a few percent off the spec), not a different chip.
+ * An unknown class is still estimated, so the plan says so.
+ */
+export declare const REFERENCE_MATCH_FRACTION = 0.05;
+/** N100 iGPU: 24 execution units, 750 MHz graphics max (Intel specification). */
+export declare const N100_IGPU_EU = 24;
+export declare const N100_IGPU_CLOCK_MHZ = 750;
+/**
+ * Core Ultra 7 265K iGPU: 4 Xe-cores. OpenVINO's execution-unit count for
+ * Xe-LP is 16 per Xe-core, and the graphics max dynamic frequency is 2000 MHz.
+ * Used only to choose the nearest column for a chip that is not itself a
+ * Core Ultra — that class is the measurement and is never scaled.
+ */
+export declare const CORE_ULTRA_265K_IGPU_EU = 64;
+export declare const CORE_ULTRA_265K_IGPU_CLOCK_MHZ = 2000;
+/** Phoenix / Hawk Point Radeon 780M: 12 compute units. */
+export declare const PHOENIX_780M_CU = 12;
+export declare const PrecisionGopsSchema: z.ZodObject<{
+    int8: z.ZodPipe<z.ZodNullable<z.ZodNumber>, z.ZodTransform<number | null, number | null>>;
+    fp16: z.ZodPipe<z.ZodNullable<z.ZodNumber>, z.ZodTransform<number | null, number | null>>;
+}, z.core.$strip>;
+export type PrecisionGops = z.infer<typeof PrecisionGopsSchema>;
+/** What one accelerator device reported. Every failed query is null. */
+export declare const AcceleratorComputeSchema: z.ZodObject<{
+    deviceKey: z.ZodString;
+    fullDeviceName: z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | null, string | null>>;
+    executionUnits: z.ZodPipe<z.ZodNullable<z.ZodNumber>, z.ZodTransform<number | null, number | null>>;
+    clockMHz: z.ZodPipe<z.ZodNullable<z.ZodNumber>, z.ZodTransform<number | null, number | null>>;
+    gops: z.ZodNullable<z.ZodObject<{
+        int8: z.ZodPipe<z.ZodNullable<z.ZodNumber>, z.ZodTransform<number | null, number | null>>;
+        fp16: z.ZodPipe<z.ZodNullable<z.ZodNumber>, z.ZodTransform<number | null, number | null>>;
+    }, z.core.$strip>>;
+    architecture: z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | null, string | null>>;
+    npuName: z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | null, string | null>>;
+    tops: z.ZodPipe<z.ZodNullable<z.ZodNumber>, z.ZodTransform<number | null, number | null>>;
+    vendor: z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | null, string | null>>;
+    webgpuArchitecture: z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | null, string | null>>;
+    webgpuDevice: z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | null, string | null>>;
+    computeUnits: z.ZodPipe<z.ZodNullable<z.ZodNumber>, z.ZodTransform<number | null, number | null>>;
+}, z.core.$strip>;
+export type AcceleratorCompute = z.infer<typeof AcceleratorComputeSchema>;
+/** The unit a compute ratio is taken in. Two scores of different units are not compared. */
+export type ComputeMetric = 'gops-int8' | 'gops-fp16' | 'eu-mhz' | 'cu' | 'tops';
+export interface ComputeScore {
+    readonly metric: ComputeMetric;
+    readonly value: number;
+}
+/** The compute of one measured column, in the unit the probe reports. */
+export interface ReferenceCompute {
+    readonly hardwareClass: HardwareClassId;
+    readonly accelerator: AcceleratorKind;
+    readonly score: ComputeScore;
+}
+/**
+ * Compute of the machines the latency columns were measured on.
+ * GOPS is preferred when a column carries it; none of these do yet — the
+ * boxes were measured before the probe reported `DEVICE_GOPS` — so the scale
+ * uses execution units × clock (Intel) or compute units (AMD) until a
+ * re-measure locks a GOPS figure on the column.
+ */
+export declare const REFERENCE_COMPUTE: readonly ReferenceCompute[];
+export interface ResolveLatencyInput {
+    readonly hardwareClass: HardwareClassId;
+    readonly accelerator: AcceleratorKind;
+    readonly report: AcceleratorCompute | null;
+    readonly perf?: DetectorPerfTable;
+    readonly references?: readonly ReferenceCompute[];
+}
+export interface ResolvedLatencyColumn {
+    readonly column: DetectorLatencyColumn;
+    /** Null when the column is the measurement itself. */
+    readonly estimatedFrom: HardwareClassId | null;
+}
+/** Parse a probe payload. `null` means the probe failed — not "no accelerators". */
+export declare function parseAcceleratorFactsJson(raw: unknown): readonly AcceleratorCompute[] | null;
+/** Scores in the order the estimate prefers. A non-positive field is absent. */
+export declare function computeScores(report: AcceleratorCompute): readonly ComputeScore[];
+/** True when this report can scale a measured column of `kind`. */
+export declare function reportIsScalable(report: AcceleratorCompute, kind: AcceleratorKind, references?: readonly ReferenceCompute[]): boolean;
+/**
+ * The latency column for one device. A measured class other than the N-series
+ * spread is returned unchanged — one class there is one measured machine.
+ * `intel-n-series` is the N100 column; a different reported compute scales it.
+ * An unknown class scales from the nearest reference of the same kind.
+ */
+export declare function resolveLatencyColumn(input: ResolveLatencyInput): ResolvedLatencyColumn | null;

package/dist/pipeline/auto-tune/detector-performance.d.ts

@@ -21,6 +21,11 @@ export interface DetectorLatencyCell {
     readonly fps: number;
     /** False for a cell derived from another column (scaled), not measured. */
     readonly measured: boolean;
+    /**
+     * Set when this cell was scaled from another class's measured column (D930).
+     * Absent on a measured cell and on a cell derived inside the same column.
+     */
+    readonly estimatedFrom?: HardwareClassId;
 }
 /** `modelId → cell` for one (hardware class, accelerator) column. */
 export type DetectorLatencyColumn = Readonly<Record<string, DetectorLatencyCell>>;

package/dist/pipeline/auto-tune/hardware-class.d.ts

@@ -1,11 +1,12 @@
 /**
- * Static hardware classification for the Auto tune recommender (D745).
+ * Static hardware classification for the Auto tune recommender (D745, D930).
  *
  * A node is classified from the facts its platform probe already reports —
  * `cpuModel`, `arch`, `gpu`, `npu` — never from a benchmark. The class picks a
- * column of the measured latency table (`detector-performance.ts`); a node
- * whose CPU matches no measured class is `unknown` and the recommender leaves
- * it alone, saying so.
+ * column of the measured latency table (`detector-performance.ts`). A CPU that
+ * matches no measured class is `unknown`: the recommender then scales from
+ * reported accelerator compute when the probe supplied it, and leaves the
+ * node alone only when it has neither.
  *
  * `cpuModel` is the host's CPU string even inside Docker (`os.cpus()`), which
  * is why it is the discriminator: "Intel(R) Core(TM) Ultra 7 265K",

package/dist/pipeline/auto-tune/index.d.ts

@@ -5,5 +5,6 @@
  */
 export * from './hardware-class.js';
 export * from './detector-performance.js';
+export * from './accelerator-compute.js';
 export * from './recommend.js';
 export * from './plan-schemas.js';

package/dist/pipeline/auto-tune/plan-schemas.d.ts

@@ -99,6 +99,16 @@ export declare const LatencySourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"node-benchmark">;
     resultId: z.ZodString;
     measuredAtMs: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"estimated">;
+    estimatedFrom: z.ZodEnum<{
+        "amd-phoenix": "amd-phoenix";
+        "apple-m-base": "apple-m-base";
+        "apple-m-pro": "apple-m-pro";
+        "intel-core-ultra": "intel-core-ultra";
+        "intel-n-series": "intel-n-series";
+        unknown: "unknown";
+    }>;
 }, z.core.$strip>], "kind">;
 export type LatencySource = z.infer<typeof LatencySourceSchema>;
 export declare const DeviceModelChoiceSchema: z.ZodObject<{
@@ -112,7 +122,25 @@ export declare const DeviceModelChoiceSchema: z.ZodObject<{
         kind: z.ZodLiteral<"node-benchmark">;
         resultId: z.ZodString;
         measuredAtMs: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"estimated">;
+        estimatedFrom: z.ZodEnum<{
+            "amd-phoenix": "amd-phoenix";
+            "apple-m-base": "apple-m-base";
+            "apple-m-pro": "apple-m-pro";
+            "intel-core-ultra": "intel-core-ultra";
+            "intel-n-series": "intel-n-series";
+            unknown: "unknown";
+        }>;
     }, z.core.$strip>], "kind">>;
+    estimatedFrom: z.ZodOptional<z.ZodEnum<{
+        "amd-phoenix": "amd-phoenix";
+        "apple-m-base": "apple-m-base";
+        "apple-m-pro": "apple-m-pro";
+        "intel-core-ultra": "intel-core-ultra";
+        "intel-n-series": "intel-n-series";
+        unknown: "unknown";
+    }>>;
     capacitySessions: z.ZodNumber;
     personRecall: z.ZodNumber;
 }, z.core.$strip>;
@@ -141,7 +169,25 @@ export declare const DeviceRecommendationSchema: z.ZodObject<{
             kind: z.ZodLiteral<"node-benchmark">;
             resultId: z.ZodString;
             measuredAtMs: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"estimated">;
+            estimatedFrom: z.ZodEnum<{
+                "amd-phoenix": "amd-phoenix";
+                "apple-m-base": "apple-m-base";
+                "apple-m-pro": "apple-m-pro";
+                "intel-core-ultra": "intel-core-ultra";
+                "intel-n-series": "intel-n-series";
+                unknown: "unknown";
+            }>;
         }, z.core.$strip>], "kind">>;
+        estimatedFrom: z.ZodOptional<z.ZodEnum<{
+            "amd-phoenix": "amd-phoenix";
+            "apple-m-base": "apple-m-base";
+            "apple-m-pro": "apple-m-pro";
+            "intel-core-ultra": "intel-core-ultra";
+            "intel-n-series": "intel-n-series";
+            unknown: "unknown";
+        }>>;
         capacitySessions: z.ZodNumber;
         personRecall: z.ZodNumber;
     }, z.core.$strip>>;
@@ -243,7 +289,25 @@ export declare const NodeRecommendationSchema: z.ZodObject<{
                 kind: z.ZodLiteral<"node-benchmark">;
                 resultId: z.ZodString;
                 measuredAtMs: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"estimated">;
+                estimatedFrom: z.ZodEnum<{
+                    "amd-phoenix": "amd-phoenix";
+                    "apple-m-base": "apple-m-base";
+                    "apple-m-pro": "apple-m-pro";
+                    "intel-core-ultra": "intel-core-ultra";
+                    "intel-n-series": "intel-n-series";
+                    unknown: "unknown";
+                }>;
             }, z.core.$strip>], "kind">>;
+            estimatedFrom: z.ZodOptional<z.ZodEnum<{
+                "amd-phoenix": "amd-phoenix";
+                "apple-m-base": "apple-m-base";
+                "apple-m-pro": "apple-m-pro";
+                "intel-core-ultra": "intel-core-ultra";
+                "intel-n-series": "intel-n-series";
+                unknown: "unknown";
+            }>>;
             capacitySessions: z.ZodNumber;
             personRecall: z.ZodNumber;
         }, z.core.$strip>>;
@@ -445,7 +509,25 @@ export declare const AutoTunePlanSchema: z.ZodObject<{
                     kind: z.ZodLiteral<"node-benchmark">;
                     resultId: z.ZodString;
                     measuredAtMs: z.ZodNumber;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"estimated">;
+                    estimatedFrom: z.ZodEnum<{
+                        "amd-phoenix": "amd-phoenix";
+                        "apple-m-base": "apple-m-base";
+                        "apple-m-pro": "apple-m-pro";
+                        "intel-core-ultra": "intel-core-ultra";
+                        "intel-n-series": "intel-n-series";
+                        unknown: "unknown";
+                    }>;
                 }, z.core.$strip>], "kind">>;
+                estimatedFrom: z.ZodOptional<z.ZodEnum<{
+                    "amd-phoenix": "amd-phoenix";
+                    "apple-m-base": "apple-m-base";
+                    "apple-m-pro": "apple-m-pro";
+                    "intel-core-ultra": "intel-core-ultra";
+                    "intel-n-series": "intel-n-series";
+                    unknown: "unknown";
+                }>>;
                 capacitySessions: z.ZodNumber;
                 personRecall: z.ZodNumber;
             }, z.core.$strip>>;
@@ -673,7 +755,25 @@ export declare const AutoTuneApplyResultSchema: z.ZodDiscriminatedUnion<[z.ZodOb
                         kind: z.ZodLiteral<"node-benchmark">;
                         resultId: z.ZodString;
                         measuredAtMs: z.ZodNumber;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"estimated">;
+                        estimatedFrom: z.ZodEnum<{
+                            "amd-phoenix": "amd-phoenix";
+                            "apple-m-base": "apple-m-base";
+                            "apple-m-pro": "apple-m-pro";
+                            "intel-core-ultra": "intel-core-ultra";
+                            "intel-n-series": "intel-n-series";
+                            unknown: "unknown";
+                        }>;
                     }, z.core.$strip>], "kind">>;
+                    estimatedFrom: z.ZodOptional<z.ZodEnum<{
+                        "amd-phoenix": "amd-phoenix";
+                        "apple-m-base": "apple-m-base";
+                        "apple-m-pro": "apple-m-pro";
+                        "intel-core-ultra": "intel-core-ultra";
+                        "intel-n-series": "intel-n-series";
+                        unknown: "unknown";
+                    }>>;
                     capacitySessions: z.ZodNumber;
                     personRecall: z.ZodNumber;
                 }, z.core.$strip>>;

package/dist/pipeline/auto-tune/recommend.d.ts

@@ -7,18 +7,21 @@
  * Per node:
  *  1. Classify the hardware (`classifyInferenceHardware`). An unknown class,
  *     an offline node or a node with nothing to recommend is left untouched —
- *     unless the node has its own measurements (below).
- *  1b. MEASURED ON THE NODE BEATS THE TABLE (D791): a fresh node benchmark
- *     result for (device, model) replaces the table's cell, and the choice
- *     names it as its source. A node of unknown hardware with measurements is
- *     recommended from them alone.
+ *     unless the node has its own measurements (below) or a device reported
+ *     compute that can be scaled from a measured column (D930).
+ *  1b. MEASURED ON THE NODE BEATS THE TABLE (D791), and the table beats an
+ *     estimate: a fresh node benchmark result for (device, model) replaces
+ *     whatever cell the class or the compute scale produced. A node of
+ *     unknown hardware with measurements is recommended from them alone.
  *  2. The node's ACCELERATORS (NPU, iGPU, Neural Engine) that are enabled and
  *     available share ONE model — so a camera's floors never flip with the
  *     device the balancer rotated it onto. A candidate must have a build for
  *     every accelerator's format and a latency cell for each.
  *  3. A candidate FITS a device when the device sustains at least
  *     `minSessionsPerDevice` parallel sessions with it:
- *     ⌊fps × (1 − headroom) / camera fps⌋ ≥ minSessionsPerDevice.
+ *     ⌊fps × factor × (1 − headroom) / camera fps⌋ ≥ minSessionsPerDevice.
+ *     factor is 1 at 10 fps; below that an Intel iGPU uses the measured
+ *     overlap (D930).
  *  4. Among candidates that fit everywhere, the most accurate wins (person
  *     recall at the shipped floor); within `RECALL_TIE` of the best, the
  *     fastest wins. That IS the step-down order the data gives: the first
@@ -37,7 +40,7 @@
 import type { HardwareInfo } from '../../interfaces/platform.js';
 import type { ModelFormat } from '../../types/models.js';
 import { type DetectorPerfTable } from './detector-performance.js';
-import { type NodeRecommendation } from './plan-schemas.js';
+import { type AcceleratorKind, type NodeRecommendation } from './plan-schemas.js';
 /** The family the cluster runs. */
 export declare const AUTO_TUNE_FAMILY = "yolov9";
 /**
@@ -51,8 +54,27 @@ export declare const RECALL_TIE = 0.02;
 export declare const DEFAULT_HEADROOM = 0.4;
 /** Detection rate a session is counted at when no camera says otherwise. */
 export declare const DEFAULT_CAMERA_FPS = 10;
-/** Parallel sessions one device sustains at `fps` with `headroom` kept free. */
-export declare function capacitySessionsOf(fps: number, headroom: number, cameraFps: number): number;
+/**
+ * Camera rate at which serial `1000/p50` matched the cameras that held
+ * (N100 iGPU, 2026-10-24). Below this the second InferRequest's overlap
+ * becomes extra sessions; at and above it the serial ceiling is the count.
+ */
+export declare const SERIAL_CAPACITY_CAMERA_FPS = 10;
+/**
+ * Aggregate throughput ÷ serial throughput when the frame interval is wide
+ * enough to hide the second request. intel-igpu is the N100 measurement
+ * (~1.4× under LATENCY with 2 InferRequests). Every other kind stays 1
+ * until it is measured the same way.
+ */
+export declare const AGGREGATE_THROUGHPUT_BY_KIND: Readonly<Partial<Record<AcceleratorKind, number>>>;
+/** The overlap factor for this kind at this camera rate. 1 at {@link SERIAL_CAPACITY_CAMERA_FPS} and above. */
+export declare function aggregateThroughputFactor(kind: AcceleratorKind, cameraFps: number): number;
+/**
+ * Parallel sessions one device sustains at `fps` with `headroom` kept free.
+ * `aggregateFactor` is the kind's overlap (1 unless the caller measured
+ * extra throughput at this camera rate).
+ */
+export declare function capacitySessionsOf(fps: number, headroom: number, cameraFps: number, aggregateFactor?: number): number;
 /** A latency measured on the node itself (a fresh node benchmark result, D791). */
 export interface MeasuredLatencyCell {
     readonly p50Ms: number;

package/dist/pipeline/second-pass/index.d.ts

@@ -0,0 +1,2 @@
+export * from './small-subject-recovery.js';
+export * from './motion-crop-plan.js';

package/dist/pipeline/second-pass/motion-crop-plan.d.ts

@@ -0,0 +1,183 @@
+/**
+ * The MEASURED motion-crop recipe (D396) — per camera, default off.
+ *
+ * ## What this adds to the pass that already exists
+ *
+ * `small-subject-recovery.ts` ships a second detector pass gated on an
+ * UNCOVERED motion region: a region is worth a crop when it is small AND
+ * mostly NOT accounted for by a full-frame box. That rule was built to find a
+ * subject standing NEXT TO one the detector already sees, and it works.
+ *
+ * The measurement says the cheaper question is the better one. On camera 615,
+ * against the production detector (`yolov9m-320-int8`, python+openvino) on the
+ * node that runs that camera, over 38 visually confirmed positive frames from
+ * six real animal pass-bys: full-frame recall at our animal floor **24%**,
+ * detecting on motion-derived crops **42%**, the same crops with the motion
+ * area bar lowered **74%**. Per pass-by 4/6 → 6/6 at our floor, 3/6 → 6/6 at
+ * a 0.70 floor. The score distribution moves with it — full frame median
+ * 0.780 / p25 0.526, crops 0.840 / p25 0.652.
+ *
+ * So this rule keeps every moving region, and treats a tracked box that
+ * intersects one as a SEED rather than as an exclusion.
+ *
+ * ## Additive, never substitutive
+ *
+ * On frames where motion is silent the crop arm scores 0% and the full-frame
+ * arm still scores 5% — and the full frame is the only arm that can see a
+ * STATIONARY subject at all. Both recipes only ever ADD boxes to the
+ * full-frame result; nothing here can remove one.
+ *
+ * ## Cost
+ *
+ * Mean 0.25 extra detector invocations per frame at the shipped motion
+ * sensitivity and 0.88 at the lowered bar, on the node that would run it. A
+ * crop costs about the same as a full frame (45.2 ms vs 40.8 ms p50) — it is
+ * not cheaper, it is better aimed — and the whole thing is bounded by the
+ * motion duty cycle. The runner's own per-camera rate limit
+ * (`RECOVERY_MIN_INTERVAL_MS`) is the ceiling above that.
+ *
+ * ## What this is NOT (D52)
+ *
+ * Not a detail/CLIP crop, for the same reason `small-subject-recovery.ts` is
+ * not one: `deriveDetailCropRect` derives the rectangle an enrichment step is
+ * fed from a KNOWN subject box, and `object-clip` is one vector index that
+ * tolerates exactly one such derivation. This module derives a square from a
+ * MOTION region, before any subject exists, for the FIRST-LEVEL detector; its
+ * output is a detection, never a vector. Nothing here calls the detail
+ * derivation and nothing here may be reused for one.
+ *
+ * Pure: no runner state, no IPC, no pixels.
+ *
+ * Lives in `@camstack/types` so the live runner (`addon-pipeline`) and the
+ * offline accuracy evaluation (`addon-benchmark`) plan the SAME crops: one
+ * module, two callers, no copy to drift.
+ */
+import type { ObjectDetection } from '../../types/detection.js';
+import type { PipelineStepInputOutput } from '../../capabilities/pipeline-executor.cap.js';
+import { type NormalizedRect, type RecoveryCrop, type RecoveryPlanInput } from './small-subject-recovery.js';
+/**
+ * Which region rule this camera's second pass runs.
+ *
+ * The selector is per camera and defaults to the shipped rule, exactly like
+ * the motion area bar's own `minArea: 0` opt-in (D394): a deploy changes
+ * nothing until an operator moves a camera.
+ */
+export type RecoveryRecipe = 'uncovered-region' | 'motion-crop';
+/**
+ * Step-settings key of the opt-in, on the `object-detection` step — so it is
+ * per camera through `pipelineOrchestrator.setCameraStepSettings` (a
+ * camera-semantic key, D927), and it rides the same
+ * `PipelineStepInputOutput.settings` the per-macro confidence floors ride.
+ */
+export declare const MOTION_CROP_DISPATCH_KEY = "motionCropDispatch";
+/**
+ * Read the opt-in. Anything that is not the boolean `true` is the shipped
+ * rule: a stored string or a number is a mis-write (this repo has shipped a
+ * setting written into the wrong sqlite table before), and a mis-write must
+ * not silently change what a camera detects on.
+ */
+export declare function readRecoveryRecipe(settings: Readonly<Record<string, unknown>> | undefined): RecoveryRecipe;
+/**
+ * The recipe this camera's resolved step tree selects.
+ *
+ * Reads the ENABLED first-level detector's own settings, which is where
+ * `pipelineOrchestrator.setCameraStepSettings` writes a per-camera value. A
+ * tree with no enabled detector runs no second pass at all, so the answer
+ * there is the shipped rule and it is never used.
+ */
+export declare function readRecoveryRecipeForSteps(steps: readonly PipelineStepInputOutput[]): RecoveryRecipe;
+/**
+ * A motion box is grown ×1.5 about its centre before anything else.
+ *
+ * The motion step's box is the CHANGED pixels, which on a moving animal is the
+ * leading edge plus its shadow, not the animal. The detector needs the subject
+ * and the context it was trained on.
+ */
+export declare const MOTION_CROP_MOTION_PAD = 1.5;
+/**
+ * An intersecting tracked box is grown ×1.25 — less, because it is already a
+ * subject rectangle rather than a change mask.
+ */
+export declare const MOTION_CROP_TRACKED_PAD = 1.25;
+/**
+ * Regions per frame, largest area first.
+ *
+ * Measured as NON-BINDING: over the 156 frames of the recall harness the cap
+ * bound on 0 of them. It is the bound on a storm, not a tuning knob, and the
+ * runner reports when it binds so a camera on which it starts to is visible.
+ */
+export declare const MOTION_CROP_MAX_REGIONS = 3;
+/**
+ * The floor a `person` or `vehicle` box must clear when it came out of a CROP
+ * rather than out of the full frame.
+ *
+ * Collected, not assumed: 3 085 quiet frames produced 27 motion-positive
+ * frames and 28 crop invocations. The full-frame arm produced 0 boxes above
+ * any gate; the crop arm produced 3, of which two are genuine false positives,
+ * and both are night-IR corners upscaled into a 320 model — `vehicle 0.749`
+ * and `person 0.701`. Zero false `animal` at any gate, which is why `animal`
+ * is deliberately absent from this table: the class the pass exists to recover
+ * is the class that never produced a false positive, and gating it would cost
+ * the whole measured gain.
+ *
+ * This is a CROP-ONLY floor, applied on top of the per-macro floors the
+ * executor already enforced. A full-frame `person` at 0.70 is untouched — the
+ * full-frame arm is the one arm with ground truth behind its floor
+ * (`minConfidencePerson` 0.65, raised on 2026-07-30 from a measured
+ * distribution).
+ *
+ * The cost of this floor is stated rather than assumed away: it can also
+ * remove a real distant person or vehicle recovered from a crop at 0.70–0.80.
+ * Nothing in the quiet-footage sample measures that, so the floor is a
+ * constant here rather than a slider, and the runner reports every drop it
+ * makes per camera.
+ */
+export declare const CROP_CLASS_FLOORS: Readonly<Record<string, number>>;
+/** One box the crop floor removed, with the numbers that removed it. */
+export interface CropFloorDrop {
+    readonly macroClass: string;
+    readonly score: number;
+    readonly floor: number;
+}
+/** What {@link applyCropClassFloors} kept, and everything it did not. */
+export interface CropFloorVerdict {
+    readonly kept: readonly ObjectDetection[];
+    readonly dropped: readonly CropFloorDrop[];
+}
+/**
+ * Apply the crop-only class floors, REPORTING every drop.
+ *
+ * A class with no entry in {@link CROP_CLASS_FLOORS} is kept: a floor this
+ * table cannot express is not a floor of zero, and silently dropping a class
+ * nobody measured is the exact shape of silent drop this repo has paid for
+ * three separate times.
+ */
+export declare function applyCropClassFloors(detections: readonly ObjectDetection[]): CropFloorVerdict;
+/**
+ * The regions the measured recipe judges this frame on.
+ *
+ * Motion boxes padded {@link MOTION_CROP_MOTION_PAD}; every full-frame box
+ * that intersects a RAW motion box padded {@link MOTION_CROP_TRACKED_PAD} and
+ * added as a seed of its own; everything that overlaps merged; the result
+ * clamped to the frame, ordered largest first and capped at
+ * {@link MOTION_CROP_MAX_REGIONS}.
+ *
+ * There is deliberately no coverage gate and no size gate here. Those belong
+ * to the shipped rule, and they are what makes it a rule about a subject
+ * BESIDE a detected one; the measurement says the pass is worth running on the
+ * detected subject's own region too.
+ */
+export declare function planMotionCropRegions(input: RecoveryPlanInput): readonly NormalizedRect[];
+/**
+ * The crops the measured recipe runs on this frame.
+ *
+ * Dedupe is by CONTAINMENT only. Two squares that merely overlap both run: the
+ * pixels the second adds are pixels no other crop shows the detector, and the
+ * fusion step downstream already refuses a duplicate BOX. Dropping a crop
+ * because it overlapped would drop the subject sitting at its edge, which is
+ * the whole population this pass exists for.
+ *
+ * A frame that cannot hold the smallest crop yields nothing: it is already
+ * seen at scale.
+ */
+export declare function planMotionCrops(input: RecoveryPlanInput): readonly RecoveryCrop[];