@camstack/types 1.2.158 → 1.2.160

package/dist/interfaces/recording-config.d.ts

@@ -29,17 +29,29 @@ export type RecordingWeekday = z.infer<typeof RecordingWeekdaySchema>;
 /**
  * DERIVED per-camera storage summary — the single field cheap consumers read
  * (the viewer's status dot, the camera list) instead of walking `bands`:
- *  - `off`        — no band covers the camera (or it is disabled).
- *  - `events`     — every band records around triggers only.
- *  - `continuous` — at least one band records continuously.
+ *  - `off`               — no band covers the camera (or it is disabled).
+ *  - `events`            — every band records around triggers only.
+ *  - `continuous`        — at least one band records continuously.
+ *  - `on-device-decision`— the DEVICE decides: recording runs for as long as the
+ *    camera raises its own `recording-signal` level (a robot that cleans). There
+ *    is no schedule to author, because there is no hour to program — see
+ *    {@link RecordingConfigSchema}`.deviceDecision`.
  *
- * NEVER authored: the recorder stamps it from the authoritative `bands` on
- * every save (`activeModeForConfig`). Writing it has no effect.
+ * NEVER authored: the recorder stamps it from the authoritative intent
+ * (`bands` + `deviceDecision`) on every save (`activeModeForConfig`). Writing it
+ * has no effect.
+ *
+ * `on-device-decision` is named for WHO decides, not for how the recording is
+ * requested. `on-demand` was rejected: in this repo's vocabulary a "demand" is
+ * something the operator makes (the live gate is the recorder's own "demand
+ * window"), and a knob whose name suggests the operator starts it while the
+ * device actually does is the D62 shape — a control nobody can predict.
  */
 export declare const RecordingStorageModeSchema: z.ZodEnum<{
     off: "off";
     events: "events";
     continuous: "continuous";
+    "on-device-decision": "on-device-decision";
 }>;
 export type RecordingStorageMode = z.infer<typeof RecordingStorageModeSchema>;
 /**
@@ -72,7 +84,6 @@ export declare const RecordingTriggersSchema: z.ZodObject<{
         animal: "animal";
     }>>>;
     sensorDeviceIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
-    deviceSignal: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type RecordingTriggers = z.infer<typeof RecordingTriggersSchema>;
 /**
@@ -101,7 +112,6 @@ export declare const RecordingBandTriggersSchema: z.ZodObject<{
         animal: "animal";
     }>>>;
     sensorDeviceIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
-    deviceSignal: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type RecordingBandTriggers = z.infer<typeof RecordingBandTriggersSchema>;
 /**
@@ -129,7 +139,6 @@ export declare const RecordingBandSchema: z.ZodObject<{
             animal: "animal";
         }>>>;
         sensorDeviceIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
-        deviceSignal: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     preBufferSec: z.ZodOptional<z.ZodNumber>;
     postBufferSec: z.ZodOptional<z.ZodNumber>;
@@ -149,30 +158,44 @@ export type RecordingBand = z.infer<typeof RecordingBandSchema>;
  * `postBufferSec` must therefore exceed one segment length plus the attach
  * latency (ffmpeg spawn + RTSP dial), or the window closes before the first
  * segment is ever finalized and the camera records nothing anyway. At the 10 s
- * default segment length, 30 s leaves room for two full segments. `preBufferSec`
- * is retroactive only — it costs nothing at record time, it merely keeps
- * already-written segments.
- *
- * ## Why `preBufferSec` is 15 and not one segment length
+ * default segment length, 30 s leaves room for two full segments.
  *
- * It has to cover the broker's RECORDING pre-roll, which is media handed to the
- * writer from BEFORE the trigger (D192/D193). If this bound were narrower, the
- * keep gate would delete the very seconds the ring just supplied — two
- * authorities disagreeing about the same footage, which is the failure D191 was
- * written against. It is therefore set to `RECORDING_PRE_ROLL_MAX_MS` (15 s),
- * the widest window the broker can be configured to serve, so an operator
- * raising the cluster pre-roll can never walk past the gate silently. The
- * addon-side guard is
- * `packages/addon-pipeline/src/recorder/addon/__tests__/band-decision.spec.ts`.
+ * ## There is no `preBufferSec` here any more (D381)
  *
- * An EXPLICIT `0` is left alone: that is an operator statement, not an omission,
- * and it is excluded from that invariant by name.
+ * There used to be, at 15 s, and its whole justification was that it had to
+ * cover the widest pre-roll the broker could serve. A number whose only
+ * correct value is another subsystem's ceiling is not a setting; it is that
+ * ceiling, restated where it can drift. The keep bound is derived from the
+ * prebuffer ceiling directly now, in `band-decision.ts`, so an operator
+ * raising the prebuffer cannot walk past the gate at all rather than merely
+ * being warned not to.
  */
 export declare const DEFAULT_EVENTS_BAND_BUFFER_SEC: {
-    readonly preBufferSec: 15;
     readonly postBufferSec: 30;
 };
 export type DefaultEventsBandBufferSec = typeof DEFAULT_EVENTS_BAND_BUFFER_SEC;
+/**
+ * Drop the RETIRED band `preBufferSec` from a persisted recording config.
+ *
+ * Explicit, and it reports what it removed, because the alternative is a
+ * silent strip: `RecordingBandSchema` is a plain `z.object`, so the key
+ * survives a parse and disappears on the next save with no line anywhere. An
+ * operator who had typed a number would find it gone and nothing would say
+ * when or why.
+ *
+ * Nothing is carried forward: the value it held was always required to be at
+ * least the broker's widest pre-roll, and the gate is now derived from exactly
+ * that ceiling. Every configuration that was legal therefore keeps a keep-gate
+ * at least as wide as the one it had — including an explicit `0`, which widens.
+ * That is deliberate and it is the only behaviour change: a band that kept
+ * nothing before its trigger now keeps up to the prebuffer ceiling of
+ * already-written footage, which is media that exists either way.
+ */
+export declare function stripRetiredBandPreBufferSec(config: RecordingConfig): {
+    readonly config: RecordingConfig;
+    /** Index of every band a value was removed from. Empty = nothing to do. */
+    readonly strippedBands: readonly number[];
+};
 /**
  * Adjacent recorded ranges closer than this belong to the SAME videoclip visit.
  *
@@ -223,6 +246,7 @@ export declare const RecordingConfigSchema: z.ZodObject<{
         off: "off";
         events: "events";
         continuous: "continuous";
+        "on-device-decision": "on-device-decision";
     }>>;
     profiles: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         high: "high";
@@ -247,19 +271,19 @@ export declare const RecordingConfigSchema: z.ZodObject<{
                 animal: "animal";
             }>>>;
             sensorDeviceIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
-            deviceSignal: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
         preBufferSec: z.ZodOptional<z.ZodNumber>;
         postBufferSec: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>;
+    deviceDecision: z.ZodOptional<z.ZodBoolean>;
     retention: z.ZodOptional<z.ZodObject<{
         maxAgeDays: z.ZodOptional<z.ZodNumber>;
         maxSizeGb: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strict>;
 export type RecordingConfig = z.infer<typeof RecordingConfigSchema>;
-/** The bands + enabled flag a mode is derived from — all {@link deriveRecordingMode} reads. */
-export type RecordingModeSource = Pick<RecordingConfig, 'enabled' | 'bands'>;
+/** The authored intent a mode is derived from — all {@link deriveRecordingMode} reads. */
+export type RecordingModeSource = Pick<RecordingConfig, 'enabled' | 'bands' | 'deviceDecision'>;
 /**
  * Derive the {@link RecordingStorageModeSchema} summary from the authoritative
  * bands: `continuous` when any band records continuously, `events` when a band
@@ -289,3 +313,36 @@ export declare const DEFAULT_RECORDING_PROFILES: readonly CamProfile[];
  * still records something). Empty assigned → empty result.
  */
 export declare function resolveRecordingProfiles(assigned: readonly CamProfile[], override: readonly CamProfile[] | undefined): CamProfile[];
+/** What {@link migrateLegacyDeviceSignalConfig} did to one stored row. */
+export interface LegacyDeviceSignalMigration {
+    /** The row to persist/parse. The SAME reference when nothing was legacy. */
+    readonly value: unknown;
+    /** The config now says `deviceDecision: true` — the mode was recovered. */
+    readonly migrated: boolean;
+    /**
+     * The legacy key was on a band that ALSO listened to something else (motion,
+     * a sensor …), so the key was dropped and the band kept. The camera keeps its
+     * other triggers and LOSES the device signal until an operator picks the new
+     * mode — the honest outcome: folding a mixed band into a mode would silently
+     * delete a schedule the operator authored.
+     */
+    readonly strippedOnly: boolean;
+}
+/**
+ * Turn a config stored under D371 (`bands[].triggers.deviceSignal: true`) into
+ * a D380 one (`deviceDecision: true`, no bands). Pure, total and IDEMPOTENT —
+ * a row with no legacy key comes back as the SAME reference, `migrated: false`.
+ *
+ * ## Why the schema cannot be left to do this
+ *
+ * `RecordingTriggersSchema` is a non-strict `z.object`, so the retired key is
+ * SILENTLY STRIPPED on read. The camera whose only trigger it was would parse
+ * cleanly into an `events` band that lists nothing — "enabled, and records
+ * nothing, forever", the exact shape `eventsBandCanEverDemand` exists to shout
+ * about, reached without a single line in the log. On the reference hub that is
+ * camera 4374, the one camera an operator had configured by hand.
+ *
+ * `enabled` is carried through untouched: a camera the operator had switched
+ * OFF comes out of a migration still off (D62).
+ */
+export declare function migrateLegacyDeviceSignalConfig(raw: unknown): LegacyDeviceSignalMigration;

package/dist/{sleep-IaOr7P-z.mjs → sleep-Cfij6Jj9.mjs}

@@ -3859,7 +3859,7 @@ function createDeviceProxy(api, binding, opts) {
 * can answer "may a rule actuate this?" without importing the schema barrel
 * (~144MB RSS per runner, D28).
 *
-* Coverage: 82 device-scoped capabilities.
+* Coverage: 83 device-scoped capabilities.
 */
 var DEVICE_SCOPED_CAPS = new Set([
 	"accessories",
@@ -3924,6 +3924,7 @@ var DEVICE_SCOPED_CAPS = new Set([
 	"ptz",
 	"ptz-autotrack",
 	"reboot",
+	"recording-signal",
 	"scene-monitor",
 	"script-runner",
 	"smoke",

package/dist/{sleep-BGiOgxye.js → sleep-DDIFZGbc.js}

@@ -3859,7 +3859,7 @@ function createDeviceProxy(api, binding, opts) {
 * can answer "may a rule actuate this?" without importing the schema barrel
 * (~144MB RSS per runner, D28).
 *
-* Coverage: 82 device-scoped capabilities.
+* Coverage: 83 device-scoped capabilities.
 */
 var DEVICE_SCOPED_CAPS = new Set([
 	"accessories",
@@ -3924,6 +3924,7 @@ var DEVICE_SCOPED_CAPS = new Set([
 	"ptz",
 	"ptz-autotrack",
 	"reboot",
+	"recording-signal",
 	"scene-monitor",
 	"script-runner",
 	"smoke",

package/dist/types/detection.d.ts

@@ -16,6 +16,12 @@ export interface SpatialDetection {
      * measured at native resolution is not the thing they exist to kill.
      */
     readonly nativeRecovery?: NativeRecoveryEvidence;
+    /**
+     * Mirrored from {@link ObjectDetection.birthEvidence} when this detection
+     * enters the tracker, so a birth the tracker mints carries the pixels that
+     * produced it all the way to the confirmation gate (D379).
+     */
+    readonly birthEvidence?: BirthEvidence;
 }
 export interface CropInput {
     readonly frame: FrameInput;
@@ -230,6 +236,12 @@ export interface DetectionBase {
      * {@link NativeRecoveryEvidence}.
      */
     readonly nativeRecovery?: NativeRecoveryEvidence;
+    /**
+     * The box's own pixels, cut by the runner at the instant of detection, for a
+     * box it had not seen recently. See {@link BirthEvidence} — this is what the
+     * confirmation gate looks at instead of asking for pixels afterwards.
+     */
+    readonly birthEvidence?: BirthEvidence;
 }
 /**
  * What a native-resolution second pass ALREADY measured about a box.
@@ -255,6 +267,64 @@ export interface NativeRecoveryEvidence {
     /** Side of the compressed view the model actually saw, in pixels. */
     readonly viewPx: number;
 }
+/**
+ * The pixels of a candidate birth, CUT AT THE INSTANT IT WAS DETECTED.
+ *
+ * ## Why this exists (D379)
+ *
+ * The confirmation gate asks one question of a new track: re-run the detector
+ * on a crop of the box and see whether the subject is really there. Until now
+ * it asked for those pixels AFTERWARDS, by `FrameHandle`, across a process
+ * boundary — and measured on the live hub over three hours that request fails
+ * 7 452 times, 99.9% of them `worker-lease-gone`, at a median handle age of
+ * 1 347 ms and misses recorded as early as 254 ms. The frame is not evicted
+ * late; it is very often never retained at all (`leaseAdmitted:9` against
+ * `leaseMarks:297` on one measured worker, `leaseReleasedEarly:288`). 1 191 of
+ * 1 883 gate verdicts in that window (63%) never saw a pixel.
+ *
+ * So the crop is cut where the pixels are already in hand — in the runner, on
+ * the frame the detection was measured on — and RIDES the detection. No store,
+ * no handle, no lease, no round trip, and above all no OTHER INSTANT: a subject
+ * that has moved is not in a later frame, and its absence there is not evidence
+ * it was never here.
+ *
+ * This is the same discipline Scrypted enforces structurally: its decoded frame
+ * is invalidated the moment the `for await` body returns
+ * (`plugins/python-codecs/src/libav.py:105-112`), so every second look — face
+ * crop, embedding, retained detection image — is taken IN BAND
+ * (`plugins/objectdetector/src/main.ts:512-520`).
+ *
+ * ## What it is NOT
+ *
+ * Not a detail/CLIP crop, and nothing here calls `deriveDetailCropRect` (D52):
+ * this rectangle is the detection box padded for a CLASSIFICATION question and
+ * is never fed to an embedder, never stored as media, never indexed. It is also
+ * not a frame: it is one small JPEG of one box, cut only for a box the runner
+ * has not seen recently, so it never crosses a boundary at frame rate (D9/D18).
+ */
+export interface BirthEvidence {
+    /** Base64 JPEG of {@link rect}, cut from the frame this detection was measured on. */
+    readonly jpegBase64: string;
+    /**
+     * The rectangle the JPEG covers, in ABSOLUTE pixels of the analysis frame —
+     * the same space as `DetectionBoundingBox`. The gate needs it to put a
+     * crop-space re-detection back into the frame (secondary promotion), and it
+     * is the padded box, never the bare one.
+     */
+    readonly rect: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+    /**
+     * Which raster it was cut from. `analysis` is the ≤640 detection frame the
+     * runner holds in its own address space — the only raster that is present,
+     * for free, at the instant of detection. A future native rung would add a
+     * value here rather than change the meaning of this one.
+     */
+    readonly tier: 'analysis';
+}
 /** Object detection (first-level person/vehicle/animal OR detail face/plate). */
 export interface ObjectDetection extends DetectionBase {
     readonly kind: 'first-level' | 'detail';

package/package.json

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