@trillboards/edge-sdk 0.2.61 → 0.2.63

package/dist/analyzeCostObserver.d.ts

@@ -0,0 +1,96 @@
+/**
+ * analyzeCostObserver — what a frame costs ON THIS BOX, measured by this box.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────
+ *
+ * `MEASURED_LOCAL_ANALYZE_MS` is ONE constant, and the fleet it sizes does not
+ * vary by a little. As of 2026-08-19 the measured spread on the SHIPPED path is
+ * an Apple M4 Max at 0.45 s/frame against a GPU-less 2-vCPU x86 box at tens of
+ * seconds — and `periodicIntervalMsForFeedCount` turns that constant directly
+ * into the still-scene heartbeat, which IS the resolution of the hazard
+ * persistence timeline the SOP product's legal argument turns on. So a single
+ * global number is wrong in both directions at once: it asks the slow box for a
+ * cadence it cannot serve, and it denies the fast box resolution it has already
+ * paid for.
+ *
+ * The fix is not a better constant. There is no constant that is right for a
+ * fleet with that spread, and picking the fast desk is the exact error
+ * `.claude/lessons/2026-08-18-a-benchmark-with-no-machine-axis-is-a-spec-for-one-desk.md`
+ * was written about. The fix is that the box measures ITSELF — it is already
+ * running the very inference the number describes, once per frame, forever.
+ *
+ * ── Why the constant stays, and stays at 7.30 s ─────────────────────────────
+ *
+ * `MEASURED_LOCAL_ANALYZE_MS` becomes the BOOTSTRAP: what to assume before this
+ * machine has measured itself. It should therefore be conservative rather than
+ * accurate, and 7.30 s is exactly that — the docblock on it already says it is
+ * not a measurement of any machine. A connector that guessed FAST on a slow box
+ * would oversubscribe the single admission slot from its first minute; guessing
+ * slow costs only heartbeat resolution, and only until this observer settles.
+ *
+ * ── Three decisions worth not re-deriving ───────────────────────────────────
+ *
+ * 1. MEDIAN, never mean. One degenerate generation runs to the token cap
+ *    (measured 15-23 s against a sub-second median). A mean would let a single
+ *    bad frame re-tune the cadence for every camera on the host; a median over
+ *    a 16-frame window cannot be moved by fewer than 8 of them.
+ *
+ * 2. Only a SUCCESSFUL analysis is recorded. A throw is not a frame cost — the
+ *    same reasoning that makes `localInferencesCompleted` count past every
+ *    throw, and the same reasoning `keptForTiming` applies in the bench. A
+ *    request that failed fast would otherwise look like a very quick frame.
+ *
+ * 3. `medianMs()` is NULL until MIN_SAMPLES, and that is not a nicety. The first
+ *    frames on a cold box carry the model load and the slower settle behind it —
+ *    the bench spends WARMUP_CALLS_BEFORE_TIMING (16) untimed calls excluding
+ *    exactly that, having measured a 36% monotonic drift over the frames after a
+ *    single warm-up. A connector cannot refuse to sense while it warms up, so it
+ *    does the other half instead: it keeps the conservative bootstrap until it
+ *    has enough samples, and because the window ROLLS, the cold frames age out
+ *    on their own. Convergence is therefore downward, which is the safe
+ *    direction — a box never claims to be faster than it has proved.
+ */
+/**
+ * Frames behind the rolling median. Matched to the bench's
+ * `WARMUP_CALLS_BEFORE_TIMING` on purpose: that is the measured order of
+ * magnitude on which this runtime settles, so a window shorter than it would
+ * still be reporting the settle.
+ */
+export declare const ANALYZE_COST_WINDOW = 16;
+/**
+ * Samples before this observer will answer at all. Half the window: enough that
+ * the median is a median, few enough that a connector converges off its
+ * bootstrap within minutes rather than hours at a 30 s analyze floor.
+ */
+export declare const ANALYZE_COST_MIN_SAMPLES = 8;
+/**
+ * A bounded ring of recent per-frame costs. Bounded because a connector runs for
+ * months: an unbounded array here is a slow leak on a box we are also telling
+ * customers needs only 8 GB.
+ */
+export declare class AnalyzeCostObserver {
+    private readonly window;
+    private readonly minSamples;
+    private readonly ring;
+    private next;
+    private seen;
+    constructor(options?: {
+        window?: number;
+        minSamples?: number;
+    });
+    /** Record ONE completed analysis. Anything that is not a duration is dropped. */
+    record(ms: unknown): void;
+    /** Completed analyses ever recorded — not the ring size. */
+    get sampleCount(): number;
+    /** Has this box measured itself enough to overrule the bootstrap constant? */
+    settled(): boolean;
+    /**
+     * The median of the rolling window, or `null` while the bootstrap still
+     * governs. `null` is deliberately not `MEASURED_LOCAL_ANALYZE_MS`: the caller
+     * must be able to tell "this box has not measured itself yet" from "this box
+     * measured itself and got the default", because only the first should be
+     * re-derived later.
+     */
+    medianMs(): number | null;
+}
+//# sourceMappingURL=analyzeCostObserver.d.ts.map

package/dist/analyzeCostObserver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzeCostObserver.d.ts","sourceRoot":"","sources":["../src/analyzeCostObserver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAU1C;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IAErC,OAAO,CAAC,IAAI,CAAK;IAEjB,OAAO,CAAC,IAAI,CAAK;gBAEL,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO;IASlE,iFAAiF;IACjF,MAAM,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI;IAQzB,4DAA4D;IAC5D,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,8EAA8E;IAC9E,OAAO,IAAI,OAAO;IAIlB;;;;;;OAMG;IACH,QAAQ,IAAI,MAAM,GAAG,IAAI;CAQ1B"}

package/dist/analyzeCostObserver.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * analyzeCostObserver — what a frame costs ON THIS BOX, measured by this box.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────
+ *
+ * `MEASURED_LOCAL_ANALYZE_MS` is ONE constant, and the fleet it sizes does not
+ * vary by a little. As of 2026-08-19 the measured spread on the SHIPPED path is
+ * an Apple M4 Max at 0.45 s/frame against a GPU-less 2-vCPU x86 box at tens of
+ * seconds — and `periodicIntervalMsForFeedCount` turns that constant directly
+ * into the still-scene heartbeat, which IS the resolution of the hazard
+ * persistence timeline the SOP product's legal argument turns on. So a single
+ * global number is wrong in both directions at once: it asks the slow box for a
+ * cadence it cannot serve, and it denies the fast box resolution it has already
+ * paid for.
+ *
+ * The fix is not a better constant. There is no constant that is right for a
+ * fleet with that spread, and picking the fast desk is the exact error
+ * `.claude/lessons/2026-08-18-a-benchmark-with-no-machine-axis-is-a-spec-for-one-desk.md`
+ * was written about. The fix is that the box measures ITSELF — it is already
+ * running the very inference the number describes, once per frame, forever.
+ *
+ * ── Why the constant stays, and stays at 7.30 s ─────────────────────────────
+ *
+ * `MEASURED_LOCAL_ANALYZE_MS` becomes the BOOTSTRAP: what to assume before this
+ * machine has measured itself. It should therefore be conservative rather than
+ * accurate, and 7.30 s is exactly that — the docblock on it already says it is
+ * not a measurement of any machine. A connector that guessed FAST on a slow box
+ * would oversubscribe the single admission slot from its first minute; guessing
+ * slow costs only heartbeat resolution, and only until this observer settles.
+ *
+ * ── Three decisions worth not re-deriving ───────────────────────────────────
+ *
+ * 1. MEDIAN, never mean. One degenerate generation runs to the token cap
+ *    (measured 15-23 s against a sub-second median). A mean would let a single
+ *    bad frame re-tune the cadence for every camera on the host; a median over
+ *    a 16-frame window cannot be moved by fewer than 8 of them.
+ *
+ * 2. Only a SUCCESSFUL analysis is recorded. A throw is not a frame cost — the
+ *    same reasoning that makes `localInferencesCompleted` count past every
+ *    throw, and the same reasoning `keptForTiming` applies in the bench. A
+ *    request that failed fast would otherwise look like a very quick frame.
+ *
+ * 3. `medianMs()` is NULL until MIN_SAMPLES, and that is not a nicety. The first
+ *    frames on a cold box carry the model load and the slower settle behind it —
+ *    the bench spends WARMUP_CALLS_BEFORE_TIMING (16) untimed calls excluding
+ *    exactly that, having measured a 36% monotonic drift over the frames after a
+ *    single warm-up. A connector cannot refuse to sense while it warms up, so it
+ *    does the other half instead: it keeps the conservative bootstrap until it
+ *    has enough samples, and because the window ROLLS, the cold frames age out
+ *    on their own. Convergence is therefore downward, which is the safe
+ *    direction — a box never claims to be faster than it has proved.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalyzeCostObserver = exports.ANALYZE_COST_MIN_SAMPLES = exports.ANALYZE_COST_WINDOW = void 0;
+/**
+ * Frames behind the rolling median. Matched to the bench's
+ * `WARMUP_CALLS_BEFORE_TIMING` on purpose: that is the measured order of
+ * magnitude on which this runtime settles, so a window shorter than it would
+ * still be reporting the settle.
+ */
+exports.ANALYZE_COST_WINDOW = 16;
+/**
+ * Samples before this observer will answer at all. Half the window: enough that
+ * the median is a median, few enough that a connector converges off its
+ * bootstrap within minutes rather than hours at a 30 s analyze floor.
+ */
+exports.ANALYZE_COST_MIN_SAMPLES = 8;
+/**
+ * Ignore a duration that cannot be a frame. Zero and negatives are clock
+ * artifacts, not fast frames, and a NaN would poison the median silently.
+ */
+function isUsable(ms) {
+    return typeof ms === 'number' && Number.isFinite(ms) && ms > 0;
+}
+/**
+ * A bounded ring of recent per-frame costs. Bounded because a connector runs for
+ * months: an unbounded array here is a slow leak on a box we are also telling
+ * customers needs only 8 GB.
+ */
+class AnalyzeCostObserver {
+    constructor(options = {}) {
+        this.ring = [];
+        this.next = 0;
+        this.seen = 0;
+        const w = isUsable(options.window) ? Math.floor(options.window) : exports.ANALYZE_COST_WINDOW;
+        this.window = Math.max(1, w);
+        const m = isUsable(options.minSamples) ? Math.floor(options.minSamples) : exports.ANALYZE_COST_MIN_SAMPLES;
+        // Never require more samples than the ring can hold, or the observer could
+        // never settle and the bootstrap would silently be permanent.
+        this.minSamples = Math.max(1, Math.min(this.window, m));
+    }
+    /** Record ONE completed analysis. Anything that is not a duration is dropped. */
+    record(ms) {
+        if (!isUsable(ms))
+            return;
+        if (this.ring.length < this.window)
+            this.ring.push(ms);
+        else
+            this.ring[this.next] = ms;
+        this.next = (this.next + 1) % this.window;
+        this.seen += 1;
+    }
+    /** Completed analyses ever recorded — not the ring size. */
+    get sampleCount() {
+        return this.seen;
+    }
+    /** Has this box measured itself enough to overrule the bootstrap constant? */
+    settled() {
+        return this.ring.length >= this.minSamples;
+    }
+    /**
+     * The median of the rolling window, or `null` while the bootstrap still
+     * governs. `null` is deliberately not `MEASURED_LOCAL_ANALYZE_MS`: the caller
+     * must be able to tell "this box has not measured itself yet" from "this box
+     * measured itself and got the default", because only the first should be
+     * re-derived later.
+     */
+    medianMs() {
+        if (!this.settled())
+            return null;
+        const sorted = [...this.ring].sort((a, b) => a - b);
+        const mid = sorted.length >> 1;
+        return sorted.length % 2 === 1
+            ? sorted[mid]
+            : (sorted[mid - 1] + sorted[mid]) / 2;
+    }
+}
+exports.AnalyzeCostObserver = AnalyzeCostObserver;
+//# sourceMappingURL=analyzeCostObserver.js.map

package/dist/analyzeCostObserver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzeCostObserver.js","sourceRoot":"","sources":["../src/analyzeCostObserver.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;;;AAEH;;;;;GAKG;AACU,QAAA,mBAAmB,GAAG,EAAE,CAAC;AAEtC;;;;GAIG;AACU,QAAA,wBAAwB,GAAG,CAAC,CAAC;AAE1C;;;GAGG;AACH,SAAS,QAAQ,CAAC,EAAW;IAC3B,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,MAAa,mBAAmB;IAW9B,YAAY,UAAoD,EAAE;QANjD,SAAI,GAAa,EAAE,CAAC;QAE7B,SAAI,GAAG,CAAC,CAAC;QAET,SAAI,GAAG,CAAC,CAAC;QAGf,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,2BAAmB,CAAC;QACtF,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC7B,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,gCAAwB,CAAC;QACnG,2EAA2E;QAC3E,8DAA8D;QAC9D,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,iFAAiF;IACjF,MAAM,CAAC,EAAW;QAChB,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAAE,OAAO;QAC1B,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;;YAClD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1C,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;IACjB,CAAC;IAED,4DAA4D;IAC5D,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,8EAA8E;IAC9E,OAAO;QACL,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC;IAC7C,CAAC;IAED;;;;;;OAMG;IACH,QAAQ;QACN,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE;YAAE,OAAO,IAAI,CAAC;QACjC,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACpD,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;QAC/B,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC;YAC5B,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;YACb,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IAC1C,CAAC;CACF;AAtDD,kDAsDC"}

package/dist/connectorCadence.d.ts

@@ -44,11 +44,13 @@
  *             of 493 analyses/hour for the WHOLE connector, however many
  *             cameras it runs.
  *             STALE — see the block under MEASURED_LOCAL_ANALYZE_MS. The same
- *             harness measures 1.90 s (and 1.22 s with the 2026-08-19
- *             config.json change) on the pinned 0.16.0, so the real ceiling on
- *             this machine class is ~1,895/hour and ~2,951/hour respectively.
- *             The constant is kept as a conservative FLEET default because the
- *             fleet varies ~7x; do not quote 493 as this machine's ceiling.
+ *             harness measures 1.90 s, then 1.22 s with the 2026-08-19
+ *             config.json change, then a further paired 2.42x with the 2026-08-19
+ *             fast-conversation shim, on the pinned 0.16.0 — so the real ceiling
+ *             on this machine class is ~1,895/hour, ~2,951/hour and higher again
+ *             respectively. The constant is kept as a conservative FLEET default
+ *             because the fleet varies ~7x; do not quote 493 as this machine's
+ *             ceiling.
  *             (The DOOH audience schema measured 12.48 s median and ranged to
  *             23.8 s because it emits a free-text narrative. The SOP field set
  *             is both cheaper and far tighter — 6.0-7.5 s — which is a second,
@@ -141,25 +143,81 @@ export declare const MEASURED_LOCAL_ANALYZE_MS = 7300;
  * the box can afford, which costs hazard-persistence resolution against the
  * 111 s constructive-notice bracket — the one thing this file exists to protect.
  *
- * ── Why it is NOT simply lowered here ──────────────────────────────────────
- *
- * Because this is ONE constant for a fleet that varies ~7x, and every number
- * above is one desk. `cctv-local-inference-hardware-floor.md` §7 measures
- * 34.78 s/frame on the `windows-latest` class. Replacing 7.30 s with 1.22 s (the
- * M4 Max WITH the 2026-08-19 config.json change) would demand ~28x what that box
- * can deliver, and replacing it with the slow box's number makes every heartbeat
- * worse than today. A single global constant cannot be right for both, and
- * picking the fast desk is exactly the error `.claude/lessons/2026-08-18-a-
- * benchmark-with-no-machine-axis-is-a-spec-for-one-desk.md` was written about.
- *
- * The fix is to DERIVE this per machine — the connector already measures its own
- * frame cost, and `deployedCadence` already exists to reconcile a deployed
- * cadence with what a machine can afford. Until that lands, treat 7.30 s as a
- * deliberately conservative fleet default and NOT as a measurement of any
- * machine: quoting it as one is what this block exists to stop. Changing the
- * value also moves `sensingCatchRate.DEFAULT_SAMPLER.analyzeS`, so it requires
- * re-running `replay-catch-rate.mjs` and regenerating
- * `.github/contracts/sensing-catch-rate-baseline.json` in the same change.
+ * ── AND IT MOVED AGAIN, 2026-08-19 (the shim) ──────────────────────────────
+ *
+ * `litert-lm serve` built `ConstrainedDecodingConfig(enable=True, …)` for every
+ * request even when nothing asked for a `response_format`, so every frame paid
+ * a constraint build for a grammar nothing used. Removing it (see
+ * `deploy/litertlm/trillboards_litertlm_shim.py`) is worth a further **paired
+ * 2.42x** on the shipped path — two stock serves on two ports, interleaved,
+ * n=16, 16/16 schema-valid and 16/16 BYTE-IDENTICAL generations on both arms.
+ * `bench-local-vlm.mjs --arms gpu-sop`, back to back in the same window, moves
+ * **1.32 -> 0.72 s/frame, i.e. 2,727 -> 5,000 analyses/hour**, at load 22-25
+ * where the same harness measures the stock arm at 1.32 s against the 1.22 s
+ * this file already records for it — so that window is close to the regime the
+ * 1.22 s was taken in, and 0.72 s is the nearest thing to a quotable per-frame
+ * number this machine class has.
+ *
+ * TWO CAVEATS THAT TRAVEL WITH IT. The ratio is itself load-dependent — 3.734x
+ * at 0.0% CPU idle against 2.42x at load 25 — because the removed work is
+ * CPU-bound and the retained work is GPU-bound, so a figure taken under
+ * contention flatters the change. And 0.72 s/frame is still BELOW the capacity
+ * target: 4 cameras resolving a 2 s bracket needs 0.5 s/frame (7,200
+ * analyses/hour), and this serves 2-3.
+ *
+ * ── IT IS NOT LOWERED HERE. IT IS NOW A BOOTSTRAP. (2026-08-19) ───────────
+ *
+ * This is ONE constant for a fleet whose measured spread on the SHIPPED path is
+ * 0.50 s/frame (M4 Max, post-#12567/#12594) against tens of seconds on a
+ * GPU-less x86 box. No constant is right for both: the fast desk's number would
+ * demand ~70x what the slow box can deliver, and the slow box's number makes
+ * every heartbeat worse than today. Picking the fast desk is exactly the error
+ * `.claude/lessons/2026-08-18-a-benchmark-with-no-machine-axis-is-a-spec-for-
+ * one-desk.md` was written about.
+ *
+ * So the fix was never a better constant, and as of 2026-08-19 it is built: the
+ * box DERIVES this for itself. `AnalyzeCostObserver` (analyzeCostObserver.ts)
+ * times every successful `analyze()` in `LocalSensingClient`, reports a rolling
+ * median over 16 frames, and `periodicIntervalMsForFeedCount` /
+ * `resolveDeployedCadence` take it as an optional input. A connector that has
+ * measured itself uses its OWN number; one that has not uses this one.
+ *
+ * NOTE WHAT THAT MAKES THIS CONSTANT. It is the value to assume BEFORE a machine
+ * has measured itself, so it should be conservative rather than accurate — and
+ * 7.30 s is exactly that. Guessing FAST on a slow box oversubscribes the single
+ * admission slot from the first minute; guessing slow costs only heartbeat
+ * resolution, and only until the observer settles (8 frames). It is therefore
+ * deliberately NOT lowered, and quoting it as a measurement of any machine is
+ * still what this block exists to stop.
+ *
+ * A CONSEQUENCE WORTH KNOWING: because this value does not move, neither does
+ * `sensingCatchRate.DEFAULT_SAMPLER.analyzeS`, so none of this required a
+ * corpus replay or a `.github/contracts/sensing-catch-rate-baseline.json`
+ * regeneration. If you ever DO move it, all of that becomes mandatory in the
+ * same change — and the catch-rate ratchet is shrink-only, so a baseline may
+ * never be regenerated merely to clear red.
+ *
+ * ── The idle-box objection, and why it does not block the derivation ────────
+ *
+ * The 2026-08-19 predecessor of this block held the per-machine derivation back
+ * for want of a per-frame number taken on an idle box, on the grounds that a
+ * figure measured at 0.0% CPU idle would hardcode one session's contention into
+ * every connector. That objection is answered twice over.
+ *
+ * First, it no longer applies to the DERIVATION at all: nothing global is
+ * derived from a measured number any more. Each box measures itself, in situ,
+ * under whatever load it actually runs at — which is the right load by
+ * definition, and is the one thing a bench on someone else's desk can never
+ * reproduce.
+ *
+ * Second, the verdict turned out not to depend on it. Three measurements of the
+ * shipped arm on one M4 Max across a 3x load range: 0.45 s at load 7.77, 0.50 s
+ * at load 11.87, 0.72 s at load 22-25. All three clear the 13.88 s/frame budget
+ * for 4 cameras by 19-31x, so "this class clears 4 cameras" is invariant across
+ * everything that could be measured. Load moves the quotable figure, not the
+ * verdict — and the post-merge path is markedly LESS load-sensitive than the one
+ * that motivated the objection, because the work #12594 removed was CPU-bound
+ * and what remains is GPU-bound.
  */
 /**
  * Share of the single admission slot the STILL-scene heartbeat floor may take.
@@ -213,8 +271,13 @@ export declare const STILL_FLOOR_SLOT_SHARE = 0.5;
  */
 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.
+ * Measured wall-clock cost of ONE LOOK on the PER-GRAB capture path, in ms — a
+ * real RTSP grab, not the decode-and-detect that follows it.
+ *
+ * STILL LIVE, and still exactly right for the path it describes: the per-grab
+ * provider is what a feed runs when it cannot hold a persistent session (see
+ * `MEASURED_STREAM_LOOK_MS`), so this is the number `lookIntervalMsForFeedCount`
+ * uses in `'per_grab'` mode and nothing about it has changed.
  *
  * 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
@@ -247,6 +310,75 @@ export declare const MIN_ANALYZE_INTERVAL_MS = 30000;
  * the connector is not running.
  */
 export declare const MEASURED_LOOK_MS = 2000;
+/**
+ * Measured wall-clock cost of ONE LOOK on the PERSISTENT capture path, in ms.
+ *
+ * `RTSPStreamCameraProvider` holds one long-lived ffmpeg per feed decoding into
+ * a bounded ring, so `getFrame()` is a memory read of the newest frame rather
+ * than a process start plus a DESCRIBE/SETUP/PLAY plus a wait for an IDR. The
+ * handshake is paid ONCE, at open.
+ *
+ * MEASURED 2026-08-18 against the same rig, same clip, same degraded profile
+ * (640x360 / 399 kbps / GOP 2 s), driving looks at the shipped cadence so a
+ * fresh frame is already in hand — which is the condition the connector runs
+ * in and the only one where "cost of a look" means anything:
+ *
+ *     per-grab      p50 2,000 ms
+ *     persistent    p50 0 ms   (sub-millisecond; the ring read is a pointer)
+ *
+ * Reproduce: `node scripts/measure-persistent-capture.mjs --feeds 1
+ * --seconds 60 --pace-ms 500`. The rig is committed — see that file's header
+ * for why, and for why a `file://` fixture cannot stand in for it.
+ *
+ * It is 1 rather than 0 so that `lookIntervalMsForFeedCount` can never divide
+ * by it, and so nobody reads a zero as "free" — a look still costs the
+ * detector's `MEASURED_LOOK_DETECT_MS`, which is what actually bounds the
+ * persistent path.
+ */
+export declare const MEASURED_STREAM_LOOK_MS = 1;
+/**
+ * Cost of a look AFTER the frame is in hand, in ms: pull it down to ~178x100
+ * grey and run `SceneChangeDetector`. Measured 3.6 ms median / 7.1 ms p95.
+ *
+ * This is the number the cascade budget has always quoted, and until the
+ * capture path changed it was irrelevant — a 3.6 ms stage behind a 2,000 ms
+ * one bounds nothing. On the persistent path it is the ONLY per-look cost
+ * left, so it becomes the binding term and gets named here rather than living
+ * in a comment.
+ */
+export declare const MEASURED_LOOK_DETECT_MS = 3.6;
+/**
+ * Share of ONE core the motion detector may take across every feed.
+ *
+ * The one judgement in the persistent derivation, stated rather than hidden —
+ * the same shape as `STILL_FLOOR_SLOT_SHARE`. Detection is the cheapest stage
+ * on the box and it must not become the noisy neighbour: the connector also
+ * runs one ffmpeg decode per feed (measured on the rig at ~2.4% of a core per
+ * feed at this profile) and one local VLM slot, and the VLM is the thing the
+ * product is actually spending money on.
+ *
+ * A quarter of a core does not bind at any realistic feed count — see
+ * `lookIntervalMsForFeedCount` — which is the point: it is a guard rail, not a
+ * throttle, and it exists so that a future 64-feed host derives a cadence it
+ * can serve instead of one it merely asked for.
+ */
+export declare const LOOK_DETECT_CPU_SHARE = 0.25;
+/**
+ * The persistent session's frame interval, in ms — the freshest a look can
+ * possibly be, because a look reads the newest DECODED frame.
+ *
+ * `RTSPStreamCameraProvider` defaults `streamFps` to 4, i.e. 250 ms. Restated
+ * here rather than imported because `edge-sdk` must not depend on a platform
+ * package, and asserted against the real default by `connectorCadence.test.ts`
+ * so the two cannot drift — the same treatment `LOOK_CAPTURE_CONCURRENCY` gets.
+ *
+ * `LOOK_INTERVAL_MS` must never be finer than this: asking for a 100 ms look
+ * cadence against a 250 ms stream would hand the same frame to the motion
+ * detector twice, which the provider refuses (it throws rather than repeat a
+ * frame) and which would report as a stale-stream fault on a perfectly healthy
+ * camera.
+ */
+export declare const MEASURED_STREAM_FRAME_INTERVAL_MS = 250;
 /**
  * Concurrent RTSP grabs one physical recorder will take —
  * `DEFAULT_MAX_CONCURRENT_CAPTURES_PER_SOURCE` in `RTSPCameraProvider`, which
@@ -296,32 +428,59 @@ export declare const LEGACY_LOOK_INTERVAL_MS = 30000;
  *     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.
+ *      0.5 s    100.0%   93.2%       100%     100%
+ *
+ * ── 2 000 -> 500 ms ON 2026-08-18, AND THE REASON IS THE CAPTURE PATH ──────
+ *
+ * This constant was 2 000 ms, and the comment here said why in as many words:
+ * "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. So 90% on every shape is NOT reachable by
+ * look cadence on the current capture architecture… 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."
+ *
+ * That is now built (`RTSPStreamCameraProvider`), the constraint it named is
+ * gone, and this is the number that moves as a result. A look is a memory read
+ * of the newest decoded frame — `MEASURED_STREAM_LOOK_MS`, sub-millisecond —
+ * so the recorder no longer bounds the look cadence at all. Brief clears the
+ * 90% target at 0.75 s; 500 ms is the next value that is BOTH under it and a
+ * whole multiple of the persistent session's 250 ms frame interval
+ * (`MEASURED_STREAM_FRAME_INTERVAL_MS`), so a look always finds an unseen frame
+ * in hand and never blocks.
+ *
+ * ── WHY STOP AT 500 ms ────────────────────────────────────────────────────
+ *
+ * The same stopping rule that picked 2 000 ms: go until the last unmet target
+ * is met, and no further. At 500 ms every reporting group clears 90% — the
+ * first cadence in the product's history where that is true. Below it the
+ * corpus has nothing left to buy (Instant and Brief are saturated, Sustained
+ * and State were never look-limited) while the cost is real and linear: each
+ * halving doubles both the detector's CPU (`MEASURED_LOOK_DETECT_MS` per look
+ * per feed) and the session's JPEG-encode rate.
+ *
+ * ── AND IT MUST NOT COST ANALYSES ─────────────────────────────────────────
+ *
+ * Looking 4x more often must not analyse 4x more often, or the change has
+ * failed: one 7.30 s slot is 493 analyses/hour for the whole connector and
+ * there is no cloud path left to absorb an overflow. Three things hold that,
+ * and all three are asserted rather than assumed:
+ *   - `MIN_ANALYZE_INTERVAL_MS` (30 s) is a SEPARATE constant and is what
+ *     `MotionGate.minAnalyzeIntervalMs` floors on.
+ *   - `periodicIntervalMsForFeedCount` floors on the ANALYZE floor, never on
+ *     the look cadence, so the still-scene heartbeat does not move.
+ *   - a still scene contributes exactly ZERO motion-triggered analyses, which
+ *     is what makes the extra looks free at the model.
+ * The `sensing-catch-rate` guard's volume ratchet is the mechanical version:
+ * `volume.idleAnalyses` may only go DOWN.
+ *
+ * Do not raise or lower this without re-running the replay — the guard re-reads
+ * this constant and fails if it drifts from the cadence the corpus baseline was
+ * measured at.
  */
-export declare const LOOK_INTERVAL_MS = 2000;
+export declare const LOOK_INTERVAL_MS = 500;
 /** The DOOH audience default (`DEFAULT_PERIODIC_MS`). The slow end of the clamp. */
 export declare const DOOH_PERIODIC_MS = 300000;
 /**
@@ -334,29 +493,99 @@ export declare const DOOH_PERIODIC_MS = 300000;
  * Returns `null` when the count is not a positive integer, so a caller can omit
  * the key entirely rather than write a cadence derived from a bad count.
  */
-export declare function periodicIntervalMsForFeedCount(feedCount: unknown): number | null;
+export declare function periodicIntervalMsForFeedCount(feedCount: unknown, 
 /**
- * The fastest look cadence a connector running `feedCount` feeds against ONE
- * recorder can actually SUSTAIN, in ms.
+ * What a frame ACTUALLY costs on this box, in ms, when this box has measured
+ * itself (`AnalyzeCostObserver.medianMs()`). Omitted or `null` falls back to
+ * `MEASURED_LOCAL_ANALYZE_MS`, which is the BOOTSTRAP — deliberately
+ * conservative, and not a measurement of any machine.
+ *
+ * This parameter is the whole reason a fleet spanning 0.45 s/frame to tens of
+ * seconds can share one code path: the equation was always per-machine, and
+ * until 2026-08-19 only its input was global.
+ */
+analyzeMs?: number | null): number | null;
+/**
+ * How a feed's frames are acquired. The look cadence a connector can SUSTAIN
+ * depends on this and on nothing else about the box.
+ *
+ *   'persistent'  one long-lived ffmpeg per feed into a bounded ring
+ *                 (`RTSPStreamCameraProvider`). A look is a memory read.
+ *   'per_grab'    one ffmpeg per grab (`RTSPCameraProvider`). A look is an RTSP
+ *                 handshake, and the RECORDER is the bound.
+ */
+export type CaptureMode = 'persistent' | 'per_grab';
+/**
+ * The fastest look cadence a connector running `feedCount` feeds 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.
+ * inference slot among N feeds; this one divides whatever the capture path's
+ * scarce resource is — and the whole point of the persistent session is that it
+ * CHANGES WHICH RESOURCE THAT IS.
+ *
+ * ── 'per_grab' — the RECORDER is the bound (unchanged) ────────────────────
  *
  *     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.
+ * 16.0 s/feed, observed 16.0 s/feed. This is still exactly right for a feed that
+ * could not hold a persistent session and degraded — see
+ * `RTSPStreamCameraProvider`'s degrade path — so the branch stays live rather
+ * than being deleted as legacy.
+ *
+ * ── 'persistent' — the recorder drops out and the DETECTOR is the bound ───
+ *
+ * A look no longer touches the recorder, so `LOOK_CAPTURE_CONCURRENCY` and
+ * `MEASURED_LOOK_MS` have nothing to say about it. What is left is the cost
+ * AFTER the frame is in hand:
+ *
+ *     N feeds x (1 look / T) x MEASURED_LOOK_DETECT_MS  <=  LOOK_DETECT_CPU_SHARE
+ *                                                  T  >=  N x 3.6 / 0.25 ms
+ *
+ * That is 230 ms at 16 feeds and 461 ms at 32 — both BELOW `LOOK_INTERVAL_MS`,
+ * so the clamp wins and a realistic connector simply gets the eval target. It
+ * begins to bind past ~34 feeds, which is the honest place for it to bind: a
+ * host with 34 cameras has other problems (its still-scene heartbeat pinned at
+ * `DOOH_PERIODIC_MS` since 21 feeds) and `getSensingHealth()` reports the
+ * effective interval either way.
  *
  * 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.
+ * 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, captureMode?: CaptureMode): number | null;
+/**
+ * Decoded frames a persistent session must produce per LOOK.
+ *
+ * TWO, and the second one is not waste. `RTSPStreamCameraProvider.getFrame()`
+ * refuses to hand back a frame it has already served — that refusal is the
+ * whole reason a frozen camera cannot report as healthy — so a look that
+ * arrives before the next frame does BLOCKS, and if it blocks past the
+ * staleness deadline it throws on a camera that is working perfectly.
+ *
+ * Running the stream at exactly the look rate makes that a coin flip on every
+ * tick, because neither clock is locked to the other: the session's frame
+ * cadence follows the CAMERA's timestamps and the look cadence follows a Node
+ * timer, and they drift. One frame of headroom removes the race for the cost of
+ * one extra scale+encode per look — the cheapest stage in the pipeline, and one
+ * that never touches the recorder or the model.
+ */
+export declare const STREAM_LOOK_HEADROOM = 2;
+/**
+ * Frames per second a persistent session should decode to serve a given look
+ * cadence. Derived, so the two can never be set independently and drift into
+ * the blocking case above.
+ *
+ * At the shipped 500 ms look cadence this is 4 fps — which is also the
+ * provider's own default (`MEASURED_STREAM_FRAME_INTERVAL_MS`), and
+ * `connectorCadence.test.ts` asserts the agreement rather than trusting it.
  */
-export declare function lookIntervalMsForFeedCount(feedCount: unknown): number | null;
+export declare function streamFpsForLookIntervalMs(lookIntervalMs: unknown): number;
 /**
  * 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