@trillboards/edge-sdk 0.2.188 → 0.2.189

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.
Files changed (35) hide show
  1. package/dist/AudienceAnalyzeClient.d.ts +4 -0
  2. package/dist/AudienceAnalyzeClient.d.ts.map +1 -1
  3. package/dist/AudienceAnalyzeClient.js.map +1 -1
  4. package/dist/CloudSensingManager.d.ts +22 -0
  5. package/dist/CloudSensingManager.d.ts.map +1 -1
  6. package/dist/CloudSensingManager.js +31 -0
  7. package/dist/CloudSensingManager.js.map +1 -1
  8. package/dist/DurableVlmCandidateSpool.d.ts +12 -0
  9. package/dist/DurableVlmCandidateSpool.d.ts.map +1 -1
  10. package/dist/DurableVlmCandidateSpool.js +63 -7
  11. package/dist/DurableVlmCandidateSpool.js.map +1 -1
  12. package/dist/EdgeAgent.js +1 -1
  13. package/dist/LiteRtVlmProvider.d.ts +13 -0
  14. package/dist/LiteRtVlmProvider.d.ts.map +1 -1
  15. package/dist/LiteRtVlmProvider.js +26 -1
  16. package/dist/LiteRtVlmProvider.js.map +1 -1
  17. package/dist/VlmCandidateBuffer.d.ts +10 -0
  18. package/dist/VlmCandidateBuffer.d.ts.map +1 -1
  19. package/dist/VlmCandidateBuffer.js.map +1 -1
  20. package/dist/continuousReview.d.ts +22 -0
  21. package/dist/continuousReview.d.ts.map +1 -1
  22. package/dist/continuousReview.js +26 -1
  23. package/dist/continuousReview.js.map +1 -1
  24. package/dist/diagnose.d.ts +1 -1
  25. package/dist/diagnose.js +1 -1
  26. package/dist/localSensing.d.ts.map +1 -1
  27. package/dist/localSensing.js +10 -2
  28. package/dist/localSensing.js.map +1 -1
  29. package/package.json +3 -3
  30. package/retained/ArchiveLifecycle.cjs +9 -2
  31. package/retained/RetainedCaptureClient.cjs +140 -13
  32. package/retained/__tests__/realtime-schedule.test.cjs +337 -0
  33. package/retained/__tests__/runtime.test.cjs +8 -2
  34. package/retained/manager.cjs +8 -0
  35. package/retained/website-api-capability.cjs +7 -1
@@ -4,6 +4,15 @@ const sha=b=>crypto.createHash('sha256').update(b).digest('hex');
4
4
  const {selectTemporal,resolveTemporalCoverage}=require('./temporal-grouping.cjs');
5
5
  const {pinActorWindowHistory,resolveActorWindow}=require('./actor-window.cjs');
6
6
  const reviewExecution=new (require('node:async_hooks').AsyncLocalStorage)();
7
+ // Mirrors trillboard-api/services/fein/routeReviewTiming.js: a wait/recheck
8
+ // anchor older than wait + this confirms nothing. A cross-package test holds
9
+ // the two values equal.
10
+ const RECHECK_ANCHOR_GRACE_MS=60000;
11
+ // Selected frames the realtime schedule retired without a model call.
12
+ const UNREVIEWED=new Set(['shed_superseded','expired_unreviewed']);
13
+ const unreviewed=r=>UNREVIEWED.has(r?.disposition);
14
+ // Timed rules and ordered sequences need every observation in capture order.
15
+ const realtimeContext=c=>!c?.temporalReviewContract&&!c?.orderedSequence&&!c?.orderedCaptureContract;
7
16
  function commit(file,value) {
8
17
  const bytes=Buffer.isBuffer(value)?value:Buffer.from(JSON.stringify(value));
9
18
  const tmp=file+'.tmp';const fd=fs.openSync(tmp,'w');try{fs.writeFileSync(fd,bytes);fs.fsyncSync(fd);}finally{fs.closeSync(fd);}fs.renameSync(tmp,file);
@@ -13,31 +22,41 @@ function commit(file,value) {
13
22
  * Every original is retained. Sampling is explicit; archived intermediate images are NOT called reviewed.
14
23
  */
15
24
  class RetainedCaptureClient {
16
- constructor(client,directory,{cameraId,intervalMs=500,maxCaptures=100000,maxBytes=32*1024**3,offerWindow=16,reviewStage=()=>'active',selectionMode='all',groupingPolicy=null,configuredApiBaseUrl,archiveRetentionMs,actorPerceiver}={}) {
25
+ constructor(client,directory,{cameraId,intervalMs=500,maxCaptures=100000,maxBytes=32*1024**3,offerWindow=16,reviewStage=()=>'active',selectionMode='all',groupingPolicy=null,configuredApiBaseUrl,archiveRetentionMs,actorPerceiver,realtimeReview}={}) {
17
26
  require('../dist/continuousReview').assertRetainedReviewReceiver(client.getEndpoint(),configuredApiBaseUrl);
18
27
  assert(cameraId && Number.isSafeInteger(intervalMs)&&intervalMs>=500);
19
28
  assert(['all','state-change-v1'].includes(selectionMode));
20
29
  if(selectionMode==='state-change-v1')assert(groupingPolicy&&groupingPolicy.mode==='shadow','Explicit grouping policy required');
21
30
  assert(Number.isSafeInteger(maxCaptures)&&maxCaptures>0&&Number.isSafeInteger(maxBytes)&&maxBytes>0,'Invalid archive capacity');
22
31
  assert(archiveRetentionMs===undefined||Number.isSafeInteger(archiveRetentionMs)&&archiveRetentionMs>=500&&archiveRetentionMs<=86400000,'Invalid archive retention');
32
+ // freshnessMs is the live-alert age bound (0 = none); see realtimeCandidates.
33
+ assert(realtimeReview===undefined||!!realtimeReview&&Number.isSafeInteger(realtimeReview.freshnessMs)&&realtimeReview.freshnessMs>=0
34
+ &&(realtimeReview.now===undefined||typeof realtimeReview.now==='function'),'Invalid realtime review schedule');
23
35
  Object.assign(this,{client,directory,cameraId,intervalMs,maxCaptures,maxBytes,offerWindow,reviewStage,selectionMode,archiveRetentionMs,actorPerceiver});
36
+ this.realtime=realtimeReview?{freshnessMs:realtimeReview.freshnessMs,now:realtimeReview.now??Date.now}:null;this.reviewQueue=null;
37
+ // The newest capture the model has answered: no older selection can be newer news.
38
+ this.lastReviewed=null;
24
39
  if(actorPerceiver)assert((actorPerceiver.policy||typeof actorPerceiver.policyForContext==='function')&&typeof actorPerceiver.perceive==='function'&&typeof actorPerceiver.validate==='function','A complete actor perception client is required');
25
40
  this.perceptionBusy=false;
26
41
  this.groupReferences=new Map();this.previousCaptureRecord=null;this.previousSelectedRecord=null;
27
42
  this.entries=new Map();this.queued=new Set();this.anchor=null;this.nextDue=null;this.lastAt=-1;this.bytes=0;
28
- this.counts={captures:0,selected:0,reviewed:0,received:0,inactive:0,grouped:0};
43
+ this.counts={captures:0,selected:0,reviewed:0,received:0,inactive:0,grouped:0,shed:0,expired:0};
29
44
  fs.mkdirSync(directory,{recursive:true});fs.mkdirSync(path.join(directory,'images'),{recursive:true});
30
45
  this.records=new Map();
31
46
  const policy={version:1,cameraId,intervalMs,maxCaptures,maxBytes,...(configuredApiBaseUrl?{configuredApiBaseUrl}:{}),...(archiveRetentionMs===undefined?{}:{archiveRetentionMs,archiveLifecycle:'resolved_and_unneeded_only_v1'}),algorithm:'first_capture_at_or_after_fixed_slot; no synthetic timestamps',...(selectionMode==='all'?{}:{selectionMode,groupingPolicy,temporalPolicy:'explicit_grouped_continuity_opt_in_else_preserve_all'})};
32
47
  const policyFile=path.join(directory,'POLICY.json');
33
48
  if(fs.existsSync(policyFile))assert.deepEqual(JSON.parse(fs.readFileSync(policyFile)),policy,'Archive policy changed');else commit(policyFile,policy);
34
49
  this.lifecycle=archiveRetentionMs===undefined?null:new(require('./ArchiveLifecycle.cjs').ArchiveLifecycle)(directory);
35
- if(this.lifecycle)this.counts={...this.lifecycle.state.pruned};
50
+ if(this.lifecycle)this.counts={...this.counts,...this.lifecycle.state.pruned};
36
51
  const files=fs.readdirSync(directory).filter(f=>/^[a-f0-9]{32}\.json$/.test(f));
37
52
  const records=files.map(f=>JSON.parse(fs.readFileSync(path.join(directory,f)))).sort((a,b)=>a.capturedAt-b.capturedAt);
38
- for(const r of records){assert.equal(r.cameraId,cameraId);assert.equal(sha(fs.readFileSync(this.image(r))),r.imageSha256);this.records.set(r.id,r);if(r.actorPerceptionPolicy){assert(this.actorPerceiver,'Archived actor perception requires its runtime');if(r.actorPerception)this.actorPerceiver.validate(r.actorPerception,this.perceptionInput(r),r.actorPerceptionPolicy);}if(r.selected&&!r.acknowledged)this.entries.set(r.id,r);this.counts.captures++;if(r.selected)this.counts.selected++;if(r.result)this.counts.reviewed++;if(r.acknowledged)this.counts.received++;if(r.reviewStage===null)this.counts.inactive++;if(r.disposition==='archived_grouped_unchanged')this.counts.grouped++;this.bytes+=r.imageBytes;this.advance(r);}
53
+ for(const r of records){assert.equal(r.cameraId,cameraId);assert.equal(sha(fs.readFileSync(this.image(r))),r.imageSha256);this.records.set(r.id,r);if(r.actorPerceptionPolicy){assert(this.actorPerceiver,'Archived actor perception requires its runtime');if(r.actorPerception)this.actorPerceiver.validate(r.actorPerception,this.perceptionInput(r),r.actorPerceptionPolicy);}if(r.selected&&!r.acknowledged&&!unreviewed(r))this.entries.set(r.id,r);this.counts.captures++;if(r.selected)this.counts.selected++;if(r.result)this.counts.reviewed++;if(r.acknowledged)this.counts.received++;if(r.reviewStage===null)this.counts.inactive++;if(r.disposition==='archived_grouped_unchanged')this.counts.grouped++;if(r.disposition==='shed_superseded')this.counts.shed++;if(r.disposition==='expired_unreviewed')this.counts.expired++;if(r.result)this.noteReviewed(r);this.bytes+=r.imageBytes;this.advance(r);}
39
54
  }
40
55
  image(r){return path.join(this.directory,'images',r.imageSha256+'.jpg');}
56
+ noteReviewed(r){
57
+ if(!realtimeContext(r.candidate?.reviewContext))return;
58
+ if(!this.lastReviewed||r.capturedAt>=this.lastReviewed.capturedAt)this.lastReviewed={id:r.id,capturedAt:r.capturedAt};
59
+ }
41
60
  file(id){return path.join(this.directory,id+'.json');}
42
61
  advance(r){this.previousCaptureRecord=r;if(r.selected){this.previousSelectedRecord=r;const key=this.referenceKey(r.capturedAt,r.imageSha256,r.candidate.reviewContext);this.groupReferences.set(key,r.id);if(this.groupReferences.size>256)this.groupReferences.delete(this.groupReferences.keys().next().value);}if(this.anchor===null){this.anchor=r.capturedAt;this.nextDue=r.capturedAt;}if(r.selected)this.nextDue=this.anchor+(Math.floor((r.capturedAt-this.anchor)/this.intervalMs)+1)*this.intervalMs;this.lastAt=r.capturedAt;}
43
62
  referenceKey(at,digest,context){return JSON.stringify([at,digest,sha(Buffer.from(JSON.stringify(context??null)))]);}
@@ -115,7 +134,7 @@ class RetainedCaptureClient {
115
134
  const rows=[];
116
135
  for(const r of this.records.values()){
117
136
  if(rows.length>=64)break;
118
- if(pins.has(r.id)||r.selected&&!r.acknowledged||r.disposition==='awaiting_rule_decision'
137
+ if(pins.has(r.id)||r.selected&&!r.acknowledged&&!unreviewed(r)||r.disposition==='awaiting_rule_decision'
119
138
  ||Math.max(r.capturedAt,r.acknowledgedAtCaptureMs??r.capturedAt)>at-this.archiveRetentionMs)continue;
120
139
  rows.push(r);
121
140
  }
@@ -142,14 +161,111 @@ class RetainedCaptureClient {
142
161
  commit(this.file(id),r);this.records.set(id,r);if(selected)this.entries.set(id,r);this.counts.captures++;if(selected)this.counts.selected++;if(reviewStage===null)this.counts.inactive++;if(r.disposition==='archived_grouped_unchanged')this.counts.grouped++;this.bytes+=c.jpeg.length;this.advance(r);
143
162
  }
144
163
  pendingOrderedCandidates(){
145
- const available=this.offerWindow-this.queued.size;if(available<=0)return[];const out=[];
146
- for(const r of this.entries.values()){
164
+ return this.realtime?this.realtimeCandidates():this.captureOrderCandidates(this.entries.values());
165
+ }
166
+ offerFor(r,extra={}){
167
+ return {...r.candidate,jpeg:fs.readFileSync(this.image(r)),retainedId:r.id,...extra,
168
+ reviewContext:{...r.candidate.reviewContext,retainedCapture:{version:1,id:r.id,kind:'retained_single_capture'}}};
169
+ }
170
+ captureOrderCandidates(rows,available=this.offerWindow-this.queued.size){
171
+ if(available<=0)return[];const out=[];
172
+ for(const r of rows){
147
173
  if(!r.selected||r.acknowledged||this.queued.has(r.id)||r.actorPerceptionPolicy&&!r.actorPerception)continue;
148
- out.push({...r.candidate,jpeg:fs.readFileSync(this.image(r)),retainedId:r.id,
149
- reviewContext:{...r.candidate.reviewContext,retainedCapture:{version:1,id:r.id,kind:'retained_single_capture'}}});
174
+ out.push(this.offerFor(r));
150
175
  if(out.length>=available)break;
151
176
  }return out;
152
177
  }
178
+ /**
179
+ * Realtime route review. One review answers every route on this camera, so the
180
+ * camera's newest selected frame is its one pending review: each older
181
+ * unanswered selection is shed when a newer one is ready. A wait/recheck
182
+ * endpoint that admission marked (`followUp`) keeps a reserved slot, never
183
+ * shed by a newer frame, for exactly as long as the server would still pair it
184
+ * with its anchor. Nothing starts once older than the live-alert bound: the
185
+ * frame expires, and its offer carries the deadline its model calls may not
186
+ * pass. Shed and expired originals stay under the archive's ordinary
187
+ * retention and are counted; none is reviewed late. Answered frames awaiting
188
+ * receipt are never touched.
189
+ *
190
+ * Across cameras, the spool's least-recently-served rotation serves these
191
+ * slots round robin. Earliest-capture-first was rejected: every slot holds a
192
+ * frame at most one selection old, so it would favor whichever camera selects
193
+ * least often and let a constantly changing camera wait indefinitely. Round
194
+ * robin bounds every camera's wait to one review of each other camera.
195
+ */
196
+ realtimeCandidates(){
197
+ assert(this.reviewQueue,'Realtime review scheduling requires its review queue');
198
+ const now=this.realtime.now(),freshnessMs=this.realtime.freshnessMs;
199
+ const stale=r=>freshnessMs>0&&now>=r.capturedAt+freshnessMs;
200
+ const unanswered=[],answered=[],ordered=[];
201
+ for(const r of this.entries.values()){
202
+ if(r.acknowledged)continue;
203
+ if(!realtimeContext(r.candidate.reviewContext))ordered.push(r);
204
+ else (r.result?answered:unanswered).push(r);
205
+ }
206
+ const byCapture=(a,b)=>a.capturedAt-b.capturedAt||a.id.localeCompare(b.id);
207
+ unanswered.sort(byCapture);
208
+ // The newest view this camera has: reviewable now, or already answered. A
209
+ // frame still waiting for its original actor perception cannot be offered yet.
210
+ const ready=unanswered.filter(r=>!(r.actorPerceptionPolicy&&!r.actorPerception));
211
+ const newest=[...ready,...answered,...(this.lastReviewed?[this.lastReviewed]:[])].sort(byCapture).pop()??null;
212
+ const reserved=new Map();
213
+ for(const r of ready){const f=this.followUpOf(r);if(f&&!reserved.has(f.routeId))reserved.set(f.routeId,r);}
214
+ const keep=new Set([...reserved.values()].map(r=>r.id));
215
+ // Expired first: a frame past the bound (including one whose review was cut
216
+ // at its deadline) could not have become a live alert, whatever replaced it.
217
+ const decide=r=>stale(r)?'expired':newest&&r.id!==newest.id&&!keep.has(r.id)&&byCapture(r,newest)<0?'shed':null;
218
+ // A queued copy can win the next take, so it leaves now. The rest is
219
+ // bookkeeping, bounded per pump so capture stays responsive while a backlog drains.
220
+ let budget=16;
221
+ for(const r of [...unanswered.filter(r=>this.queued.has(r.id)),...unanswered.filter(r=>!this.queued.has(r.id))]){
222
+ const outcome=decide(r);if(!outcome)continue;
223
+ const queued=this.queued.has(r.id);
224
+ if(!queued&&budget<=0)break;
225
+ if(this.retireUnreviewed(r,outcome,now,newest)&&!queued)budget--;
226
+ }
227
+ const current=newest&&!keep.has(newest.id)?this.entries.get(newest.id):null;
228
+ const slots=[...reserved.values(),...(current&&!current.result?[current]:[])];
229
+ const out=slots.filter(r=>this.entries.has(r.id)&&!this.queued.has(r.id)&&!stale(r))
230
+ .map(r=>this.offerFor(r,{...(freshnessMs>0?{reviewDeadlineAtMs:r.capturedAt+freshnessMs}:{}),...(keep.has(r.id)?{reviewPriority:'urgent'}:{})}));
231
+ // A saved answer re-offered after restart is a delivery, never subject to a deadline.
232
+ out.push(...this.captureOrderCandidates(answered,this.offerWindow));
233
+ return [...out,...this.captureOrderCandidates(ordered)];
234
+ }
235
+ /** Admission's mark for a wait/recheck endpoint, reserved while the server
236
+ * would still pair it with its anchor: captured inside
237
+ * [anchor + wait, anchor + wait + RECHECK_ANCHOR_GRACE_MS]. */
238
+ followUpOf(r){
239
+ const f=r?.followUp;
240
+ if(!f||f.version!==1||typeof f.routeId!=='string'||!f.routeId||!Number.isSafeInteger(f.anchorCapturedAtMs)
241
+ ||!Number.isSafeInteger(f.waitMs)||f.waitMs<0)return null;
242
+ const dueAtMs=f.anchorCapturedAtMs+f.waitMs;
243
+ return r.capturedAt>=dueAtMs&&r.capturedAt<=dueAtMs+RECHECK_ANCHOR_GRACE_MS?f:null;
244
+ }
245
+ /** The queue copy leaves first. Work the model already took is never retired. */
246
+ retireUnreviewed(r,outcome,now,by){
247
+ const queued=this.reviewQueue.withdraw(r.id);
248
+ if(queued==='in_flight'||queued==='reviewed')return false;
249
+ const f=this.followUpOf(r);
250
+ const next={...r,disposition:outcome==='shed'?'shed_superseded':'expired_unreviewed',
251
+ scheduleOutcome:{version:1,outcome,decidedAtMs:now,slot:f?'follow_up':'latest',...(f?{routeId:f.routeId}:{}),
252
+ ...(outcome==='shed'?{supersededBy:by.id,supersededByCapturedAtMs:by.capturedAt}:{freshnessMs:this.realtime.freshnessMs})}};
253
+ commit(this.file(r.id),next);Object.assign(r,next);this.records.set(r.id,r);
254
+ this.entries.delete(r.id);this.queued.delete(r.id);this.counts[outcome]++;
255
+ return true;
256
+ }
257
+ /** The manager's durable spool, so a retired frame's queued copy leaves with it. */
258
+ attachReviewQueue(queue){
259
+ assert(typeof queue?.withdraw==='function','Realtime review needs a queue that can withdraw retired frames');
260
+ this.reviewQueue=queue;
261
+ }
262
+ getReviewScheduleStats(){
263
+ if(!this.realtime)return null;
264
+ const {selected,reviewed,shed,expired}=this.counts;
265
+ // selected = reviewed + shed + expired + pending: an answer awaiting receipt is reviewed.
266
+ const pending=[...this.entries.values()].filter(r=>!r.result).length;
267
+ return {freshnessMs:this.realtime.freshnessMs,pending,selected,reviewed,shed,expired};
268
+ }
153
269
  offered(c,result){if(result==='buffered'||result==='coalesced')this.queued.add(c.retainedId);}
154
270
  flushOrderedCapture(){}
155
271
  perceptionInput(r){
@@ -189,12 +305,23 @@ class RetainedCaptureClient {
189
305
  }
190
306
  async prepare(request){
191
307
  const r=this.entries.get(request.evidenceId)??(/^[a-f0-9]{32}$/.test(request.evidenceId)&&fs.existsSync(this.file(request.evidenceId))?JSON.parse(fs.readFileSync(this.file(request.evidenceId))):null);assert(r&&r.selected,'Unknown selected evidence');
308
+ // A queue copy that outlived its retirement (a failed delete, then restart):
309
+ // coded so the manager drops the copy instead of retrying it forever.
310
+ if(unreviewed(r))throw Object.assign(Error('Evidence was retired unreviewed ('+r.disposition+'); this queue copy is stale'),
311
+ {code:require('../dist/continuousReview').RETAINED_EVIDENCE_RETIRED});
192
312
  assert.equal(request.capturedAt,r.capturedAt);assert.equal(sha(request.jpeg),r.imageSha256);
193
313
  assert.deepEqual(this.baseContext(request.reviewContext),r.candidate.reviewContext,'Capture context changed');
194
314
  const coverageCache=new Map();
195
315
  if(r.actorPerceptionPolicy)assert(r.actorPerception,'Original actor perception must complete before review');
196
- const req={...request,...(r.actorPerception?{actorPerception:this.actorPerceiver.validate(r.actorPerception,this.perceptionInput(r),r.actorPerceptionPolicy)}:{}),reviewContext:r.candidate.reviewContext,resolveActorWindow:(actor,modelId)=>resolveActorWindow(this,r,actor,modelId),temporalContinuityBreak:r.temporalContinuityBroken===true,resolveTemporalCoverage:contract=>{const key=JSON.stringify(contract);if(!coverageCache.has(key))coverageCache.set(key,resolveTemporalCoverage(this,r,contract));return coverageCache.get(key);},cachedAnalysis:request.cachedAnalysis??r.result,
197
- checkpointAnalysis:result=>{const first=!r.result;r.result=result;commit(this.file(r.id),r);if(first)this.counts.reviewed++;request.checkpointAnalysis(result);}};
316
+ // Frozen once, when the review starts: every upload retry reports the same facts.
317
+ if(this.realtime&&!r.result&&!r.reviewSchedule&&realtimeContext(r.candidate.reviewContext)){
318
+ const f=this.followUpOf(r),{selected,reviewed,shed,expired}=this.counts;
319
+ r.reviewSchedule={version:1,slot:f?'follow_up':'latest',...(f?{routeId:f.routeId}:{}),freshnessMs:this.realtime.freshnessMs,
320
+ startedAtMs:this.realtime.now(),selected,reviewed,shed,expired};
321
+ commit(this.file(r.id),r);
322
+ }
323
+ const req={...request,...(r.reviewSchedule?{reviewSchedule:r.reviewSchedule}:{}),...(r.actorPerception?{actorPerception:this.actorPerceiver.validate(r.actorPerception,this.perceptionInput(r),r.actorPerceptionPolicy)}:{}),reviewContext:r.candidate.reviewContext,resolveActorWindow:(actor,modelId)=>resolveActorWindow(this,r,actor,modelId),temporalContinuityBreak:r.temporalContinuityBroken===true,resolveTemporalCoverage:contract=>{const key=JSON.stringify(contract);if(!coverageCache.has(key))coverageCache.set(key,resolveTemporalCoverage(this,r,contract));return coverageCache.get(key);},cachedAnalysis:request.cachedAnalysis??r.result,
324
+ checkpointAnalysis:result=>{const first=!r.result;r.result=result;commit(this.file(r.id),r);if(first)this.counts.reviewed++;this.noteReviewed(r);request.checkpointAnalysis(result);}};
198
325
  await reviewExecution.run({evidenceId:r.id,cameraId:r.cameraId},()=>this.client.reviewCandidate(req));assert(r.result,'No durable result');return {...req,cachedAnalysis:r.result};
199
326
  }
200
327
  async reviewCandidate(request){await this.prepare(request);}
@@ -205,6 +332,6 @@ class RetainedCaptureClient {
205
332
  const r=this.entries.get(request.evidenceId)??JSON.parse(fs.readFileSync(this.file(request.evidenceId)));const first=!r.acknowledged;r.acknowledged=true;r.acknowledgedAtCaptureMs=this.lastAt;r.disposition='reviewed_and_received';commit(this.file(r.id),r);this.records.set(r.id,r);if(first)this.counts.received++;this.queued.delete(r.id);this.entries.delete(r.id);
206
333
  }return response;
207
334
  }
208
- stats(){const actorRows=[...this.records.values()].filter(r=>r.actorPerceptionPolicy),actorPending=actorRows.filter(r=>!r.actorPerception);const {captures,selected,reviewed,received,inactive,grouped}=this.counts;return{...(this.actorPerceiver?{actorPerception:{completed:actorRows.length-actorPending.length,pending:actorPending.length,oldestPendingCapturedAt:actorPending[0]?.capturedAt??null,unavailable:actorPending.some(r=>r.actorPerceptionFailure)}}:{}),captures,selected,archivedProfileInactive:inactive,archivedBetweenReviews:captures-selected-inactive-grouped,archivedGroupedUnreviewed:grouped,reviewed,received,pending:this.entries.size,oldestPendingCapturedAt:this.entries.values().next().value?.capturedAt??null,logicalImageBytes:this.bytes,retainedCaptures:this.records.size,prunedCaptures:this.lifecycle?.state.pruned.captures??0};}
335
+ stats(){const actorRows=[...this.records.values()].filter(r=>r.actorPerceptionPolicy),actorPending=actorRows.filter(r=>!r.actorPerception);const {captures,selected,reviewed,received,inactive,grouped,shed,expired}=this.counts;return{...(this.actorPerceiver?{actorPerception:{completed:actorRows.length-actorPending.length,pending:actorPending.length,oldestPendingCapturedAt:actorPending[0]?.capturedAt??null,unavailable:actorPending.some(r=>r.actorPerceptionFailure)}}:{}),captures,selected,archivedProfileInactive:inactive,archivedBetweenReviews:captures-selected-inactive-grouped,archivedGroupedUnreviewed:grouped,reviewed,received,shedUnreviewed:shed,expiredUnreviewed:expired,pending:this.entries.size,oldestPendingCapturedAt:this.entries.values().next().value?.capturedAt??null,logicalImageBytes:this.bytes,retainedCaptures:this.records.size,prunedCaptures:this.lifecycle?.state.pruned.captures??0};}
209
336
  }
210
- module.exports={RetainedCaptureClient,reviewExecution};
337
+ module.exports={RetainedCaptureClient,reviewExecution,RECHECK_ANCHOR_GRACE_MS};
@@ -0,0 +1,337 @@
1
+ 'use strict';
2
+ // Realtime retained review: latest frame wins per camera, slots served round
3
+ // robin, wait/recheck endpoints reserved, nothing started past the live-alert
4
+ // bound. Real camera JPEGs, the real durable spool, the real server timing rule.
5
+ const { test } = require('node:test');
6
+ const assert = require('node:assert/strict');
7
+ const fs = require('node:fs'), os = require('node:os'), path = require('node:path'), crypto = require('node:crypto');
8
+ const { decode, encode } = require('jpeg-js');
9
+ const { RetainedCaptureClient, RECHECK_ANCHOR_GRACE_MS } = require('../RetainedCaptureClient.cjs');
10
+ const take = name => require(path.join(__dirname, '../../dist', name));
11
+ const { DurableVlmCandidateSpool } = take('DurableVlmCandidateSpool');
12
+ const routeReviewTiming = require(path.resolve(__dirname, '../../../../../trillboard-api/services/fein/routeReviewTiming.js'));
13
+
14
+ const sha = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
15
+ const LIVE_BOUND_MS = 180000, REVIEW_WINDOW_MS = 150000, ENDPOINT = 'http://127.0.0.1:18791/v2/earner/audience-analyze';
16
+ const sources = ['cctv-cstore-empty.jpg', 'cctv-kitchen-people.jpg']
17
+ .map(name => decode(fs.readFileSync(path.join(__dirname, '../../src/__tests__/fixtures', name))));
18
+ let stamp = 0;
19
+ // A distinct original per capture: the real store frame with a tagged corner.
20
+ function original(which = 0) {
21
+ const source = sources[which], data = Buffer.from(source.data), tag = ++stamp;
22
+ for (let y = 0; y < 8; y++) for (let x = 0; x < 8; x++) {
23
+ const i = (y * source.width + x) * 4;
24
+ data[i] = tag * 31 % 255; data[i + 1] = tag * 67 % 255; data[i + 2] = tag * 97 % 255;
25
+ }
26
+ return Buffer.from(encode({ data, width: source.width, height: source.height }, 90).data);
27
+ }
28
+ const reviewContext = camera => ({ version: 1, profileState: 'active', camera,
29
+ schema: { type: 'object', properties: { person_present: { type: 'boolean' } }, required: ['person_present'] },
30
+ prompt: 'Is a person present?', producerFields: [], regions: [], operatingPoints: [], absenceWatchedFields: [] });
31
+
32
+ function rig(names, { freshnessMs = LIVE_BOUND_MS, inner } = {}) {
33
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'realtime-schedule-'));
34
+ const state = { now: Date.parse('2026-11-03T15:00:00Z') }, clock = () => state.now;
35
+ const spoolOptions = { directory: path.join(root, 'spool'), now: clock, reviewWindowMs: REVIEW_WINDOW_MS,
36
+ retentionMs: 86400000, priorityScheduling: true, preserveArchivedPending: true, maxPerFeed: 128, maxFrames: 512 };
37
+ const rigState = { spool: new DurableVlmCandidateSpool(spoolOptions) };
38
+ rigState.spool.startRun();
39
+ const reviews = [];
40
+ const native = inner ?? { getEndpoint: () => ENDPOINT,
41
+ async reviewCandidate(req) {
42
+ // A saved answer is re-validated before upload; only a fresh one is a model call.
43
+ if (!req.cachedAnalysis) reviews.push({ camera: req.reviewContext.camera, evidenceId: req.evidenceId,
44
+ capturedAt: req.capturedAt, startedAt: state.now, deadline: req.reviewDeadlineAtMs });
45
+ req.checkpointAnalysis(req.cachedAnalysis ?? { version: 1, evidenceSha256: sha(req.jpeg), structured: { person_present: true } });
46
+ },
47
+ async analyze(req) {
48
+ return { ok: true, body: { accepted: true, evidenceId: req.evidenceId, evidenceReview: { version: 1, capturedAtMs: req.capturedAt } } };
49
+ } };
50
+ const archives = new Map();
51
+ const open = (name, options = {}) => {
52
+ const archive = new RetainedCaptureClient(native, path.join(root, 'archive-' + name), { cameraId: name,
53
+ archiveRetentionMs: 600000, realtimeReview: { freshnessMs, now: clock }, ...options });
54
+ if (archive.realtime) archive.attachReviewQueue(rigState.spool);
55
+ archives.set(name, archive);
56
+ return archive;
57
+ };
58
+ for (const name of names) open(name);
59
+ const capture = (name, which = 0) => {
60
+ const archive = archives.get(name);
61
+ archive.retainOrderedCapture({ name, enqueuedAtMs: state.now, jpeg: original(which), reviewContext: reviewContext(name),
62
+ captureMode: 'periodic', reason: 'motion', signature: null, reviewKind: 'event' });
63
+ return archive.previousCaptureRecord;
64
+ };
65
+ // CloudSensingManager.pumpCandidates: each archive offers, the spool holds.
66
+ const pump = () => { for (const archive of archives.values()) for (const c of archive.pendingOrderedCandidates()) archive.offered(c, rigState.spool.offer(c)); };
67
+ const next = () => { pump(); return rigState.spool.take(undefined, 'review'); };
68
+ // serveCandidate (review slot) + pumpDeliveries (upload), as the manager runs them.
69
+ const request = c => ({ jpeg: c.jpeg, capturedAt: c.enqueuedAtMs, evidenceId: c.spoolId, reviewWindowMs: REVIEW_WINDOW_MS,
70
+ reviewContext: c.reviewContext, ...(c.reviewDeadlineAtMs !== undefined ? { reviewDeadlineAtMs: c.reviewDeadlineAtMs } : {}),
71
+ checkpointAnalysis: result => rigState.spool.checkpoint(c, result) });
72
+ const finish = async c => {
73
+ const archive = archives.get(c.name);
74
+ await archive.reviewCandidate(request(c));
75
+ rigState.spool.readyForDelivery(c);
76
+ const delivery = rigState.spool.take(undefined, 'delivery');
77
+ assert.equal(delivery.spoolId, c.spoolId);
78
+ await archive.analyze({ ...request(delivery), cachedAnalysis: delivery.cachedAnalysis, checkpointAnalysis() {} });
79
+ rigState.spool.complete(delivery);
80
+ return c;
81
+ };
82
+ const serve = async () => { const c = next(); return c ? finish(c) : null; };
83
+ const restartSpool = () => { rigState.spool = new DurableVlmCandidateSpool(spoolOptions); rigState.spool.startRun();
84
+ for (const archive of archives.values()) if (archive.realtime) archive.attachReviewQueue(rigState.spool); };
85
+ const row = (name, id) => JSON.parse(fs.readFileSync(archives.get(name).file(id)));
86
+ return { root, state, rigState, archives, open, capture, pump, next, finish, serve, restartSpool, row, reviews,
87
+ spool: () => rigState.spool, cleanup: () => fs.rmSync(root, { recursive: true, force: true }) };
88
+ }
89
+ // What an admission layer does when it selects a wait/recheck endpoint.
90
+ function markFollowUp(archive, record, followUp) {
91
+ record.followUp = followUp;
92
+ fs.writeFileSync(archive.file(record.id), JSON.stringify(record));
93
+ }
94
+
95
+ test('a newer selection replaces the pending one: the replaced frame is shed, kept on disk, never reviewed', async () => {
96
+ const r = rig(['counter']);
97
+ try {
98
+ const first = r.capture('counter'); r.pump();
99
+ assert.equal(r.spool().getStats().buffered, 1);
100
+ r.state.now += 1000; const newest = r.capture('counter');
101
+ const served = await r.serve();
102
+ assert.equal(served.spoolId, newest.id);
103
+ assert.deepEqual(r.reviews.map(x => x.evidenceId), [newest.id]);
104
+ const shed = r.row('counter', first.id);
105
+ assert.equal(shed.disposition, 'shed_superseded');
106
+ assert.deepEqual(shed.scheduleOutcome, { version: 1, outcome: 'shed', decidedAtMs: r.state.now, slot: 'latest',
107
+ supersededBy: newest.id, supersededByCapturedAtMs: newest.capturedAt });
108
+ assert.equal(sha(fs.readFileSync(r.archives.get('counter').image(shed))), shed.imageSha256);
109
+ assert.equal(r.spool().getStats().withdrawn, 1);
110
+ assert.deepEqual(r.archives.get('counter').getReviewScheduleStats(),
111
+ { freshnessMs: LIVE_BOUND_MS, pending: 0, selected: 2, reviewed: 1, shed: 1, expired: 0 });
112
+ } finally { r.cleanup(); }
113
+ });
114
+
115
+ test('the frame the model is already reviewing is never shed; the newest waits behind it, then runs', async () => {
116
+ const r = rig(['counter']);
117
+ try {
118
+ const running = r.capture('counter'); const inFlight = r.next();
119
+ assert.equal(inFlight.spoolId, running.id);
120
+ r.state.now += 1000; const middle = r.capture('counter');
121
+ r.state.now += 1000; const newest = r.capture('counter');
122
+ r.pump();
123
+ assert.equal(r.row('counter', running.id).disposition, 'pending_review');
124
+ assert.equal(r.row('counter', middle.id).disposition, 'shed_superseded');
125
+ assert.equal(r.spool().take(undefined, 'review'), null); // one review per camera at a time
126
+ assert.equal(r.archives.get('counter').getReviewScheduleStats().pending, 2);
127
+ await r.archives.get('counter').reviewCandidate({ jpeg: inFlight.jpeg, capturedAt: inFlight.enqueuedAtMs,
128
+ evidenceId: inFlight.spoolId, reviewWindowMs: REVIEW_WINDOW_MS, reviewContext: inFlight.reviewContext,
129
+ checkpointAnalysis() {} });
130
+ // Answered and awaiting receipt is reviewed, not pending: selected 3 = reviewed 1 + shed 1 + pending 1.
131
+ assert.deepEqual(r.archives.get('counter').getReviewScheduleStats(),
132
+ { freshnessMs: LIVE_BOUND_MS, pending: 1, selected: 3, reviewed: 1, shed: 1, expired: 0 });
133
+ await r.finish(inFlight);
134
+ assert.equal((await r.serve()).spoolId, newest.id);
135
+ assert.deepEqual(r.reviews.map(x => x.evidenceId), [running.id, newest.id]);
136
+ } finally { r.cleanup(); }
137
+ });
138
+
139
+ test('camera slots are served round robin: a constantly changing camera cannot starve quiet ones', async () => {
140
+ const r = rig(['paint', 'door', 'lot']);
141
+ try {
142
+ let quietDue = r.state.now;
143
+ const served = [];
144
+ for (let review = 0; review < 12; review++) {
145
+ // Ten seconds of capture while the previous ~10 s review ran: the paint
146
+ // counter faces a changing screen and selects twice a second; the others
147
+ // select one quiet check every ten seconds.
148
+ for (let t = 0; t < 10000; t += 500) {
149
+ r.state.now += 500; r.capture('paint');
150
+ if (r.state.now >= quietDue) { r.capture('door', 1); r.capture('lot', 1); quietDue += 10000; }
151
+ }
152
+ const c = r.next();
153
+ served.push({ camera: c.name, ageMs: r.state.now - c.enqueuedAtMs });
154
+ await r.finish(c);
155
+ }
156
+ for (let i = 0; i + 3 <= served.length; i += 3) {
157
+ assert.deepEqual(served.slice(i, i + 3).map(s => s.camera).sort(), ['door', 'lot', 'paint']);
158
+ }
159
+ assert.equal(Math.max(...served.filter(s => s.camera === 'paint').map(s => s.ageMs)), 0); // its newest frame
160
+ assert(Math.max(...served.map(s => s.ageMs)) <= 10000);
161
+ const paint = r.archives.get('paint').getReviewScheduleStats();
162
+ assert.equal(paint.reviewed, 4);
163
+ assert.equal(paint.selected, paint.reviewed + paint.shed + paint.pending);
164
+ assert.equal(paint.expired, 0);
165
+ } finally { r.cleanup(); }
166
+ });
167
+
168
+ test('a wait/recheck endpoint keeps a reserved slot exactly while the server would pair it with its anchor', async () => {
169
+ // The connector mirrors the server rule rather than inventing one.
170
+ assert.equal(RECHECK_ANCHOR_GRACE_MS, routeReviewTiming.RECHECK_ANCHOR_GRACE_MS);
171
+ const policy = { reviewTimingMode: 'wait_recheck', reviewWaitSeconds: 60 };
172
+ const opened = routeReviewTiming.nextReviewTiming(policy, { capturedAtMs: 1000, evidenceId: 'anchor', matches: true, contextId: 'c' });
173
+ const at = ms => routeReviewTiming.nextReviewTiming(policy, { capturedAtMs: 1000 + ms, evidenceId: 'recheck', matches: true, contextId: 'c' }, opened.state);
174
+ assert.equal(at(60000 + RECHECK_ANCHOR_GRACE_MS).eligible, true);
175
+ assert.equal(at(60000 + RECHECK_ANCHOR_GRACE_MS + 1).eligible, false);
176
+
177
+ const r = rig(['phone', 'door']);
178
+ try {
179
+ const phone = r.archives.get('phone');
180
+ const anchor = r.capture('phone'); await r.serve();
181
+ const followUp = { version: 1, routeId: 'rt_phone', anchorCapturedAtMs: anchor.capturedAt, waitMs: 60000 };
182
+ r.state.now = anchor.capturedAt + 60000;
183
+ const recheck = r.capture('phone'); markFollowUp(phone, recheck, followUp);
184
+ r.state.now += 1000; const later = r.capture('phone'); r.capture('door', 1);
185
+ r.pump();
186
+ assert.equal(r.row('phone', recheck.id).disposition, 'pending_review'); // a newer frame cannot take its slot
187
+ const first = r.next();
188
+ assert.equal(first.spoolId, recheck.id); // ahead of the other camera's fresh frame
189
+ assert.equal(first.reviewPriority, 'urgent');
190
+ await r.finish(first);
191
+ assert.deepEqual([(await r.serve()).name, (await r.serve()).spoolId], ['door', later.id]);
192
+ // Past anchor + wait + grace the server starts a new wait instead: an ordinary frame.
193
+ r.state.now = anchor.capturedAt + 60000 + RECHECK_ANCHOR_GRACE_MS + 1;
194
+ const lapsed = r.capture('phone'); markFollowUp(phone, lapsed, followUp);
195
+ r.state.now += 1000; const newer = r.capture('phone'); r.pump();
196
+ assert.equal(r.row('phone', lapsed.id).disposition, 'shed_superseded');
197
+ assert.equal((await r.serve()).spoolId, newer.id);
198
+ } finally { r.cleanup(); }
199
+ });
200
+
201
+ test('nothing starts past the live-alert bound: the queue copy leaves and the archive counts it expired', async () => {
202
+ const r = rig(['lot']);
203
+ try {
204
+ const stale = r.capture('lot'); r.pump();
205
+ assert.equal(r.spool().peek(undefined, 'review').reviewDeadlineAtMs, stale.capturedAt + LIVE_BOUND_MS);
206
+ r.state.now = stale.capturedAt + LIVE_BOUND_MS;
207
+ assert.equal(r.spool().take(undefined, 'review'), null);
208
+ assert.equal(r.spool().getStats().expired, 1);
209
+ r.pump();
210
+ const row = r.row('lot', stale.id);
211
+ assert.equal(row.disposition, 'expired_unreviewed');
212
+ assert.deepEqual(row.scheduleOutcome, { version: 1, outcome: 'expired', decidedAtMs: r.state.now, slot: 'latest', freshnessMs: LIVE_BOUND_MS });
213
+ assert.deepEqual(r.archives.get('lot').pendingOrderedCandidates(), []);
214
+ assert.equal(r.reviews.length, 0);
215
+ assert.deepEqual(r.archives.get('lot').getReviewScheduleStats(),
216
+ { freshnessMs: LIVE_BOUND_MS, pending: 0, selected: 1, reviewed: 0, shed: 0, expired: 1 });
217
+ await assert.rejects(r.archives.get('lot').prepare({ evidenceId: stale.id }), /retired unreviewed/);
218
+ } finally { r.cleanup(); }
219
+ });
220
+
221
+ test('a review cut at its deadline counts as expired, even after a newer frame took the slot', async () => {
222
+ const r = rig(['counter']);
223
+ try {
224
+ const cut = r.capture('counter'); const taken = r.next();
225
+ assert.equal(taken.spoolId, cut.id);
226
+ r.state.now = cut.capturedAt + 170000; const newer = r.capture('counter');
227
+ r.state.now = cut.capturedAt + LIVE_BOUND_MS;
228
+ r.spool().retry(taken); // what the manager does after a ReviewDeadlineExceededError
229
+ r.pump();
230
+ assert.equal(r.row('counter', cut.id).disposition, 'expired_unreviewed');
231
+ assert.equal((await r.serve()).spoolId, newer.id);
232
+ assert.deepEqual(r.archives.get('counter').getReviewScheduleStats(),
233
+ { freshnessMs: LIVE_BOUND_MS, pending: 0, selected: 2, reviewed: 1, shed: 0, expired: 1 });
234
+ } finally { r.cleanup(); }
235
+ });
236
+
237
+ test('a server bound of 0 means no bound: nothing expires and no deadline is stamped', async () => {
238
+ const r = rig(['lot'], { freshnessMs: 0 });
239
+ try {
240
+ const row = r.capture('lot');
241
+ r.state.now += 10 * 86400000;
242
+ const c = r.next();
243
+ assert.equal(c.spoolId, row.id); assert.equal(c.reviewDeadlineAtMs, undefined);
244
+ await r.finish(c);
245
+ assert.equal(r.reviews[0].deadline, undefined);
246
+ } finally { r.cleanup(); }
247
+ });
248
+
249
+ test('restart keeps retired frames retired; lifetime counts survive reclamation and pre-existing lifecycle files', async () => {
250
+ const r = rig(['counter']);
251
+ try {
252
+ for (let i = 0; i < 4; i++) { r.capture('counter'); r.state.now += 1000; }
253
+ await r.serve(); // reviews the newest of four, sheds three
254
+ r.state.now += 1000; const stale = r.capture('counter'); r.pump();
255
+ r.state.now += LIVE_BOUND_MS; r.pump(); // the last selection ages out
256
+ const expected = { freshnessMs: LIVE_BOUND_MS, pending: 0, selected: 5, reviewed: 1, shed: 3, expired: 1 };
257
+ assert.deepEqual(r.archives.get('counter').getReviewScheduleStats(), expected);
258
+ r.restartSpool();
259
+ const reopened = r.open('counter');
260
+ assert.deepEqual(reopened.getReviewScheduleStats(), expected);
261
+ assert.deepEqual(reopened.pendingOrderedCandidates(), []);
262
+ assert.equal(r.row('counter', stale.id).disposition, 'expired_unreviewed');
263
+ // Ordinary retention retires the unreviewed originals; their counts persist.
264
+ r.state.now += 600001;
265
+ for (let i = 0; i < 3; i++) { r.capture('counter'); await r.serve(); r.state.now += 1000; }
266
+ const lifecycle = JSON.parse(fs.readFileSync(path.join(r.root, 'archive-counter', 'ARCHIVE-LIFECYCLE.json')));
267
+ assert.equal(lifecycle.pruned.shed, 3); assert.equal(lifecycle.pruned.expired, 1);
268
+ assert.deepEqual(r.open('counter').getReviewScheduleStats(), { ...expected, selected: 8, reviewed: 4 });
269
+ // An archive written before these counters existed loads with zero retired frames.
270
+ const legacyDir = path.join(r.root, 'archive-legacy');
271
+ fs.mkdirSync(legacyDir, { recursive: true });
272
+ fs.writeFileSync(path.join(legacyDir, 'ARCHIVE-LIFECYCLE.json'), JSON.stringify({ version: 1, pending: null,
273
+ pruned: { captures: 9, selected: 4, reviewed: 4, received: 4, inactive: 0, grouped: 2 } }));
274
+ assert.deepEqual(r.open('legacy').stats().shedUnreviewed, 0);
275
+ assert.equal(r.open('legacy').stats().captures, 9);
276
+ } finally { r.cleanup(); }
277
+ });
278
+
279
+ test('an upgraded archive drops its old oldest-first backlog in bounded steps and reviews the newest frame first', async () => {
280
+ const r = rig([]);
281
+ try {
282
+ // The previous release: capture order, 40 selections a day old, 16 of them queued.
283
+ const legacy = r.open('counter', { realtimeReview: undefined });
284
+ r.state.now -= 86400000;
285
+ const backlog = [];
286
+ for (let i = 0; i < 40; i++) { backlog.push(r.capture('counter')); r.state.now += 1000; }
287
+ for (const c of legacy.pendingOrderedCandidates()) legacy.offered(c, r.spool().offer(c));
288
+ assert.equal(r.spool().getStats().buffered, 16);
289
+ // The upgrade: same disk, new release.
290
+ r.state.now = Date.parse('2026-11-03T15:00:00Z');
291
+ r.restartSpool();
292
+ r.open('counter');
293
+ const fresh = r.capture('counter');
294
+ r.pump();
295
+ assert.equal(r.spool().getStats().buffered, 1); // the 16 queued old frames left in the first pump
296
+ assert.equal(backlog.filter(row => r.row('counter', row.id).disposition === 'expired_unreviewed').length, 16);
297
+ assert.equal((await r.serve()).spoolId, fresh.id);
298
+ for (let i = 0; i < 3; i++) r.pump();
299
+ // A day old: past the live-alert bound, whatever replaced it.
300
+ assert.equal(backlog.every(row => r.row('counter', row.id).disposition === 'expired_unreviewed'), true);
301
+ assert.deepEqual(r.reviews.map(x => x.evidenceId), [fresh.id]);
302
+ assert.deepEqual(r.archives.get('counter').getReviewScheduleStats(),
303
+ { freshnessMs: LIVE_BOUND_MS, pending: 0, selected: 41, reviewed: 1, shed: 0, expired: 40 });
304
+ } finally { r.cleanup(); }
305
+ });
306
+
307
+ test('shed and expired counts reach the review receipt the server stores; the deadline reaches the model call', async () => {
308
+ const calls = [], uploads = [];
309
+ const local = new (take('localSensing').LocalSensingClient)({
310
+ analyze: async request => { calls.push(request); return { person_present: true }; },
311
+ }, { getEndpoint: () => ENDPOINT,
312
+ analyzePreAnalyzed: async (result, options) => {
313
+ uploads.push({ result, options: JSON.parse(JSON.stringify(options)) });
314
+ return { ok: true, statusCode: 200, body: { accepted: true, evidenceId: options.evidenceId,
315
+ evidenceReview: { version: 1, capturedAtMs: options.capturedAt } } };
316
+ } });
317
+ const r = rig(['counter'], { inner: local });
318
+ try {
319
+ r.capture('counter'); r.state.now += 1000; r.capture('counter'); r.state.now += 1000;
320
+ const reviewed = r.capture('counter');
321
+ r.state.now += 2000;
322
+ const c = r.next();
323
+ assert.equal(c.spoolId, reviewed.id);
324
+ await r.finish(c);
325
+ assert.equal(calls.length, 1);
326
+ assert.equal(calls[0].deadlineAtMs, reviewed.capturedAt + LIVE_BOUND_MS);
327
+ const schedule = uploads[0].options.extra.evidenceReview.schedule;
328
+ assert.deepEqual(schedule, { version: 1, slot: 'latest', freshnessMs: LIVE_BOUND_MS, startedAtMs: r.state.now,
329
+ selected: 3, reviewed: 0, shed: 2, expired: 0 });
330
+ // An upload retry reports the same frozen facts, so the server's payload hash holds.
331
+ await r.archives.get('counter').analyze({ jpeg: c.jpeg, capturedAt: c.enqueuedAtMs, evidenceId: c.spoolId,
332
+ reviewWindowMs: REVIEW_WINDOW_MS, reviewContext: c.reviewContext, cachedAnalysis: r.row('counter', c.spoolId).result,
333
+ checkpointAnalysis() {} });
334
+ assert.deepEqual(uploads[1].options.extra.evidenceReview.schedule, schedule);
335
+ assert.equal(calls.length, 1);
336
+ } finally { r.cleanup(); }
337
+ });
@@ -250,7 +250,7 @@ test('real website factory retains the captured contract and builds one/two slot
250
250
  localProvider: { analyze: () => { throw Error('No model call allowed'); } }, producerOptions: {}, producerInjected: false } })) };
251
251
  require.cache[modules[1].key].exports = { resolveFeeds: config => config.cameras,
252
252
  CloudSensingManager: class {
253
- constructor(options) { this.options = options; this.candidates = { offer: () => 'buffered' };
253
+ constructor(options) { this.options = options; this.candidates = { offer: () => 'buffered', withdraw: () => 'absent' };
254
254
  this.frameGroupers = new Map(options.loops.map(loop => [loop.name, {}])); }
255
255
  async start() { starts++; throw Error('No live manager start allowed'); }
256
256
  } };
@@ -269,6 +269,9 @@ test('real website factory retains the captured contract and builds one/two slot
269
269
  const website = await createWebsiteManager(automatic, path.join(directory, 'website-managed'));
270
270
  assert.equal(website.manager.options.maxConcurrentAnalyses, 1);
271
271
  for (const client of website.clients) {
272
+ // An API that serves no live-alert bound leaves the connector's review window in force.
273
+ assert.equal(client.getReviewScheduleStats().freshnessMs, 150000);
274
+ assert.equal(client.reviewQueue, website.manager.candidates);
272
275
  const actual = client.captureReviewContext();
273
276
  assert.deepEqual(actual.retainedFieldContract, fieldContext.retainedFieldContract);
274
277
  assert.deepEqual(actual.modelSelection, fieldContext.modelSelection);
@@ -316,7 +319,7 @@ test('normal website startup resolves thirteen paired cameras with two active pr
316
319
  capabilities++;
317
320
  if (denied) { res.writeHead(403).end('{}'); return; }
318
321
  res.end(JSON.stringify({ retainedReview: true, protocolVersion: 1, lateEvidenceAccepted: true,
319
- timedModes: ['any', 'wait_recheck'], cameraId, maxBodyBytes: 2 * 1024 * 1024 })); return;
322
+ timedModes: ['any', 'wait_recheck'], cameraId, maxBodyBytes: 2 * 1024 * 1024, maxCaptureAgeMs: 120000 })); return;
320
323
  }
321
324
  if (!url.pathname.endsWith('/sensing-profile')) { res.writeHead(405).end('{}'); return; }
322
325
  profiles++;
@@ -349,6 +352,9 @@ test('normal website startup resolves thirteen paired cameras with two active pr
349
352
  localProviderFactory: () => ({ analyze: () => { models++; throw Error('No inference in startup fixture'); } }) };
350
353
  const runtime = await createWebsiteManager(input, path.join(directory, 'state'), deps);
351
354
  assert.equal(runtime.loops.length, 13); assert.equal(capabilities, 13); assert.equal(profiles, 13);
355
+ // The server's own live-alert bound, not a second connector constant, schedules every camera.
356
+ assert.deepEqual([...new Set(runtime.clients.map(client => client.getReviewScheduleStats().freshnessMs))], [120000]);
357
+ assert.equal(runtime.clients.every(client => client.reviewQueue === runtime.manager.candidates), true);
352
358
  assert.equal(runtime.clients.filter(client => client.isReviewActive()).length, 2);
353
359
  assert.equal(runtime.clients.filter(client => !client.isReviewActive()).length, 11);
354
360
  for (const client of runtime.clients.slice(0, 2)) {
@@ -53,6 +53,11 @@ async function createWebsiteManager(input, stateDirectory, deps = {}) {
53
53
  // Complete every check before constructing cameras/providers. A failed gate
54
54
  // does not start capture, submit historical images, or change account settings.
55
55
  for (const feed of feeds) capabilities.set(feed.name, await (deps.capabilityCheck ?? checkRetainedApi)(base, feed));
56
+ // One live-alert age bound: the value the server suppresses late alerts with
57
+ // (SENSING_LOCAL_MAX_CAPTURE_AGE_MS), or this connector's review window when
58
+ // an older API does not serve it. Realtime reviews never start past it.
59
+ const served = [...capabilities.values()].map(c => c.maxCaptureAgeMs).filter(Number.isSafeInteger);
60
+ const freshnessMs = served.length ? Math.min(...served) : options.reviewWindowMs;
56
61
  fs.mkdirSync(stateDirectory, { recursive: true });
57
62
  const grouping = { mode: 'shadow', separateProfileWork: true, pixelDelta: 12,
58
63
  minChangedPixels: 12, quietIntervalMs: 10000, followUpMs: 1000 };
@@ -128,6 +133,8 @@ async function createWebsiteManager(input, stateDirectory, deps = {}) {
128
133
  maxCaptures: config.pilot.maxCapturesPerCamera, maxBytes: config.pilot.maxBytesPerCamera,
129
134
  archiveRetentionMs: config.pilot.archiveRetentionMs ?? 600000,
130
135
  offerWindow: rule.mode === 'wait_recheck' ? 1 : 16, unclearRetryMs: 2000,
136
+ // Latest frame wins per camera; capture-order contracts keep their window.
137
+ realtimeReview: { freshnessMs },
131
138
  ...(rule.mode==='immediate'?{actorPerceiver:new SelectedActorPerceptionClient(binding)}:{}),
132
139
  });
133
140
  loop.client = client; clients.push(client);
@@ -137,6 +144,7 @@ async function createWebsiteManager(input, stateDirectory, deps = {}) {
137
144
  candidateBuffer: { ...config.cloudSensing.candidateBuffer, diskSpool: {
138
145
  directory: path.join(stateDirectory, 'spool'), maxFrames: 512, maxPerFeed: 128,
139
146
  maxBytes: 512 * 1024 ** 2, preserveArchivedPending: true }, pumpIntervalMs: 50 } });
147
+ for (const client of clients) client.attachReviewQueue(manager.candidates);
140
148
  // The native manager constructs a shadow grouper per feed. Match it to the
141
149
  // exact policy recorded in that feed's durable archive before capture starts.
142
150
  const { FrameGroupingShadow } = take('FrameGroupingShadow');