@trillboards/edge-sdk 0.2.222 → 0.2.225

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -9,6 +9,7 @@ const fs = require('node:fs'), os = require('node:os'), path = require('node:pat
9
9
  const { WebsiteAdmissionCaptureClient, readAdmission } = require('../WebsiteAdmissionCaptureClient.cjs');
10
10
  const { RetainedCaptureClient, RECHECK_ANCHOR_GRACE_MS } = require('../RetainedCaptureClient.cjs');
11
11
  const { DurableVlmCandidateSpool } = require('../../dist/DurableVlmCandidateSpool');
12
+ const { FrameGroupingShadow, groupingScopes } = require('../../dist/FrameGroupingShadow');
12
13
  const admissionApi = require('../../../../../trillboard-api/services/retainedWebsiteReviewAdmission');
13
14
  const timing = require('../../../../../trillboard-api/services/fein/routeReviewTiming');
14
15
  const { isHistoricalReview } = require('../../../../../trillboard-api/services/retainedCctvReviewProtocol');
@@ -48,8 +49,20 @@ function context(name, at, extra = {}) {
48
49
  delete captured.websiteReviewAdmission;
49
50
  return captured;
50
51
  }
51
- function rig(t, names = ['phone'], { freshnessMs = LIVE_BOUND_MS } = {}) {
52
+ // The website manager's grouping for an immediate rule (retained/manager.cjs: every website
53
+ // camera's rule is immediate, so followUpMs is 5000).
54
+ const GROUPING = { mode: 'shadow', separateProfileWork: true, pixelDelta: 12, minChangedPixels: 12,
55
+ quietIntervalMs: 10000, followUpMs: 5000 };
56
+ // The motion-resolution grey frame the grouper compares. A still scene repeats it exactly; a
57
+ // moving one shifts 40 bright pixels on every frame, a visible change each time (Texas camera 23).
58
+ function scene(at, moving) {
59
+ const data = new Uint8Array(32 * 24).fill(90);
60
+ if (moving) for (let i = 0; i < 40; i++) data[(i * 13 + Math.floor(at / 100)) % data.length] = 220;
61
+ return { width: 32, height: 24, data };
62
+ }
63
+ function rig(t, names = ['phone'], { freshnessMs = LIVE_BOUND_MS, grouping = false, liveLookIntervalMs, moving = [] } = {}) {
52
64
  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'website-admission-realtime-'));
65
+ const groupers = new Map();
53
66
  const state = { now: 1000, answer: true, accepted: true, receiptVersion: 1 };
54
67
  const archives = new Map(), clients = new Map(), current = new Map(), server = new Map();
55
68
  const calls = [], uploads = [];
@@ -89,6 +102,8 @@ function rig(t, names = ['phone'], { freshnessMs = LIVE_BOUND_MS } = {}) {
89
102
  cameraId: name, pairedCameraId: 'paired-' + name, intervalMs: 500, offerWindow: 16,
90
103
  maxCaptures: 1000, maxBytes: 128 * 1024 ** 2, archiveRetentionMs: 600000,
91
104
  realtimeReview: { freshnessMs, now: () => state.now }, admissionNowMs: () => state.now,
105
+ ...(grouping ? { selectionMode: 'state-change-v1', groupingPolicy: GROUPING } : {}),
106
+ ...(liveLookIntervalMs === undefined ? {} : { liveLookIntervalMs }),
92
107
  });
93
108
  archive.attachReviewQueue(spool); archives.set(name, archive); return archive;
94
109
  }
@@ -100,9 +115,17 @@ function rig(t, names = ['phone'], { freshnessMs = LIVE_BOUND_MS } = {}) {
100
115
  function capture(name, at, extra = {}) {
101
116
  state.now = at;
102
117
  const captured = context(name, at, extra); current.set(name, captured);
103
- const archive = archives.get(name);
104
- archive.retainOrderedCapture({ name, enqueuedAtMs: at, jpeg: original(), captureMode: 'periodic',
105
- reason: 'motion', signature: String(at), reviewKind: 'event', reviewContext: captured });
118
+ const archive = archives.get(name), jpeg = original();
119
+ // With grouping on, the real grouper decides from the scene, exactly as CloudSensingManager feeds it.
120
+ let groupingShadow;
121
+ if (grouping) {
122
+ if (!groupers.has(name)) groupers.set(name, new FrameGroupingShadow(GROUPING));
123
+ groupingShadow = groupers.get(name).observe(scene(at, moving.includes(name)), groupingScopes(captured),
124
+ captured, at, sha(jpeg));
125
+ }
126
+ archive.retainOrderedCapture({ name, enqueuedAtMs: at, jpeg, captureMode: 'periodic',
127
+ reason: 'motion', signature: String(at), reviewKind: 'event', reviewContext: captured,
128
+ ...(groupingShadow ? { groupingShadow } : {}) });
106
129
  return archive.previousCaptureRecord;
107
130
  }
108
131
  function pump() {
@@ -302,6 +325,107 @@ test('three website cameras rotate fairly while one producer accumulates changed
302
325
  assert.deepEqual(served.slice(turn, turn + 3).sort(), ['door', 'lot', 'paint']);
303
326
  });
304
327
 
328
+ // A still camera, decided by the real grouper: without a live-look interval it is looked at
329
+ // only when the grouper re-selects (its first view, the 5 s follow-up, then the 10 s quiet
330
+ // check), the cadence the Texas store's still cameras showed on 2026-11-09.
331
+ test('a still website camera is looked at every live-look interval, not only when the grouper re-selects', async t => {
332
+ const runs = new Map();
333
+ for (const liveLookIntervalMs of [undefined, 2000]) {
334
+ const r = rig(t, ['person'], { grouping: true, liveLookIntervalMs }); r.state.answer = false;
335
+ const looked = [];
336
+ for (let at = 1000; at <= 12000; at += 500) {
337
+ r.capture('person', at, { websiteReviewAdmission: undefined });
338
+ if (r.pump().length) { const item = await r.review(); await r.upload(); looked.push(item.enqueuedAtMs); }
339
+ }
340
+ runs.set(liveLookIntervalMs, { r, looked });
341
+ }
342
+ assert.deepEqual(runs.get(undefined).looked, [1000, 6000]);
343
+ const { r, looked } = runs.get(2000);
344
+ assert.deepEqual(looked, [1000, 3000, 5000, 6000, 8000, 10000, 12000]);
345
+ const reasons = looked.map(at => [...r.archives.get('person').records.values()].find(row => row.capturedAt === at).selectionReason);
346
+ assert.deepEqual(reasons, ['group_selected', 'live_look_interval', 'live_look_interval', 'group_selected',
347
+ 'live_look_interval', 'live_look_interval', 'live_look_interval']);
348
+ const skipped = [...r.archives.get('person').records.values()].filter(row => !looked.includes(row.capturedAt));
349
+ assert(skipped.length && skipped.every(row => row.disposition === 'archived_grouped_unchanged'),
350
+ 'Between live looks an unchanged frame stays a saved, unreviewed grouped view');
351
+ });
352
+
353
+ test('a website wait window keeps the camera\'s live look; the server still confirms only at the deadline', async t => {
354
+ const r = rig(t, ['phone'], { liveLookIntervalMs: 2000 });
355
+ const first = r.capture('phone', 1000); await r.serve(); // true: the ten-second wait starts at 1000
356
+ const looked = [], eligible = [];
357
+ for (let at = 1500; at < 11000; at += 500) {
358
+ r.capture('phone', at);
359
+ if (r.pump().length) {
360
+ const item = await r.review(), delivered = await r.upload();
361
+ looked.push(item.enqueuedAtMs); eligible.push(delivered.decision.eligible);
362
+ }
363
+ }
364
+ assert.deepEqual(looked, [3000, 5000, 7000, 9000]);
365
+ assert.deepEqual(eligible, [false, false, false, false], 'A positive inside the window confirms nothing');
366
+ const omitted = [...r.archives.get('phone').records.values()].filter(row => row.capturedAt > 1000 && !looked.includes(row.capturedAt));
367
+ assert(omitted.length && omitted.every(row => row.disposition === 'archived_wait_window'));
368
+ const due = r.capture('phone', 11000); r.pump();
369
+ const item = r.spool.take(undefined, 'review');
370
+ assert.equal(item.spoolId, due.id);
371
+ assert.equal(item.reviewPriority, 'urgent', 'The deadline endpoint keeps its reserved, urgent slot');
372
+ await r.review(item); const delivered = await r.upload();
373
+ assert.equal(delivered.decision.eligible, true);
374
+ assert.equal(delivered.decision.confirmationBasis, 'first_and_follow_up');
375
+ assert.equal(delivered.decision.state.anchorCapturedAtMs, first.capturedAt);
376
+ });
377
+
378
+ // The Texas store PC at night, 2026-11-09: five alert cameras, camera 23's drawn area changing on
379
+ // every frame and the other four still, on a box that finishes ~1.46 looks a second. Served one at
380
+ // a time here, 700 ms each on the 100 ms clock: the same throughput.
381
+ async function texasNight(t, liveLookIntervalMs) {
382
+ const names = ['c20', 'c22', 'c23', 'c24', 'c3'], LOOK_MS = 700;
383
+ const r = rig(t, names, { grouping: true, liveLookIntervalMs, moving: ['c23'] }); r.state.answer = false;
384
+ const looks = [];
385
+ let busyUntil = 0;
386
+ for (let at = 1000; at <= 61000; at += 100) {
387
+ // Each camera captures every 500 ms, 100 ms after the previous one (the manager's feed stagger).
388
+ r.capture(names[(at / 100) % names.length], at, { websiteReviewAdmission: undefined });
389
+ r.pump();
390
+ if (at < busyUntil) continue;
391
+ const item = r.spool.take(at, 'review');
392
+ if (!item) continue;
393
+ await r.review(item); await r.upload();
394
+ looks.push({ name: item.name, capturedAt: item.enqueuedAtMs, startedAt: at });
395
+ busyUntil = at + LOOK_MS;
396
+ }
397
+ const pct = (values, q) => { const v = [...values].sort((a, b) => a - b); return v[Math.min(v.length - 1, Math.floor(q * v.length))]; };
398
+ const cameras = {};
399
+ for (const name of names) {
400
+ const mine = looks.filter(look => look.name === name);
401
+ const gaps = mine.slice(1).map((look, i) => look.capturedAt - mine[i].capturedAt);
402
+ cameras[name] = { looks: mine.length, share: mine.length / looks.length, gapP50: pct(gaps, 0.5), gapP90: pct(gaps, 0.9),
403
+ gapMax: Math.max(...gaps), ageMax: Math.max(...mine.map(look => look.startedAt - look.capturedAt)) };
404
+ }
405
+ return { looks, cameras };
406
+ }
407
+
408
+ test('Texas shape: the still cameras starve beside the changing one without a live-look interval', async t => {
409
+ const { cameras } = await texasNight(t, undefined);
410
+ t.diagnostic(JSON.stringify(cameras));
411
+ assert(cameras.c23.share > 0.5, 'camera 23 took ' + cameras.c23.share);
412
+ for (const name of ['c20', 'c22', 'c24', 'c3']) assert(cameras[name].gapP90 >= 9500, name + ' ' + JSON.stringify(cameras[name]));
413
+ });
414
+
415
+ test('Texas shape: with the live-look interval every camera gets one look per round, none above its share', async t => {
416
+ const { looks, cameras } = await texasNight(t, 2000);
417
+ t.diagnostic(JSON.stringify(cameras));
418
+ const share = looks.length / 5;
419
+ for (const [name, camera] of Object.entries(cameras)) {
420
+ const detail = name + ' ' + JSON.stringify(camera);
421
+ assert(Math.abs(camera.looks - share) <= 1.5, 'not one look per round: ' + detail);
422
+ // Five cameras x 700 ms: a round is 3.5 s.
423
+ assert(camera.gapP50 <= 4000 && camera.gapP90 <= 4000 && camera.gapMax <= 5000, detail);
424
+ // A still camera's waiting frame is never older than the interval plus one capture.
425
+ assert(camera.ageMax <= 2500, 'stale frame served: ' + detail);
426
+ }
427
+ });
428
+
305
429
  const exemptions = {
306
430
  temporalReviewContract: { version: 1, cameraId: 'phone', field: 'phone_use', mode: 'any', minObservations: 1,
307
431
  durationMs: 0, maxGapMs: 2000, unknownPolicy: 'reset_confirmation_keep_alert_latch' },
@@ -28,6 +28,16 @@ function assertSelectedModelsPrepared(models, actorPolicy, requiresDetector) {
28
28
  // artifact identity still pass before capture; this is not a second installer.
29
29
  /** LocalDetectorClient's own per-call default, which every other detector call of a look waits. */
30
30
  const PAIRED_DETECTOR_CALL_MS = 5000;
31
+ /**
32
+ * A website alert camera's newest frame is reviewed once it is this far past both the camera's
33
+ * newest selection and the start of its newest look, changed or not
34
+ * (WebsiteAdmissionCaptureClient.liveLookDue). Half the 4 s look target: when the box is the
35
+ * bound, every camera has a fresh frame waiting before its turn comes, so the spool's
36
+ * least-recently-served rotation splits the box evenly (Texas: five cameras, ~1.46 looks/s with
37
+ * two in flight, one look per camera every ~3.4 s, each of a frame ~1.4 s old); on a box with
38
+ * room a still camera is looked at every 2-2.5 s. A changed frame still selects at once.
39
+ */
40
+ const LIVE_LOOK_INTERVAL_MS = 2000;
31
41
 
32
42
  async function createWebsiteManager(input, stateDirectory, deps = {}) {
33
43
  const config = JSON.parse(JSON.stringify(input));
@@ -171,6 +181,7 @@ async function createWebsiteManager(input, stateDirectory, deps = {}) {
171
181
  offerWindow: rule.mode === 'wait_recheck' ? 1 : 16, unclearRetryMs: 2000,
172
182
  // Latest frame wins per camera; capture-order contracts keep their window.
173
183
  realtimeReview: { freshnessMs },
184
+ ...(websiteManaged ? { liveLookIntervalMs: LIVE_LOOK_INTERVAL_MS } : {}),
174
185
  ...(rule.mode==='immediate'?{actorPerceiver:new SelectedActorPerceptionClient(binding)}:{}),
175
186
  });
176
187
  loop.client = client; clients.push(client);