@trillboards/edge-sdk 0.2.4 → 0.2.6

package/dist/connectorCadence.d.ts

@@ -0,0 +1,135 @@
+/**
+ * connectorCadence — how often THIS connector looks at a scene where nothing
+ * is moving.
+ *
+ * ── Why this is not one constant ────────────────────────────────────────────
+ *
+ * `DEFAULT_PERIODIC_MS` is 300 s. That number was chosen for the DOOH audience
+ * product — a screen sampling the people in front of it, where five-minute
+ * granularity is fine because the question is "who saw this ad".
+ *
+ * The Sense-Anything / SOP product asks a different question, and it is the one
+ * the legal argument turns on: HOW LONG has this hazard been there. Courts have
+ * found no constructive notice at 111 seconds and at four minutes, and have let
+ * the question reach a jury at fifteen-plus. A spill that a PERSON creates is a
+ * motion event and the cascade catches it immediately. A spill that nobody
+ * creates — a leaking cooler, condensation, a slow seep, product that settled
+ * out of a bag — never moves, so the ONLY thing that can put a timestamp on it
+ * is the periodic heartbeat. Whatever that interval is, IT IS the resolution of
+ * the persistence timeline: the dwell time is bracketed by the last look that
+ * showed clean floor and the first that showed the hazard.
+ *
+ * At 300 s that bracket is five minutes wide, which cannot place a hazard on
+ * either side of a 111-second line. So the cadence has to come down — but not
+ * globally, because every analysis is spent from ONE budget.
+ *
+ * ── Why it lives HERE and not on the server ─────────────────────────────────
+ *
+ * Both inputs are facts about this machine, and the server has neither.
+ * `mergeConfigFile` folds a finalize batch into whatever feeds the config
+ * already holds, so the API only ever sees the cameras added in the CURRENT
+ * setup session: sizing there would send a 1-feed cadence to a connector that
+ * ends up running 21 of them, which is ~2,520 still-scene analyses/hour against
+ * a budget of 493. The post-merge feed count only exists on this side.
+ *
+ * ── The budget (measured 2026-08-12, real frames, real code paths) ──────────
+ *
+ *   ANALYZE   `litert-lm serve` is a single-conversation server and
+ *             CloudSensingManager gives local sensing exactly ONE admission
+ *             slot. Median 7.30 s/frame over 8 real CCTV frames (an empty
+ *             convenience store and a kitchen with people) through the actual
+ *             connector path — LiteRtVlmProvider against Gemma 4 E2B on the
+ *             `,gpu` delegate, with the operator/SOP schema and prompt
+ *             localInferenceSchema builds. One slot at 7.30 s is a hard ceiling
+ *             of 493 analyses/hour for the WHOLE connector, however many
+ *             cameras it runs.
+ *             (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,
+ *             independent reason the two products should not share a cadence.)
+ *
+ *   LOOKING   is free and is not the constraint: 3.6 ms median / 7.1 ms p95 to
+ *             pull a frame down to ~178x100 grey and run the motion detector.
+ *             Sixteen feeds looking every 30 s is 0.19% of one core.
+ *
+ *   FLOOR     on a still scene the motion gate contributes exactly ZERO
+ *             analyses — verified across byte-identical frames and gaussian
+ *             sensor noise to sigma=12, at the 30 s look cadence, for
+ *             heartbeats from 300 s down to 60 s. So a still feed's cost is
+ *             precisely 3600/heartbeat analyses per hour and nothing else.
+ *             (Only true with the contrast-history seeding fix in
+ *             SceneChangeDetector.ts; before it a still scene spent ~53
+ *             inferences per camera per start on phantom motion.)
+ *
+ * ── The derivation ──────────────────────────────────────────────────────────
+ *
+ *   N feeds x (3600 / H) analyses/hour  <=  SHARE x (3600 / ANALYZE)
+ *                                    H  >=  N x ANALYZE / SHARE
+ *
+ * SHARE is the one judgement here and it is stated rather than hidden: the
+ * still-scene floor may consume at most HALF the slot, leaving the other half
+ * for motion-triggered analyses — the alerts the product actually exists to
+ * fire. A floor that ate the whole budget would starve them, and the connector
+ * would degrade into reporting empty aisles on time while missing the incident.
+ *
+ * Two clamps, both from values the system already declares:
+ *   - never faster than the LOOK interval (`faceTriggeredIntervalMs`, 30 s):
+ *     you cannot analyze more often than you look.
+ *   - never slower than the DOOH default (300 s): this can only make a
+ *     connector sample MORE often than it does today, never less.
+ *
+ * Result, at the measured 7.30 s: 1-2 feeds 30 s, 4 feeds 59 s, 8 feeds 117 s,
+ * 16 feeds 234 s, 21+ feeds pinned at 300 s. A deployment of seven or fewer
+ * feeds per host resolves the 111-second threshold; past that the operator
+ * needs a second connector host, and `getSensingHealth()` already reports the
+ * honest effective interval so that shows up rather than hiding.
+ *
+ * ── Why not the profile's own capture_interval_ms ───────────────────────────
+ *
+ * `sensing_profiles.capture_interval_ms` exists and is per-screen, but across
+ * the 147 active `custom_intent` profiles it holds 5-30 s. Those are the
+ * ANDROID tablet's capture rate, where a frame costs a BlazeFace pass, not a
+ * VLM generation. Feeding 5 s to a connector whose ceiling is 493 analyses/hour
+ * would demand 11,520 and oversubscribe the single slot ~23x. The profile says
+ * what the operator wants; this says what the machine can deliver.
+ */
+/**
+ * Measured median seconds per on-device analysis, in ms. See the header for the
+ * measurement. Re-measure and update this when the model tier, the delegate, or
+ * the SOP schema changes — it is the only free variable here.
+ */
+export declare const MEASURED_LOCAL_ANALYZE_MS = 7300;
+/**
+ * Share of the single admission slot the STILL-scene heartbeat floor may take.
+ * The rest is held for motion-triggered analyses.
+ */
+export declare const STILL_FLOOR_SLOT_SHARE = 0.5;
+/**
+ * The connector's look cadence (`faceTriggeredIntervalMs` default, which is
+ * also the motion gate's scan interval). A heartbeat can never be finer.
+ */
+export declare const LOOK_INTERVAL_MS = 30000;
+/** The DOOH audience default (`DEFAULT_PERIODIC_MS`). The slow end of the clamp. */
+export declare const DOOH_PERIODIC_MS = 300000;
+/**
+ * Sustainable still-scene heartbeat for a connector running `feedCount` feeds
+ * against ONE local inference slot.
+ *
+ * `feedCount` MUST be the connector's TOTAL feed count after any merge, not the
+ * feeds added by one setup session — see the header.
+ *
+ * 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;
+/**
+ * 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
+ * assertable in tests and readable in a log line rather than being folded away
+ * inside one expression.
+ */
+export declare function stillSceneLoad(feedCount: unknown, periodicIntervalMs: unknown): {
+    analysesPerHour: number;
+    slotShare: number;
+};
+//# sourceMappingURL=connectorCadence.d.ts.map

package/dist/connectorCadence.d.ts.map

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

package/dist/connectorCadence.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * connectorCadence — how often THIS connector looks at a scene where nothing
+ * is moving.
+ *
+ * ── Why this is not one constant ────────────────────────────────────────────
+ *
+ * `DEFAULT_PERIODIC_MS` is 300 s. That number was chosen for the DOOH audience
+ * product — a screen sampling the people in front of it, where five-minute
+ * granularity is fine because the question is "who saw this ad".
+ *
+ * The Sense-Anything / SOP product asks a different question, and it is the one
+ * the legal argument turns on: HOW LONG has this hazard been there. Courts have
+ * found no constructive notice at 111 seconds and at four minutes, and have let
+ * the question reach a jury at fifteen-plus. A spill that a PERSON creates is a
+ * motion event and the cascade catches it immediately. A spill that nobody
+ * creates — a leaking cooler, condensation, a slow seep, product that settled
+ * out of a bag — never moves, so the ONLY thing that can put a timestamp on it
+ * is the periodic heartbeat. Whatever that interval is, IT IS the resolution of
+ * the persistence timeline: the dwell time is bracketed by the last look that
+ * showed clean floor and the first that showed the hazard.
+ *
+ * At 300 s that bracket is five minutes wide, which cannot place a hazard on
+ * either side of a 111-second line. So the cadence has to come down — but not
+ * globally, because every analysis is spent from ONE budget.
+ *
+ * ── Why it lives HERE and not on the server ─────────────────────────────────
+ *
+ * Both inputs are facts about this machine, and the server has neither.
+ * `mergeConfigFile` folds a finalize batch into whatever feeds the config
+ * already holds, so the API only ever sees the cameras added in the CURRENT
+ * setup session: sizing there would send a 1-feed cadence to a connector that
+ * ends up running 21 of them, which is ~2,520 still-scene analyses/hour against
+ * a budget of 493. The post-merge feed count only exists on this side.
+ *
+ * ── The budget (measured 2026-08-12, real frames, real code paths) ──────────
+ *
+ *   ANALYZE   `litert-lm serve` is a single-conversation server and
+ *             CloudSensingManager gives local sensing exactly ONE admission
+ *             slot. Median 7.30 s/frame over 8 real CCTV frames (an empty
+ *             convenience store and a kitchen with people) through the actual
+ *             connector path — LiteRtVlmProvider against Gemma 4 E2B on the
+ *             `,gpu` delegate, with the operator/SOP schema and prompt
+ *             localInferenceSchema builds. One slot at 7.30 s is a hard ceiling
+ *             of 493 analyses/hour for the WHOLE connector, however many
+ *             cameras it runs.
+ *             (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,
+ *             independent reason the two products should not share a cadence.)
+ *
+ *   LOOKING   is free and is not the constraint: 3.6 ms median / 7.1 ms p95 to
+ *             pull a frame down to ~178x100 grey and run the motion detector.
+ *             Sixteen feeds looking every 30 s is 0.19% of one core.
+ *
+ *   FLOOR     on a still scene the motion gate contributes exactly ZERO
+ *             analyses — verified across byte-identical frames and gaussian
+ *             sensor noise to sigma=12, at the 30 s look cadence, for
+ *             heartbeats from 300 s down to 60 s. So a still feed's cost is
+ *             precisely 3600/heartbeat analyses per hour and nothing else.
+ *             (Only true with the contrast-history seeding fix in
+ *             SceneChangeDetector.ts; before it a still scene spent ~53
+ *             inferences per camera per start on phantom motion.)
+ *
+ * ── The derivation ──────────────────────────────────────────────────────────
+ *
+ *   N feeds x (3600 / H) analyses/hour  <=  SHARE x (3600 / ANALYZE)
+ *                                    H  >=  N x ANALYZE / SHARE
+ *
+ * SHARE is the one judgement here and it is stated rather than hidden: the
+ * still-scene floor may consume at most HALF the slot, leaving the other half
+ * for motion-triggered analyses — the alerts the product actually exists to
+ * fire. A floor that ate the whole budget would starve them, and the connector
+ * would degrade into reporting empty aisles on time while missing the incident.
+ *
+ * Two clamps, both from values the system already declares:
+ *   - never faster than the LOOK interval (`faceTriggeredIntervalMs`, 30 s):
+ *     you cannot analyze more often than you look.
+ *   - never slower than the DOOH default (300 s): this can only make a
+ *     connector sample MORE often than it does today, never less.
+ *
+ * Result, at the measured 7.30 s: 1-2 feeds 30 s, 4 feeds 59 s, 8 feeds 117 s,
+ * 16 feeds 234 s, 21+ feeds pinned at 300 s. A deployment of seven or fewer
+ * feeds per host resolves the 111-second threshold; past that the operator
+ * needs a second connector host, and `getSensingHealth()` already reports the
+ * honest effective interval so that shows up rather than hiding.
+ *
+ * ── Why not the profile's own capture_interval_ms ───────────────────────────
+ *
+ * `sensing_profiles.capture_interval_ms` exists and is per-screen, but across
+ * the 147 active `custom_intent` profiles it holds 5-30 s. Those are the
+ * ANDROID tablet's capture rate, where a frame costs a BlazeFace pass, not a
+ * VLM generation. Feeding 5 s to a connector whose ceiling is 493 analyses/hour
+ * would demand 11,520 and oversubscribe the single slot ~23x. The profile says
+ * what the operator wants; this says what the machine can deliver.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOOH_PERIODIC_MS = exports.LOOK_INTERVAL_MS = exports.STILL_FLOOR_SLOT_SHARE = exports.MEASURED_LOCAL_ANALYZE_MS = void 0;
+exports.periodicIntervalMsForFeedCount = periodicIntervalMsForFeedCount;
+exports.stillSceneLoad = stillSceneLoad;
+/**
+ * Measured median seconds per on-device analysis, in ms. See the header for the
+ * measurement. Re-measure and update this when the model tier, the delegate, or
+ * the SOP schema changes — it is the only free variable here.
+ */
+exports.MEASURED_LOCAL_ANALYZE_MS = 7300;
+/**
+ * Share of the single admission slot the STILL-scene heartbeat floor may take.
+ * The rest is held for motion-triggered analyses.
+ */
+exports.STILL_FLOOR_SLOT_SHARE = 0.5;
+/**
+ * The connector's look cadence (`faceTriggeredIntervalMs` default, which is
+ * also the motion gate's scan interval). A heartbeat can never be finer.
+ */
+exports.LOOK_INTERVAL_MS = 30000;
+/** The DOOH audience default (`DEFAULT_PERIODIC_MS`). The slow end of the clamp. */
+exports.DOOH_PERIODIC_MS = 300000;
+/**
+ * Sustainable still-scene heartbeat for a connector running `feedCount` feeds
+ * against ONE local inference slot.
+ *
+ * `feedCount` MUST be the connector's TOTAL feed count after any merge, not the
+ * feeds added by one setup session — see the header.
+ *
+ * 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.
+ */
+function periodicIntervalMsForFeedCount(feedCount) {
+    const n = Number(feedCount);
+    if (!Number.isFinite(n) || n < 1)
+        return null;
+    const required = Math.ceil((Math.trunc(n) * exports.MEASURED_LOCAL_ANALYZE_MS) / exports.STILL_FLOOR_SLOT_SHARE);
+    return Math.min(exports.DOOH_PERIODIC_MS, Math.max(exports.LOOK_INTERVAL_MS, required));
+}
+/**
+ * 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
+ * assertable in tests and readable in a log line rather than being folded away
+ * inside one expression.
+ */
+function stillSceneLoad(feedCount, periodicIntervalMs) {
+    const n = Math.max(0, Math.trunc(Number(feedCount) || 0));
+    const h = Number(periodicIntervalMs);
+    if (!Number.isFinite(h) || h <= 0)
+        return { analysesPerHour: 0, slotShare: 0 };
+    const analysesPerHour = (n * 3600000) / h;
+    const ceilingPerHour = 3600000 / exports.MEASURED_LOCAL_ANALYZE_MS;
+    return { analysesPerHour, slotShare: analysesPerHour / ceilingPerHour };
+}
+//# sourceMappingURL=connectorCadence.js.map

package/dist/connectorCadence.js.map

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

package/dist/dataDir.d.ts

@@ -0,0 +1,33 @@
+/**
+ * On-disk roots for the agent, in their OWN module.
+ *
+ * Deliberately not in EdgeAgent.ts: combinedSense.ts lazy-`require`s EdgeAgent so
+ * the module can be loaded and unit-tested WITHOUT the ~200 MB onnxruntime stack
+ * (see that file's header, and the cli `start` arm that keeps the
+ * cloud-sense/pair connector bundle free of it). A static
+ * `import { tileDataDir } from './EdgeAgent'` would have made every consumer of
+ * combinedSense pull the ONNX stack eagerly and undone that.
+ */
+/**
+ * The agent's data root. ONE definition, because per-screen isolation depends on
+ * it: a mosaic fans out N EdgeAgents that each open `signal_buffer.db`, a
+ * SubsystemHealthRegistry and a persistenceDir beneath this path, so a second
+ * copy of the default that drifted would silently re-collide the tiles
+ * tileDataDir() exists to separate.
+ */
+export declare function resolveDataDir(configured?: string): string;
+/**
+ * Per-tile data directory for a mosaic fan-out.
+ *
+ * Each tile is its own EdgeAgent authenticating with its OWN deviceToken, but the
+ * `...config` spread handed them all the same dataDir — so they opened one shared
+ * signal_buffer.db. SignalBuffer.flushBuffer() reads rows and DELETES them on
+ * success, so during an offline/reconnect window screen A's buffered signals
+ * could be emitted under screen B's token, or dropped by whichever tile flushed
+ * first. This bit even with dataDir unset, since the default is shared too.
+ *
+ * Keyed on screenId — stable across restarts, which is what makes a persisted
+ * buffer worth having. The index is only a fallback for a feed with no screenId.
+ */
+export declare function tileDataDir(configured: string | undefined, screenId: string | undefined, index: number): string;
+//# sourceMappingURL=dataDir.d.ts.map

package/dist/dataDir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataDir.d.ts","sourceRoot":"","sources":["../src/dataDir.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAK1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,GACZ,MAAM,CAGR"}

package/dist/dataDir.js

@@ -0,0 +1,76 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDataDir = resolveDataDir;
+exports.tileDataDir = tileDataDir;
+const path = __importStar(require("path"));
+/**
+ * On-disk roots for the agent, in their OWN module.
+ *
+ * Deliberately not in EdgeAgent.ts: combinedSense.ts lazy-`require`s EdgeAgent so
+ * the module can be loaded and unit-tested WITHOUT the ~200 MB onnxruntime stack
+ * (see that file's header, and the cli `start` arm that keeps the
+ * cloud-sense/pair connector bundle free of it). A static
+ * `import { tileDataDir } from './EdgeAgent'` would have made every consumer of
+ * combinedSense pull the ONNX stack eagerly and undone that.
+ */
+/**
+ * The agent's data root. ONE definition, because per-screen isolation depends on
+ * it: a mosaic fans out N EdgeAgents that each open `signal_buffer.db`, a
+ * SubsystemHealthRegistry and a persistenceDir beneath this path, so a second
+ * copy of the default that drifted would silently re-collide the tiles
+ * tileDataDir() exists to separate.
+ */
+function resolveDataDir(configured) {
+    return configured || path.join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.trillboards');
+}
+/**
+ * Per-tile data directory for a mosaic fan-out.
+ *
+ * Each tile is its own EdgeAgent authenticating with its OWN deviceToken, but the
+ * `...config` spread handed them all the same dataDir — so they opened one shared
+ * signal_buffer.db. SignalBuffer.flushBuffer() reads rows and DELETES them on
+ * success, so during an offline/reconnect window screen A's buffered signals
+ * could be emitted under screen B's token, or dropped by whichever tile flushed
+ * first. This bit even with dataDir unset, since the default is shared too.
+ *
+ * Keyed on screenId — stable across restarts, which is what makes a persisted
+ * buffer worth having. The index is only a fallback for a feed with no screenId.
+ */
+function tileDataDir(configured, screenId, index) {
+    const key = (screenId && String(screenId).replace(/[^A-Za-z0-9._-]/g, '_')) || `tile-${index}`;
+    return path.join(resolveDataDir(configured), 'tiles', key);
+}
+//# sourceMappingURL=dataDir.js.map

package/dist/dataDir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataDir.js","sourceRoot":"","sources":["../src/dataDir.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoBA,wCAKC;AAeD,kCAOC;AA/CD,2CAA6B;AAE7B;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,SAAgB,cAAc,CAAC,UAAmB;IAChD,OAAO,UAAU,IAAI,IAAI,CAAC,IAAI,CAC5B,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,MAAM,EACrD,cAAc,CACf,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,WAAW,CACzB,UAA8B,EAC9B,QAA4B,EAC5B,KAAa;IAEb,MAAM,GAAG,GAAG,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC,IAAI,QAAQ,KAAK,EAAE,CAAC;IAC/F,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;AAC7D,CAAC"}

package/dist/deployedCadence.d.ts

@@ -0,0 +1,167 @@
+/**
+ * deployedCadence — reconcile the cadence the OPERATOR deployed with the one
+ * this machine can actually afford to run.
+ *
+ * ── The bug this exists to close ────────────────────────────────────────────
+ *
+ * `sensing_profiles.capture_interval_ms` is per-screen, is set from the portal,
+ * and IS served to the connector: `GET /v2/earner/cameras/sensing-profile`
+ * returns it on a 5-minute TTL. The connector then throws it away. It is parsed
+ * in `SensingProfileClient.fetchProfile()` and never read again — the local
+ * refresh consumes `profileName`, `profileType` and `fields` and drops
+ * `captureIntervalMs` on the floor, and the CLOUD path does not even construct a
+ * profile client. So a venue that sets "look every 10 seconds" in the portal
+ * gets 300 000 ms forever, and nothing anywhere says so.
+ *
+ * Worse, the ONLY other way in is one-shot: `mergeConfigFile` honours a cadence
+ * at SETUP time, writes it to `trillboards.config.json`, and
+ * `CloudSensingManager` freezes it at construction. Changing a deployed camera's
+ * cadence today means editing a file on the venue's machine and restarting the
+ * process.
+ *
+ * ── Why it is not simply "use what the profile says" ───────────────────────
+ *
+ * Because the two run modes are metered by completely different things, and
+ * neither of them is time.
+ *
+ * LOCAL is metered by a MACHINE. `litert-lm serve` is a single-conversation
+ * server with exactly one admission slot at a measured 7.30 s/frame, so the
+ * whole connector has a hard ceiling of 493 analyses/hour however many cameras
+ * it runs. That ceiling is what `connectorCadence.periodicIntervalMsForFeedCount`
+ * already computes, and it is why the profile's own 5-30 s values were rejected
+ * as a cadence source when that module was written: they are the ANDROID
+ * tablet's capture rate, where a frame costs a BlazeFace pass rather than a VLM
+ * generation, and feeding 5 s to a connector would demand 11 520 analyses/hour
+ * against a budget of 493.
+ *
+ * CLOUD is metered by MONEY, and this is the number nobody had:
+ *
+ *   Measured on production 2026-08-12 — 255 812 image-bearing cloud VLM calls
+ *   over 7 days, `gemini-3.1-flash-lite` via `audienceVisionService.analyzeFrame`
+ *   — the mean cost of one analyzed frame is $0.007008 (p50 $0.006838, p90
+ *   $0.008481; $1 790.92 of spend over the window). Per camera per 30-day month:
+ *
+ *       cadence     frames/mo    $/camera/mo
+ *       300 s        8 640          60.55      <- today's silent default
+ *       120 s       21 600         151.37
+ *        60 s       43 200         302.75
+ *        30 s       86 400         605.49
+ *
+ *   Against a $100-500 subscription. So "sensing within 30 seconds" is not a
+ *   config default on the cloud path — it is a $605/camera/month line item, and
+ *   a 16-camera store would be $9 688/month of COGS. The same 30 s cadence on
+ *   the LOCAL path costs nothing per frame; it costs one machine.
+ *
+ * The honest resolution is therefore not to pick a number. It is to let the
+ * operator's request through, clamp it at the floor its OWN mode implies, and
+ * make the clamp legible — `resolve()` returns the reason and the projected
+ * bill, so `getSensingHealth()` can say "you asked for 30 s; running 303 s;
+ * cloud budget $60/camera/month" instead of silently sampling every 5 minutes.
+ *
+ * ── The default is deliberately a no-op ────────────────────────────────────
+ *
+ * `DEFAULT_CLOUD_MONTHLY_BUDGET_USD_PER_CAMERA` is 60, which at the measured
+ * price is a 302 746 ms floor — within 1% of the 300 000 ms every cloud
+ * connector already runs. Fixing the wire therefore cannot change anybody's
+ * bill: it changes who is ALLOWED to change it, and makes buying a faster
+ * cadence an explicit purchase instead of an invisible one.
+ */
+export type SensingRunModeName = 'cloud' | 'local';
+/**
+ * Mean USD per analyzed frame on the cloud VLM path. MEASURED, not listed:
+ * 255,812 successful image-bearing `vision_call_log` rows over the 7 days ending
+ * 2026-08-12. Re-measure with:
+ *
+ *   SELECT avg(cost_usd) FROM vision_call_log
+ *    WHERE called_at >= now() - interval '7 days'
+ *      AND success AND image_s3_key IS NOT NULL;
+ *
+ * and update this when the model tier or the profile schema size changes — a
+ * bigger response schema moves it (per-screen means ranged $0.0054-$0.0158 over
+ * the same window, tracking prompt size).
+ */
+export declare const MEASURED_CLOUD_USD_PER_FRAME = 0.007008;
+/**
+ * Cloud spend per camera per month the connector may commit to WITHOUT the
+ * operator raising it. 60 USD is today's actual spend at the 300 s default, so
+ * this default changes no bill; it exists so that going faster is a decision
+ * somebody makes rather than a constant somebody edits.
+ */
+export declare const DEFAULT_CLOUD_MONTHLY_BUDGET_USD_PER_CAMERA = 60;
+/** A 30-day month, in ms — the unit the budget is quoted in. */
+export declare const MONTH_MS: number;
+/**
+ * The SLOWEST cadence a deployed profile may put on a running connector.
+ *
+ * This is not a taste bound, it is a MECHANISM bound. The cadence becomes the
+ * `setTimeout` delay of every capture loop, and Node's delay is a 32-bit signed
+ * int: 2 147 483 648 ms does not wrap to "a long time", it SILENTLY becomes 1 ms
+ * and fires on the next tick. So the one input the server controls end-to-end —
+ * `sensing_profiles.capture_interval_ms`, a plain integer column with no CHECK —
+ * inverts into its exact opposite: a row that reads "look once every 25 days"
+ * turns the connector into a hot loop that pulls every camera as fast as ffmpeg
+ * can decode. Measured through the real manager: 91 RTSP grabs in 120 ms of wall
+ * clock, i.e. ~750 frames/second per feed, which on the cloud path is the whole
+ * $60/camera/month budget in about eleven seconds.
+ *
+ * Nothing upstream stops it. `resolveDeployedCadence` clamped only the FLOOR
+ * (going too fast costs money), so every value above the floor was passed
+ * through verbatim — including `Number.MAX_SAFE_INTEGER`. A units mistake (s vs
+ * ms, ms vs ns), a bad migration, or a fat-fingered portal field is enough.
+ *
+ * 24 h is the ceiling because a sensing cadence slower than a day is not a
+ * cadence anybody deploys on purpose, and it is two orders of magnitude inside
+ * the overflow. It is REPORTED (`reason: 'cadence_ceiling'`) rather than
+ * silently applied, so a nonsense row shows up as a nonsense row.
+ */
+export declare const MAX_CADENCE_MS: number;
+export type CadenceReason = 
+/** No deployed cadence to honour — the caller keeps exactly what it had. */
+'no_request'
+/** The operator's request was affordable and is being run verbatim. */
+ | 'operator_request'
+/** Slowed to fit the cloud spend budget. */
+ | 'cloud_cost_budget'
+/** Slowed to fit the single local inference slot. */
+ | 'local_inference_budget'
+/** Faster than the connector ever looks — a cadence finer than a look is meaningless. */
+ | 'look_interval'
+/** SPED UP to `MAX_CADENCE_MS`: the request was slower than a capture loop can express. */
+ | 'cadence_ceiling';
+export interface DeployedCadence {
+    /** The interval to run, or null when there was nothing to honour. */
+    intervalMs: number | null;
+    /** What the deployed profile asked for, normalized. null when it asked nothing. */
+    requestedMs: number | null;
+    /** The fastest this mode may run. */
+    floorMs: number;
+    /** The slowest a capture loop can express (see MAX_CADENCE_MS). */
+    ceilingMs: number;
+    /** True when the request is NOT being run verbatim (floor OR ceiling). */
+    clamped: boolean;
+    reason: CadenceReason;
+    /** Projected cloud spend at `intervalMs`. null for local (no per-frame cost). */
+    estimatedMonthlyUsdPerCamera: number | null;
+}
+/**
+ * The fastest cloud cadence that keeps ONE camera inside `budgetUsd` per month
+ * at `usdPerFrame`.
+ */
+export declare function cloudFloorMsForBudget(budgetUsd?: number, usdPerFrame?: number): number;
+/** Projected cloud spend for one camera at `intervalMs`. */
+export declare function monthlyUsdPerCamera(intervalMs: number, usdPerFrame?: number): number;
+/**
+ * Reconcile a deployed cadence with what this mode can afford.
+ *
+ * Returns `intervalMs: null` when the profile requested nothing — the caller
+ * MUST then leave its current cadence alone, so a connector whose server says
+ * nothing behaves exactly as it does today.
+ */
+export declare function resolveDeployedCadence(input: {
+    requestedMs: unknown;
+    mode: SensingRunModeName;
+    feedCount: number;
+    monthlyBudgetUsdPerCamera?: number;
+    usdPerFrame?: number;
+}): DeployedCadence;
+//# sourceMappingURL=deployedCadence.d.ts.map

package/dist/deployedCadence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployedCadence.d.ts","sourceRoot":"","sources":["../src/deployedCadence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAQH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,OAAO,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,4BAA4B,WAAW,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,2CAA2C,KAAK,CAAC;AAE9D,gEAAgE;AAChE,eAAO,MAAM,QAAQ,QAAwB,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,cAAc,QAAmB,CAAC;AAE/C,MAAM,MAAM,aAAa;AACvB,4EAA4E;AAC1E,YAAY;AACd,uEAAuE;GACrE,kBAAkB;AACpB,4CAA4C;GAC1C,mBAAmB;AACrB,qDAAqD;GACnD,wBAAwB;AAC1B,yFAAyF;GACvF,eAAe;AACjB,2FAA2F;GACzF,iBAAiB,CAAC;AAEtB,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,mFAAmF;IACnF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;IACtB,iFAAiF;IACjF,4BAA4B,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,MAAoD,EAC/D,WAAW,GAAE,MAAqC,GACjD,MAAM,CAUR;AAED,4DAA4D;AAC5D,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,WAAW,GAAE,MAAqC,GACjD,MAAM,CAIR;AASD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,eAAe,CAsDlB"}