@camstack/types 1.2.172 → 1.2.175

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

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_event_category = require("./event-category-BVo6ta6_.js");
-const require_sleep = require("./sleep-Bo9cUOXp.js");
+const require_event_category = require("./event-category-BNJ9EE5B.js");
+const require_sleep = require("./sleep-CTHjJilA.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 //#region src/generated/cap-input-defaults.ts
 /**

package/dist/addon.mjs

@@ -1,5 +1,5 @@
-import { t as EventCategory } from "./event-category-CnLqLOKs.mjs";
-import { D as adminUiCapability, E as DeviceType, G as scopeKey, H as ReadinessTimeoutError, M as expandCapMethods, R as nodePin, S as DEVICE_CHILDREN_BATCH_MAX, V as ReadinessRegistry, _t as DATAPLANE_SECRET_HEADER, a as asJsonObject, b as deviceOpsCapability, bt as BaseAddon, d as BOOT_RECOVERY_BACKOFF_MS, f as DEVICE_SCOPED_CAPS, h as createEventBusSliceSource, m as createDeviceProxy, p as isDeviceScopedCap, s as asString, t as sleep, u as parseJsonUnknown, wt as emitReadiness, x as viewerUiCapability, xt as normalizeAddonInitResult, yt as DisposerChain, z as readNodePin } from "./sleep-DMghvp8F.mjs";
+import { t as EventCategory } from "./event-category-DAXzJeTX.mjs";
+import { D as adminUiCapability, E as DeviceType, G as scopeKey, H as ReadinessTimeoutError, M as expandCapMethods, R as nodePin, S as DEVICE_CHILDREN_BATCH_MAX, V as ReadinessRegistry, _t as DATAPLANE_SECRET_HEADER, a as asJsonObject, b as deviceOpsCapability, bt as BaseAddon, d as BOOT_RECOVERY_BACKOFF_MS, f as DEVICE_SCOPED_CAPS, h as createEventBusSliceSource, m as createDeviceProxy, p as isDeviceScopedCap, s as asString, t as sleep, u as parseJsonUnknown, wt as emitReadiness, x as viewerUiCapability, xt as normalizeAddonInitResult, yt as DisposerChain, z as readNodePin } from "./sleep-ox21Ig4I.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
 //#region src/generated/cap-input-defaults.ts
 /**

package/dist/capabilities/battery.cap.d.ts

@@ -104,8 +104,8 @@ export declare const batteryCapability: {
     /**
      * Runtime-state slice — every provider that registers this cap
      * stores the same shape under `device.runtimeState[battery]`.
-     * Cross-provider uniformity: a Reolink Argus, a Frigate sensor
-     * proxy, an ONVIF battery cam all read/write the same keys.
+     * Cross-provider uniformity: a Reolink Argus, a sensor proxy,
+     * an ONVIF battery cam all read/write the same keys.
      * Consumers (BatteryBadge, snapshot wrapper sleep gate) read once
      * via `device.runtimeState.getCapState('battery')` regardless of
      * the underlying driver.

package/dist/capabilities/camera-credentials.cap.d.ts

@@ -14,7 +14,7 @@ import { DeviceType } from '../device/device-type.js';
  *
  * Implementations:
  *   - Each camera-providing addon registers this cap natively per
- *     device (Reolink, Hikvision, RTSP, Frigate, ONVIF self).
+ *     device (Reolink, Hikvision, RTSP, ONVIF self).
  *   - Returns a snapshot from the persisted device config blob — no
  *     extra round-trip to the camera, no probing.
  *   - The cap is admin-only (`auth: 'admin'`) — credentials must not

package/dist/capabilities/capability-definition.d.ts

@@ -406,8 +406,8 @@ export interface CapabilityDefinition<TName extends string = string, TMethods ex
      * .setCapState('<capName>', value)`. Examples:
      *
      *   - `batteryCapability.runtimeState`: `{ percentage, charging,
-     *     sleeping, lastUpdated }`. A Reolink Argus, a Frigate sensor
-     *     proxy, an ONVIF battery cam — every provider stores the
+     *     sleeping, lastUpdated }`. A Reolink Argus, a sensor proxy,
+     *     an ONVIF battery cam — every provider stores the
      *     same shape under `state.battery`.
      *   - `ptzCapability.runtimeState`: `{ pan, tilt, zoom }`.
      *

package/dist/capabilities/device-manager.cap.d.ts

@@ -7,7 +7,7 @@
  *   - `device-management.router.ts` (deleted in Phase 2)
  *   - `device-ops.router.ts` (compat layer — deleted; device-provider ops absorbed here)
  *
- * All device provider addons (rtsp, onvif, frigate, …) are hub-local: they may
+ * All device provider addons (rtsp, onvif, …) are hub-local: they may
  * fork into separate processes but never run on remote cluster agents. Therefore:
  *   - No nodeId routing needed — this is a pure hub singleton.
  *   - The hub's DeviceRegistry is the single source of truth for all live devices.

package/dist/capabilities/index.d.ts

@@ -87,8 +87,8 @@ export type { NativeCropRef, PipelineStepInputOutput, PipelineValidationIssue, P
 export { ModelSubstitutionSchema, NativeCropRefSchema, PipelineDefaultStepSchema, PipelineEngineChoiceSchema, PipelineRunResultBridge, PipelineStepInputSchema, PipelineValidationIssueSchema, PipelineValidationResultSchema, pipelineExecutorCapability, } from './pipeline-executor.cap.js';
 export type { CameraAssignmentStatus, CameraAudioStatus, CameraBrokerProfile, CameraBrokerStatus, CameraDecoderShm, CameraDecoderStatus, CameraDetectionPhase, CameraDetectionProvisioning, CameraDetectionProvisioningState, CameraDetectionStatus, CameraMotionStatus, CameraRecordingMode, CameraRecordingStatus, CameraSourceStatus, CameraSourceStream, CameraStatus, CameraStatusDegradation, CameraStatusDegradationReason, CameraStatusStage, DiskReconcileJob, InferenceDeviceExclusionReason, IngestOwner, NodeInferenceDevice, NodeInferenceDevices, } from './pipeline-orchestrator.cap.js';
 export { AgentLoadSummarySchema, CameraAssignmentStatusSchema, CameraAudioStatusSchema, CameraBrokerProfileSchema, CameraBrokerStatusSchema, CameraDecoderShmSchema, CameraDecoderStatusSchema, CameraDetectionPhaseSchema, CameraDetectionProvisioningSchema, CameraDetectionProvisioningStateSchema, CameraDetectionStatusSchema, CameraMotionStatusSchema, CameraRecordingModeSchema, CameraRecordingStatusSchema, CameraSourceStatusSchema, CameraSourceStreamSchema, CameraStatusDegradationReasonSchema, CameraStatusDegradationSchema, CameraStatusSchema, CameraStatusStageSchema, CapabilityBindingsSchema, DiskReconcileJobSchema, GlobalMetricsSchema, INFERENCE_DEVICE_EXCLUSION_REASONS, InferenceDeviceExclusionReasonSchema, IngestOwnerSchema, PipelineAssignmentSchema, pipelineOrchestratorCapability, } from './pipeline-orchestrator.cap.js';
-export type { DetailParent, DetailResult, MotionSource, MotionSources, ReportMotionInput, RunDetailSubtreeInput, RunDetailSubtreeResult, RunnerFrameSource, RunnerInferenceDevice, RunStatelessStepInput, RunStatelessStepResult, StatelessStepRefusal, } from './pipeline-runner.cap.js';
-export { FrameLazyCountersSchema, FrameLazyMetricsSchema, MotionSourceEnum, MotionSourcesSchema, type NativeCropBbox, NativeCropBboxSchema, NativeCropResultSchema, pipelineRunnerCapability, ReportMotionInputSchema, RunnerCameraConfigSchema, RunnerCameraDeviceUIFields, RunnerFrameSourceSchema, RunnerInferenceDeviceSchema, RunnerLocalLoadSchema, RunnerLocalMetricsSchema, } from './pipeline-runner.cap.js';
+export type { DetailParent, DetailResult, MotionSource, MotionSources, ParkedFrameKind, ParkedTrackFrame, ParkRefusal, ParkTrackFrameResult, ReportMotionInput, RunDetailSubtreeInput, RunDetailSubtreeResult, RunnerFrameSource, RunnerInferenceDevice, RunStatelessStepInput, RunStatelessStepResult, StatelessStepRefusal, } from './pipeline-runner.cap.js';
+export { FrameLazyCountersSchema, FrameLazyMetricsSchema, MotionSourceEnum, MotionSourcesSchema, type NativeCropBbox, NativeCropBboxSchema, NativeCropResultSchema, ParkedFrameKindSchema, ParkedTrackFrameSchema, ParkRefusalSchema, ParkTrackFrameResultSchema, pipelineRunnerCapability, ReportMotionInputSchema, RunnerCameraConfigSchema, RunnerCameraDeviceUIFields, RunnerFrameSourceSchema, RunnerInferenceDeviceSchema, RunnerLocalLoadSchema, RunnerLocalMetricsSchema, } from './pipeline-runner.cap.js';
 export { AudioChunkInputSchema, AudioClassificationLabelSchema, AudioLevelSchema, BoundingBoxSchema, FrameInputSchema, SpatialDetectionSchema, } from './schemas/detection-shared.js';
 export { CameraMetricsSchema, CameraMetricsWithDeviceIdSchema, OrchestratorMetricsSchema, } from './schemas/orchestrator-metrics.js';
 export type { CameraStream, CamProfile, CamStreamKind, DecodedAudioChunkWire, FrameHandleFormat, ProfileRtspEntry, ProfileSlot, ProfileSlotStatus, SubscribeAudioChunksInput, SubscribeAudioChunksResult, SubscribeFramesInput, SubscribeFramesResult, } from './schemas/streaming-shared.js';

package/dist/capabilities/notification-rules.cap.d.ts

@@ -697,9 +697,9 @@ export type NcMediaFrame = z.infer<typeof NcMediaFrameSchema>;
 export declare const NcMediaPolicySchema: z.ZodObject<{
     attach: z.ZodDefault<z.ZodEnum<{
         none: "none";
+        keyFrame: "keyFrame";
         best: "best";
         "best-matching": "best-matching";
-        keyFrame: "keyFrame";
     }>>;
     frame: z.ZodOptional<z.ZodEnum<{
         full: "full";
@@ -961,9 +961,9 @@ export declare const NcRuleInputSchema: z.ZodObject<{
     media: z.ZodDefault<z.ZodObject<{
         attach: z.ZodDefault<z.ZodEnum<{
             none: "none";
+            keyFrame: "keyFrame";
             best: "best";
             "best-matching": "best-matching";
-            keyFrame: "keyFrame";
         }>>;
         frame: z.ZodOptional<z.ZodEnum<{
             full: "full";
@@ -1297,9 +1297,9 @@ export declare const NcRulePatchSchema: z.ZodObject<{
     media: z.ZodOptional<z.ZodObject<{
         attach: z.ZodDefault<z.ZodEnum<{
             none: "none";
+            keyFrame: "keyFrame";
             best: "best";
             "best-matching": "best-matching";
-            keyFrame: "keyFrame";
         }>>;
         frame: z.ZodOptional<z.ZodEnum<{
             full: "full";
@@ -1478,9 +1478,9 @@ export declare const NcRuleSchema: z.ZodObject<{
     media: z.ZodDefault<z.ZodObject<{
         attach: z.ZodDefault<z.ZodEnum<{
             none: "none";
+            keyFrame: "keyFrame";
             best: "best";
             "best-matching": "best-matching";
-            keyFrame: "keyFrame";
         }>>;
         frame: z.ZodOptional<z.ZodEnum<{
             full: "full";
@@ -2174,9 +2174,9 @@ export declare const notificationRulesCapability: {
                 media: z.ZodDefault<z.ZodObject<{
                     attach: z.ZodDefault<z.ZodEnum<{
                         none: "none";
+                        keyFrame: "keyFrame";
                         best: "best";
                         "best-matching": "best-matching";
-                        keyFrame: "keyFrame";
                     }>>;
                     frame: z.ZodOptional<z.ZodEnum<{
                         full: "full";
@@ -2435,9 +2435,9 @@ export declare const notificationRulesCapability: {
                 media: z.ZodDefault<z.ZodObject<{
                     attach: z.ZodDefault<z.ZodEnum<{
                         none: "none";
+                        keyFrame: "keyFrame";
                         best: "best";
                         "best-matching": "best-matching";
-                        keyFrame: "keyFrame";
                     }>>;
                     frame: z.ZodOptional<z.ZodEnum<{
                         full: "full";
@@ -2694,9 +2694,9 @@ export declare const notificationRulesCapability: {
                 media: z.ZodDefault<z.ZodObject<{
                     attach: z.ZodDefault<z.ZodEnum<{
                         none: "none";
+                        keyFrame: "keyFrame";
                         best: "best";
                         "best-matching": "best-matching";
-                        keyFrame: "keyFrame";
                     }>>;
                     frame: z.ZodOptional<z.ZodEnum<{
                         full: "full";
@@ -2947,9 +2947,9 @@ export declare const notificationRulesCapability: {
                 media: z.ZodDefault<z.ZodObject<{
                     attach: z.ZodDefault<z.ZodEnum<{
                         none: "none";
+                        keyFrame: "keyFrame";
                         best: "best";
                         "best-matching": "best-matching";
-                        keyFrame: "keyFrame";
                     }>>;
                     frame: z.ZodOptional<z.ZodEnum<{
                         full: "full";
@@ -3283,9 +3283,9 @@ export declare const notificationRulesCapability: {
                 media: z.ZodOptional<z.ZodObject<{
                     attach: z.ZodDefault<z.ZodEnum<{
                         none: "none";
+                        keyFrame: "keyFrame";
                         best: "best";
                         "best-matching": "best-matching";
-                        keyFrame: "keyFrame";
                     }>>;
                     frame: z.ZodOptional<z.ZodEnum<{
                         full: "full";
@@ -3463,9 +3463,9 @@ export declare const notificationRulesCapability: {
                 media: z.ZodDefault<z.ZodObject<{
                     attach: z.ZodDefault<z.ZodEnum<{
                         none: "none";
+                        keyFrame: "keyFrame";
                         best: "best";
                         "best-matching": "best-matching";
-                        keyFrame: "keyFrame";
                     }>>;
                     frame: z.ZodOptional<z.ZodEnum<{
                         full: "full";
@@ -3770,9 +3770,9 @@ export declare const notificationRulesCapability: {
                 media: z.ZodDefault<z.ZodObject<{
                     attach: z.ZodDefault<z.ZodEnum<{
                         none: "none";
+                        keyFrame: "keyFrame";
                         best: "best";
                         "best-matching": "best-matching";
-                        keyFrame: "keyFrame";
                     }>>;
                     frame: z.ZodOptional<z.ZodEnum<{
                         full: "full";

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

@@ -594,6 +594,13 @@ export declare const ZoneCrossingSchema: z.ZodObject<{
     zoneName: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ZoneCrossing = z.infer<typeof ZoneCrossingSchema>;
+/** One zone a box was stamped with, and how much of the BOX fell inside it. */
+export declare const ZoneOverlapSchema: z.ZodObject<{
+    zoneId: z.ZodString;
+    zoneName: z.ZodOptional<z.ZodString>;
+    overlapPct: z.ZodNumber;
+}, z.core.$strip>;
+export type ZoneOverlap = z.infer<typeof ZoneOverlapSchema>;
 declare const ObjectEventSchema: z.ZodObject<{
     confidence: z.ZodOptional<z.ZodNumber>;
     bbox: z.ZodOptional<z.ZodObject<{
@@ -603,6 +610,12 @@ declare const ObjectEventSchema: z.ZodObject<{
         h: z.ZodNumber;
     }, z.core.$strip>>;
     zones: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    zoneOverlaps: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        zoneId: z.ZodString;
+        zoneName: z.ZodOptional<z.ZodString>;
+        overlapPct: z.ZodNumber;
+    }, z.core.$strip>>>>;
+    spawnRefused: z.ZodOptional<z.ZodString>;
     state: z.ZodOptional<z.ZodEnum<{
         moving: "moving";
         left: "left";
@@ -1495,6 +1508,12 @@ export declare const ScoredObjectEventSchema: z.ZodObject<{
         h: z.ZodNumber;
     }, z.core.$strip>>;
     zones: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    zoneOverlaps: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        zoneId: z.ZodString;
+        zoneName: z.ZodOptional<z.ZodString>;
+        overlapPct: z.ZodNumber;
+    }, z.core.$strip>>>>;
+    spawnRefused: z.ZodOptional<z.ZodString>;
     state: z.ZodOptional<z.ZodEnum<{
         moving: "moving";
         left: "left";
@@ -2269,6 +2288,12 @@ export declare const pipelineAnalyticsCapability: {
                 h: z.ZodNumber;
             }, z.core.$strip>>;
             zones: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+            zoneOverlaps: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                zoneId: z.ZodString;
+                zoneName: z.ZodOptional<z.ZodString>;
+                overlapPct: z.ZodNumber;
+            }, z.core.$strip>>>>;
+            spawnRefused: z.ZodOptional<z.ZodString>;
             state: z.ZodOptional<z.ZodEnum<{
                 moving: "moving";
                 left: "left";
@@ -3938,6 +3963,12 @@ export declare const pipelineAnalyticsCapability: {
                 h: z.ZodNumber;
             }, z.core.$strip>>;
             zones: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+            zoneOverlaps: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                zoneId: z.ZodString;
+                zoneName: z.ZodOptional<z.ZodString>;
+                overlapPct: z.ZodNumber;
+            }, z.core.$strip>>>>;
+            spawnRefused: z.ZodOptional<z.ZodString>;
             state: z.ZodOptional<z.ZodEnum<{
                 moving: "moving";
                 left: "left";

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

@@ -26,6 +26,67 @@ export declare const NativeCropResultSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type NativeCropBbox = z.infer<typeof NativeCropBboxSchema>;
 export type NativeCropCapResult = z.infer<typeof NativeCropResultSchema>;
+/**
+ * What a PARKED frame is for — the `kind` half of the `(deviceId, trackId,
+ * kind)` key ([D422](../../../docs/decisions/adr-0422-a-relevant-frame-is-parked-when-it-becomes-relevant.md)).
+ *
+ * - `keyFrame` — the track's clean best FULL frame at native width (capped by
+ *   the caller's `maxWidth`). What `keyFrame` + `keyFrameSmall` are written
+ *   from, and what the detail plane's full-frame rung cuts from.
+ * - `thumbnail` — the best-shot subject slab: the caller's 16:9 central-square
+ *   window, cut by the runner at uncapped native resolution.
+ *
+ * The runner never interprets `trackId`; it is an opaque key the hub owns.
+ */
+export declare const ParkedFrameKindSchema: z.ZodEnum<{
+    keyFrame: "keyFrame";
+    thumbnail: "thumbnail";
+}>;
+export type ParkedFrameKind = z.infer<typeof ParkedFrameKindSchema>;
+/**
+ * Why a park did NOT happen. Every one is logged on the runner with
+ * `tags: { deviceId }` and the handle's measured age, because a handle already
+ * gone at park time IS the defect the 150–500 ms window exists to prevent —
+ * never a reason to retry in a loop.
+ *
+ * - `handle-gone` — the native surface no longer resolves this handle (never
+ *   registered, past the lease bound, or the worker released it). `detail`
+ *   carries the runner's own miss reason.
+ * - `encode-failed` — pixels resolved and the JPEG encode threw.
+ */
+export declare const ParkRefusalSchema: z.ZodEnum<{
+    "handle-gone": "handle-gone";
+    "encode-failed": "encode-failed";
+}>;
+export type ParkRefusal = z.infer<typeof ParkRefusalSchema>;
+/** Answer to `parkTrackFrame` — a discriminated union, so "not parked" always names why. */
+export declare const ParkTrackFrameResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    parked: z.ZodLiteral<true>;
+    nodeId: z.ZodString;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    bytes: z.ZodNumber;
+    replaced: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    parked: z.ZodLiteral<false>;
+    nodeId: z.ZodString;
+    reason: z.ZodEnum<{
+        "handle-gone": "handle-gone";
+        "encode-failed": "encode-failed";
+    }>;
+    handleAgeMs: z.ZodNullable<z.ZodNumber>;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "parked">;
+export type ParkTrackFrameResult = z.infer<typeof ParkTrackFrameResultSchema>;
+/** A retrieved parcel — the runner's own JPEG, base64 for the wire. */
+export declare const ParkedTrackFrameSchema: z.ZodObject<{
+    jpeg: z.ZodString;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    timestamp: z.ZodNumber;
+    parkedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type ParkedTrackFrame = z.infer<typeof ParkedTrackFrameSchema>;
 /** Parent detection context passed to `runDetailSubtree` — the crop's
  *  originating detection, in FRAME-space coordinates. Reuses
  *  `NativeCropBboxSchema`'s `{x,y,w,h}` shape (same numeric fields; here
@@ -927,6 +988,107 @@ export declare const pipelineRunnerCapability: {
             }>;
             detail: z.ZodString;
         }, z.core.$strip>], "kind">, "mutation">;
+        /**
+         * PARK a frame for a track at the instant it is judged to matter
+         * ([D422](../../../docs/decisions/adr-0422-a-relevant-frame-is-parked-when-it-becomes-relevant.md)).
+         *
+         * The hub's `BestDetectionTracker` — the single "best per track" policy —
+         * concludes a frame is a track's best and calls this on the node that
+         * owns `handle` (`nodePin(handle.nodeId)`), while the handle is young. The
+         * runner cuts `bbox` from the native surface it already holds (a full
+         * frame for `keyFrame`, the caller's subject window for `thumbnail`),
+         * encodes ONE JPEG, and keeps it under `(deviceId, trackId, kind)`. Every
+         * later consumer retrieves by that key (`getParkedTrackFrame`) — a lookup
+         * that cannot miss on age. D52 holds: the rectangle is cut by the runner,
+         * never a pre-cut tile the caller decided. D9/D18 hold: one compressed
+         * encode at a decision point, never a stream.
+         *
+         * Idempotent per `(trackId, kind)`: a later park replaces (the ranking is
+         * the hub's; this adds no second opinion), an out-of-order older instant
+         * is ignored. Bounded per device and per node on the runner
+         * (`parked-frame-store.ts`), oldest-first eviction, never a refusal for
+         * space. A refusal names its reason and is logged on the runner with the
+         * handle's measured age — it is never retried into a loop.
+         */
+        readonly parkTrackFrame: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            trackId: z.ZodString;
+            kind: z.ZodEnum<{
+                keyFrame: "keyFrame";
+                thumbnail: "thumbnail";
+            }>;
+            handle: z.ZodObject<{
+                shmId: z.ZodString;
+                slot: z.ZodNumber;
+                seq: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                format: z.ZodEnum<{
+                    jpeg: "jpeg";
+                    rgb: "rgb";
+                    bgr: "bgr";
+                    yuv420: "yuv420";
+                    gray: "gray";
+                }>;
+                pts: z.ZodNumber;
+                byteLength: z.ZodNumber;
+                nodeId: z.ZodString;
+                slotCount: z.ZodNumber;
+            }, z.core.$strip>;
+            bbox: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                w: z.ZodNumber;
+                h: z.ZodNumber;
+            }, z.core.$strip>;
+            maxWidth: z.ZodOptional<z.ZodNumber>;
+            timestamp: z.ZodNumber;
+        }, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+            parked: z.ZodLiteral<true>;
+            nodeId: z.ZodString;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            bytes: z.ZodNumber;
+            replaced: z.ZodBoolean;
+        }, z.core.$strip>, z.ZodObject<{
+            parked: z.ZodLiteral<false>;
+            nodeId: z.ZodString;
+            reason: z.ZodEnum<{
+                "handle-gone": "handle-gone";
+                "encode-failed": "encode-failed";
+            }>;
+            handleAgeMs: z.ZodNullable<z.ZodNumber>;
+            detail: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "parked">, "mutation">;
+        /**
+         * Retrieve a parked parcel by `(deviceId, trackId, kind)`. Pinned to the
+         * node that answered the park (`ParkTrackFrameResult.nodeId`). `null` means
+         * nothing was parked under that key on this node — never "too old".
+         */
+        readonly getParkedTrackFrame: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            trackId: z.ZodString;
+            kind: z.ZodEnum<{
+                keyFrame: "keyFrame";
+                thumbnail: "thumbnail";
+            }>;
+        }, z.core.$strip>, z.ZodNullable<z.ZodObject<{
+            jpeg: z.ZodString;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            timestamp: z.ZodNumber;
+            parkedAt: z.ZodNumber;
+        }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * Drop every parcel of a track — the hub closed it. Idempotent. A track
+         * whose release is lost ages out on the runner under a hard ceiling.
+         */
+        readonly releaseParkedTrackFrames: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            trackId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            released: z.ZodNumber;
+        }, z.core.$strip>, "mutation">;
     };
 };
 export type IPipelineRunnerProvider = InferProvider<typeof pipelineRunnerCapability>;

package/dist/capabilities/recording.cap.d.ts

@@ -108,12 +108,31 @@ export declare const RecordingManifestSchema: z.ZodObject<{
     playbackEndpoints: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 export type RecordingManifest = z.infer<typeof RecordingManifestSchema>;
-/** Recording storage usage for one camera (bytes on disk across all its
- *  profiles/subtrees/locations on this node). */
+/**
+ * Recording storage usage for one camera — what the ARCHIVE holds for it,
+ * across every profile and every resolvable location on this node.
+ *
+ * ## Archive vs residency, which is the whole point of this shape (D418)
+ *
+ * `usedBytes` / `oldestMs` / `segments` are the durable hour ledger's numbers:
+ * the same quantity `RecordingLocationUsage.usedBytes` reports for the volume
+ * this camera writes to, so the two can be added up and compared.
+ *
+ * They were not always. Until D418 this row came from the recorder's in-RAM
+ * `RecordingIndex`, which since D287 holds only the live tail plus the hours
+ * somebody hydrated — so a hub with 1.9 TB and 3.3 days of footage reported
+ * 60.5 GB and "oldest: three hours ago" on the same page as the volume row
+ * that said otherwise, and two people read it as retention eating recent
+ * footage. Residency is still reported, under `residentBytes` /
+ * `residentOldestMs`, which answer a different question and say so.
+ */
 export declare const RecordingDeviceUsageSchema: z.ZodObject<{
     deviceId: z.ZodNumber;
     usedBytes: z.ZodNumber;
     oldestMs: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    segments: z.ZodOptional<z.ZodNumber>;
+    residentBytes: z.ZodOptional<z.ZodNumber>;
+    residentOldestMs: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
 export type RecordingDeviceUsage = z.infer<typeof RecordingDeviceUsageSchema>;
 /** Recording storage usage + capacity for one storage location. */
@@ -136,7 +155,14 @@ export declare const RecordingStorageUsageSchema: z.ZodObject<{
         deviceId: z.ZodNumber;
         usedBytes: z.ZodNumber;
         oldestMs: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        segments: z.ZodOptional<z.ZodNumber>;
+        residentBytes: z.ZodOptional<z.ZodNumber>;
+        residentOldestMs: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strip>>;
+    devicesRead: z.ZodOptional<z.ZodEnum<{
+        unavailable: "unavailable";
+        archive: "archive";
+    }>>;
     locations: z.ZodOptional<z.ZodArray<z.ZodObject<{
         locationId: z.ZodNullable<z.ZodString>;
         locationIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -446,7 +472,14 @@ export declare const recordingCapability: {
                 deviceId: z.ZodNumber;
                 usedBytes: z.ZodNumber;
                 oldestMs: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                segments: z.ZodOptional<z.ZodNumber>;
+                residentBytes: z.ZodOptional<z.ZodNumber>;
+                residentOldestMs: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
             }, z.core.$strip>>;
+            devicesRead: z.ZodOptional<z.ZodEnum<{
+                unavailable: "unavailable";
+                archive: "archive";
+            }>>;
             locations: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 locationId: z.ZodNullable<z.ZodString>;
                 locationIds: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/device/base-device-provider.d.ts

@@ -81,7 +81,7 @@ export interface FieldProbeResult {
  */
 export declare function toDeviceSummary(device: IDevice, addonId: string): DeviceSummary;
 /**
- * Base class for device-provider addons (rtsp, onvif, frigate).
+ * Base class for device-provider addons (rtsp, onvif).
  *
  * Provides default implementations for the common device-provider cap
  * methods (`start`, `stop`, `getStatus`, `getDevices`, `supportsDiscovery`,

package/dist/device/device-runtime-state.d.ts

@@ -7,8 +7,8 @@ import { z } from 'zod';
  * Shape: `Record<capName, capStateSlice>`. Each slice's schema is
  * declared by the capability itself (`CapabilityDefinition.runtimeState`)
  * so that any provider implementing the cap inherits the same shape —
- * the BatteryStatus shape a Reolink cam emits is the same a Frigate or
- * ONVIF cam emits, no driver-specific re-declaration.
+ * the BatteryStatus shape a Reolink cam emits is the same an ONVIF cam
+ * emits, no driver-specific re-declaration.
  *
  * Schemas are registered DYNAMICALLY as the device's caps are
  * installed (see `BaseDevice.registerNativeCap`). A slice without a

package/dist/device/device.d.ts

@@ -61,7 +61,7 @@ export interface IDevice {
      * Kernel-managed per-device runtime-state surface (cap-keyed slices:
      * `device-status`, `feature-probe`, `battery`, …). Present on every
      * `BaseDevice` subclass; optional here because a handful of direct
-     * `IDevice` implementors (legacy Onvif/Frigate camera classes) predate
+     * `IDevice` implementors (legacy Onvif camera classes) predate
      * the runtime-state machinery and don't carry one. Consumers that read
      * it (e.g. the device-manager's `probed`-flag derivation) tolerate
      * `undefined` as "no slice".

package/dist/device/source-info.d.ts

@@ -38,7 +38,7 @@ export type SourceInfo = z.infer<typeof SourceInfoSchema>;
 /**
  * Build the synthetic SourceInfo every existing provider falls back to
  * when no upstream value has been persisted. Keeps non-migrated providers
- * (Reolink / Hikvision / ONVIF / Frigate / RTSP) functional without code
+ * (Reolink / Hikvision / ONVIF / RTSP) functional without code
  * changes — `id` reuses the CamStack stableId, `system` reuses the addon
  * id. Real upstream identity replaces this once a provider migrates and
  * calls `updateSourceInfo()` with concrete values.

package/dist/enums/event-category.d.ts

@@ -589,7 +589,6 @@ export declare enum EventCategory {
      * issue. Payload `PipelineAnalyticsPlateGalleryChangedPayload`.
      */
     PipelineAnalyticsPlateGalleryChanged = "pipeline-analytics.plate-gallery-changed",
-    FrigateLiveEvent = "frigate.live-event",
     CameraStreamsProfileSlotsChanged = "camera-streams.onProfileSlotsChanged",
     /**
      * Stream-broker health watchdog. Per-broker (deviceId/profile) emission.

package/dist/enums.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_event_category = require("./event-category-BVo6ta6_.js");
+const require_event_category = require("./event-category-BNJ9EE5B.js");
 //#region src/enums/event-source-type.ts
 var EventSourceType = /* @__PURE__ */ function(EventSourceType) {
 	EventSourceType["Addon"] = "addon";

package/dist/enums.mjs

@@ -1,4 +1,4 @@
-import { t as EventCategory } from "./event-category-CnLqLOKs.mjs";
+import { t as EventCategory } from "./event-category-DAXzJeTX.mjs";
 //#region src/enums/event-source-type.ts
 var EventSourceType = /* @__PURE__ */ function(EventSourceType) {
 	EventSourceType["Addon"] = "addon";