@camstack/types 1.2.171 → 1.2.173

package/dist/addon/mint-once.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Mint-on-empty, with the read-back that makes it safe.
+ *
+ * ## The shape, and why it is a trap
+ *
+ * ```ts
+ * let secret = await state.get()
+ * if (secret === '') {
+ *   secret = randomUUID()
+ *   await state.set(secret)
+ * }
+ * ```
+ *
+ * `state.get()` cannot distinguish "never minted" from "the store could not be
+ * read": `readAddonStoreWithRetry` gives up and answers `{}`, so a store that
+ * is merely unreachable reads as EMPTY and this mints a SECOND secret over a
+ * perfectly good first one. For a signing secret that invalidates every link
+ * already handed out. For the HomeKit bridge identity it is irreversible —
+ * every paired iPhone loses the bridge, and no later write of the store brings
+ * it back.
+ *
+ * The read-back is the only evidence available at this layer that the store is
+ * actually answering. `snapshot.addon.ts` (`ensureLinkSecret`) has done this
+ * since 2026-08-14 and was the only site that did.
+ *
+ * ## What it does NOT fix
+ *
+ * If the write genuinely lands, the read-back confirms it and the old value is
+ * already gone — a read-back cannot undo a write. It is a gate on USING the
+ * minted value, and it is load-bearing only because the settings view refuses
+ * to write at all when the last read of the addon store failed
+ * (`writeAddonStore`'s refusal). The two together are what close the window;
+ * the durable fix is a discriminated read result carried all the way up —
+ * `docs/design/plans/2026-08-27-lettura-fallita-non-diventa-un-default.md`.
+ */
+/** Why a mint was refused. Both mean: the store is not answering. */
+export type MintRefusalReason = 'read-back-empty' | 'read-back-mismatch';
+export interface MintRefusalDetail {
+    readonly reason: MintRefusalReason;
+    /** True when the read-back answered the fallback — the usual store-down shape. */
+    readonly readBackEmpty: boolean;
+}
+export type MintOnceOutcome<TValue> = {
+    readonly kind: 'existing';
+    readonly value: TValue;
+} | {
+    readonly kind: 'minted';
+    readonly value: TValue;
+} | {
+    readonly kind: 'refused';
+};
+export interface MintOnceReadBackInput<TValue> {
+    /** Read the persisted value. MUST answer the fallback (not throw) when absent. */
+    readonly read: () => Promise<TValue>;
+    /** Is this the fallback — i.e. "nothing persisted, or nothing readable"? */
+    readonly isEmpty: (value: TValue) => boolean;
+    /** Produce a fresh value. Called at most once, and only when `isEmpty` holds. */
+    readonly mint: () => TValue;
+    /** Persist the freshly minted value. */
+    readonly write: (value: TValue) => Promise<void>;
+    /** Value equality for the read-back. Defaults to `Object.is`. */
+    readonly equals?: (a: TValue, b: TValue) => boolean;
+    /** Always log this: a refusal means a feature is deliberately not starting. */
+    readonly onRefused: (detail: MintRefusalDetail) => void;
+}
+/**
+ * Resolve a mint-once secret/identity: reuse what is stored, or mint, persist
+ * and READ BACK — refusing the minted value when the read-back disagrees.
+ *
+ * A `refused` outcome is never cached by this function; the caller may retry on
+ * the next tick, when the store may be answering again.
+ */
+export declare function mintOnceWithReadBack<TValue>(input: MintOnceReadBackInput<TValue>): Promise<MintOnceOutcome<TValue>>;

package/dist/addon.js

@@ -149,6 +149,8 @@ var CAP_INPUT_DEFAULTS = Object.freeze({
 			"pipelineEnabled": true,
 			"zones": [],
 			"onboardMotionDrivesAnalyzer": true,
+			"preRollInferenceEnabled": true,
+			"preRollInferenceFrames": 12,
 			"occupancyRecheckEnabled": true,
 			"occupancyRecheckSec": 300,
 			"occupancyRecheckFrames": 4,

package/dist/addon.mjs

@@ -148,6 +148,8 @@ var CAP_INPUT_DEFAULTS = Object.freeze({
 			"pipelineEnabled": true,
 			"zones": [],
 			"onboardMotionDrivesAnalyzer": true,
+			"preRollInferenceEnabled": true,
+			"preRollInferenceFrames": 12,
 			"occupancyRecheckEnabled": true,
 			"occupancyRecheckSec": 300,
 			"occupancyRecheckFrames": 4,

package/dist/capabilities/pipeline-runner.cap.d.ts

@@ -256,6 +256,8 @@ declare const RunnerCameraConfigSchema: z.ZodObject<{
         color: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>>>;
     onboardMotionDrivesAnalyzer: z.ZodDefault<z.ZodBoolean>;
+    preRollInferenceEnabled: z.ZodDefault<z.ZodBoolean>;
+    preRollInferenceFrames: z.ZodDefault<z.ZodNumber>;
     occupancyRecheckEnabled: z.ZodDefault<z.ZodBoolean>;
     occupancyRecheckSec: z.ZodDefault<z.ZodNumber>;
     occupancyRecheckFrames: z.ZodDefault<z.ZodNumber>;
@@ -516,6 +518,8 @@ export declare const pipelineRunnerCapability: {
                 color: z.ZodDefault<z.ZodString>;
             }, z.core.$strip>>>>;
             onboardMotionDrivesAnalyzer: z.ZodDefault<z.ZodBoolean>;
+            preRollInferenceEnabled: z.ZodDefault<z.ZodBoolean>;
+            preRollInferenceFrames: z.ZodDefault<z.ZodNumber>;
             occupancyRecheckEnabled: z.ZodDefault<z.ZodBoolean>;
             occupancyRecheckSec: z.ZodDefault<z.ZodNumber>;
             occupancyRecheckFrames: z.ZodDefault<z.ZodNumber>;

package/dist/index.js

@@ -21324,6 +21324,22 @@ var occupancyRecheckFramesField = {
 	step: 1
 };
 /**
+* Frames one PRE-ROLL catch-up burst may send to inference at session open.
+*
+* The default of 12 over a ~4 s retained window is one frame per ~333 ms of
+* footage, and costs ~480 ms of ONE inference permit at the 40 ms/frame this
+* fleet measures — one-shot, and only ever taken while a permit would still be
+* spare for live. `0` turns the burst off entirely (the history is still
+* decoded, because that is how the dial reaches a decodable GOP, and is then
+* discarded — the pre-D411 behaviour).
+*/
+var preRollInferenceFramesField = {
+	min: 0,
+	max: 30,
+	default: 12,
+	step: 1
+};
+/**
 * Source enum for motion signals fed to the runner. Extensible — add
 * new variants here when new motion-trigger paths are wired in
 * (`wasm-cross-camera`, `event-bus-relay`, etc.). The runner uses
@@ -21564,6 +21580,31 @@ var RunnerCameraConfigSchema = zod.z.object({
 	* to every occupancy rule until something moved in front of it. The churn is
 	* now paid on the interval instead — see `occupancyRecheckSecField`.
 	*/
+	/**
+	* Infer the session's PRE-ROLL — the retained history the restreamer replays
+	* at session open — instead of decoding it and throwing it away.
+	*
+	* DEFAULT `true`, and the default is the argument. This is not a new
+	* capability being offered cautiously: the pre-roll is ALREADY requested,
+	* already served, already decoded and already paid for on every on-motion
+	* detection session that asks for history. What shipped was a last-moment
+	* discard — `FrameSlot`'s throttle compares wall clocks, and ~4 s of media
+	* arriving inside a few hundred ms of wall clock looks to it like one frame's
+	* worth. Device 617, 2026-09-08: a re-run of the SAME model over the stored
+	* recording scored the subject `vehicle 0.5669` — above the 0.50 floor —
+	* 1.68 s BEFORE the live track was born, on a frame that was in the pre-roll,
+	* was decoded, and was freed.
+	*
+	* Shipping that as opt-in would ship the bug: an operator cannot discover a
+	* setting whose absence looks exactly like a camera that noticed the cyclist
+	* late. What makes ON safe is not a switch but the BOUND —
+	* `preRollInferenceFrames`, a wall-clock ceiling, and a lane that never takes
+	* the last inference permit — so the switch exists for the camera where the
+	* history is worthless (a doorbell whose subject is always already at the
+	* door), not as a hedge against the feature.
+	*/
+	preRollInferenceEnabled: zod.z.boolean().default(true),
+	preRollInferenceFrames: zod.z.number().min(preRollInferenceFramesField.min).max(preRollInferenceFramesField.max).default(preRollInferenceFramesField.default),
 	occupancyRecheckEnabled: zod.z.boolean().default(true),
 	occupancyRecheckSec: zod.z.number().min(occupancyRecheckSecField.min).max(occupancyRecheckSecField.max).default(occupancyRecheckSecField.default),
 	occupancyRecheckFrames: zod.z.number().min(occupancyRecheckFramesField.min).max(occupancyRecheckFramesField.max).default(occupancyRecheckFramesField.default),
@@ -21718,6 +21759,29 @@ var RunnerCameraDeviceUIFields = [
 			includes: "onboard"
 		}
 	},
+	{
+		key: "preRollInferenceEnabled",
+		type: "boolean",
+		style: "checkbox",
+		label: "Detect in the pre-roll",
+		description: "Run detection over the few seconds of footage the camera had already buffered when motion fired, so a subject that was in view before the trigger is found at the moment it appeared rather than seconds later. The burst is bounded and never delays live detection.",
+		default: true
+	},
+	{
+		key: "preRollInferenceFrames",
+		type: "slider",
+		label: "Pre-roll frames",
+		description: "How many frames of buffered history may be detected on, per session. Higher samples the history more densely; 0 disables the pass.",
+		min: preRollInferenceFramesField.min,
+		max: preRollInferenceFramesField.max,
+		step: preRollInferenceFramesField.step,
+		default: preRollInferenceFramesField.default,
+		showValue: true,
+		showWhen: {
+			field: "preRollInferenceEnabled",
+			equals: true
+		}
+	},
 	{
 		key: "occupancyRecheckEnabled",
 		type: "boolean",

package/dist/index.mjs

@@ -21323,6 +21323,22 @@ var occupancyRecheckFramesField = {
 	step: 1
 };
 /**
+* Frames one PRE-ROLL catch-up burst may send to inference at session open.
+*
+* The default of 12 over a ~4 s retained window is one frame per ~333 ms of
+* footage, and costs ~480 ms of ONE inference permit at the 40 ms/frame this
+* fleet measures — one-shot, and only ever taken while a permit would still be
+* spare for live. `0` turns the burst off entirely (the history is still
+* decoded, because that is how the dial reaches a decodable GOP, and is then
+* discarded — the pre-D411 behaviour).
+*/
+var preRollInferenceFramesField = {
+	min: 0,
+	max: 30,
+	default: 12,
+	step: 1
+};
+/**
 * Source enum for motion signals fed to the runner. Extensible — add
 * new variants here when new motion-trigger paths are wired in
 * (`wasm-cross-camera`, `event-bus-relay`, etc.). The runner uses
@@ -21563,6 +21579,31 @@ var RunnerCameraConfigSchema = z.object({
 	* to every occupancy rule until something moved in front of it. The churn is
 	* now paid on the interval instead — see `occupancyRecheckSecField`.
 	*/
+	/**
+	* Infer the session's PRE-ROLL — the retained history the restreamer replays
+	* at session open — instead of decoding it and throwing it away.
+	*
+	* DEFAULT `true`, and the default is the argument. This is not a new
+	* capability being offered cautiously: the pre-roll is ALREADY requested,
+	* already served, already decoded and already paid for on every on-motion
+	* detection session that asks for history. What shipped was a last-moment
+	* discard — `FrameSlot`'s throttle compares wall clocks, and ~4 s of media
+	* arriving inside a few hundred ms of wall clock looks to it like one frame's
+	* worth. Device 617, 2026-09-08: a re-run of the SAME model over the stored
+	* recording scored the subject `vehicle 0.5669` — above the 0.50 floor —
+	* 1.68 s BEFORE the live track was born, on a frame that was in the pre-roll,
+	* was decoded, and was freed.
+	*
+	* Shipping that as opt-in would ship the bug: an operator cannot discover a
+	* setting whose absence looks exactly like a camera that noticed the cyclist
+	* late. What makes ON safe is not a switch but the BOUND —
+	* `preRollInferenceFrames`, a wall-clock ceiling, and a lane that never takes
+	* the last inference permit — so the switch exists for the camera where the
+	* history is worthless (a doorbell whose subject is always already at the
+	* door), not as a hedge against the feature.
+	*/
+	preRollInferenceEnabled: z.boolean().default(true),
+	preRollInferenceFrames: z.number().min(preRollInferenceFramesField.min).max(preRollInferenceFramesField.max).default(preRollInferenceFramesField.default),
 	occupancyRecheckEnabled: z.boolean().default(true),
 	occupancyRecheckSec: z.number().min(occupancyRecheckSecField.min).max(occupancyRecheckSecField.max).default(occupancyRecheckSecField.default),
 	occupancyRecheckFrames: z.number().min(occupancyRecheckFramesField.min).max(occupancyRecheckFramesField.max).default(occupancyRecheckFramesField.default),
@@ -21717,6 +21758,29 @@ var RunnerCameraDeviceUIFields = [
 			includes: "onboard"
 		}
 	},
+	{
+		key: "preRollInferenceEnabled",
+		type: "boolean",
+		style: "checkbox",
+		label: "Detect in the pre-roll",
+		description: "Run detection over the few seconds of footage the camera had already buffered when motion fired, so a subject that was in view before the trigger is found at the moment it appeared rather than seconds later. The burst is bounded and never delays live detection.",
+		default: true
+	},
+	{
+		key: "preRollInferenceFrames",
+		type: "slider",
+		label: "Pre-roll frames",
+		description: "How many frames of buffered history may be detected on, per session. Higher samples the history more densely; 0 disables the pass.",
+		min: preRollInferenceFramesField.min,
+		max: preRollInferenceFramesField.max,
+		step: preRollInferenceFramesField.step,
+		default: preRollInferenceFramesField.default,
+		showValue: true,
+		showWhen: {
+			field: "preRollInferenceEnabled",
+			equals: true
+		}
+	},
 	{
 		key: "occupancyRecheckEnabled",
 		type: "boolean",

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

@@ -345,6 +345,21 @@ export interface PipelineInferenceResultPayload {
      * → delivery latency. Undefined when the frame carried no capture stamp.
      */
     readonly capturedAt?: number;
+    /**
+     * Wall-clock (ms) read on the RUNNER's node at the instant this payload was
+     * handed to the bus. A consumer's `now - emittedAt` is the delivery lag —
+     * the one number that tells a late DELIVERY apart from a slow CONSUMER when
+     * both produce the same signature (a silence, then a burst-drain). See
+     * `addon-post-analysis/src/pipeline-analytics/frame-lag-observer.ts` for how
+     * it is read and why the absolute value is not a latency.
+     *
+     * Optional, and undefined is UNKNOWN, never 0 (D8): the bus is telemetry,
+     * and during a rolling deploy a runner older than this field emits payloads
+     * without it as the normal case. A consumer that folds an absent stamp in as
+     * 0 reports "delivered instantly" and fabricates exactly the verdict the
+     * field exists to establish.
+     */
+    readonly emittedAt?: number;
     /** Child steps enabled for this camera + their scheduling policy (from the catalog). */
     readonly detailSteps?: readonly DetailStepAnnounce[];
     readonly [key: string]: unknown;

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/package.json

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