@trillboards/edge-sdk 0.2.14 → 0.2.16

package/dist/CloudSensingManager.js

@@ -12,6 +12,7 @@ const runtimePaths_1 = require("./runtimePaths");
 const legacyRecorderProfile_1 = require("./legacyRecorderProfile");
 const VlmAdmissionGate_1 = require("./VlmAdmissionGate");
 const SceneChangeDetector_1 = require("./SceneChangeDetector");
+const VlmCandidateBuffer_1 = require("./VlmCandidateBuffer");
 /**
  * Thin cloud-sensing run mode.
  *
@@ -32,11 +33,11 @@ const SceneChangeDetector_1 = require("./SceneChangeDetector");
  * (`litert-lm serve`) takes one conversation at a time. So a tick is not "grab
  * a frame and send it"; it is a two-stage cascade, cheapest stage first:
  *
- *   1. ADMISSION (`VlmAdmissionGate`, global, one slot). Checked before the
- *      inference capture. Denied ticks DROP inference work and re-arm at a
- *      short retry delay. A separate, serialized decode-only probe runs at a
- *      much slower cadence so model saturation never makes healthy video look
- *      disconnected; that probe is not encoded, queued, or analyzed.
+ *   1. ADMISSION (`VlmAdmissionGate`, global, one slot). Denied ticks DROP
+ *      inference work and re-arm at a short retry delay. A separate, serialized
+ *      decode-only probe runs at a much slower cadence so model saturation never
+ *      makes healthy video look disconnected; that probe is not encoded,
+ *      queued, or analyzed.
  *   2. DECIMATION (`motionGate.scanIntervalMs`, floored at
  *      `DEFAULT_MIN_MOTION_SCAN_INTERVAL_MS`). Frigate's stage 1: never LOOK
  *      faster than 5 fps, because motion does not get more truthful above that
@@ -49,6 +50,36 @@ const SceneChangeDetector_1 = require("./SceneChangeDetector");
  *      the same cells as the last analyzed frame is a parked car or a swinging
  *      sign, and costs 1/N of a moving one.
  *
+ * ── Where admission sits, and the candidate buffer ──────────────────────────
+ * With the cascade OFF, admission is checked FIRST: nothing has classified the
+ * frame, so there is no reason to pay for a grab the model cannot take, and a
+ * denied tick drops without touching the camera. That is the original order and
+ * it is unchanged.
+ *
+ * With the cascade ON, the order inverts — LOOK first, admit second — and a
+ * candidate the gate cannot take right now is HELD in `VlmCandidateBuffer`
+ * rather than dropped. Both halves of that are load-bearing:
+ *
+ *   - Admission-first meant a saturated connector never looked. The motion
+ *     stage only runs on a frame we grabbed, so while the model was busy no
+ *     feed could even form an opinion, and "the cascade already decided this
+ *     frame is interesting" was unreachable exactly when it mattered. Measured
+ *     in the field on 32 cameras (connector 0.2.13): ~2.4 analyses/min, so a
+ *     given camera waits ~13 minutes for its turn — longer than any spill,
+ *     fall or restricted-area entry lasts.
+ *   - Holding is bounded and only for CANDIDATES. A no-change frame is never
+ *     held; that would rebuild the undifferentiated backlog the gate refuses.
+ *     See VlmCandidateBuffer for the three bounds, the freshness TTL, and why
+ *     "a stale frame is worthless" is true of ambient sampling and false of
+ *     alerting.
+ *
+ * Looking while the model is busy is affordable because looking is the cheap
+ * half by construction (stage 1 floors it at 5 fps per feed, and a real
+ * deployment runs ~150x slower than that), and because the denied path ALREADY
+ * pulled a decode-only health frame and threw the information away. The
+ * inversion also narrows what an admission slot means: it is now held for the
+ * inference alone, not for the grab and encode in front of it.
+ *
  * Every stage is independently disableable, and every drop is attributed to the
  * stage that made it in `getSensingHealth().cascade.byReason` — because the
  * honest form of degradation on a machine that cannot keep up is a number an
@@ -190,6 +221,7 @@ class CloudSensingManager extends events_1.EventEmitter {
         /** The last cadence verdict applied, surfaced by getSensingHealth(). */
         this.cadence = null;
         this.cadenceTimer = null;
+        this.candidatePumpTimer = null;
         /** Retained so a cadence change can rebuild each feed's gate heartbeat. */
         this.motionGateOptions = null;
         /** Look-rate for a still feed when the cascade is on. null ⇒ cascade off. */
@@ -278,6 +310,14 @@ class CloudSensingManager extends events_1.EventEmitter {
                 });
             }
         }
+        // The hold exists only where a cascade can name a candidate. `enabled`
+        // can turn it OFF where it would otherwise run; it can never turn it on
+        // without a classifier, because that is the queue the gate refuses.
+        const candidateBufferEnabled = motionGateEnabled && options.candidateBuffer?.enabled !== false;
+        this.candidates = candidateBufferEnabled
+            ? new VlmCandidateBuffer_1.VlmCandidateBuffer({ ...options.candidateBuffer, now: this.now })
+            : null;
+        this.candidatePumpIntervalMs = Math.max(1, Math.trunc(options.candidateBuffer?.pumpIntervalMs ?? this.admissionRetryDelayMs));
         this.motionDrivesCadence = options.motionDrivesCadence ?? motionGateEnabled;
         this.cadenceSource = options.cadenceSource;
         this.cadenceRefreshIntervalMs = Math.max(1000, Math.trunc(options.cadenceRefreshIntervalMs ?? DEFAULT_CADENCE_REFRESH_MS));
@@ -409,6 +449,10 @@ class CloudSensingManager extends events_1.EventEmitter {
         const cloudEscalated = escalation.reduce((n, e) => n + e.escalated, 0);
         // Per-stage attribution: read each feed's gate once, then fold.
         const gateStats = this.loops.map((s) => s.motionGate?.getStats() ?? null);
+        // One read of the hold, so the top-level totals and the per-feed rows can
+        // never describe two different instants.
+        const candidateStats = this.candidates?.getStats() ?? null;
+        const candidateByFeed = new Map((candidateStats?.perFeed ?? []).map((f) => [f.name, f]));
         const cascadeByReason = emptyMotionReasonCounts();
         let cascadeEvaluated = 0;
         let cascadeAnalyzed = 0;
@@ -447,6 +491,21 @@ class CloudSensingManager extends events_1.EventEmitter {
                 skipped: cascadeEvaluated - cascadeAnalyzed,
                 byReason: cascadeByReason,
             },
+            candidateBuffer: {
+                enabled: this.candidates !== null,
+                buffered: candidateStats?.buffered ?? 0,
+                bytes: candidateStats?.bytes ?? 0,
+                maxFrames: candidateStats?.maxFrames ?? 0,
+                maxPerFeed: candidateStats?.maxPerFeed ?? 0,
+                maxBytes: candidateStats?.maxBytes ?? 0,
+                ttlMs: candidateStats?.ttlMs ?? 0,
+                enqueued: candidateStats?.enqueued ?? 0,
+                served: candidateStats?.served ?? 0,
+                evicted: candidateStats?.evicted ?? 0,
+                expired: candidateStats?.expired ?? 0,
+                oldestAgeMs: candidateStats?.oldestAgeMs ?? null,
+                perFeed: candidateStats?.perFeed ?? [],
+            },
             cloudEscalated,
             cloudEscalationEnabled: escalation.some((e) => e.enabled),
             accelerator: foldAcceleratorHealth(this.loops.map((s) => acceleratorHealthFor(s)).filter((a) => a !== null)),
@@ -459,6 +518,8 @@ class CloudSensingManager extends events_1.EventEmitter {
                 motionSkippedByReason: gateStats[i]
                     ? { ...emptyMotionReasonCounts(), ...gateStats[i].byReason }
                     : emptyMotionReasonCounts(),
+                candidatesBuffered: candidateByFeed.get(s.deps.name)?.buffered ?? 0,
+                candidatesServed: candidateByFeed.get(s.deps.name)?.served ?? 0,
                 cloudEscalated: escalation[i].escalated,
                 faceDetected: s.faceDetected,
                 currentIntervalMs: this.intervalFor(s),
@@ -486,6 +547,11 @@ class CloudSensingManager extends events_1.EventEmitter {
             s.runMotionSkipped = 0;
             void this.startLoop(s, generation).catch((err) => this.emitLoopError(s, err));
         }
+        // A candidate held across a stop()/start() cycle is a frame from a run
+        // whose cameras may now be pointing somewhere else — the same reason the
+        // motion gate re-seeds above.
+        this.candidates?.reset();
+        this.scheduleCandidatePump(generation);
         // Ask once at startup so a connector picks up its deployed cadence on boot
         // rather than after a full refresh period, then keep asking. Both are
         // best-effort: refreshDeployedCadence never throws and never resets the
@@ -509,6 +575,12 @@ class CloudSensingManager extends events_1.EventEmitter {
         // closed against the NEXT run.
         this.admissionGate.reset();
         this.healthCaptureInFlight = false;
+        if (this.candidatePumpTimer) {
+            clearTimeout(this.candidatePumpTimer);
+            this.candidatePumpTimer = null;
+        }
+        // Held frames belong to the run that captured them.
+        this.candidates?.reset();
         if (this.cadenceTimer) {
             clearInterval(this.cadenceTimer);
             this.cadenceTimer = null;
@@ -623,7 +695,9 @@ class CloudSensingManager extends events_1.EventEmitter {
                     }
                     return;
                 }
-                this.reportCameraOpen(s, { frameProven: true, sensingState: 'idle' });
+                // The handshake succeeded — that is REACHABILITY, not video. The first
+                // real capture below is what proves frames decode.
+                this.reportCameraOpen(s, { streamOpened: true, sensingState: 'idle' });
             }
             catch (err) {
                 if (!this.isCurrentStart(generation)) {
@@ -828,7 +902,11 @@ class CloudSensingManager extends events_1.EventEmitter {
             // frame as "changed". The heartbeat clock is deliberately NOT reset: an
             // outage must not delay the feed's next guaranteed report.
             s.motionGate?.reset();
-            this.reportCameraOpen(s, { frameProven: true, sensingState: 'idle' });
+            // A re-open proves the recorder answered again — NOT that video came
+            // back. Claiming a frame here let a flapping feed refresh its own video
+            // clock forever, so a camera that reconnected every few seconds and
+            // decoded nothing could never age into "waiting for video".
+            this.reportCameraOpen(s, { streamOpened: true, sensingState: 'idle' });
             this.emit('reconnected', { name: s.deps.name });
             return true;
         }
@@ -887,14 +965,35 @@ class CloudSensingManager extends events_1.EventEmitter {
             });
         });
     }
+    /**
+     * Report this feed as `open`, carrying the proof we ACTUALLY have.
+     *
+     * `frameProven` and `streamOpened` are two different facts and the caller must
+     * not conflate them:
+     *
+     *   `streamOpened` — `camera.open()` resolved. The RTSP handshake completed,
+     *                    so the RECORDER IS REACHABLE. No frame has decoded, so
+     *                    this deliberately carries NO `lastFrameAtMs` and does NOT
+     *                    advance `lastCaptureAtMs` — a feed that has proved only
+     *                    reachability is still owed a video probe, immediately.
+     *   `frameProven`  — ffmpeg handed us real bytes. VIDEO IS HEALTHY.
+     *
+     * Both force a report, because both are transitions an operator is waiting on
+     * ("Connecting…" must clear the moment the recorder answers).
+     */
     reportCameraOpen(s, options = {}) {
         const sensingState = options.sensingState ?? s.lastSensingState ?? 'idle';
         const now = this.now();
         const stateChanged = s.lastSensingState !== sensingState;
         const heartbeatDue = s.lastHealthReportAtMs == null ||
             now - s.lastHealthReportAtMs >= this.cameraHealthHeartbeatIntervalMs;
-        if (!options.frameProven && !options.force && !stateChanged && !heartbeatDue)
+        if (!options.frameProven &&
+            !options.streamOpened &&
+            !options.force &&
+            !stateChanged &&
+            !heartbeatDue) {
             return;
+        }
         if (options.frameProven)
             s.lastCaptureAtMs = now;
         this.reportCameraHealth(s, {
@@ -903,7 +1002,9 @@ class CloudSensingManager extends events_1.EventEmitter {
             sensingState,
             ...(options.frameProven
                 ? { lastFrameAtMs: now, captureProof: 'decoded_frame' }
-                : {}),
+                : options.streamOpened
+                    ? { captureProof: 'stream_open' }
+                    : {}),
         });
     }
     healthProbeDue(s) {
@@ -935,17 +1036,141 @@ class CloudSensingManager extends events_1.EventEmitter {
         }
     }
     /**
-     * One cascade pass for a feed: admission → capture → motion → inference,
-     * with a bounded decode-only health probe when admission is denied.
+     * One cascade pass for a feed. Which pass depends on whether there is a
+     * cascade to name a candidate — see the class header for why the order
+     * differs and why that is not two behaviours bolted together.
      *
-     * The admission check comes first so denied inference frames are dropped,
-     * never buffered. Video health is independent: at most one feed at a time
-     * may take a slow-cadence decode-only proof while the model is occupied.
+     * Deliberately NOT `async`: it hands the chosen pass's promise straight back
+     * instead of adopting it. An `async` dispatcher would insert two microtask
+     * hops in front of every capture on a path this PR does not otherwise
+     * change, and a fake-timer test that advances a fixed number of drains would
+     * then complete fewer ticks per advance — which is not a behaviour change but
+     * is indistinguishable from one at 2 a.m. Zero delta on the untouched path is
+     * cheaper to hold than the argument about whether the delta mattered.
      */
-    async captureAndPost(s) {
+    captureAndPost(s) {
         if (!s.deps.camera.isOpen()) {
-            throw new Error(`CloudSensingManager: camera "${s.deps.name}" is not open`);
+            return Promise.reject(new Error(`CloudSensingManager: camera "${s.deps.name}" is not open`));
+        }
+        if (this.candidates && s.motionGate) {
+            return this.lookThenAdmit(s, this.candidates, s.motionGate);
+        }
+        return this.admitThenLook(s);
+    }
+    /**
+     * LOOK FIRST, admit second: capture → motion → (candidate) → admission.
+     *
+     * Runs only with the cascade on, because only the cascade can answer "is
+     * this frame worth holding?". A candidate the gate cannot take right now
+     * goes into the bounded hold instead of onto the floor; anything the cascade
+     * rejected is dropped exactly as before and is never offered.
+     */
+    async lookThenAdmit(s, candidates, motionGate) {
+        const frame = await s.deps.camera.getFrame();
+        const res = safeGetResolution(s.deps.camera);
+        const jpeg = await this.toJpeg(frame, res?.width, res?.height);
+        s.captureCount++;
+        this.reportCameraOpen(s, { frameProven: true, sensingState: 'analyzing', force: true });
+        this.emit('frameCaptured', { name: s.deps.name, faceDetected: s.faceDetected });
+        const verdict = await motionGate.evaluate(jpeg);
+        if (this.motionDrivesCadence) {
+            this.applyMotionCadence(s, verdict.motion);
+        }
+        if (!verdict.analyze) {
+            s.motionSkipCount++;
+            s.runMotionSkipped++;
+            this.emit('motionSkipped', {
+                name: s.deps.name,
+                reason: verdict.reason,
+                pctMotion: verdict.pctMotion,
+                regions: verdict.boxes.length,
+            });
+            this.reportCameraOpen(s, { sensingState: 'idle' });
+            return null;
+        }
+        // The cascade says this frame is worth an inference. Everything below is
+        // about WHEN it gets one, never about whether it survives.
+        const captureMode = s.faceDetected ? 'face_triggered' : 'periodic';
+        const ticket = this.admissionGate.tryAcquire(s.deps.name);
+        if (!ticket) {
+            s.admissionDeniedCount++;
+            s.runAdmissionDenied++;
+            // Only a CHANGE is held. A still-scene heartbeat or an undecodable frame
+            // is a sample, and for a sample the admission gate's original rule is
+            // exactly right: the newest one is the best one, so holding an old one
+            // would spend a slot a real event could have had. Measured at 32 cameras
+            // on the CPU profile, that distinction is not cosmetic — starvation makes
+            // almost every feed permanently heartbeat-due, so a hold that took every
+            // heartbeat filled with proof-of-life frames and crowded the arrivals out
+            // of their own buffer.
+            //
+            // `isChangeCandidate` reads the whole verdict and not its label, because
+            // that same starvation is what makes a REAL arrival arrive labelled
+            // `heartbeat` — the gate resolves heartbeat-due before it looks at the
+            // motion verdict, so the change survives only in `verdict.motion`.
+            const buffered = (0, SceneChangeDetector_1.isChangeCandidate)(verdict) &&
+                candidates.offer({
+                    name: s.deps.name,
+                    jpeg,
+                    captureMode,
+                    reason: verdict.reason,
+                    signature: verdict.signature,
+                    // Travels WITH the frame. A candidate can be served long after the
+                    // camera moved on, so re-reading the camera at serve time would
+                    // describe a different frame than the one being analyzed.
+                    imageWidth: res?.width,
+                    imageHeight: res?.height,
+                }) === 'buffered';
+            this.emit('admissionDenied', {
+                name: s.deps.name,
+                // No short retry either way. Unlike the no-cascade path, this tick has
+                // already LOOKED: a held frame is safe until the pump takes it, and a
+                // frame we chose not to hold is one whose successor is strictly
+                // better — so the right next move is the normal scan cadence, not a
+                // 250 ms re-grab of the same scene on all 32 feeds at once.
+                retryInMs: null,
+                buffered,
+                reason: verdict.reason,
+                inFlight: this.admissionGate.getInFlight(),
+                maxInFlight: this.admissionGate.getMaxInFlight(),
+            });
+            this.reportCameraOpen(s, { sensingState: 'waiting_for_capacity' });
+            return null;
+        }
+        try {
+            let response;
+            try {
+                // Same measured dimensions the encoder used, on the cascade path too —
+                // this is the path the multi-channel CCTV connector actually runs.
+                // Same measured dimensions the encoder used, on the cascade path too —
+                // this is the path the multi-channel CCTV connector actually runs.
+                response = await s.deps.client.analyze({
+                    jpeg,
+                    captureMode,
+                    imageWidth: res?.width,
+                    imageHeight: res?.height,
+                });
+            }
+            catch (err) {
+                this.reportCameraOpen(s, { sensingState: 'unavailable' });
+                throw err;
+            }
+            this.recordAnalysis(s, response, verdict.signature);
+            return response;
+        }
+        finally {
+            this.admissionGate.release(ticket);
         }
+    }
+    /**
+     * ADMIT FIRST, look second — the original order, unchanged, and the only one
+     * available without a cascade: nothing has classified the frame, so paying
+     * for a grab the model cannot take buys nothing, and a denied tick drops
+     * without touching the camera. Video health stays independent: at most one
+     * feed at a time may take a slow-cadence decode-only proof while the model
+     * is occupied.
+     */
+    async admitThenLook(s) {
         const ticket = this.admissionGate.tryAcquire(s.deps.name);
         if (!ticket) {
             s.admissionDeniedCount++;
@@ -981,8 +1206,10 @@ class CloudSensingManager extends events_1.EventEmitter {
             this.emit('frameCaptured', { name: s.deps.name, faceDetected: s.faceDetected });
             // Cheap stage: is this frame worth the expensive one? Releasing the slot
             // here (via the finally) costs the backend nothing but one grab.
+            let signature = null;
             if (s.motionGate) {
                 const verdict = await s.motionGate.evaluate(jpeg);
+                signature = verdict.signature;
                 if (this.motionDrivesCadence) {
                     this.applyMotionCadence(s, verdict.motion);
                 }
@@ -1012,25 +1239,167 @@ class CloudSensingManager extends events_1.EventEmitter {
                 response = await s.deps.client.analyze({
                     jpeg,
                     captureMode: s.faceDetected ? 'face_triggered' : 'periodic',
+                    // The dimensions we ALREADY decoded this frame at, above. They were
+                    // computed only to drive the JPEG encoder and then dropped, while the
+                    // wire carried the client's per-feed configured width instead — a
+                    // value that is absent on exactly the multi-channel feeds where the
+                    // question "what resolution did this camera actually deliver?" is
+                    // asked. Undefined when the provider implements no getResolution(),
+                    // in which case the client falls back to its constructor value.
+                    imageWidth: res?.width,
+                    imageHeight: res?.height,
                 });
             }
             catch (err) {
                 this.reportCameraOpen(s, { sensingState: 'unavailable' });
                 throw err;
             }
-            s.postCount++;
-            s.runAnalyses++;
-            // Stamp the heartbeat only once the call actually landed, so a frame lost
-            // to the network cannot silence a feed for a whole heartbeat window.
-            s.motionGate?.markAnalyzed();
-            this.reportCameraOpen(s, { sensingState: 'active' });
-            this.emit('analyzed', { name: s.deps.name, response });
+            this.recordAnalysis(s, response, signature);
             return response;
         }
         finally {
             this.admissionGate.release(ticket);
         }
     }
+    /**
+     * Everything that happens once a frame has been analyzed, in ONE place, so a
+     * held frame and a fresh one can never be counted — or reported to the portal
+     * — differently.
+     *
+     * Synchronous on purpose. The obvious factoring wraps the `analyze()` call
+     * itself, but that turns every caller's inline await into an await of an
+     * async helper, which adds microtask hops to the pre-existing capture path
+     * for no behavioural gain. What the two callers genuinely share is the
+     * bookkeeping AFTER the call, and that is what lives here; the four-line
+     * try/catch around the call stays at each site, where its `unavailable`
+     * report is visible next to the thing that can fail.
+     */
+    recordAnalysis(s, response, signature) {
+        s.postCount++;
+        s.runAnalyses++;
+        // Stamp the heartbeat AND the stationary baseline only once the call
+        // actually landed, so a frame lost to the network, to an eviction or to the
+        // freshness bound cannot silence a feed for a heartbeat window or suppress
+        // the rest of its event as `stationary`.
+        s.motionGate?.markAnalyzed(undefined, signature);
+        this.reportCameraOpen(s, { sensingState: 'active' });
+        this.emit('analyzed', { name: s.deps.name, response });
+    }
+    /**
+     * Arm the candidate pump for ONE run of the manager.
+     *
+     * A manager-scoped chain rather than a per-feed one, and that is the point:
+     * service order across feeds has to be a DECISION (least-recently-served,
+     * see VlmCandidateBuffer), not a race between 32 independent timers all
+     * polling for the same freed slot. `generation` carries the same meaning it
+     * carries in `scheduleNext` — a pump that survives a stop()/start() cycle
+     * must not arm a second chain.
+     */
+    scheduleCandidatePump(generation) {
+        if (!this.candidates || !this.isCurrentStart(generation))
+            return;
+        this.candidatePumpTimer = setTimeout(() => {
+            if (!this.isCurrentStart(generation))
+                return;
+            try {
+                this.pumpCandidates(generation);
+            }
+            finally {
+                this.scheduleCandidatePump(generation);
+            }
+        }, clampTimerDelay(this.candidatePumpIntervalMs));
+        // Never hold the process open for a poll that may have nothing to do.
+        if (typeof this.candidatePumpTimer.unref === 'function')
+            this.candidatePumpTimer.unref();
+    }
+    /**
+     * Offer the hold to every slot that is free right now.
+     *
+     * Synchronous by construction: each admitted candidate is launched as its own
+     * task and the pump does not await it, so one slow inference cannot delay the
+     * next pump tick or another feed's turn. Concurrency stays bounded by the
+     * admission gate, which is the only thing that ever knew the backend's real
+     * capacity.
+     */
+    pumpCandidates(generation) {
+        const buffer = this.candidates;
+        if (!buffer)
+            return;
+        // Age out first: a candidate past its TTL must never win a slot from one
+        // that is still current.
+        buffer.expire();
+        // Bounded by the slot count — this loop can hand out capacity, never spin.
+        for (let guard = this.admissionGate.getMaxInFlight(); guard > 0; guard--) {
+            if (buffer.size() === 0)
+                return;
+            if (this.admissionGate.getInFlight() >= this.admissionGate.getMaxInFlight())
+                return;
+            const next = buffer.peek();
+            if (!next)
+                return;
+            const s = this.loops.find((l) => l.deps.name === next.name);
+            if (!s) {
+                // Unreachable by construction: `loops` is fixed at construction and a
+                // candidate is only ever offered under its own loop's name. If it ever
+                // does happen, the frame cannot be analyzed and leaving it would block
+                // the head of the rotation forever — so drop it, but LOUDLY. The drop
+                // lands in the buffer's `served` counter, which would be a lie, and a
+                // quiet lie in the accounting is the exact defect this buffer exists to
+                // remove; the event is what makes it findable.
+                buffer.take();
+                this.emit('error', {
+                    name: next.name,
+                    error: new Error(`CloudSensingManager: held candidate for unknown feed "${next.name}" — dropped`),
+                });
+                continue;
+            }
+            const ticket = this.admissionGate.tryAcquire(next.name);
+            if (!ticket)
+                return; // lost the slot to a live tick — try again next pump
+            // Nothing above awaited, so this is the candidate `peek()` named.
+            const candidate = buffer.take();
+            if (!candidate) {
+                this.admissionGate.release(ticket);
+                return;
+            }
+            void this.serveCandidate(s, candidate, ticket, generation);
+        }
+    }
+    /** Analyze one held candidate and give the slot back. Never throws. */
+    async serveCandidate(s, candidate, ticket, generation) {
+        const waitedMs = Math.max(0, this.now() - candidate.enqueuedAtMs);
+        try {
+            let response;
+            try {
+                response = await s.deps.client.analyze({
+                    jpeg: candidate.jpeg,
+                    captureMode: candidate.captureMode,
+                    // The dimensions recorded when this frame was CAPTURED, not whatever
+                    // the camera reports now — the frame may have waited in the buffer.
+                    imageWidth: candidate.imageWidth,
+                    imageHeight: candidate.imageHeight,
+                });
+            }
+            catch (err) {
+                this.reportCameraOpen(s, { sensingState: 'unavailable' });
+                throw err;
+            }
+            this.recordAnalysis(s, response, candidate.signature);
+            if (this.isCurrentStart(generation)) {
+                this.emit('candidateAnalyzed', {
+                    name: s.deps.name,
+                    waitedMs,
+                    reason: candidate.reason,
+                });
+            }
+        }
+        catch (err) {
+            this.emitLoopError(s, err);
+        }
+        finally {
+            this.admissionGate.release(ticket);
+        }
+    }
     /**
      * Convert a camera frame to JPEG bytes for the POST.
      *