@trillboards/edge-sdk 0.2.4 → 0.2.6

package/dist/CloudSensingManager.js

@@ -0,0 +1,1254 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloudSensingManager = void 0;
+exports.classifyRtspFailureClass = classifyRtspFailureClass;
+exports.buildSensingLoops = buildSensingLoops;
+exports.buildTiledCameras = buildTiledCameras;
+exports.resolveFeeds = resolveFeeds;
+const events_1 = require("events");
+const AudienceAnalyzeClient_1 = require("./AudienceAnalyzeClient");
+const MosaicSource_1 = require("./MosaicSource");
+const runtimePaths_1 = require("./runtimePaths");
+const legacyRecorderProfile_1 = require("./legacyRecorderProfile");
+const VlmAdmissionGate_1 = require("./VlmAdmissionGate");
+const SceneChangeDetector_1 = require("./SceneChangeDetector");
+/**
+ * Thin cloud-sensing run mode.
+ *
+ * RTSP frame → (optional cheap motion/face gate) → AudienceAnalyzeClient POST.
+ * NO local ONNX — the cloud VLM does the inference. This is the agent's
+ * "point any CCTV at Trillboards" core: one connector process runs N capture
+ * loops (one per feed), each POSTing under ITS OWN device token so the cloud
+ * resolves THAT screen's profile.
+ *
+ * The cadence loop is ported from `@trillboards/edge-cloud`'s
+ * FrameCaptureManager: capture every `periodicIntervalMs` (5 min default) when
+ * NO faces, every `faceTriggeredIntervalMs` (30 s) when faces ARE present; POST
+ * only when faceDetected OR on the periodic cadence (cost control). Edge motion
+ * gating drives `setFaceDetected(...)`.
+ *
+ * ── The 16-camera cascade ───────────────────────────────────────────────────
+ * N feeds share ONE inference backend, and in local-sensing mode that backend
+ * (`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.
+ *   2. MOTION (`MotionGate`, per feed). Runs on a ~178x100 greyscale frame and
+ *      answers "did anything change?" in single-digit milliseconds. A frame
+ *      that fails it releases the admission slot immediately — an empty aisle
+ *      costs one cheap grab instead of a 6–32 s inference.
+ *
+ * Both stages are counted per feed (`getSensingHealth()`), because the honest
+ * form of degradation on a machine that cannot keep up is a number an operator
+ * can read — "sampling every 104 s per camera; 9.5 analyses/min sustained" —
+ * not silent frame loss.
+ */
+const DEFAULT_PERIODIC_MS = 300000; // 5 min
+const DEFAULT_FACE_MS = 30000; // 30 s
+const DEFAULT_JPEG_QUALITY = 70;
+// Avoid a multi-camera stampede against consumer NVRs: on startup/reconnect,
+// phase capture loops apart by feed index. One-camera installs keep zero offset.
+//
+// `feedStaggerMs` is the DESIRED step and `maxFeedStaggerMs` the total spread
+// WINDOW — the step shrinks to fit the window when there are many feeds, so
+// every feed keeps a DISTINCT phase. The previous shape clamped each feed's
+// offset at the window instead, which made feed 15, 16, 17 … share one offset:
+// anti-stampede protection failed exactly at the 16-camera target it existed
+// for. The window is additionally capped by the fastest cadence so the spread
+// can never exceed one capture period.
+const DEFAULT_FEED_STAGGER_MS = 1000;
+const DEFAULT_MAX_FEED_STAGGER_MS = 15000;
+// Re-attempt bounds for a tick the admission gate denied. Derived from the
+// stagger step (so 16 feeds poll a freed slot ~2 s apart, not all at once).
+const MIN_ADMISSION_RETRY_MS = 250;
+const MAX_ADMISSION_RETRY_MS = 5000;
+// RTSP self-recovery backoff: a feed/network blip must NEVER permanently kill
+// sensing on an unattended 24/7 connector. When a camera drops (the RTSP
+// provider gives up its per-attempt retries and closes itself), the loop
+// re-opens it with bounded exponential backoff — starting here, doubling each
+// failure, clamped at the cap — and retries FOREVER (the camera may come back at
+// any time). The backoff resets the instant a re-open succeeds.
+const DEFAULT_RECONNECT_INITIAL_MS = 1000; // 1 s
+const DEFAULT_RECONNECT_MAX_MS = 30000; // 30 s
+const DEFAULT_CAMERA_HEALTH_FAILURE_GRACE_COUNT = 3;
+const DEFAULT_CAMERA_HEALTH_PROBE_INTERVAL_MS = 120000;
+const DEFAULT_CAMERA_HEALTH_HEARTBEAT_INTERVAL_MS = 60000;
+// How often a running connector re-asks what cadence its operator deployed.
+// Matches the sensing-profile client's own TTL so the two do not disagree about
+// how stale a profile may be.
+const DEFAULT_CADENCE_REFRESH_MS = 300000;
+/**
+ * Node's `setTimeout` delay is a 32-bit SIGNED int. A larger value does not
+ * saturate and does not throw — it is coerced to 1 ms and the callback fires on
+ * the next tick. For a capture loop that inverts the request completely: "look
+ * once every 25 days" becomes "pull this camera as fast as ffmpeg can decode".
+ * Every delay this class hands to `setTimeout` goes through `clampTimerDelay`,
+ * so no config, no server row and no future code path can express a schedule the
+ * runtime will silently turn inside out. `deployedCadence.MAX_CADENCE_MS` is the
+ * policy bound two orders of magnitude inside this one; this is the mechanism
+ * bound that has to hold even if the policy one is bypassed.
+ */
+const MAX_TIMER_DELAY_MS = 2147483647;
+function clampTimerDelay(ms) {
+    if (!Number.isFinite(ms))
+        return 0;
+    return Math.min(MAX_TIMER_DELAY_MS, Math.max(0, ms));
+}
+const AUTH_FAILURE_RE = /(\b(?:401|403)\b|unauthori[sz]ed|forbidden|authentication failed|auth failed|invalid (user|username|password)|wrong password|bad credentials|access denied)/i;
+const TIMEOUT_FAILURE_RE = /(timed? out|timeout|etimedout|i\/o timeout|connection timed out|rtsp frame capture timed out)/i;
+const UNREACHABLE_FAILURE_RE = /(econnrefused|connection refused|enetunreach|ehostunreach|network is unreachable|host is unreachable|no route to host|could not resolve|name or service not known|getaddrinfo|not found|404)/i;
+const DECODE_FAILURE_RE = /(missing pps|non-existing pps|missing sps|non-existing sps|decode_slice_header|illegal poc|invalid nal|corrupt(?:ed)?|error while decoding|concealing \d+|reference picture missing|mmco|cabac|sps_id|pps_id)/i;
+const NO_FRAMES_FAILURE_RE = /(no frame|no video|unexpected frame size|invalid jpeg|invalid data|output file is empty|end of file|eof)/i;
+const NVR_BUSY_FAILURE_RE = /(\b(?:453|455)\b|not enough bandwidth|session limit|too many (?:viewers|connections|sessions)|maximum (?:viewer|connection|session)|max(?:imum)? clients)/i;
+const URL_CREDENTIAL_RE = /\b((?:rtsp|rtsps|https?):\/\/)([^@\s]+)@/gi;
+const SECRET_PARAM_RE = /\b(password|passwd|pwd|pass|token|deviceToken|device_token)=([^&\s]+)/gi;
+const AUTH_HEADER_RE = /\b(authorization:\s*(?:basic|bearer)\s+)[^\s]+/gi;
+function classifyRtspFailureClass(err) {
+    const message = errorMessage(err);
+    if (AUTH_FAILURE_RE.test(message))
+        return 'rtsp_auth';
+    if (NVR_BUSY_FAILURE_RE.test(message))
+        return 'nvr_busy';
+    if (UNREACHABLE_FAILURE_RE.test(message))
+        return 'rtsp_unreachable';
+    if (TIMEOUT_FAILURE_RE.test(message))
+        return 'rtsp_timeout';
+    if (DECODE_FAILURE_RE.test(message))
+        return 'decode_error';
+    if (NO_FRAMES_FAILURE_RE.test(message))
+        return 'no_frames';
+    return 'rtsp_unreachable';
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err ?? '');
+}
+function redactAndTruncateFailureMessage(err) {
+    return redactSensitiveFailureMessage(errorMessage(err)).slice(0, 512);
+}
+function redactSensitiveFailureMessage(message) {
+    return message
+        .replace(URL_CREDENTIAL_RE, '$1[redacted]@')
+        .replace(SECRET_PARAM_RE, '$1=[redacted]')
+        .replace(AUTH_HEADER_RE, '$1[redacted]');
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+class CloudSensingManager extends events_1.EventEmitter {
+    constructor(options) {
+        super();
+        /** The last cadence verdict applied, surfaced by getSensingHealth(). */
+        this.cadence = null;
+        this.cadenceTimer = 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. */
+        this.motionScanIntervalMs = null;
+        this.running = false;
+        this.startGeneration = 0;
+        this.runStartedAtMs = null;
+        /** One decode-only probe at a time protects recorder session limits. */
+        this.healthCaptureInFlight = false;
+        if (!options.loops || options.loops.length === 0) {
+            throw new Error('CloudSensingManager requires at least one capture loop');
+        }
+        this.now = options.now ?? Date.now;
+        const motionGateEnabled = !!options.motionGate && options.motionGate.enabled !== false;
+        this.loops = options.loops.map((deps, index) => ({
+            index,
+            deps,
+            faceDetected: false,
+            timer: null,
+            captureCount: 0,
+            postCount: 0,
+            cameraHealthRetryCount: 0,
+            reconnectDelayMs: null,
+            motionGate: null,
+            admissionDeniedCount: 0,
+            motionSkipCount: 0,
+            runAnalyses: 0,
+            runAdmissionDenied: 0,
+            runMotionSkipped: 0,
+            retryDelayMs: null,
+            tickInFlight: false,
+            lastCaptureAtMs: null,
+            lastHealthReportAtMs: null,
+            lastSensingState: null,
+        }));
+        this.periodicIntervalMs = options.periodicIntervalMs ?? DEFAULT_PERIODIC_MS;
+        this.faceTriggeredIntervalMs = options.faceTriggeredIntervalMs ?? DEFAULT_FACE_MS;
+        this.jpegQuality = options.jpegQuality ?? DEFAULT_JPEG_QUALITY;
+        this.skipPostWhenNoFaces = options.skipPostWhenNoFaces ?? true;
+        this.width = options.width;
+        this.height = options.height;
+        // Clamp the floor to 1ms so a 0/negative config can't busy-spin the loop.
+        this.reconnectInitialDelayMs = Math.max(1, options.reconnectInitialDelayMs ?? DEFAULT_RECONNECT_INITIAL_MS);
+        // The cap can never be below the initial delay (a smaller cap would make the
+        // "double then clamp" schedule shrink the first step).
+        this.reconnectMaxDelayMs = Math.max(this.reconnectInitialDelayMs, options.reconnectMaxDelayMs ?? DEFAULT_RECONNECT_MAX_MS);
+        this.feedStaggerMs = Math.max(0, Math.trunc(options.feedStaggerMs ?? (options.loops.length > 1 ? DEFAULT_FEED_STAGGER_MS : 0)));
+        this.maxFeedStaggerMs = Math.max(0, Math.trunc(options.maxFeedStaggerMs ?? DEFAULT_MAX_FEED_STAGGER_MS));
+        this.cameraHealthFailureGraceCount = Math.max(1, Math.trunc(options.cameraHealthFailureGraceCount ??
+            DEFAULT_CAMERA_HEALTH_FAILURE_GRACE_COUNT));
+        this.cameraHealthProbeIntervalMs = Math.max(1000, Math.trunc(options.cameraHealthProbeIntervalMs ?? DEFAULT_CAMERA_HEALTH_PROBE_INTERVAL_MS));
+        this.cameraHealthHeartbeatIntervalMs = Math.max(1000, Math.trunc(options.cameraHealthHeartbeatIntervalMs ?? DEFAULT_CAMERA_HEALTH_HEARTBEAT_INTERVAL_MS));
+        // One gate for the whole process. Defaulting to one slot PER LOOP keeps the
+        // cloud path (a genuinely concurrent backend) exactly as it is today; the
+        // local path passes 1 because its backend is single-conversation.
+        this.admissionGate = new VlmAdmissionGate_1.VlmAdmissionGate({
+            maxInFlight: Math.max(1, Math.trunc(options.maxConcurrentAnalyses ?? this.loops.length)),
+            maxInFlightMs: options.maxAnalysisInFlightMs,
+            now: this.now,
+        });
+        this.admissionRetryDelayMs = Math.max(1, Math.trunc(options.admissionRetryDelayMs ??
+            Math.min(MAX_ADMISSION_RETRY_MS, Math.max(MIN_ADMISSION_RETRY_MS, this.staggerStepMs()))));
+        if (motionGateEnabled) {
+            const gateOptions = options.motionGate;
+            this.motionScanIntervalMs = Math.max(1, Math.trunc(gateOptions.scanIntervalMs ?? this.faceTriggeredIntervalMs));
+            this.motionGateOptions = gateOptions;
+            for (const s of this.loops) {
+                s.motionGate = new SceneChangeDetector_1.MotionGate({
+                    ...gateOptions,
+                    // The gate reuses the cadence knobs the config already carries: a
+                    // still scene still reports on the periodic cadence, and a busy one
+                    // can never analyze faster than the face-triggered cadence.
+                    heartbeatIntervalMs: gateOptions.heartbeatIntervalMs ?? this.periodicIntervalMs,
+                    minAnalyzeIntervalMs: gateOptions.minAnalyzeIntervalMs ?? this.faceTriggeredIntervalMs,
+                    now: this.now,
+                });
+            }
+        }
+        this.motionDrivesCadence = options.motionDrivesCadence ?? motionGateEnabled;
+        this.cadenceSource = options.cadenceSource;
+        this.cadenceRefreshIntervalMs = Math.max(1000, Math.trunc(options.cadenceRefreshIntervalMs ?? DEFAULT_CADENCE_REFRESH_MS));
+    }
+    /**
+     * Retune a RUNNING connector's still-scene cadence.
+     *
+     * Timers are NOT cancelled: each loop re-arms from `nextDelayFor` in its own
+     * `.finally`, so the new interval takes effect on the next tick. Cancelling
+     * and rescheduling here would collapse every feed's carefully-staggered phase
+     * onto the same instant — the multi-camera NVR stampede `staggerStepMs`
+     * exists to prevent — for no gain, since the worst-case lag is one old
+     * period.
+     *
+     * The motion gate's HEARTBEAT tracks the cadence, because the heartbeat IS
+     * the still-scene reporting floor: leaving it at the old value would let a
+     * gate keep reporting on a cadence the operator has replaced.
+     *
+     * The heartbeat is retuned IN PLACE (`MotionGate.setHeartbeatIntervalMs`) and
+     * NOT by rebuilding the gate. A fresh `MotionGate` is a fresh
+     * `SceneChangeDetector`: no background model, `calibrating` re-armed, the
+     * contrast ring un-seeded, the stationary signature forgotten and — the
+     * expensive one — `lastAnalyzedAtMs` back to null, which makes the very next
+     * look heartbeat-DUE and forces an inference on a scene the gate had already
+     * proven still. Measured: a byte-identical still frame costs 0 analyses over
+     * ten looks, then exactly +1 per feed the instant the cadence moves. On a
+     * 16-camera store that is 16 forced generations against the connector's single
+     * slot for a change that was meant to cost nothing. Rebuilding also swapped
+     * the object mid-tick, so a frame's `evaluate()` and its `markAnalyzed()`
+     * could land on two different gates.
+     *
+     * @returns true when the interval actually changed.
+     */
+    setPeriodicIntervalMs(intervalMs) {
+        const raw = Number(intervalMs);
+        if (!Number.isFinite(raw) || raw <= 0)
+            return false;
+        // A cadence the timer cannot express is not a cadence — see clampTimerDelay.
+        // Clamping HERE (not only at setTimeout) keeps getPeriodicIntervalMs
+        // truthful: what it reports is what the loops actually run.
+        const next = clampTimerDelay(Math.trunc(raw));
+        if (next <= 0 || next === this.periodicIntervalMs)
+            return false;
+        this.periodicIntervalMs = next;
+        if (this.motionGateOptions) {
+            // Only the DERIVED heartbeat follows the cadence. An explicitly
+            // configured heartbeat is the operator's own floor and stays theirs.
+            if (this.motionGateOptions.heartbeatIntervalMs === undefined) {
+                for (const s of this.loops)
+                    s.motionGate?.setHeartbeatIntervalMs(next);
+            }
+        }
+        return true;
+    }
+    /** The still-scene cadence currently in force. */
+    getPeriodicIntervalMs() {
+        return this.periodicIntervalMs;
+    }
+    /**
+     * Ask the cadence source what the operator deployed and apply it. Best-effort
+     * and never throws: a failed lookup leaves the running cadence untouched,
+     * because a connector that resets to a default every time the API blips is
+     * worse than one that is briefly stale.
+     */
+    async refreshDeployedCadence() {
+        if (!this.cadenceSource)
+            return null;
+        let verdict = null;
+        try {
+            verdict = await this.cadenceSource.resolve();
+        }
+        catch (err) {
+            this.emit('error', err instanceof Error ? err : new Error(String(err)));
+            return null;
+        }
+        if (!verdict)
+            return null;
+        this.cadence = verdict;
+        if (verdict.intervalMs === null)
+            return verdict;
+        if (this.setPeriodicIntervalMs(verdict.intervalMs)) {
+            // A DISTINCT event from 'cadenceChanged': that one is a per-feed
+            // face-state switch carrying {name, intervalMs, reason}. This is a
+            // whole-connector retune, and overloading the same event would make a
+            // consumer's `reason` field mean two unrelated things.
+            this.emit('deployedCadenceChanged', verdict);
+        }
+        return verdict;
+    }
+    /** Number of independent capture loops (== number of feeds/tokens). */
+    getLoopCount() {
+        return this.loops.length;
+    }
+    /** Per-loop stats (capture + POST counts, cadence, cascade drops). */
+    getStats() {
+        return this.loops.map((s) => ({
+            name: s.deps.name,
+            captureCount: s.captureCount,
+            postCount: s.postCount,
+            faceDetected: s.faceDetected,
+            currentIntervalMs: this.intervalFor(s),
+            admissionDeniedCount: s.admissionDeniedCount,
+            motionSkipCount: s.motionSkipCount,
+        }));
+    }
+    /** Live admission-gate counters (admitted / dropped / stale-reclaimed). */
+    getAdmissionStats() {
+        return this.admissionGate.getStats();
+    }
+    /**
+     * The operator-facing answer to "why is my 16-camera store only sampling
+     * every N seconds?" — sustained analyses/minute is what the machine can
+     * actually do, and `effectiveSampleIntervalMs` is what that buys each camera.
+     * Drops are attributed: `admissionDenied` means the backend is the ceiling,
+     * `motionSkipped` means the cascade decided the frame was not worth paying
+     * for. Both are wins over the old failure mode, where the surplus vanished
+     * into 120 s timeouts.
+     */
+    getSensingHealth() {
+        const uptimeMs = this.runStartedAtMs === null ? 0 : Math.max(0, this.now() - this.runStartedAtMs);
+        const analyses = this.loops.reduce((n, s) => n + s.runAnalyses, 0);
+        const admissionDenied = this.loops.reduce((n, s) => n + s.runAdmissionDenied, 0);
+        const motionSkipped = this.loops.reduce((n, s) => n + s.runMotionSkipped, 0);
+        const analysesPerMinute = uptimeMs > 0 ? (analyses * 60000) / uptimeMs : 0;
+        // Escalation counts live on the CLIENT (it owns the policy), not on the
+        // loop: the manager never sees the local/cloud choice, and duplicating the
+        // count here would be a second home for one number.
+        const escalation = this.loops.map((s) => escalationStatsFor(s));
+        const cloudEscalated = escalation.reduce((n, e) => n + e.escalated, 0);
+        return {
+            loops: this.loops.length,
+            maxConcurrentAnalyses: this.admissionGate.getMaxInFlight(),
+            inFlight: this.admissionGate.getInFlight(),
+            uptimeMs,
+            analyses,
+            analysesPerMinute,
+            // Per CAMERA: how long between two looks by the model, given the
+            // throughput the machine actually sustained.
+            effectiveSampleIntervalMs: analyses > 0 && uptimeMs > 0 ? (uptimeMs * this.loops.length) / analyses : null,
+            periodicIntervalMs: this.periodicIntervalMs,
+            deployedCadence: this.cadence,
+            admissionDenied,
+            motionSkipped,
+            cloudEscalated,
+            cloudEscalationEnabled: escalation.some((e) => e.enabled),
+            perFeed: this.loops.map((s, i) => ({
+                name: s.deps.name,
+                captures: s.captureCount,
+                analyses: s.runAnalyses,
+                admissionDenied: s.runAdmissionDenied,
+                motionSkipped: s.runMotionSkipped,
+                cloudEscalated: escalation[i].escalated,
+                faceDetected: s.faceDetected,
+                currentIntervalMs: this.intervalFor(s),
+            })),
+        };
+    }
+    isRunning() {
+        return this.running;
+    }
+    /** Open cameras, prove one frame, and start capture loops without one slow feed blocking others. */
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.runStartedAtMs = this.now();
+        const generation = ++this.startGeneration;
+        for (const s of this.loops) {
+            // A stop()/start() cycle may resume on a different view (re-paired
+            // camera, changed mosaic crop), so the background model must not carry
+            // over — a stale baseline reports a whole-frame change that never
+            // happened, and the heartbeat clock restarts with the run.
+            s.motionGate?.reset();
+            s.runAnalyses = 0;
+            s.runAdmissionDenied = 0;
+            s.runMotionSkipped = 0;
+            void this.startLoop(s, generation).catch((err) => this.emitLoopError(s, err));
+        }
+        // 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
+        // cadence on failure.
+        if (this.cadenceSource) {
+            void this.refreshDeployedCadence();
+            this.cadenceTimer = setInterval(() => {
+                void this.refreshDeployedCadence();
+            }, this.cadenceRefreshIntervalMs);
+            // Never hold the process open for a cadence poll.
+            if (typeof this.cadenceTimer.unref === 'function')
+                this.cadenceTimer.unref();
+        }
+    }
+    /** Stop all loops and close cameras. */
+    async stop() {
+        this.running = false;
+        this.startGeneration++;
+        this.runStartedAtMs = null;
+        // Drop every held slot: a capture still unwinding must not leave the gate
+        // closed against the NEXT run.
+        this.admissionGate.reset();
+        this.healthCaptureInFlight = false;
+        if (this.cadenceTimer) {
+            clearInterval(this.cadenceTimer);
+            this.cadenceTimer = null;
+        }
+        for (const s of this.loops) {
+            if (s.timer) {
+                clearTimeout(s.timer);
+                s.timer = null;
+            }
+            s.retryDelayMs = null;
+            s.tickInFlight = false;
+        }
+        for (const s of this.loops) {
+            try {
+                if (s.deps.camera.isOpen()) {
+                    await s.deps.camera.close();
+                }
+            }
+            catch {
+                // best-effort close
+            }
+        }
+    }
+    /**
+     * Notify a loop (by feed name) that its face-detection state changed —
+     * switches that loop between the periodic and face-triggered cadence.
+     */
+    setFaceDetected(loopName, detected) {
+        const s = this.loops.find((l) => l.deps.name === loopName);
+        if (!s)
+            return;
+        const prev = s.faceDetected;
+        s.faceDetected = detected;
+        if (prev === detected || !this.running)
+            return;
+        this.emit('cadenceChanged', {
+            name: s.deps.name,
+            intervalMs: this.intervalFor(s),
+            reason: detected ? 'face_detected' : 'no_faces',
+        });
+        // A tick already running re-arms from its own `.finally` and will read the
+        // interval we just changed. Arming here as well is the same double-chain
+        // `applyMotionCadence` avoids by construction — the in-tick twin of this
+        // method — except this one is public and can be called at any instant.
+        if (s.tickInFlight)
+            return;
+        if (s.timer) {
+            clearTimeout(s.timer);
+            s.timer = null;
+        }
+        this.scheduleNext(s, this.startGeneration);
+    }
+    /**
+     * Same cadence switch, but from INSIDE a running tick: record the new state
+     * and announce it WITHOUT rescheduling. The tick's own `finally` already
+     * calls scheduleNext and will read the updated interval — rescheduling here
+     * as well would leave the feed running two concurrent timers.
+     */
+    applyMotionCadence(s, motion) {
+        if (s.faceDetected === motion)
+            return;
+        s.faceDetected = motion;
+        this.emit('cadenceChanged', {
+            name: s.deps.name,
+            intervalMs: this.intervalFor(s),
+            reason: motion ? 'face_detected' : 'no_faces',
+        });
+    }
+    /**
+     * Capture + (conditionally) POST one frame for a given loop, immediately.
+     *
+     * Goes through the SAME cascade as a scheduled tick — an out-of-band capture
+     * that jumped the admission gate would break the very invariant the gate
+     * exists to hold. Returns `null` (rather than waiting) when the gate is
+     * closed or the motion stage judged the frame not worth an inference.
+     */
+    async captureNow(loopName) {
+        const s = this.loops.find((l) => l.deps.name === loopName);
+        if (!s)
+            return null;
+        return this.captureAndPost(s);
+    }
+    // ─── Private ────────────────────────────────────────────────────────────────
+    isCurrentStart(generation) {
+        return this.running && this.startGeneration === generation;
+    }
+    async startLoop(s, generation) {
+        // Fresh start → clear any stale backoff from a previous run (so a
+        // stop()→start() cycle resumes at the normal cadence, not a climbed delay).
+        s.reconnectDelayMs = null;
+        s.cameraHealthRetryCount = 0;
+        s.lastCaptureAtMs = null;
+        s.lastHealthReportAtMs = null;
+        s.lastSensingState = null;
+        let needsOpen = !s.deps.camera.isOpen();
+        const startupDelayMs = this.staggerFor(s);
+        if (startupDelayMs > 0) {
+            await sleep(startupDelayMs);
+        }
+        if (!this.isCurrentStart(generation))
+            return;
+        needsOpen = !s.deps.camera.isOpen();
+        if (needsOpen) {
+            // A camera unreachable at startup must NOT crash the connector — enter
+            // reconnect mode so the loop keeps retrying until the feed comes up,
+            // exactly as it does for a mid-run drop. Other feeds start independently.
+            try {
+                await s.deps.camera.open();
+                if (!this.isCurrentStart(generation)) {
+                    if (!this.running) {
+                        await this.closeCameraQuietly(s);
+                    }
+                    return;
+                }
+                this.reportCameraOpen(s, { frameProven: true, sensingState: 'idle' });
+            }
+            catch (err) {
+                if (!this.isCurrentStart(generation)) {
+                    if (!this.running) {
+                        await this.closeCameraQuietly(s);
+                    }
+                    return;
+                }
+                this.reportCameraFailure(s, err);
+                this.emitLoopError(s, err);
+                this.enterReconnect(s);
+            }
+        }
+        else {
+            this.reportCameraOpen(s, { sensingState: 'idle' });
+        }
+        // Do not leave a newly paired camera at "Connecting..." until the first
+        // periodic cadence (five minutes by default). The startup stagger above
+        // still protects multi-channel recorders from a connection burst, while
+        // this first capture gives the portal real proof of video promptly.
+        if (this.isCurrentStart(generation) && s.deps.camera.isOpen()) {
+            // Counts as a tick in flight: this call also ends in a scheduleNext, so a
+            // concurrent setFaceDetected must not arm a second chain underneath it.
+            s.tickInFlight = true;
+            try {
+                await this.captureAndPost(s);
+            }
+            catch (err) {
+                if (!this.isCurrentStart(generation))
+                    return;
+                if (!s.deps.camera.isOpen()) {
+                    this.reportCameraFailure(s, err);
+                    this.enterReconnect(s);
+                }
+                this.emitLoopError(s, err);
+            }
+            finally {
+                s.tickInFlight = false;
+            }
+        }
+        this.scheduleNext(s, generation);
+    }
+    async closeCameraQuietly(s) {
+        try {
+            if (s.deps.camera.isOpen()) {
+                await s.deps.camera.close();
+            }
+        }
+        catch {
+            // best-effort close
+        }
+    }
+    /**
+     * How long until this feed's next LOOK.
+     *
+     * Without the cascade this is the historical rule: fast while faces are
+     * present, slow otherwise. With the cascade on, a still feed keeps looking at
+     * the scan cadence — looking is cheap and only analysis is gated — and
+     * `periodicIntervalMs` becomes the gate's heartbeat, i.e. the floor on
+     * REPORTING rather than the rate of watching.
+     */
+    intervalFor(s) {
+        if (s.faceDetected)
+            return this.faceTriggeredIntervalMs;
+        return this.motionScanIntervalMs ?? this.periodicIntervalMs;
+    }
+    /**
+     * Per-feed phase step, derived from FEED COUNT and CADENCE instead of a fixed
+     * per-feed cap.
+     *
+     * The spread window is the smaller of the configured `maxFeedStaggerMs` and
+     * the fastest capture cadence (a spread longer than one period would just
+     * re-alias), and the step is the largest value that fits every feed inside
+     * it, never exceeding the configured `feedStaggerMs`. Small installs keep
+     * exactly today's offsets (4 feeds x 1000 ms); a 16-camera store gets 16
+     * DISTINCT offsets instead of feeds 15+ colliding on the cap.
+     */
+    staggerStepMs() {
+        if (this.feedStaggerMs <= 0 || this.loops.length <= 1)
+            return 0;
+        const window = Math.min(this.maxFeedStaggerMs, this.periodicIntervalMs, this.faceTriggeredIntervalMs);
+        if (window <= 0)
+            return 0;
+        return Math.max(1, Math.min(this.feedStaggerMs, Math.floor(window / this.loops.length)));
+    }
+    staggerFor(s) {
+        if (s.index <= 0)
+            return 0;
+        return s.index * this.staggerStepMs();
+    }
+    /**
+     * Delay before the next tick.
+     *
+     * - Camera dropped → the reconnect backoff, PLUS the phase offset so a
+     *   recorder that rebooted does not get all N feeds re-opening in lock-step.
+     * - Admission denied → a short one-shot retry (consumed here) so the loop
+     *   takes the inference slot as soon as it frees rather than idling a full
+     *   cadence.
+     * - Otherwise → exactly the capture cadence. The phase offset is applied ONCE
+     *   at startup (and on reconnect); adding it to every tick would make feed i's
+     *   period `cadence + offset_i`, quietly stretching the last feed's cadence by
+     *   the whole spread window — a 47 % slower camera 16 at the 30 s cadence.
+     *   Equal periods preserve the startup phase difference forever.
+     */
+    nextDelayFor(s) {
+        if (s.reconnectDelayMs != null)
+            return s.reconnectDelayMs + this.staggerFor(s);
+        if (s.retryDelayMs != null) {
+            const delay = s.retryDelayMs;
+            s.retryDelayMs = null;
+            return delay;
+        }
+        return this.intervalFor(s);
+    }
+    /**
+     * Arm this feed's next tick, for ONE run of the manager.
+     *
+     * `generation` is not decoration. A tick re-arms from its own `.finally`, and
+     * that `.finally` can run AFTER a stop()/start() cycle — the auto-sense
+     * supervisor stops and restarts the SAME manager instance every time
+     * `litert-lm` appears or disappears, and a cloud analyze can be in flight for
+     * up to two minutes. Without the generation the surviving tick re-arms a
+     * chain, `startLoop` arms another, and `s.timer` holds only the second one, so
+     * `stop()` can never clear the first: the feed now captures twice per cadence,
+     * permanently, and every further flap adds another chain. Measured: two
+     * pending timers for ONE feed after a single cycle. On the cloud path
+     * `maxConcurrentAnalyses` defaults to one slot PER LOOP, so the duplicate
+     * chain is duplicate Vertex spend, not just duplicate RTSP load.
+     */
+    scheduleNext(s, generation) {
+        if (!this.isCurrentStart(generation))
+            return;
+        const delayMs = clampTimerDelay(this.nextDelayFor(s));
+        s.timer = setTimeout(() => {
+            if (!this.isCurrentStart(generation))
+                return;
+            s.tickInFlight = true;
+            this.runScheduledTick(s)
+                .catch((err) => this.emitLoopError(s, err))
+                .finally(() => {
+                s.tickInFlight = false;
+                this.scheduleNext(s, generation);
+            });
+        }, delayMs);
+    }
+    /**
+     * One scheduled loop iteration with built-in RTSP self-recovery.
+     *
+     * If the camera is dropped (closed), this attempts to RE-OPEN it (the keystone
+     * 24/7 fix — a transient feed/network blip used to wedge the loop on "camera
+     * is not open" forever). On a successful re-open the backoff resets and the
+     * tick falls through to a normal capture so sensing resumes immediately; on a
+     * failed re-open the backoff doubles (capped) and we retry FOREVER. The
+     * per-attempt connect timeout still lives in the RTSP provider's open() — only
+     * the give-up-forever behavior changes to retry-forever.
+     */
+    async runScheduledTick(s) {
+        if (!s.deps.camera.isOpen()) {
+            // Camera dropped. If we just discovered the closure (not yet in reconnect
+            // mode), arm the backoff and let the NEXT tick — scheduled at the initial
+            // delay — do the actual re-open, so the first attempt always waits the
+            // initial backoff regardless of how the drop was detected.
+            if (s.reconnectDelayMs == null) {
+                this.enterReconnect(s);
+                return;
+            }
+            const ok = await this.tryReopen(s);
+            if (!ok)
+                return; // still down — backoff already armed for the next tick
+        }
+        // Camera is open (healthy, or just recovered) → capture as usual.
+        try {
+            await this.captureAndPost(s);
+        }
+        catch (err) {
+            // A capture failure that drops the camera (the RTSP provider gives up its
+            // per-attempt retries and re-closes itself) must hand off to the backoff
+            // re-open path, NOT silently wait a full cadence interval. Arm reconnect
+            // mode so the next tick fires at the initial backoff and starts re-opening.
+            if (!s.deps.camera.isOpen()) {
+                this.reportCameraFailure(s, err);
+                this.enterReconnect(s);
+            }
+            throw err; // surface to the loop's error handler (emits 'error')
+        }
+    }
+    /**
+     * Attempt one camera re-open. Returns true on success (backoff cleared, sensing
+     * resumes), false on failure (backoff doubled+capped for the next attempt).
+     * Emits `reconnecting` before each attempt and `reconnected` on recovery so
+     * operators can observe the self-healing on an unattended connector.
+     */
+    async tryReopen(s) {
+        const attemptDelayMs = s.reconnectDelayMs ?? this.reconnectInitialDelayMs;
+        this.emit('reconnecting', { name: s.deps.name, delayMs: attemptDelayMs });
+        try {
+            await s.deps.camera.open();
+            s.cameraHealthRetryCount = 0;
+            s.reconnectDelayMs = null; // recovered → reset backoff to healthy cadence
+            // The background model is as old as the outage — and the camera may have
+            // come back pointing somewhere else. Re-seed rather than report the whole
+            // 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' });
+            this.emit('reconnected', { name: s.deps.name });
+            return true;
+        }
+        catch (err) {
+            this.reportCameraFailure(s, err);
+            this.emitLoopError(s, err);
+            // Double the backoff, clamped at the cap (then it holds at the cap and
+            // keeps retrying — never gives up).
+            s.reconnectDelayMs = Math.min(attemptDelayMs * 2, this.reconnectMaxDelayMs);
+            return false;
+        }
+    }
+    /**
+     * Put a loop into reconnect mode (camera dropped). Idempotent: an already
+     * dropped loop keeps its current (climbing) backoff rather than resetting to
+     * the initial delay.
+     */
+    enterReconnect(s) {
+        if (s.reconnectDelayMs == null) {
+            s.reconnectDelayMs = this.reconnectInitialDelayMs;
+        }
+        // A dropped camera outranks a busy model: drop any pending admission retry
+        // so the two schedules can never interleave. Reconnect is never gated —
+        // a saturated model must not be able to turn a blip into permanent
+        // blindness on an unattended 24/7 connector.
+        s.retryDelayMs = null;
+    }
+    emitLoopError(s, err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        this.emit('error', { name: s.deps.name, error });
+    }
+    reportCameraFailure(s, err) {
+        s.cameraHealthRetryCount += 1;
+        const lastFailureClass = classifyRtspFailureClass(err);
+        if (lastFailureClass !== 'rtsp_auth' &&
+            s.cameraHealthRetryCount < this.cameraHealthFailureGraceCount) {
+            return;
+        }
+        this.reportCameraHealth(s, {
+            state: 'failed',
+            retryCount: s.cameraHealthRetryCount,
+            lastFailureClass,
+            lastFailureMessage: redactAndTruncateFailureMessage(err),
+        });
+    }
+    reportCameraHealth(s, cameraHealth) {
+        if (typeof s.deps.client.reportCameraHealth !== 'function')
+            return;
+        s.lastHealthReportAtMs = this.now();
+        if (cameraHealth.sensingState)
+            s.lastSensingState = cameraHealth.sensingState;
+        s.deps.client.reportCameraHealth(cameraHealth).catch((err) => {
+            this.emit('healthReportError', {
+                name: s.deps.name,
+                error: err instanceof Error ? err : new Error(String(err)),
+            });
+        });
+    }
+    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)
+            return;
+        if (options.frameProven)
+            s.lastCaptureAtMs = now;
+        this.reportCameraHealth(s, {
+            state: 'open',
+            retryCount: 0,
+            sensingState,
+            ...(options.frameProven
+                ? { lastFrameAtMs: now, captureProof: 'decoded_frame' }
+                : {}),
+        });
+    }
+    healthProbeDue(s) {
+        return (!this.healthCaptureInFlight &&
+            (s.lastCaptureAtMs == null || this.now() - s.lastCaptureAtMs >= this.cameraHealthProbeIntervalMs));
+    }
+    /**
+     * Prove video locally without waiting for the model. The global boolean keeps
+     * legacy recorders to one extra short-lived ffmpeg pull at a time.
+     */
+    async captureHealthFrame(s) {
+        this.healthCaptureInFlight = true;
+        try {
+            await s.deps.camera.getFrame();
+            s.captureCount++;
+            this.reportCameraOpen(s, {
+                frameProven: true,
+                sensingState: 'waiting_for_capacity',
+                force: true,
+            });
+            this.emit('frameCaptured', {
+                name: s.deps.name,
+                faceDetected: s.faceDetected,
+                healthOnly: true,
+            });
+        }
+        finally {
+            this.healthCaptureInFlight = false;
+        }
+    }
+    /**
+     * One cascade pass for a feed: admission → capture → motion → inference,
+     * with a bounded decode-only health probe when admission is denied.
+     *
+     * 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.
+     */
+    async captureAndPost(s) {
+        if (!s.deps.camera.isOpen()) {
+            throw new Error(`CloudSensingManager: camera "${s.deps.name}" is not open`);
+        }
+        const ticket = this.admissionGate.tryAcquire(s.deps.name);
+        if (!ticket) {
+            s.admissionDeniedCount++;
+            s.runAdmissionDenied++;
+            // Poll back soon instead of idling a whole cadence: the slot frees when
+            // the current inference lands, which is usually seconds away.
+            s.retryDelayMs = this.admissionRetryDelayMs;
+            this.emit('admissionDenied', {
+                name: s.deps.name,
+                retryInMs: this.admissionRetryDelayMs,
+                inFlight: this.admissionGate.getInFlight(),
+                maxInFlight: this.admissionGate.getMaxInFlight(),
+            });
+            this.reportCameraOpen(s, { sensingState: 'waiting_for_capacity' });
+            if (this.healthProbeDue(s)) {
+                await this.captureHealthFrame(s);
+            }
+            return null;
+        }
+        try {
+            const frame = await s.deps.camera.getFrame();
+            // Resolve frame dimensions from the camera so raw RGB24 buffers always
+            // encode — works for every feed regardless of config shape (multi-channel
+            // feeds carry no top-level camera.width/height).
+            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 });
+            // Cheap stage: is this frame worth the expensive one? Releasing the slot
+            // here (via the finally) costs the backend nothing but one grab.
+            if (s.motionGate) {
+                const verdict = await s.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;
+                }
+            }
+            // With the cascade on, the motion gate is the SOLE authority on whether a
+            // frame is analyzed — one decision, one place. Without it, the historical
+            // rule stands: POST when faces are present OR on the periodic cadence.
+            const shouldPost = s.motionGate ? true : s.faceDetected || !this.skipPostWhenNoFaces;
+            if (!shouldPost) {
+                this.reportCameraOpen(s, { sensingState: 'idle' });
+                return null;
+            }
+            let response;
+            try {
+                response = await s.deps.client.analyze({
+                    jpeg,
+                    captureMode: s.faceDetected ? 'face_triggered' : 'periodic',
+                });
+            }
+            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 });
+            return response;
+        }
+        finally {
+            this.admissionGate.release(ticket);
+        }
+    }
+    /**
+     * Convert a camera frame to JPEG bytes for the POST.
+     *
+     * RTSP frames arrive as raw RGB24 Buffers, so we encode them with `sharp`
+     * when available (the standard sensing dep). If `sharp` is missing AND the
+     * frame is already JPEG (some providers emit JPEG directly), we ship it
+     * as-is; raw-RGB-without-sharp is rejected loudly so it never silently POSTs
+     * an un-decodable frame.
+     *
+     * Dimensions are needed to decode raw RGB24. Resolution order: the camera's
+     * own getResolution() (passed in by the caller — works for multi-channel
+     * feeds with no top-level camera.width/height), then the manager's configured
+     * width/height, then EdgeImageData's own dims.
+     */
+    async toJpeg(frame, camWidth, camHeight) {
+        const buffer = Buffer.isBuffer(frame) ? frame : Buffer.from(frame.data.buffer);
+        // Already JPEG? (SOI marker 0xFFD8) — ship as-is.
+        if (buffer.length >= 2 && buffer[0] === 0xff && buffer[1] === 0xd8) {
+            return buffer;
+        }
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const sharp = require('sharp');
+            const width = camWidth ?? this.width ?? (Buffer.isBuffer(frame) ? undefined : frame.width);
+            const height = camHeight ?? this.height ?? (Buffer.isBuffer(frame) ? undefined : frame.height);
+            if (width && height) {
+                return await sharp(buffer, { raw: { width, height, channels: 3 } })
+                    .jpeg({ quality: this.jpegQuality })
+                    .toBuffer();
+            }
+            // Unknown dimensions — let sharp sniff the format.
+            return await sharp(buffer).jpeg({ quality: this.jpegQuality }).toBuffer();
+        }
+        catch (err) {
+            throw new Error(`CloudSensingManager: cannot encode raw frame to JPEG (install "sharp" or ` +
+                `have the camera emit JPEG): ${err instanceof Error ? err.message : err}`);
+        }
+    }
+}
+exports.CloudSensingManager = CloudSensingManager;
+/**
+ * Read a loop's cloud-escalation counters defensively. The cloud client does not
+ * implement `getEscalationStats` at all (it has nothing to escalate to), and a
+ * test double may not either, so an absent method reads as "no escalation" —
+ * never as an error on the health path.
+ */
+function escalationStatsFor(s) {
+    try {
+        const stats = s.deps.client.getEscalationStats?.();
+        if (stats && typeof stats.escalated === 'number') {
+            return { enabled: stats.enabled === true, escalated: stats.escalated };
+        }
+    }
+    catch {
+        // health must never throw
+    }
+    return { enabled: false, escalated: 0 };
+}
+/** Read a camera's resolution defensively (providers may not implement it). */
+function safeGetResolution(camera) {
+    try {
+        const res = camera.getResolution?.();
+        if (res && res.width > 0 && res.height > 0) {
+            return res;
+        }
+    }
+    catch {
+        // ignore — fall back to configured/EdgeImageData dims
+    }
+    return undefined;
+}
+/**
+ * Build the per-feed capture loops from an EdgeAgentConfig — the bridge between
+ * config (`cameras: [...]` multi-channel, or single `camera`) and the manager.
+ *
+ * - Multi-channel: one loop per `cameras[]` entry, each with its own token +
+ *   its own RTSP provider.
+ * - Single-camera (back-compat): one loop from the top-level `camera`/token.
+ *
+ * `rtspProviderFactory` / `clientFactory` are injectable for tests; defaults
+ * use the neutral RTSP package + AudienceAnalyzeClient.
+ */
+function buildSensingLoops(config, deps) {
+    const feeds = resolveFeeds(config);
+    if (feeds.length === 0) {
+        throw new Error('buildSensingLoops: no camera feeds configured (set `cameras: [...]` or `camera.rtspUrl`)');
+    }
+    const rtspFactory = deps?.rtspProviderFactory ??
+        ((feed) => {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { RTSPCameraProvider } = require('@trillboards/edge-platform-rtsp');
+            return new RTSPCameraProvider({
+                rtspUrl: feed.rtspUrl,
+                width: feed.width,
+                height: feed.height,
+                fps: feed.fps,
+                transport: feed.transport,
+                ffmpegPath: feed.ffmpegPath,
+                // Per-tile crop in the SAME pass that pulls the RTSP — used for the solo
+                // path (a single tile, or a group with no designated source feed). When
+                // a source feed IS present the shared-pull path below handles the carve
+                // and never sets feed.crop on the grabber.
+                crop: feed.crop,
+                // Encode to JPEG in ffmpeg so the POST needs no image library (no sharp).
+                outputFormat: feed.outputFormat ?? 'jpeg',
+                jpegQuality: feed.jpegQuality,
+                ...(deps?.streamUrlResolver
+                    ? {
+                        streamUrlResolver: (currentUrl, error) => deps.streamUrlResolver(feed, currentUrl, error),
+                    }
+                    : {}),
+                ...(0, legacyRecorderProfile_1.legacyRecorderRtspOptions)(feed.sourceType),
+            });
+        });
+    const clientFactory = deps?.clientFactory ??
+        ((feed) => new AudienceAnalyzeClient_1.AudienceAnalyzeClient({
+            apiBaseUrl: config.apiBaseUrl,
+            deviceToken: feed.deviceToken,
+            screenId: feed.screenId,
+            imageWidth: feed.width,
+            imageHeight: feed.height,
+        }, deps?.httpPoster));
+    const loop = (feed, camera) => ({
+        name: feed.name,
+        camera,
+        client: clientFactory(feed),
+    });
+    // Group feeds that share ONE physical RTSP pull. A feed opts into sharing only
+    // by `sourceFeedId` (a tile → its mosaic source) or by being that source
+    // (`id`). Mosaic-aware camera construction is shared with local sensing — see
+    // buildTiledCameras — so the carve/share behavior can NEVER diverge between the
+    // cloud and local run modes.
+    return buildTiledCameras(feeds, rtspFactory, {
+        sharedFrameMaxAgeMs: deps?.sharedFrameMaxAgeMs,
+        sharedSources: deps?.sharedSources,
+    }).map(({ feed, camera }) => loop(feed, camera));
+}
+/**
+ * Build one CameraProvider per feed, collapsing mosaic tiles that share a source
+ * onto a SINGLE shared RTSP pull. This is the ONE implementation of mosaic
+ * tiling, used by BOTH cloud-sense (buildSensingLoops) and local-sense
+ * (buildLocalSensingLoops) — no split-brain between run modes. Returns feed↔camera
+ * pairs so each caller attaches its own sensing client.
+ *
+ * Grouping: a feed opts into sharing a pull only via `sourceFeedId` (a tile → its
+ * mosaic source) or by being that source (`id`); a feed with neither is solo
+ * (keyed uniquely) and gets exactly the historical one-provider-per-feed path.
+ *
+ * `rtspFactory` builds the underlying RTSP provider and MUST honor `feed.crop`
+ * (used by the per-tile-pull fallback when no source feed is configured).
+ */
+function buildTiledCameras(feeds, rtspFactory, opts) {
+    const groups = new Map();
+    feeds.forEach((feed, i) => {
+        const key = feed.sourceFeedId ?? feed.id ?? `__solo_${i}`;
+        const arr = groups.get(key);
+        if (arr)
+            arr.push(feed);
+        else
+            groups.set(key, [feed]);
+    });
+    const out = [];
+    for (const [key, members] of groups) {
+        // Back-compat fast path: a lone feed with no crop → exactly today's provider.
+        if (members.length === 1 && !members[0].crop) {
+            out.push({ feed: members[0], camera: rtspFactory(members[0]) });
+            continue;
+        }
+        // The designated source feed (its `id` == the group key) carries the full
+        // mosaic rtspUrl + native resolution, so we can pull it ONCE and crop each
+        // tile from that single frame.
+        const source = members.find((f) => f.id === key);
+        if (source) {
+            // ONE pull per mosaic source, shared across consumers via opts.sharedSources
+            // (the VLM rail + the ONNX zoo rail attach to the same SharedFrameSource).
+            // The grabber ALWAYS pulls JPEG (crop:undefined, native res) so the per-tile
+            // ffmpeg carve (`-i pipe:0`) can decode it regardless of the per-tile output
+            // format — the pixel space the tile crops are relative to.
+            let shared = opts?.sharedSources?.get(key);
+            if (!shared) {
+                const grabber = rtspFactory({ ...source, crop: undefined, outputFormat: 'jpeg' });
+                shared = new MosaicSource_1.SharedFrameSource(grabber, { maxAgeMs: opts?.sharedFrameMaxAgeMs });
+                opts?.sharedSources?.set(key, shared);
+            }
+            const sourceWidth = source.width;
+            const sourceHeight = source.height;
+            for (const m of members) {
+                const cropped = !!m.crop;
+                out.push({
+                    feed: m,
+                    camera: new MosaicSource_1.CropViewProvider(shared, {
+                        crop: m.crop,
+                        // A cropped tile defaults to its crop's NATURAL size (a 1:1 carve) —
+                        // never the full mosaic res, which would upscale + distort the tile.
+                        // A full-frame member (no crop) defaults to the source's own res.
+                        width: m.width ?? (cropped ? m.crop.w : sourceWidth) ?? 640,
+                        height: m.height ?? (cropped ? m.crop.h : sourceHeight) ?? 480,
+                        // Used only for the full-frame fast-path (skip re-encode when a
+                        // no-crop JPEG view already matches the source res).
+                        sourceWidth,
+                        sourceHeight,
+                        fps: m.fps,
+                        ffmpegPath: m.ffmpegPath,
+                        jpegQuality: m.jpegQuality,
+                        outputFormat: opts?.cropOutputFormat,
+                    }),
+                });
+            }
+            continue;
+        }
+        // Tiles reference a source that wasn't configured as its own feed. Each tile
+        // already carries the (inherited or explicit) rtspUrl, so fall back to a
+        // per-tile pull that crops in one ffmpeg pass — correct output, just one RTSP
+        // session per tile. Warn so the operator can add the source feed to collapse
+        // them onto a single pull.
+        if (members.length > 1) {
+            // eslint-disable-next-line no-console
+            console.warn(`cloud-sense: ${members.length} feeds share sourceFeedId="${key}" but no source feed ` +
+                `(a feed with id="${key}") is configured — each tile will pull the RTSP independently. ` +
+                'Add the mosaic source feed to pull it once.');
+        }
+        for (const m of members) {
+            out.push({ feed: m, camera: rtspFactory(m) });
+        }
+    }
+    return out;
+}
+/**
+ * Flatten an EdgeAgentConfig into the list of feeds to run. Multi-channel
+ * `cameras[]` wins; otherwise the single `camera` (+ top-level token) becomes
+ * a one-element list (back-compat). Feeds without both a token and rtspUrl are
+ * skipped (the single-camera fallback needs both for cloud sensing).
+ */
+function resolveFeeds(config) {
+    // Cloud-sense always ships JPEG (ffmpeg encodes it → no image library).
+    const jpegQuality = config.cloudSensing?.jpegQuality;
+    const inheritedFfmpegPath = (0, runtimePaths_1.resolveFfmpegBinaryPath)(config.camera?.ffmpegPath);
+    if (Array.isArray(config.cameras) && config.cameras.length > 0) {
+        // Mosaic tiles inherit their rtspUrl from the source feed (matched by id).
+        // Defensive: resolveConfig already does this, but resolveFeeds may run on a
+        // raw config, so resolve inheritance here too.
+        const idToRtspUrl = new Map();
+        for (const f of config.cameras) {
+            if (f && f.id && f.rtspUrl)
+                idToRtspUrl.set(f.id, f.rtspUrl);
+        }
+        return config.cameras
+            .map((feed, i) => ({
+            feed,
+            i,
+            rtspUrl: feed && feed.rtspUrl
+                ? feed.rtspUrl
+                : feed && feed.sourceFeedId
+                    ? idToRtspUrl.get(feed.sourceFeedId) || ''
+                    : '',
+        }))
+            // Skip creds-stay-on-prem placeholders (no rtspUrl, no resolvable source)
+            // rather than hand the RTSP provider an empty URL. Warn so the operator
+            // knows which feeds are idle.
+            .filter(({ feed, i, rtspUrl }) => {
+            if (rtspUrl)
+                return true;
+            // eslint-disable-next-line no-console
+            console.warn(`cloud-sense: camera "${(feed && feed.name) || `camera-${i + 1}`}" has no rtspUrl — skipping. ` +
+                'Add its rtspUrl to the config (credentials stay on this machine), then restart.');
+            return false;
+        })
+            .map(({ feed, i, rtspUrl }) => ({
+            name: feed.name || `camera-${i + 1}`,
+            id: feed.id,
+            screenId: feed.screenId,
+            deviceToken: feed.deviceToken,
+            rtspUrl,
+            sourceType: feed.sourceType,
+            channelKey: feed.channelKey,
+            recorder: feed.recorder,
+            width: feed.width,
+            height: feed.height,
+            fps: feed.fps,
+            transport: feed.transport,
+            ffmpegPath: (0, runtimePaths_1.resolveFfmpegBinaryPath)(feed.ffmpegPath, inheritedFfmpegPath),
+            sourceFeedId: feed.sourceFeedId,
+            crop: feed.tile,
+            outputFormat: 'jpeg',
+            jpegQuality,
+        }));
+    }
+    if (config.camera?.rtspUrl && config.deviceToken) {
+        return [
+            {
+                name: config.screenId || 'camera-1',
+                screenId: config.screenId,
+                deviceToken: config.deviceToken,
+                rtspUrl: config.camera.rtspUrl,
+                width: config.camera.width,
+                height: config.camera.height,
+                fps: config.camera.fps,
+                transport: config.camera.transport,
+                ffmpegPath: inheritedFfmpegPath,
+                outputFormat: 'jpeg',
+                jpegQuality,
+            },
+        ];
+    }
+    return [];
+}
+//# sourceMappingURL=CloudSensingManager.js.map