@trillboards/edge-sdk 0.2.41 → 0.2.49

package/dist/connectorCadence.d.ts

@@ -48,9 +48,18 @@
  *             is both cheaper and far tighter — 6.0-7.5 s — which is a second,
  *             independent reason the two products should not share a cadence.)
  *
- *   LOOKING   is free and is not the constraint: 3.6 ms median / 7.1 ms p95 to
- *             pull a frame down to ~178x100 grey and run the motion detector.
- *             Sixteen feeds looking every 30 s is 0.19% of one core.
+ *   LOOKING   costs almost no CPU — 3.6 ms median / 7.1 ms p95 to pull a frame
+ *             down to ~178x100 grey and run the motion detector, so sixteen
+ *             feeds looking every 30 s is 0.19% of one core.
+ *
+ *             CORRECTED 2026-08-18: that is the cost AFTER the frame is in
+ *             hand, and it is NOT the cost of a look. `buildCaptureArgs` spawns
+ *             one ffmpeg per grab with `-frames:v 1`, so every look also pays a
+ *             process start, an RTSP handshake and a wait for the next
+ *             keyframe. Measured through the shipped provider: p50 1 999 ms at
+ *             a 2 s keyframe interval, 4 005 ms at 4 s. Looking is CHEAP IN CPU
+ *             and EXPENSIVE IN WALL CLOCK, and it is the wall clock that bounds
+ *             the cadence — see MEASURED_LOOK_MS and lookIntervalMsForFeedCount.
  *
  *   FLOOR     on a still scene the motion gate contributes exactly ZERO
  *             analyses — verified across byte-identical frames and gaussian
@@ -73,8 +82,11 @@
  * would degrade into reporting empty aisles on time while missing the incident.
  *
  * Two clamps, both from values the system already declares:
- *   - never faster than the LOOK interval (`faceTriggeredIntervalMs`, 30 s):
- *     you cannot analyze more often than you look.
+ *   - never faster than MIN_ANALYZE_INTERVAL_MS (30 s). This clamp used to read
+ *     "never faster than the LOOK interval", which was the same 30 s constant;
+ *     the two split on 2026-08-18 and this one is the ANALYZE floor. You still
+ *     cannot analyze more often than you look, but the look cadence is now the
+ *     faster of the two, so it is no longer what binds here.
  *   - never slower than the DOOH default (300 s): this can only make a
  *     connector sample MORE often than it does today, never less.
  *
@@ -105,10 +117,161 @@ export declare const MEASURED_LOCAL_ANALYZE_MS = 7300;
  */
 export declare const STILL_FLOOR_SLOT_SHARE = 0.5;
 /**
- * The connector's look cadence (`faceTriggeredIntervalMs` default, which is
- * also the motion gate's scan interval). A heartbeat can never be finer.
+ * ── Two cadences, two different machines ───────────────────────────────────
+ *
+ * After the 2026-08-18 split, the connector's two cadences are bounded by two
+ * DIFFERENT pieces of hardware, and that is why they cannot share a constant:
+ *
+ *   ANALYZE is bounded by the BOX. `MEASURED_LOCAL_ANALYZE_MS` is one machine's
+ *           per-frame inference cost, and it varies by ~7x across the machines
+ *           this ships on. `periodicIntervalMsForFeedCount` derives the
+ *           still-scene heartbeat from it, so a slower box automatically gets a
+ *           slower heartbeat with no other change.
+ *
+ *   LOOK    is bounded by the RECORDER. `MEASURED_LOOK_MS` is an ffmpeg spawn
+ *           plus an RTSP handshake plus a wait for the camera's next keyframe;
+ *           none of that is inference and none of it moves when the box gets
+ *           faster. `lookIntervalMsForFeedCount` derives it from the recorder's
+ *           capture concurrency.
+ *
+ * So the look cadence below is NOT a function of the box, and does not need a
+ * hardware caveat. Re-measure it when the CAPTURE PATH changes — a persistent
+ * RTSP session instead of one process per grab would move it by an order of
+ * magnitude, and is the only thing that would.
+ */
+/**
+ * The fastest a connector may ANALYZE one feed, in ms.
+ *
+ * SEPARATE FROM `LOOK_INTERVAL_MS` since 2026-08-18, and the separation is the
+ * whole point. Both were 30 000 and one constant did both jobs, so nothing
+ * anywhere distinguished "how often do we look at the scene" from "how often
+ * may we spend an inference on it" — and the look cadence could not be lowered
+ * without dragging the analyze floor down with it and multiplying VLM volume on
+ * a 493/hour ceiling.
+ *
+ * 30 s is not a fresh judgement; it is the value the system already declares in
+ * two independent places, now named once:
+ *   - `faceTriggeredIntervalMs` (`DEFAULT_FACE_MS`, 30 s) is the default for
+ *     `MotionGate.minAnalyzeIntervalMs` — the floor between two motion-driven
+ *     analyses of one feed.
+ *   - `vision_pacing_config.daily_limit_per_screen` is 2 880 for the connector
+ *     fleet, i.e. 86 400 / 2 880 = one analysis per 30 s, enforced server-side.
+ *
+ * So a connector that analyzed faster than this would be throttled by the
+ * server anyway. Lowering the LOOK cadence must not move this number, and the
+ * `analyzeFloorUnmovedByLookCadence` test asserts exactly that.
+ */
+export declare const MIN_ANALYZE_INTERVAL_MS = 30000;
+/**
+ * Measured wall-clock cost of ONE LOOK, in ms — a real RTSP grab, not the
+ * decode-and-detect that follows it.
+ *
+ * The cascade budget above quotes 3.6 ms for a look. That is the cost AFTER the
+ * frame is in hand: pull it down to ~178x100 grey and run the detector. Getting
+ * it in hand is a different order of magnitude, because `buildCaptureArgs`
+ * spawns ONE ffmpeg per grab with `-frames:v 1` and no `-ss`, so every look pays
+ * a process start, a full RTSP DESCRIBE/SETUP/PLAY handshake, and a wait for the
+ * next keyframe before anything can be decoded.
+ *
+ * MEASURED 2026-08-18 through the shipped `RTSPCameraProvider` against mediamtx
+ * re-streaming a real CCTV clip at the documented degraded profile
+ * (640x360 / 399 kbps), one feed, no contention, p50 of 8 grabs:
+ *
+ *     keyframe interval   p50 grab
+ *     1 s                 1 986 ms
+ *     2 s                 1 999 - 2 025 ms
+ *     4 s                 4 005 ms
+ *
+ * So the cost is `max(~2 s, keyframe interval)`. The floor is the RTSP SESSION,
+ * not the process: the same ffmpeg args against a local file complete in
+ * 20-30 ms, so ~99% of a look is DESCRIBE/SETUP/PLAY plus the wait for an IDR.
+ * That is a property of pulling one frame per session, not of the machine — a
+ * faster box does not move it, and a persistent session would remove almost all
+ * of it. 2 s is taken as the floor
+ * because it is the fastest observed and because a 1-2 s keyframe interval is
+ * the common CCTV default.
+ *
+ * This is why `lookIntervalMsForFeedCount` exists. Asking for a look cadence
+ * finer than the capture path can deliver does not produce more looks — the
+ * grabs queue on `CaptureAdmission` and `getSensingHealth()` reports a cadence
+ * the connector is not running.
  */
-export declare const LOOK_INTERVAL_MS = 30000;
+export declare const MEASURED_LOOK_MS = 2000;
+/**
+ * Concurrent RTSP grabs one physical recorder will take —
+ * `DEFAULT_MAX_CONCURRENT_CAPTURES_PER_SOURCE` in `RTSPCameraProvider`, which
+ * keys its admission gate on `host:port` because 32 NVR channels are usually
+ * one recorder with one session budget.
+ *
+ * Restated here rather than imported because `edge-sdk` must not depend on a
+ * platform package, and asserted against the real constant by
+ * `connectorCadence.test.ts` so the two cannot drift.
+ *
+ * Raising it does NOT buy look throughput: measured at 16 feeds on one recorder,
+ * 2 concurrent and 8 concurrent both sustained 1.00 looks/s (the per-grab p50
+ * simply rose from 9 962 ms to 9 996 ms). The recorder, not the gate, is the
+ * bound.
+ */
+export declare const LOOK_CAPTURE_CONCURRENCY = 2;
+/**
+ * The look cadence this connector ran until 2026-08-18, kept ONLY as the slow
+ * clamp on `lookIntervalMsForFeedCount`.
+ *
+ * It is numerically equal to `MIN_ANALYZE_INTERVAL_MS` and that is a
+ * coincidence of history, not a relationship: they were one constant, and the
+ * whole point of the split is that they are free to move independently. Using
+ * the analyze floor here would re-create exactly the conflation this change
+ * removes — a future PR that lowers the analyze floor would silently speed up
+ * the slowest look cadence with it.
+ *
+ * Its only job is a guarantee: deriving a look cadence can make a connector look
+ * MORE often than it used to, never less. A 32-feed host cannot sustain even
+ * this (32 feeds want 1.07 looks/s against a measured 1.00), so past ~30 feeds
+ * the derivation is pinned here and the grabs queue on `CaptureAdmission` — a
+ * pre-existing capacity fact about one recorder, not something a faster look
+ * cadence introduces.
+ */
+export declare const LEGACY_LOOK_INTERVAL_MS = 30000;
+/**
+ * The connector's TARGET look cadence, in ms — how often the motion gate gets a
+ * chance to see anything at all.
+ *
+ * DERIVED FROM THE CATCH-RATE EVAL, not chosen. An event is catchable only if a
+ * LOOK lands inside it, so for an event of duration `d` against an
+ * event-uncorrelated look cadence `T` the ceiling on catch rate is
+ * `E[min(d/T,1)]`. Evaluated over the whole 75,657-event corpus
+ * (`eval/sensing-event-corpus.json`), event-weighted per reporting group and
+ * UNCAPPED:
+ *
+ *     T        Instant   Brief   Sustained   State
+ *     30 s        8.4%   18.6%       100%     100%
+ *      5 s       50.2%   55.1%       100%     100%
+ *      2.44 s    89.1%   71.2%       100%     100%
+ *      2 s       95.5%   75.2%       100%     100%
+ *      1 s      100.0%   86.6%       100%     100%
+ *      0.75 s   100.0%   90.1%       100%     100%
+ *
+ * Two things fall out of that table and both are load bearing:
+ *
+ *   - The Instant group — "alert me if the door opens after hours", a 2.2 s
+ *     median event — clears the 90% target at 2.4 s and is at 8.4% today. This
+ *     is the promise the 30 s cadence was silently failing.
+ *
+ *   - The Brief group does NOT reach 90% until 0.75 s, and 0.75 s is well below
+ *     the measured cost of a single grab (`MEASURED_LOOK_MS`). So 90% on every
+ *     shape is NOT reachable by look cadence on the current capture
+ *     architecture, and this constant does not pretend otherwise. Closing that
+ *     gap needs a persistent RTSP session — one long-lived ffmpeg per feed
+ *     instead of one per grab — which is an architecture change, not a number.
+ *
+ * 2 000 ms is therefore the fastest cadence that is BOTH an eval output and
+ * physically deliverable: it is the measured single-grab floor, and at it the
+ * Instant group clears the target. Do not lower it without first lowering
+ * `MEASURED_LOOK_MS`, and do not raise it without re-running the replay — the
+ * `sensing-catch-rate` guard re-reads this constant and fails if it drifts from
+ * the cadence the corpus was measured at.
+ */
+export declare const LOOK_INTERVAL_MS = 2000;
 /** The DOOH audience default (`DEFAULT_PERIODIC_MS`). The slow end of the clamp. */
 export declare const DOOH_PERIODIC_MS = 300000;
 /**
@@ -122,6 +285,28 @@ export declare const DOOH_PERIODIC_MS = 300000;
  * the key entirely rather than write a cadence derived from a bad count.
  */
 export declare function periodicIntervalMsForFeedCount(feedCount: unknown): number | null;
+/**
+ * The fastest look cadence a connector running `feedCount` feeds against ONE
+ * recorder can actually SUSTAIN, in ms.
+ *
+ * Same shape as `periodicIntervalMsForFeedCount` and for the same reason: a
+ * cadence is only real if the machine can deliver it. That function divides one
+ * inference slot among N feeds; this one divides one recorder's capture
+ * capacity among N feeds.
+ *
+ *     N feeds x (1 look / T)  <=  LOOK_CAPTURE_CONCURRENCY / MEASURED_LOOK_MS
+ *                          T  >=  N x MEASURED_LOOK_MS / LOOK_CAPTURE_CONCURRENCY
+ *
+ * Measured against that formula at 16 feeds on one recorder, GOP 2 s: predicted
+ * 16.0 s/feed, observed 16.0 s/feed.
+ *
+ * Never faster than `LOOK_INTERVAL_MS` (the eval target — looking finer than
+ * that buys nothing the corpus can see) and never slower than
+ * `LEGACY_LOOK_INTERVAL_MS`, so this can only make a connector look MORE often
+ * than it did, never less. Returns `null` on an uncountable feed count so a caller can
+ * omit the key rather than derive a cadence from nothing.
+ */
+export declare function lookIntervalMsForFeedCount(feedCount: unknown): number | null;
 /**
  * The still-scene analyses/hour a whole connector demands at a heartbeat, and
  * what fraction of the single slot that is. Exposed so the derivation is

package/dist/connectorCadence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connectorCadence.d.ts","sourceRoot":"","sources":["../src/connectorCadence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AAEH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,OAAQ,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,SAAU,CAAC;AAExC;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAKhF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,OAAO,EAClB,kBAAkB,EAAE,OAAO,GAC1B;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAOhD"}
+{"version":3,"file":"connectorCadence.d.ts","sourceRoot":"","sources":["../src/connectorCadence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0GG;AAEH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,OAAQ,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,gBAAgB,OAAQ,CAAC;AAEtC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,gBAAgB,OAAQ,CAAC;AAEtC,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,SAAU,CAAC;AAExC;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CA4BhF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAK5E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,OAAO,EAClB,kBAAkB,EAAE,OAAO,GAC1B;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAOhD"}

package/dist/connectorCadence.js

@@ -49,9 +49,18 @@
  *             is both cheaper and far tighter — 6.0-7.5 s — which is a second,
  *             independent reason the two products should not share a cadence.)
  *
- *   LOOKING   is free and is not the constraint: 3.6 ms median / 7.1 ms p95 to
- *             pull a frame down to ~178x100 grey and run the motion detector.
- *             Sixteen feeds looking every 30 s is 0.19% of one core.
+ *   LOOKING   costs almost no CPU — 3.6 ms median / 7.1 ms p95 to pull a frame
+ *             down to ~178x100 grey and run the motion detector, so sixteen
+ *             feeds looking every 30 s is 0.19% of one core.
+ *
+ *             CORRECTED 2026-08-18: that is the cost AFTER the frame is in
+ *             hand, and it is NOT the cost of a look. `buildCaptureArgs` spawns
+ *             one ffmpeg per grab with `-frames:v 1`, so every look also pays a
+ *             process start, an RTSP handshake and a wait for the next
+ *             keyframe. Measured through the shipped provider: p50 1 999 ms at
+ *             a 2 s keyframe interval, 4 005 ms at 4 s. Looking is CHEAP IN CPU
+ *             and EXPENSIVE IN WALL CLOCK, and it is the wall clock that bounds
+ *             the cadence — see MEASURED_LOOK_MS and lookIntervalMsForFeedCount.
  *
  *   FLOOR     on a still scene the motion gate contributes exactly ZERO
  *             analyses — verified across byte-identical frames and gaussian
@@ -74,8 +83,11 @@
  * would degrade into reporting empty aisles on time while missing the incident.
  *
  * Two clamps, both from values the system already declares:
- *   - never faster than the LOOK interval (`faceTriggeredIntervalMs`, 30 s):
- *     you cannot analyze more often than you look.
+ *   - never faster than MIN_ANALYZE_INTERVAL_MS (30 s). This clamp used to read
+ *     "never faster than the LOOK interval", which was the same 30 s constant;
+ *     the two split on 2026-08-18 and this one is the ANALYZE floor. You still
+ *     cannot analyze more often than you look, but the look cadence is now the
+ *     faster of the two, so it is no longer what binds here.
  *   - never slower than the DOOH default (300 s): this can only make a
  *     connector sample MORE often than it does today, never less.
  *
@@ -95,8 +107,9 @@
  * what the operator wants; this says what the machine can deliver.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DOOH_PERIODIC_MS = exports.LOOK_INTERVAL_MS = exports.STILL_FLOOR_SLOT_SHARE = exports.MEASURED_LOCAL_ANALYZE_MS = void 0;
+exports.DOOH_PERIODIC_MS = exports.LOOK_INTERVAL_MS = exports.LEGACY_LOOK_INTERVAL_MS = exports.LOOK_CAPTURE_CONCURRENCY = exports.MEASURED_LOOK_MS = exports.MIN_ANALYZE_INTERVAL_MS = exports.STILL_FLOOR_SLOT_SHARE = exports.MEASURED_LOCAL_ANALYZE_MS = void 0;
 exports.periodicIntervalMsForFeedCount = periodicIntervalMsForFeedCount;
+exports.lookIntervalMsForFeedCount = lookIntervalMsForFeedCount;
 exports.stillSceneLoad = stillSceneLoad;
 /**
  * Measured median seconds per on-device analysis, in ms. See the header for the
@@ -110,10 +123,161 @@ exports.MEASURED_LOCAL_ANALYZE_MS = 7300;
  */
 exports.STILL_FLOOR_SLOT_SHARE = 0.5;
 /**
- * The connector's look cadence (`faceTriggeredIntervalMs` default, which is
- * also the motion gate's scan interval). A heartbeat can never be finer.
+ * ── Two cadences, two different machines ───────────────────────────────────
+ *
+ * After the 2026-08-18 split, the connector's two cadences are bounded by two
+ * DIFFERENT pieces of hardware, and that is why they cannot share a constant:
+ *
+ *   ANALYZE is bounded by the BOX. `MEASURED_LOCAL_ANALYZE_MS` is one machine's
+ *           per-frame inference cost, and it varies by ~7x across the machines
+ *           this ships on. `periodicIntervalMsForFeedCount` derives the
+ *           still-scene heartbeat from it, so a slower box automatically gets a
+ *           slower heartbeat with no other change.
+ *
+ *   LOOK    is bounded by the RECORDER. `MEASURED_LOOK_MS` is an ffmpeg spawn
+ *           plus an RTSP handshake plus a wait for the camera's next keyframe;
+ *           none of that is inference and none of it moves when the box gets
+ *           faster. `lookIntervalMsForFeedCount` derives it from the recorder's
+ *           capture concurrency.
+ *
+ * So the look cadence below is NOT a function of the box, and does not need a
+ * hardware caveat. Re-measure it when the CAPTURE PATH changes — a persistent
+ * RTSP session instead of one process per grab would move it by an order of
+ * magnitude, and is the only thing that would.
+ */
+/**
+ * The fastest a connector may ANALYZE one feed, in ms.
+ *
+ * SEPARATE FROM `LOOK_INTERVAL_MS` since 2026-08-18, and the separation is the
+ * whole point. Both were 30 000 and one constant did both jobs, so nothing
+ * anywhere distinguished "how often do we look at the scene" from "how often
+ * may we spend an inference on it" — and the look cadence could not be lowered
+ * without dragging the analyze floor down with it and multiplying VLM volume on
+ * a 493/hour ceiling.
+ *
+ * 30 s is not a fresh judgement; it is the value the system already declares in
+ * two independent places, now named once:
+ *   - `faceTriggeredIntervalMs` (`DEFAULT_FACE_MS`, 30 s) is the default for
+ *     `MotionGate.minAnalyzeIntervalMs` — the floor between two motion-driven
+ *     analyses of one feed.
+ *   - `vision_pacing_config.daily_limit_per_screen` is 2 880 for the connector
+ *     fleet, i.e. 86 400 / 2 880 = one analysis per 30 s, enforced server-side.
+ *
+ * So a connector that analyzed faster than this would be throttled by the
+ * server anyway. Lowering the LOOK cadence must not move this number, and the
+ * `analyzeFloorUnmovedByLookCadence` test asserts exactly that.
+ */
+exports.MIN_ANALYZE_INTERVAL_MS = 30000;
+/**
+ * Measured wall-clock cost of ONE LOOK, in ms — a real RTSP grab, not the
+ * decode-and-detect that follows it.
+ *
+ * The cascade budget above quotes 3.6 ms for a look. That is the cost AFTER the
+ * frame is in hand: pull it down to ~178x100 grey and run the detector. Getting
+ * it in hand is a different order of magnitude, because `buildCaptureArgs`
+ * spawns ONE ffmpeg per grab with `-frames:v 1` and no `-ss`, so every look pays
+ * a process start, a full RTSP DESCRIBE/SETUP/PLAY handshake, and a wait for the
+ * next keyframe before anything can be decoded.
+ *
+ * MEASURED 2026-08-18 through the shipped `RTSPCameraProvider` against mediamtx
+ * re-streaming a real CCTV clip at the documented degraded profile
+ * (640x360 / 399 kbps), one feed, no contention, p50 of 8 grabs:
+ *
+ *     keyframe interval   p50 grab
+ *     1 s                 1 986 ms
+ *     2 s                 1 999 - 2 025 ms
+ *     4 s                 4 005 ms
+ *
+ * So the cost is `max(~2 s, keyframe interval)`. The floor is the RTSP SESSION,
+ * not the process: the same ffmpeg args against a local file complete in
+ * 20-30 ms, so ~99% of a look is DESCRIBE/SETUP/PLAY plus the wait for an IDR.
+ * That is a property of pulling one frame per session, not of the machine — a
+ * faster box does not move it, and a persistent session would remove almost all
+ * of it. 2 s is taken as the floor
+ * because it is the fastest observed and because a 1-2 s keyframe interval is
+ * the common CCTV default.
+ *
+ * This is why `lookIntervalMsForFeedCount` exists. Asking for a look cadence
+ * finer than the capture path can deliver does not produce more looks — the
+ * grabs queue on `CaptureAdmission` and `getSensingHealth()` reports a cadence
+ * the connector is not running.
  */
-exports.LOOK_INTERVAL_MS = 30000;
+exports.MEASURED_LOOK_MS = 2000;
+/**
+ * Concurrent RTSP grabs one physical recorder will take —
+ * `DEFAULT_MAX_CONCURRENT_CAPTURES_PER_SOURCE` in `RTSPCameraProvider`, which
+ * keys its admission gate on `host:port` because 32 NVR channels are usually
+ * one recorder with one session budget.
+ *
+ * Restated here rather than imported because `edge-sdk` must not depend on a
+ * platform package, and asserted against the real constant by
+ * `connectorCadence.test.ts` so the two cannot drift.
+ *
+ * Raising it does NOT buy look throughput: measured at 16 feeds on one recorder,
+ * 2 concurrent and 8 concurrent both sustained 1.00 looks/s (the per-grab p50
+ * simply rose from 9 962 ms to 9 996 ms). The recorder, not the gate, is the
+ * bound.
+ */
+exports.LOOK_CAPTURE_CONCURRENCY = 2;
+/**
+ * The look cadence this connector ran until 2026-08-18, kept ONLY as the slow
+ * clamp on `lookIntervalMsForFeedCount`.
+ *
+ * It is numerically equal to `MIN_ANALYZE_INTERVAL_MS` and that is a
+ * coincidence of history, not a relationship: they were one constant, and the
+ * whole point of the split is that they are free to move independently. Using
+ * the analyze floor here would re-create exactly the conflation this change
+ * removes — a future PR that lowers the analyze floor would silently speed up
+ * the slowest look cadence with it.
+ *
+ * Its only job is a guarantee: deriving a look cadence can make a connector look
+ * MORE often than it used to, never less. A 32-feed host cannot sustain even
+ * this (32 feeds want 1.07 looks/s against a measured 1.00), so past ~30 feeds
+ * the derivation is pinned here and the grabs queue on `CaptureAdmission` — a
+ * pre-existing capacity fact about one recorder, not something a faster look
+ * cadence introduces.
+ */
+exports.LEGACY_LOOK_INTERVAL_MS = 30000;
+/**
+ * The connector's TARGET look cadence, in ms — how often the motion gate gets a
+ * chance to see anything at all.
+ *
+ * DERIVED FROM THE CATCH-RATE EVAL, not chosen. An event is catchable only if a
+ * LOOK lands inside it, so for an event of duration `d` against an
+ * event-uncorrelated look cadence `T` the ceiling on catch rate is
+ * `E[min(d/T,1)]`. Evaluated over the whole 75,657-event corpus
+ * (`eval/sensing-event-corpus.json`), event-weighted per reporting group and
+ * UNCAPPED:
+ *
+ *     T        Instant   Brief   Sustained   State
+ *     30 s        8.4%   18.6%       100%     100%
+ *      5 s       50.2%   55.1%       100%     100%
+ *      2.44 s    89.1%   71.2%       100%     100%
+ *      2 s       95.5%   75.2%       100%     100%
+ *      1 s      100.0%   86.6%       100%     100%
+ *      0.75 s   100.0%   90.1%       100%     100%
+ *
+ * Two things fall out of that table and both are load bearing:
+ *
+ *   - The Instant group — "alert me if the door opens after hours", a 2.2 s
+ *     median event — clears the 90% target at 2.4 s and is at 8.4% today. This
+ *     is the promise the 30 s cadence was silently failing.
+ *
+ *   - The Brief group does NOT reach 90% until 0.75 s, and 0.75 s is well below
+ *     the measured cost of a single grab (`MEASURED_LOOK_MS`). So 90% on every
+ *     shape is NOT reachable by look cadence on the current capture
+ *     architecture, and this constant does not pretend otherwise. Closing that
+ *     gap needs a persistent RTSP session — one long-lived ffmpeg per feed
+ *     instead of one per grab — which is an architecture change, not a number.
+ *
+ * 2 000 ms is therefore the fastest cadence that is BOTH an eval output and
+ * physically deliverable: it is the measured single-grab floor, and at it the
+ * Instant group clears the target. Do not lower it without first lowering
+ * `MEASURED_LOOK_MS`, and do not raise it without re-running the replay — the
+ * `sensing-catch-rate` guard re-reads this constant and fails if it drifts from
+ * the cadence the corpus was measured at.
+ */
+exports.LOOK_INTERVAL_MS = 2000;
 /** The DOOH audience default (`DEFAULT_PERIODIC_MS`). The slow end of the clamp. */
 exports.DOOH_PERIODIC_MS = 300000;
 /**
@@ -131,7 +295,58 @@ function periodicIntervalMsForFeedCount(feedCount) {
     if (!Number.isFinite(n) || n < 1)
         return null;
     const required = Math.ceil((Math.trunc(n) * exports.MEASURED_LOCAL_ANALYZE_MS) / exports.STILL_FLOOR_SLOT_SHARE);
-    return Math.min(exports.DOOH_PERIODIC_MS, Math.max(exports.LOOK_INTERVAL_MS, required));
+    // MEASURED 2026-08-18, and left as it is ON PURPOSE — see below.
+    //
+    // The `DOOH_PERIODIC_MS` cap stops honouring `STILL_FLOOR_SLOT_SHARE` past
+    // ~20 feeds. `required` crosses 300 s at 21 feeds, and from there the clamp
+    // returns a heartbeat FASTER than the budget asks for, so the still-scene
+    // floor takes more than its declared half of the single slot and keeps
+    // taking: 51.1% at 21 feeds, 77.9% at 32 (replay-catch-rate.mjs
+    // --sweep-admission, .github/contracts/sensing-admission-sweep.json).
+    //
+    // Honouring the share above 20 feeds would mean returning 400 s, 600 s, and
+    // so on — which is strictly WORSE for the thing the heartbeat exists to do.
+    // `absence` catch rate is E[min(d/H,1)]: at 300 s it is 66.3%, and a slower
+    // heartbeat drives it down, on the exact class whose whole point is placing a
+    // hazard against a 111-second constructive-notice line. So the clamp is not a
+    // bug to fix here; it is the honest edge of what ONE 7.30 s slot can serve,
+    // and the fix is a second connector host, which `getSensingHealth()` already
+    // reports enough to see. Changing this constant would trade a measurable
+    // alert-path regression for a cadence number that reads tidier.
+    // Floored at the ANALYZE floor, never at the LOOK cadence. Those were the
+    // same constant until 2026-08-18; clamping this at the look cadence now would
+    // let a faster look cadence pull the still-scene heartbeat down with it and
+    // double the analyses a 1-feed connector runs, which is the exact failure the
+    // look/analyze split exists to prevent.
+    return Math.min(exports.DOOH_PERIODIC_MS, Math.max(exports.MIN_ANALYZE_INTERVAL_MS, required));
+}
+/**
+ * The fastest look cadence a connector running `feedCount` feeds against ONE
+ * recorder can actually SUSTAIN, in ms.
+ *
+ * Same shape as `periodicIntervalMsForFeedCount` and for the same reason: a
+ * cadence is only real if the machine can deliver it. That function divides one
+ * inference slot among N feeds; this one divides one recorder's capture
+ * capacity among N feeds.
+ *
+ *     N feeds x (1 look / T)  <=  LOOK_CAPTURE_CONCURRENCY / MEASURED_LOOK_MS
+ *                          T  >=  N x MEASURED_LOOK_MS / LOOK_CAPTURE_CONCURRENCY
+ *
+ * Measured against that formula at 16 feeds on one recorder, GOP 2 s: predicted
+ * 16.0 s/feed, observed 16.0 s/feed.
+ *
+ * Never faster than `LOOK_INTERVAL_MS` (the eval target — looking finer than
+ * that buys nothing the corpus can see) and never slower than
+ * `LEGACY_LOOK_INTERVAL_MS`, so this can only make a connector look MORE often
+ * than it did, never less. Returns `null` on an uncountable feed count so a caller can
+ * omit the key rather than derive a cadence from nothing.
+ */
+function lookIntervalMsForFeedCount(feedCount) {
+    const n = Number(feedCount);
+    if (!Number.isFinite(n) || n < 1)
+        return null;
+    const sustainable = Math.ceil((Math.trunc(n) * exports.MEASURED_LOOK_MS) / exports.LOOK_CAPTURE_CONCURRENCY);
+    return Math.min(exports.LEGACY_LOOK_INTERVAL_MS, Math.max(exports.LOOK_INTERVAL_MS, sustainable));
 }
 /**
  * The still-scene analyses/hour a whole connector demands at a heartbeat, and

package/dist/connectorCadence.js.map

@@ -1 +1 @@
-{"version":3,"file":"connectorCadence.js","sourceRoot":"","sources":["../src/connectorCadence.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;;;AAkCH,wEAKC;AAQD,wCAUC;AAvDD;;;;GAIG;AACU,QAAA,yBAAyB,GAAG,IAAK,CAAC;AAE/C;;;GAGG;AACU,QAAA,sBAAsB,GAAG,GAAG,CAAC;AAE1C;;;GAGG;AACU,QAAA,gBAAgB,GAAG,KAAM,CAAC;AAEvC,oFAAoF;AACvE,QAAA,gBAAgB,GAAG,MAAO,CAAC;AAExC;;;;;;;;;GASG;AACH,SAAgB,8BAA8B,CAAC,SAAkB;IAC/D,MAAM,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAC5B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,iCAAyB,CAAC,GAAG,8BAAsB,CAAC,CAAC;IACjG,OAAO,IAAI,CAAC,GAAG,CAAC,wBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,wBAAgB,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;GAKG;AACH,SAAgB,cAAc,CAC5B,SAAkB,EAClB,kBAA2B;IAE3B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1D,MAAM,CAAC,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC;IACrC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,eAAe,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IAC/E,MAAM,eAAe,GAAG,CAAC,CAAC,GAAG,OAAS,CAAC,GAAG,CAAC,CAAC;IAC5C,MAAM,cAAc,GAAG,OAAS,GAAG,iCAAyB,CAAC;IAC7D,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,eAAe,GAAG,cAAc,EAAE,CAAC;AAC1E,CAAC"}
+{"version":3,"file":"connectorCadence.js","sourceRoot":"","sources":["../src/connectorCadence.ts"],"names":[],"mappings":"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"}

package/dist/deployedCadence.d.ts

@@ -93,12 +93,24 @@ export declare const MAX_CADENCE_MS: number;
 export type CadenceReason = 
 /** No deployed cadence to honour — the caller keeps exactly what it had. */
 'no_request'
+/**
+ * The profile asked for nothing, so the cadence this machine can AFFORD is
+ * used instead of whatever default the manager was constructed with.
+ */
+ | 'derived_default'
 /** The operator's request was affordable and is being run verbatim. */
  | 'operator_request'
 /** Slowed to fit the single local inference slot. */
  | 'local_inference_budget'
-/** Faster than the connector ever looks — a cadence finer than a look is meaningless. */
- | 'look_interval'
+/**
+ * Faster than the connector may ANALYZE one feed.
+ *
+ * Named `look_interval` until 2026-08-18, when the look cadence and the
+ * analyze floor stopped being the same 30 000 ms constant. The old name now
+ * describes the wrong quantity: the connector looks every 2 s and this clamp
+ * is about the 30 s floor between two inferences.
+ */
+ | 'analyze_floor'
 /** SPED UP to `MAX_CADENCE_MS`: the request was slower than a capture loop can express. */
  | 'cadence_ceiling';
 export interface DeployedCadence {
@@ -117,9 +129,10 @@ export interface DeployedCadence {
 /**
  * Reconcile a deployed cadence with what this mode can afford.
  *
- * Returns `intervalMs: null` when the profile requested nothing — the caller
- * MUST then leave its current cadence alone, so a connector whose server says
- * nothing behaves exactly as it does today.
+ * When the profile requested nothing, returns the cadence this machine can
+ * AFFORD (`reason: 'derived_default'`) rather than null — see the branch for
+ * the measurement. A bare null from `deployedCadenceSource` still means "nobody
+ * answered", and that still leaves a running connector alone.
  */
 export declare function resolveDeployedCadence(input: {
     requestedMs: unknown;

package/dist/deployedCadence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deployedCadence.d.ts","sourceRoot":"","sources":["../src/deployedCadence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAQH;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,cAAc,QAAmB,CAAC;AAE/C,MAAM,MAAM,aAAa;AACvB,4EAA4E;AAC1E,YAAY;AACd,uEAAuE;GACrE,kBAAkB;AACpB,qDAAqD;GACnD,wBAAwB;AAC1B,yFAAyF;GACvF,eAAe;AACjB,2FAA2F;GACzF,iBAAiB,CAAC;AAEtB,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,mFAAmF;IACnF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;CACvB;AASD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,eAAe,CA8ClB"}
+{"version":3,"file":"deployedCadence.d.ts","sourceRoot":"","sources":["../src/deployedCadence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAQH;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,cAAc,QAAmB,CAAC;AAE/C,MAAM,MAAM,aAAa;AACvB,4EAA4E;AAC1E,YAAY;AACd;;;GAGG;GACD,iBAAiB;AACnB,uEAAuE;GACrE,kBAAkB;AACpB,qDAAqD;GACnD,wBAAwB;AAC1B;;;;;;;GAOG;GACD,eAAe;AACjB,2FAA2F;GACzF,iBAAiB,CAAC;AAEtB,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,mFAAmF;IACnF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;CACvB;AASD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,eAAe,CAkFlB"}