@camstack/types 1.2.170 → 1.2.172

package/dist/interfaces/birth-decision-ledger.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Birth-decision ledger — one durable row per track-birth VERDICT (D409).
+ *
+ * ── Why this exists ────────────────────────────────────────────────────────
+ * On 2026-09-08 the operator marked eleven tracks for review and five of them
+ * said "traccia partita in ritardo" — the track appears to begin long after the
+ * subject entered the scene. Two causes were proposed and NEITHER was measured:
+ *
+ *  - the confirmation gate's deferral (`maxDeferralMs`, 2 s). This is now
+ *    DISPROVEN as a cause of a late TIMELINE: a track's `firstSeen` and its
+ *    first position are the CANDIDATE's first frame, not the confirmation's.
+ *    Verified on `d035f251` (device 3829): first position == `firstSeen`, with
+ *    confirmation 2 163 ms later.
+ *  - the detector simply not firing until the subject is well into the scene.
+ *    Unmeasured, and the reason this table exists.
+ *
+ * A second, real defect is also unquantified. The deferred-birth re-offer in
+ * `index.ts` takes the track from `result.tracked` with NO `matchedThisFrame`
+ * check, so a birth can be CONFIRMED on a frame the subject was never observed
+ * in. D379's carried birth evidence means some of those confirmations rest on a
+ * real observation of the birth instant anyway — and how often is exactly what
+ * nobody knows. {@link BirthDecisionRecord.decidedOnCoastedFrame} and
+ * {@link BirthDecisionRecord.decidedByBirthEvidence} are the two columns that
+ * answer it together.
+ *
+ * ── Why a TABLE and not a log line ─────────────────────────────────────────
+ * `logs.query` is an in-memory ring. Measured on the live hub on 2026-09-08 it
+ * held 40 000 entries covering 38 minutes — the whole ring is under an hour of
+ * fleet traffic. Every question this data is for ("how often, on camera 617,
+ * over the week the operator complained about") outlives that ring by two
+ * orders of magnitude, and a previous investigation in this repo was blocked
+ * for precisely this reason. The gate ALREADY writes a log line per decision
+ * (`confirmation gate: birth confirmed/suppressed/undecided`); adding a
+ * fourteenth field to it would answer nothing a day later.
+ *
+ * This is a MEASUREMENT table. It changes no behaviour, gates nothing, and
+ * nothing reads it on the frame path.
+ */
+import { z } from 'zod';
+/**
+ * How many birth decisions the cluster keeps, across every camera.
+ *
+ * Sized off a MEASURED rate, not a guess. Fleet-wide on the live hub,
+ * 2026-09-08 20:16 local, over the 38 minutes the log ring covered: 17 `track
+ * started` + 14 `birth suppressed — track record retracted` = 31 decided
+ * births, i.e. ~49/hour, ~1 200/day. Call a busy daytime hour five times that
+ * and the fleet writes ~6 000 rows/day.
+ *
+ * 30 000 rows is therefore ~25 days at the measured rate and ~5 days at five
+ * times it — comfortably past "a few days of traffic", which is the bar the
+ * operator's week-long complaint sets. At ~200 bytes a row the ceiling is
+ * ~6 MB, against a `tracks` table measured at 4.6 MB for a single 501-row page.
+ *
+ * A COUNT and not an age, for the same reason as the debug-note archive: the
+ * denominator of a miss rate is only meaningful over whatever window the table
+ * actually holds, and a quiet fleet should keep more of it, not less. Trimmed
+ * oldest-first on append.
+ */
+export declare const MAX_BIRTH_DECISION_RECORDS = 30000;
+/** Default page size for `listBirthDecisions` when the caller omits one. */
+export declare const BIRTH_DECISION_DEFAULT_LIMIT = 500;
+/**
+ * How stale a motion onset may be and still be offered as the birth-latency
+ * proxy. Beyond this the row records `null`, never a large number.
+ *
+ * 60 s is one order of magnitude above the latency being measured (the
+ * complaint is "seconds late") and one below the duration of a busy scene's
+ * continuous motion burst, where the onset is minutes old and says nothing
+ * about THIS subject. See {@link BirthDecisionRecord.birthLatencyMs} for the
+ * full error bars.
+ */
+export declare const MAX_BIRTH_LATENCY_PROXY_MS = 60000;
+/**
+ * What the gate decided about a birth, from the CALLER's point of view.
+ *
+ * Deliberately not `ConfirmationVerdict`: `undecided` is not a birth decision
+ * at all — it is a deferral, and the row is written when the deferral ENDS.
+ * The third member is the one the gate's own type cannot express, because
+ * exhaustion is a property of how long the caller waited.
+ */
+export declare const BirthDecisionVerdictSchema: z.ZodEnum<{
+    confirmed: "confirmed";
+    suppressed: "suppressed";
+    "exhausted-fallback": "exhausted-fallback";
+}>;
+export type BirthDecisionVerdict = z.infer<typeof BirthDecisionVerdictSchema>;
+/** One birth decision, as it is kept. */
+export declare const BirthDecisionRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    at: z.ZodNumber;
+    deviceId: z.ZodNumber;
+    sourceTrackId: z.ZodString;
+    className: z.ZodString;
+    verdict: z.ZodEnum<{
+        confirmed: "confirmed";
+        suppressed: "suppressed";
+        "exhausted-fallback": "exhausted-fallback";
+    }>;
+    reason: z.ZodNullable<z.ZodString>;
+    attempts: z.ZodNumber;
+    deferredForMs: z.ZodNumber;
+    decidedOnCoastedFrame: z.ZodBoolean;
+    birthEvidenceAvailable: z.ZodBoolean;
+    decidedByBirthEvidence: z.ZodBoolean;
+    bestScore: z.ZodNullable<z.ZodNumber>;
+    appliedMinConfidence: z.ZodNullable<z.ZodNumber>;
+    firstSeen: z.ZodNullable<z.ZodNumber>;
+    motionOnsetAt: z.ZodNullable<z.ZodNumber>;
+    birthLatencyMs: z.ZodNullable<z.ZodNumber>;
+    birthIndexInBurst: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type BirthDecisionRecord = z.infer<typeof BirthDecisionRecordSchema>;
+/** Query input for `listBirthDecisions` — newest first, one camera or all. */
+export declare const BirthDecisionQueryInputSchema: z.ZodObject<{
+    deviceId: z.ZodOptional<z.ZodNumber>;
+    since: z.ZodOptional<z.ZodNumber>;
+    verdict: z.ZodOptional<z.ZodEnum<{
+        confirmed: "confirmed";
+        suppressed: "suppressed";
+        "exhausted-fallback": "exhausted-fallback";
+    }>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type BirthDecisionQueryInput = z.infer<typeof BirthDecisionQueryInputSchema>;

package/dist/interfaces/pipeline-runner-capability.d.ts

@@ -83,6 +83,15 @@ export interface RunnerCameraConfig {
      * to disable the dynamic analyzer for this camera.
      */
     readonly onboardMotionDrivesAnalyzer: boolean;
+    /**
+     * Infer the session's PRE-ROLL — the retained history the restreamer replays
+     * at session open — instead of decoding it and discarding it. Mirrors
+     * `RunnerCameraConfigSchema.preRollInferenceEnabled` (default true; see the
+     * schema for why the default is the argument).
+     */
+    readonly preRollInferenceEnabled: boolean;
+    /** Frames one pre-roll catch-up burst may send to inference. `0` disables it. */
+    readonly preRollInferenceFrames: number;
     /** Master toggle — when false the occupancy recheck never arms (default). */
     readonly occupancyRecheckEnabled: boolean;
     /** Seconds between occupancy re-check bursts in watching phase. */

package/dist/interfaces/stream-broker.d.ts

@@ -149,6 +149,18 @@ export interface DecodedFrame {
     readonly capturedAt?: number;
     /** Process-local lazy source. Present with an empty `data` buffer on the co-located path. */
     readonly frameRef?: FrameRef;
+    /**
+     * True when this frame came out of a session's PRE-ROLL catch-up burst —
+     * retained history replayed at session open rather than live footage.
+     *
+     * It exists so a consumer can ROUTE the frame, not merely label it: history
+     * belongs in the runner's bounded pre-roll lane (FIFO, drained strictly
+     * behind live), never in the latest-only live detection queue, which would
+     * collapse a whole burst to its newest frame. A frame carrying this ALWAYS
+     * carries a `capturedAt` measured on the session media clock, not a fresh
+     * wall clock.
+     */
+    readonly preRoll?: boolean;
 }
 export interface DecodedAudioChunk {
     readonly data: Buffer;
@@ -446,4 +458,12 @@ export interface CameraDetectionConfig {
     readonly occupancyRecheckEnabled: boolean;
     readonly occupancyRecheckSec: number;
     readonly occupancyRecheckFrames: number;
+    /**
+     * Whether the session's already-decoded PRE-ROLL is inferred rather than
+     * dropped as stale, and how many of its frames the catch-up burst may spend
+     * (D411). Carried here because the orchestrator resolves it per camera and
+     * the runner is the one that spends it.
+     */
+    readonly preRollInferenceEnabled: boolean;
+    readonly preRollInferenceFrames: number;
 }

package/dist/{sleep-IjLtwkO5.js → sleep-Bo9cUOXp.js}

@@ -3519,6 +3519,7 @@ function createDeviceProxy(api, binding, opts) {
 			deleteTracks: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "deleteTracks", "mutation", input),
 			setTrackFlags: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "setTrackFlags", "mutation", input),
 			listArchivedDebugNotes: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "listArchivedDebugNotes", "query", input),
+			listBirthDecisions: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "listBirthDecisions", "query", input),
 			getEventStoreFootprint: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getEventStoreFootprint", "query", input),
 			getEventMediaFootprintByKind: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getEventMediaFootprintByKind", "query", input),
 			pruneEvents: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "pruneEvents", "mutation", input),

package/dist/{sleep-uGNYCvYp.mjs → sleep-DMghvp8F.mjs}

@@ -3519,6 +3519,7 @@ function createDeviceProxy(api, binding, opts) {
 			deleteTracks: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "deleteTracks", "mutation", input),
 			setTrackFlags: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "setTrackFlags", "mutation", input),
 			listArchivedDebugNotes: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "listArchivedDebugNotes", "query", input),
+			listBirthDecisions: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "listBirthDecisions", "query", input),
 			getEventStoreFootprint: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getEventStoreFootprint", "query", input),
 			getEventMediaFootprintByKind: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getEventMediaFootprintByKind", "query", input),
 			pruneEvents: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "pruneEvents", "mutation", input),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.170",
+  "version": "1.2.172",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",