@camstack/types 1.2.169 → 1.2.171

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/debug-note-archive.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Debug-note archive — the durable corpus of what operators asked to be
+ * checked, and the ONE thing about a debug note that outlives its track.
+ *
+ * D353 bound `debugNote` to the `debug` flag: turning the flag off clears the
+ * note in the same statement, so a track can never present a question without
+ * the flag that explains it. That invariant is right and stays. Its side
+ * effect was not: the act of REVIEWING a debug set destroyed every note in it,
+ * and the notes that survived a sweep aged out with their tracks anyway. On
+ * 2026-09-08 the notes from one morning's review — 25 to 27 of them — were
+ * already unreadable by the afternoon, leaving 11.
+ *
+ * So the clear now ARCHIVES first (D405). A row here is:
+ *
+ *  - written ONLY by the hub, from `applyTrackFlags`, immediately before the
+ *    note is cleared off the track row;
+ *  - keyed by ITS OWN id, derived from `(sourceTrackId, note)` so reviewing
+ *    the same track twice cannot double the corpus;
+ *  - NOT a track row, NOT subject to track retention, and NOT a durability pin
+ *    on anything — the track it names is expected to be gone.
+ *
+ * `sourceTrackId` is deliberately not called `trackId`. The analytics
+ * retention model derives track OWNERSHIP from a declared `trackId` column
+ * (`collection-classification.ts`), and a row that the cascade would delete
+ * with its track is exactly the row this table exists to keep. The name says
+ * PROVENANCE — the same distinction the stationary registry draws for the same
+ * reason.
+ */
+import { z } from 'zod';
+/**
+ * How many archived notes the cluster keeps, across every camera.
+ *
+ * GLOBAL, not per-device, and a COUNT, not an age. Both halves are deliberate:
+ *
+ *  - A per-device bound multiplies by the fleet — 30 cameras at 500 each is
+ *    15 000 rows to protect a corpus that only ever gets read fleet-wide (the
+ *    thing being mined is "what keeps going wrong", not "what goes wrong on
+ *    617"). One global ceiling is one number to reason about.
+ *  - An AGE bound would delete the corpus for being old, which is the failure
+ *    being fixed: a note from six months ago is the most valuable row in the
+ *    table precisely because the pattern it describes has had time to repeat.
+ *
+ * The number is sized off the measured rate. The 2026-09-08 sweep produced
+ * 25–27 notes; call a heavy day 100. 5 000 rows is roughly fifty such days,
+ * and at the observed rate (a few sweeps a week) several years. The cost is
+ * bounded by construction: a note is capped at `MAX_TRACK_DEBUG_NOTE_LEN`
+ * (500 chars) and the metadata beside it is under 100 bytes, so the ceiling is
+ * ~3 MB of text and the realistic occupancy is well under 1 MB — against a
+ * `tracks` table measured at 4.6 MB for a single 501-row page.
+ */
+export declare const MAX_ARCHIVED_DEBUG_NOTES = 5000;
+/** Default page size for `listArchivedDebugNotes` when the caller omits one. */
+export declare const ARCHIVED_DEBUG_NOTES_DEFAULT_LIMIT = 200;
+/** One archived note — the operator's words plus enough context to find what
+ *  they were looking at, after the track itself is gone. */
+export declare const ArchivedDebugNoteSchema: z.ZodObject<{
+    id: z.ZodString;
+    note: z.ZodString;
+    deviceId: z.ZodNumber;
+    sourceTrackId: z.ZodString;
+    archivedAt: z.ZodNumber;
+    trackStartedAt: z.ZodNullable<z.ZodNumber>;
+    trackClass: z.ZodNullable<z.ZodString>;
+    trackLabel: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ArchivedDebugNote = z.infer<typeof ArchivedDebugNoteSchema>;
+/** Query input for `listArchivedDebugNotes` — newest first, one camera or all. */
+export declare const ArchivedDebugNoteQueryInputSchema: z.ZodObject<{
+    deviceId: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ArchivedDebugNoteQueryInput = z.infer<typeof ArchivedDebugNoteQueryInputSchema>;

package/dist/interfaces/event-bus.d.ts

@@ -297,6 +297,14 @@ export interface PipelineAnalyticsPackagePickedUpPayload {
     /** The `package-events` delivery row this pick-up pairs to. */
     readonly deliveredEventId: string;
     readonly className: string;
+    /**
+     * The track of the PERSON who collected the parcel, when one was resolved
+     * (D404). It is also the pick-up row's media owner, which is what puts a
+     * frame of the collector — rather than of the empty doormat — on the
+     * notification. Absent means nobody qualified near the parcel's last
+     * sighting; the pick-up still fires, carrying the parcel's own owner.
+     */
+    readonly collectorTrackId?: string;
     readonly timestamp: number;
     readonly [key: string]: unknown;
 }

package/dist/{sleep-BZtO-eFY.js → sleep-Bo9cUOXp.js}

@@ -3518,6 +3518,8 @@ function createDeviceProxy(api, binding, opts) {
 			reconcileFromDisk: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "reconcileFromDisk", "mutation", input),
 			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-Bd-Y4RUt.mjs → sleep-DMghvp8F.mjs}

@@ -3518,6 +3518,8 @@ function createDeviceProxy(api, binding, opts) {
 			reconcileFromDisk: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "reconcileFromDisk", "mutation", input),
 			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.169",
+  "version": "1.2.171",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",