@trillboards/edge-sdk 0.2.140 → 0.2.151

package/retained/WaitRecheckCaptureClient.cjs

@@ -0,0 +1,109 @@
+'use strict';
+const fs=require('fs'),crypto=require('crypto'),assert=require('assert/strict');
+const {RetainedCaptureClient}=require('./RetainedCaptureClient.cjs');
+const {validateTemporalContract}=require('../dist/TemporalReviewJournal');
+const hash=x=>crypto.createHash('sha256').update(JSON.stringify(x)).digest('hex');
+function save(file,value){const tmp=file+'.rule-tmp',fd=fs.openSync(tmp,'w');try{fs.writeFileSync(fd,JSON.stringify(value));fs.fsyncSync(fd);}finally{fs.closeSync(fd);}fs.renameSync(tmp,file);}
+
+/** Select at the review boundary, not ahead of the first model answer.
+ * One outstanding selected observation per profile bounds admission. Capture is independent.
+ * Every deferred/omitted original remains on disk without a fabricated model result.
+ */
+class WaitRecheckCaptureClient extends RetainedCaptureClient {
+ constructor(client,directory,options){
+  super(client,directory,options);
+  this.deferred=new Map();this.waitOmitted=0;this.lastReview=null;this.unclearRetryMs=options.unclearRetryMs??0;assert(Number.isSafeInteger(this.unclearRetryMs)&&this.unclearRetryMs>=0&&this.unclearRetryMs<=5000,'Invalid unclear retry spacing');
+  const policy={version:1,unclearRetryMs:this.unclearRetryMs,dueRecheckPriority:'urgent'},policyFile=require('path').join(directory,'WAIT-POLICY.json');
+  if(fs.existsSync(policyFile))assert.deepEqual(JSON.parse(fs.readFileSync(policyFile)),policy,'Wait selection policy changed');else save(policyFile,policy);
+  const rows=fs.readdirSync(directory).filter(f=>/^[a-f0-9]{32}\.json$/.test(f)).map(f=>JSON.parse(fs.readFileSync(this.file(f.slice(0,32))))).sort((a,b)=>a.capturedAt-b.capturedAt);
+  for(const r of rows){
+   this.contract(r.candidate.reviewContext);
+   if(r.disposition==='awaiting_rule_decision')this.deferred.set(r.id,r);
+   if(r.disposition==='archived_wait_window')this.waitOmitted++;
+   if(r.result?.temporalReview)this.remember(r);
+  }
+  assert(this.entries.size<=1,'Wait/recheck archive has more than one outstanding selected observation');
+ }
+ contract(context){
+  const c=context?.temporalReviewContract;validateTemporalContract(c);
+  assert(c.mode==='wait_recheck'&&c.cameraId===this.cameraId,'Wrong wait/recheck contract');
+  assert(!(context.temporalComparisonContracts?.length),'Choose one alert rule per monitored area; comparisons use separate test arms');
+  assert(!context.orderedSequence&&!context.orderedCaptureContract,'Wait/recheck uses separately captured endpoint images');return c;
+ }
+ archivePins(){
+  const pins=super.archivePins();
+  for(const id of this.deferred?.keys()??[])pins.add(id);
+  if(this.lastReview?.decision.evidenceId)pins.add(this.lastReview.decision.evidenceId);
+  if(this.lastReview?.decision.waitAnchor)pins.add(this.lastReview.decision.waitAnchor.evidenceId);
+  return pins;
+ }
+ chooseReview(c,_digest,_due,stage){
+  this.contract(c.reviewContext);
+  return stage===null?{selected:false,disposition:'archived_profile_inactive'}:{selected:false,disposition:'awaiting_rule_decision'};
+ }
+ retainOrderedCapture(c){
+  const before=this.counts.captures;super.retainOrderedCapture(c);
+  if(this.counts.captures!==before){const r=this.previousCaptureRecord;if(r.disposition==='awaiting_rule_decision')this.deferred.set(r.id,r);}
+ }
+ remember(r){
+  const d=r.result.temporalReview;
+  assert(d.confirmationBasis==='first_and_follow_up'&&d.evidenceId===r.id&&d.imageSha256===r.imageSha256&&d.capturedAtMs===r.capturedAt,'Invalid saved wait/recheck decision');
+  if(!this.lastReview||r.capturedAt>=this.lastReview.capturedAt)this.lastReview={capturedAt:r.capturedAt,contextSha256:hash(r.candidate.reviewContext),decision:d};
+ }
+ async prepare(request){
+  const row=JSON.parse(fs.readFileSync(this.file(request.evidenceId))),anchor=row.ruleSelection?.anchor;
+  if(anchor){
+   assert(/^[a-f0-9]{32}$/.test(anchor.evidenceId),'Invalid wait anchor');
+   const first=JSON.parse(fs.readFileSync(this.file(anchor.evidenceId)));
+   assert(first.id===anchor.evidenceId&&first.imageSha256===anchor.imageSha256&&first.capturedAt===anchor.capturedAtMs
+    &&hash(first.candidate.reviewContext)===hash(row.candidate.reviewContext)&&first.result?.temporalReview?.value===true,'Wait anchor identity changed');
+   assert(crypto.createHash('sha256').update(fs.readFileSync(this.image(first))).digest('hex')===anchor.imageSha256,'Wait anchor image missing or changed');
+  }
+  const req=await super.prepare(request);this.remember(JSON.parse(fs.readFileSync(this.file(request.evidenceId))));return req;
+ }
+ pendingOrderedCandidates(){
+  // Includes delivery retry: never queue a second frame while the first is unresolved.
+  if(this.entries.size)return this.prioritize(super.pendingOrderedCandidates());
+  let processed=0;
+  for(const r of this.deferred.values()){
+   // Bounded work per pump keeps capture responsive even after a large backlog.
+   if(++processed>32)break;
+   const c=this.contract(r.candidate.reviewContext),contextSha256=hash(r.candidate.reviewContext);
+   const same=this.lastReview?.contextSha256===contextSha256;
+   const prior=same?this.lastReview.decision:null;
+   let select=false,reason='',grouped=null,dueAtMs=null;
+   if(!prior){select=true;reason='wait_initial_or_context_change';}
+   else if(prior.value==='unknown'){dueAtMs=prior.capturedAtMs+this.unclearRetryMs;select=r.capturedAt>=dueAtMs;reason=select?'wait_unclear_retry':'wait_unclear_retry_interval';}
+   else if(prior.alertLatched){dueAtMs=prior.capturedAtMs+c.followUpIntervalMs;select=r.capturedAt>=dueAtMs;reason=select?'wait_clear_check':'wait_alert_latched';}
+   else if(prior.waitAnchor){dueAtMs=prior.waitAnchor.capturedAtMs+c.durationMs;select=r.capturedAt>=dueAtMs;reason=select?'wait_deadline_check':'wait_timer_active';}
+   else {
+    grouped=this.selectionMode==='state-change-v1'?this.groupingChoice(r.candidate,r.imageSha256):{selected:true,selectionReason:'review_all_control'};
+    select=grouped.selected;reason=grouped.selectionReason;
+   }
+   // The mandatory endpoint check does not consult grouping or elapsed processing time.
+   r.ruleSelection={version:1,mode:'wait_recheck',reason,dueAtMs,fromEvidenceId:prior?.evidenceId??null,...(prior?.waitAnchor?{anchor:prior.waitAnchor}:{})};
+   r.selectionReason=reason;r.temporalContinuityBroken=!same;
+   if(select){
+    r.selected=true;r.disposition='pending_review';r.scheduledReviewPriority=prior?.waitAnchor&&r.capturedAt>=prior.waitAnchor.capturedAtMs+c.durationMs?'urgent':r.candidate.reviewPriority;save(this.file(r.id),r);
+    this.deferred.delete(r.id);this.entries.set(r.id,r);this.counts.selected++;
+    this.groupReferences.set(this.referenceKey(r.capturedAt,r.imageSha256,r.candidate.reviewContext),r.id);
+    if(this.groupReferences.size>256)this.groupReferences.delete(this.groupReferences.keys().next().value);
+    return this.prioritize(super.pendingOrderedCandidates());
+   }
+   if(grouped){r.disposition='archived_grouped_unchanged';r.groupReferenceIds=grouped.groupReferenceIds;save(this.file(r.id),r);this.counts.grouped++;}
+   else {r.disposition='archived_wait_window';save(this.file(r.id),r);this.waitOmitted++;}
+   this.records.set(r.id,r);
+   this.deferred.delete(r.id);
+  }
+  return [];
+ }
+ prioritize(items){return items.map(c=>{const r=this.entries.get(c.retainedId);return r?.scheduledReviewPriority?{...c,reviewPriority:r.scheduledReviewPriority}:c;});}
+ stats(){
+  const s=super.stats(),pendingRuleDecisions=this.deferred?.size??0,archivedWaitWindow=this.waitOmitted??0;
+  const first=this.deferred?.values().next().value?.capturedAt;
+  return {...s,archivedBetweenReviews:s.archivedBetweenReviews-pendingRuleDecisions-archivedWaitWindow,
+   pendingRuleDecisions,archivedWaitWindow,oldestPendingCapturedAt:s.oldestPendingCapturedAt??first??null,
+   waitingForDeadline:!!this.lastReview?.decision.waitAnchor&&!this.lastReview.decision.alertLatched};
+ }
+}
+module.exports={WaitRecheckCaptureClient};

package/retained/__tests__/archive-lifecycle.test.cjs

@@ -0,0 +1,117 @@
+'use strict';
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs'), path = require('node:path'), os = require('node:os');
+const { RetainedCaptureClient } = require('../RetainedCaptureClient.cjs');
+
+const endpoint = 'http://127.0.0.1:18791/v2/earner/audience-analyze';
+function fixture(extra = {}) {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'retained-lifecycle-fixture-'));
+  const client = {
+    getEndpoint: () => endpoint,
+    async reviewCandidate(req) { req.checkpointAnalysis({ fixture: true, evidenceSha256: require('node:crypto').createHash('sha256').update(req.jpeg).digest('hex') }); },
+    async analyze(req) { return { ok: true, body: { accepted: true, evidenceId: req.evidenceId, evidenceReview: { capturedAtMs: req.capturedAt } } }; },
+  };
+  const options = { cameraId: 'camera6', maxCaptures: 8, maxBytes: 100000, archiveRetentionMs: 500, ...extra };
+  const archive = new RetainedCaptureClient(client, directory, options);
+  function capture(at, label = String(at)) {
+    archive.retainOrderedCapture({ name: 'camera6', enqueuedAtMs: at,
+      jpeg: Buffer.from('synthetic-image-' + label), reviewContext: { version: 1 } });
+    return archive.previousCaptureRecord;
+  }
+  async function deliver(row) {
+    const req = { evidenceId: row.id, capturedAt: row.capturedAt, jpeg: fs.readFileSync(archive.image(row)),
+      reviewContext: row.candidate.reviewContext, checkpointAnalysis() {} };
+    await archive.analyze(req);
+  }
+  return { archive, client, directory, options, capture, deliver };
+}
+
+test('acknowledged originals are reclaimed without making lifetime counts the storage quota', async () => {
+  const f = fixture();
+  for (let i = 0; i < 100; i++) await f.deliver(f.capture(100000 + i * 500));
+  assert.equal(f.archive.stats().captures, 100);
+  assert.equal(f.archive.stats().received, 100);
+  assert(f.archive.stats().retainedCaptures <= 8);
+  assert(f.archive.stats().prunedCaptures > 90);
+  const recovered = new RetainedCaptureClient(f.client, f.directory, f.options);
+  assert.equal(recovered.stats().captures, 100);
+  assert.equal(recovered.stats().received, 100);
+  assert.equal(recovered.stats().pending, 0);
+  assert.equal(recovered.lastAt, 149500);
+  assert.equal(recovered.stats().logicalImageBytes, f.archive.stats().logicalImageBytes);
+});
+
+test('completed temporal heads do not pin all previous completed history', async () => {
+  const f = fixture();
+  for (let i = 0; i < 100; i++) {
+    const at = 100000 + i * 500;
+    f.archive.retainOrderedCapture({ name: 'camera6', enqueuedAtMs: at,
+      jpeg: Buffer.from('synthetic-temporal-' + i), reviewContext: {
+        temporalReviewContract: { groupedContinuity: { version: 1 } },
+      } });
+    await f.deliver(f.archive.previousCaptureRecord);
+  }
+  assert.equal(f.archive.stats().captures, 100);
+  assert(f.archive.stats().retainedCaptures <= 8);
+  assert(f.archive.stats().prunedCaptures > 90);
+});
+
+test('capacity pressure cannot discard an unresolved review or its exact image', async () => {
+  const f = fixture({ maxCaptures: 3 });
+  const first = f.capture(100000);
+  f.capture(100500); f.capture(101000);
+  assert.throws(() => f.capture(101500), /CAPTURE_STORAGE_EXHAUSTED/);
+  assert.equal(fs.existsSync(f.archive.file(first.id)), true);
+  assert.equal(fs.readFileSync(f.archive.image(first)).toString(), 'synthetic-image-100000');
+  assert.equal(f.archive.stats().pending, 3);
+  assert.equal(f.archive.stats().prunedCaptures, 0);
+});
+
+test('grouped and temporal references stay available until their pending consumer is acknowledged', async () => {
+  const f = fixture({ maxCaptures: 20 });
+  const first = f.capture(100000); await f.deliver(first);
+  const pending = f.capture(100500);
+  pending.groupReferenceIds = [first.id];
+  pending.candidate.reviewContext.temporalReviewContract = { groupedContinuity: { version: 1 } };
+  pending.previousSelectedId = first.id;
+  fs.writeFileSync(f.archive.file(pending.id), JSON.stringify(pending));
+  for (let i = 2; i < 12; i++) await f.deliver(f.capture(100000 + i * 500));
+  assert.equal(fs.existsSync(f.archive.file(first.id)), true);
+  assert.equal(fs.existsSync(f.archive.image(first)), true);
+  assert.equal(fs.existsSync(f.archive.file(pending.id)), true);
+  assert.equal(f.archive.stats().pending, 1);
+});
+
+test('reclamation deletes a shared image only after the last referencing record is retired', async () => {
+  const f = fixture();
+  const pending = f.capture(100000, 'shared');
+  await f.deliver(f.capture(100500, 'shared'));
+  for (let i = 2; i < 10; i++) await f.deliver(f.capture(100000 + i * 500));
+  assert.equal(fs.existsSync(f.archive.image(pending)), true);
+  await f.deliver(pending);
+  for (let i = 10; i < 15; i++) await f.deliver(f.capture(100000 + i * 500));
+  assert.equal(fs.existsSync(f.archive.image(pending)), false);
+});
+
+test('a committed reclamation resumes safely after interruption between record and image removal', async () => {
+  const f = fixture();
+  for (let i = 0; i < 4; i++) await f.deliver(f.capture(100000 + i * 500));
+  const unlink = fs.unlinkSync;
+  let interrupted = false;
+  fs.unlinkSync = file => {
+    if (!interrupted && file.endsWith('.jpg')) { interrupted = true; throw Error('synthetic interrupted cleanup'); }
+    return unlink(file);
+  };
+  try { assert.throws(() => f.capture(102000), /synthetic interrupted cleanup/); }
+  finally { fs.unlinkSync = unlink; }
+  const recovered = new RetainedCaptureClient(f.client, f.directory, f.options);
+  assert.equal(recovered.stats().captures, 4);
+  assert.equal(recovered.stats().received, 4);
+  assert.equal(recovered.stats().pending, 0);
+  assert.equal(JSON.parse(fs.readFileSync(path.join(f.directory, 'ARCHIVE-LIFECYCLE.json'))).pending, null);
+  for (const file of fs.readdirSync(f.directory).filter(name => /^[a-f0-9]{32}\.json$/.test(name))) {
+    const row = JSON.parse(fs.readFileSync(path.join(f.directory, file)));
+    assert.equal(fs.existsSync(recovered.image(row)), true);
+  }
+});

package/retained/__tests__/runtime.test.cjs

@@ -0,0 +1,384 @@
+'use strict';
+const { test } = require('node:test'), assert = require('node:assert/strict');
+const fs = require('node:fs'), path = require('node:path'), crypto = require('node:crypto');
+const http = require('node:http');
+const release = path.join(__dirname, '..');
+const take = name => require(path.join(release, '../dist', name));
+test('alert timing requires the authored structured website choice, not English heuristics', () => {
+  const { validateRule } = require('../alert-rule-policy.cjs');
+  assert.throws(() => validateRule('notify when the door has been left open'), /explicit timing mode/);
+  assert.throws(() => validateRule('alert immediately'), /explicit timing mode/);
+  assert.equal(validateRule({ mode: 'immediate' }).durationMs, 0);
+  assert.equal(validateRule({ mode: 'wait_recheck', durationMs: 10000 }).durationMs, 10000);
+});
+const { ProfileAuthorityClient, reconcilePresenceAlias } = require(path.join(release, 'ProfileAuthorityClient.cjs'));
+const { SerialModelLane, ModelStageScheduler } = require(path.join(release, 'ModelStageScheduler.cjs'));
+const sourceContract = {
+  "prompt": "Synthetic person-presence contract fixture",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "people_present": {
+        "type": "boolean"
+      },
+      "person_count": {
+        "type": "integer"
+      },
+      "confidence": {
+        "type": "number"
+      },
+      "face_count": {
+        "type": "integer"
+      }
+    },
+    "required": [
+      "people_present",
+      "person_count",
+      "confidence",
+      "face_count"
+    ]
+  },
+  "required": [
+    {
+      "field": "face_count",
+      "type": "counter"
+    },
+    {
+      "field": "person_count",
+      "type": "counter",
+      "modelId": "rfdetr_medium"
+    },
+    {
+      "field": "person_present",
+      "type": "boolean",
+      "modelId": "rfdetr_medium"
+    }
+  ],
+  "operatingPoints": [
+    [
+      "person",
+      0.5
+    ]
+  ],
+  "modelSelection": {
+    "version": 1,
+    "selectionId": "synthetic-contract",
+    "models": [
+      {
+        "modelId": "gemma_4_e2b",
+        "format": "litert-lm",
+        "sha256": "ab7838cdfc8f77e54d8ca45eadceb20452d9f01e4bfade03e5dce27911b27e42"
+      },
+      {
+        "modelId": "rfdetr_medium",
+        "format": "onnx",
+        "sha256": "8e8197112112b79d7cc5d0a94ecef659c05317a658aadc7c7643374c539d7615"
+      }
+    ],
+    "fieldOwners": [
+      {
+        "field": "face_count",
+        "modelId": "gemma_4_e2b"
+      },
+      {
+        "field": "person_count",
+        "modelId": "rfdetr_medium"
+      },
+      {
+        "field": "person_present",
+        "modelId": "rfdetr_medium"
+      }
+    ]
+  }
+};
+const digest = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+const clone = value => JSON.parse(JSON.stringify(value));
+function context() {
+  return { version: 1, prompt: sourceContract.prompt, schema: clone(sourceContract.schema),
+    retainedFieldContract: { version: 1, required: clone(sourceContract.required) },
+    producerFields: sourceContract.required.filter(f => f.modelId).map(f => ({ ...f })),
+    absenceWatchedFields: [], regions: [], operatingPoints: clone(sourceContract.operatingPoints),
+    modelSelection: clone(sourceContract.modelSelection) };
+}
+function request(overrides = {}) {
+  return { jpeg: Buffer.from('explicitly-synthetic-test-jpeg'), evidenceId: 'synthetic-proof', capturedAt: 100000,
+    reviewWindowMs: 150000, reviewContext: context(), checkpointAnalysis: () => {}, ...overrides };
+}
+function saved(req, structured = { face_count: 0, person_count: 0, person_present: false, people_present: true, confidence: .99 }) {
+  return { version: 1, structured, detectorProduced: { person_count: 'rfdetr_medium', person_present: 'rfdetr_medium' },
+    analyzeMs: 1, promptText: req.reviewContext.prompt, reviewedAtMs: 100001, evidenceSha256: digest(req.jpeg), hasSignal: true,
+    runtimeSelectionSha256: take('ProfileReviewWork').reviewContextHash(req.reviewContext) };
+}
+
+test('retained wrappers preserve the real native camera heartbeat and measured inference cost', async () => {
+  const directory = fs.mkdtempSync(path.join(require('node:os').tmpdir(), 'retained-health-fixture-'));
+  const health = { state: 'open', sensingState: 'unavailable', lastFrameAtMs: 100000 };
+  let reported;
+  const native = { getEndpoint: () => 'http://127.0.0.1:18791/v2/earner/audience-analyze',
+    getObservedAnalyzeMs: () => 1234, reportCameraHealth: async value => { reported = value; return { ok: true }; } };
+  const authority = new ProfileAuthorityClient(native);
+  const contract = { version: 1, cameraId: 'camera6', field: 'person_present', mode: 'any',
+    minObservations: 1, durationMs: 0, maxGapMs: 2000, unknownPolicy: 'reset_confirmation_keep_alert_latch' };
+  const temporal = new (take('TemporalReviewClient').TemporalReviewClient)(authority,
+    new (take('TemporalReviewJournal').TemporalReviewJournal)(path.join(directory, 'journal')), contract);
+  const capture = new (require('../RetainedCaptureClient.cjs').RetainedCaptureClient)(temporal,
+    path.join(directory, 'archive'), { cameraId: 'camera6' });
+  assert.equal((await capture.reportCameraHealth(health)).ok, true);
+  assert.equal(reported, health); assert.equal(capture.getObservedAnalyzeMs(), 1234);
+});
+test('positive RF verdict is not vetoed by a negative Gemma alias', () => {
+  const req = request(), result = reconcilePresenceAlias(saved(req,
+    { person_count: 1, person_present: true, people_present: false, face_count: 0, confidence: .99 }), req);
+  assert.equal(result.structured.people_present, true); assert.equal(result.hasSignal, true);
+});
+test('another configured signal is retained; person absence does not silence generic alerts', () => {
+  const req = request(), input = saved(req); input.structured.spill_present = true;
+  assert.equal(reconcilePresenceAlias(input, req).hasSignal, true);
+});
+test('RF-empty alias no longer creates a false signal by itself', () => {
+  const req = request(), result = reconcilePresenceAlias(saved(req), req);
+  assert.equal(result.structured.people_present, false); assert.equal(result.hasSignal, false);
+});
+test('absent specialist is unavailable, not a fabricated empty room', () => {
+  const req = request(), input = saved(req); delete input.detectorProduced.person_present;
+  assert.throws(() => reconcilePresenceAlias(input, req), /Incomplete retained review/);
+});
+test('model-selection and JPEG mismatches cannot pass a complete checkpoint', () => {
+  const req = request(); const image = saved(req); image.evidenceSha256 = '0'.repeat(64);
+  assert.throws(() => reconcilePresenceAlias(image, req), /different image/);
+  const identity = saved(req); identity.runtimeSelectionSha256 = '0'.repeat(64);
+  assert.throws(() => reconcilePresenceAlias(identity, req), /different captured/);
+});
+test('a count/presence inconsistency or forged cached correction stays an error', () => {
+  const req = request(), count = saved(req); count.structured.person_count = 1;
+  assert.throws(() => reconcilePresenceAlias(count, req), /RF presence\/count disagreement/);
+  const result = reconcilePresenceAlias(saved(req), req); result.authorityConsistency.evidenceSha256 = '0'.repeat(64);
+  assert.throws(() => reconcilePresenceAlias(result, req), /Cached authority/);
+});
+test('no declared RF ownership, independently owned alias, or lasso means no global override', () => {
+  for (const change of ['legacy', 'owned_alias', 'region', 'derived']) {
+    const req = request();
+    if (change === 'legacy') delete req.reviewContext.modelSelection;
+    if (change === 'owned_alias') {
+      req.reviewContext.retainedFieldContract.required.push({ field: 'people_present', type: 'boolean' });
+      req.reviewContext.modelSelection.fieldOwners.push({ field: 'people_present', modelId: 'gemma_4_e2b' });
+    }
+    if (change === 'region') req.reviewContext.regions = [['person_present', { points: [] }]];
+    if (change === 'derived') req.reviewContext.producerFields[0].derivation = { fixture: true };
+    const input = saved(req); assert.equal(reconcilePresenceAlias(input, req), input);
+  }
+});
+test('review and cached delivery use the same corrected answer and original raw value without another inference', async () => {
+  const req = request(); let calls = 0, posted;
+  const inner = { reviewCandidate: async r => { if (!r.cachedAnalysis) calls++; r.checkpointAnalysis(r.cachedAnalysis ?? saved(req)); },
+    analyze: async r => { posted = r; return { ok: true }; } };
+  const wrapped = new ProfileAuthorityClient(inner); let complete;
+  await wrapped.reviewCandidate({ ...req, checkpointAnalysis: value => { complete = value; } });
+  await wrapped.analyze({ ...req, cachedAnalysis: complete });
+  assert.equal(calls, 1); assert.equal(posted.cachedAnalysis.structured.people_present, false);
+  assert.equal(posted.extra.pilotAuthorityConsistency.rawValue, true); assert.equal(posted.jpeg, req.jpeg);
+});
+test('native LocalSensingClient completes all fields; compatibility repair is AFTER its RF merge', async () => {
+  const req = request(); let vlm = 0, detector = 0, uploaded;
+  const client = new (take('localSensing').LocalSensingClient)({ analyze: async () => {
+    vlm++; return { people_present: true, person_count: 4, confidence: .99, face_count: 0 };
+  } }, { getEndpoint: () => 'https://example.invalid/v2/earner/audience-analyze', analyzePreAnalyzed: async (result, extra) => {
+    uploaded = { result, extra }; return { ok: true }; } }, { retainedApiBaseUrl: 'https://example.invalid',
+    detectorFieldProducer: { produce: async () => { detector++; return { produced: [
+      { field: 'person_count', value: 0, modelId: 'rfdetr_medium' }, { field: 'person_present', value: false, modelId: 'rfdetr_medium' } ], withheld: [] }; } } });
+  const wrapped = new ProfileAuthorityClient(client); let complete;
+  await wrapped.reviewCandidate({ ...req, checkpointAnalysis: value => { complete = value; } });
+  assert.equal(complete.structured.person_count, 0); assert.equal(complete.structured.face_count, 0);
+  assert.equal(complete.structured.people_present, false); assert.equal(complete.hasSignal, false);
+  await wrapped.analyze({ ...req, cachedAnalysis: complete });
+  assert.equal(vlm, 1); assert.equal(detector, 1); assert.equal(uploaded.result.people_present, false);
+  assert.equal(uploaded.extra.capturedAt, req.capturedAt);
+});
+test('model lane never frees a still-running call on rejection of another model', async () => {
+  const lane = new SerialModelLane('test'); let release;
+  const first = lane.run(() => new Promise(resolve => { release = resolve; }));
+  await new Promise(resolve => setImmediate(resolve)); let secondStarted = false;
+  const second = lane.run(async () => { secondStarted = true; throw Error('expected failure'); });
+  const checked = assert.rejects(second, /expected failure/);
+  assert.equal(secondStarted, false); assert.equal(lane.stats().active, 1);
+  await assert.rejects(lane.run(() => {}), /overflow/);
+  release(); await first; await checked;
+  assert.equal(lane.stats().active, 0); assert.equal(lane.stats().pending, 0); assert.equal(lane.stats().maxActive, 1);
+});
+test('stage scheduler allows different model stages but binds each detector call to its own captured profile', async () => {
+  const modulePath = require.resolve(path.join(release, '../dist/DetectorFieldProducer'));
+  const original = require.cache[modulePath].exports, calls = [];
+  require.cache[modulePath].exports = { DetectorFieldProducer: class {
+    constructor(options) { this.options = options; }
+    async produce(jpeg, fields, pins) { calls.push({ sha: digest(jpeg), fields, pins, thresholds: [...this.options.classThresholds] });
+      await new Promise(resolve => setTimeout(resolve, 10)); return { produced: [], withheld: [] }; }
+  } };
+  try {
+    const scheduler = new ModelStageScheduler();
+    function client() { return { localProvider: { analyze: async () => { await new Promise(resolve => setTimeout(resolve, 10)); return {}; } },
+      producerOptions: { baseUrl: 'http://127.0.0.1:9384' }, producerInjected: false,
+      async reviewCandidate(req) { await this.localProvider.analyze({ jpeg: req.jpeg });
+        await this.producer.produce(req.jpeg, req.reviewContext.producerFields, new Map([['rfdetr_medium', 'fixture']])); } }; }
+    const first = request(), second = request({ jpeg: Buffer.from('other-synthetic-jpeg'), evidenceId: 'other', capturedAt: 100050 });
+    second.reviewContext.operatingPoints = [['person', .75]];
+    await Promise.all([scheduler.wrap(client()).reviewCandidate(first), scheduler.wrap(client()).reviewCandidate(second)]);
+    assert.deepEqual(calls.map(c => c.sha), [digest(first.jpeg), digest(second.jpeg)]);
+    assert.deepEqual(calls.map(c => c.thresholds), [[['person', .5]], [['person', .75]]]);
+    for (const lane of Object.values(scheduler.stats())) assert(lane.maxActive === 1 && lane.pending === 0 && lane.active === 0);
+  } finally { require.cache[modulePath].exports = original; }
+});
+test('stage scheduling rejects incompatible experiments and missing captured evidence', async () => {
+  const client = { localProvider: { analyze: async () => ({}) }, producerOptions: {}, producerInjected: false,
+    reviewCandidate: async () => {} };
+  const wrapped = new ModelStageScheduler().wrap(client);
+  assert.throws(() => wrapped.reviewCandidate({}), /original retained/);
+  const req = request(); req.reviewContext.mixedModelExecution = 'overlap_v1';
+  assert.throws(() => wrapped.reviewCandidate(req), /mix execution/);
+});
+test('real website factory retains the captured contract and builds one/two slots only with an explicit choice', async () => {
+  const names = [path.join(release, '../dist/localSensing'),
+    path.join(release, '../dist/CloudSensingManager'),
+    path.join(release, 'website-api-capability.cjs')];
+  const modules = names.map(name => { const key = require.resolve(name); require(key); return { key, prior: require.cache[key].exports }; });
+  const directory = fs.mkdtempSync(path.join(require('node:os').tmpdir(), 'retained-factory-fixture-'));
+  let starts = 0, apiChecks = 0;
+  const fieldContext = context();
+  try {
+    require.cache[modules[0].key].exports = { buildLocalSensingLoops: config => config.cameras.map(feed => ({ name: feed.name,
+      client: { prepareReview: async () => {}, captureReviewContext: () => clone(fieldContext),
+        getEndpoint: () => 'https://example.invalid/v2/earner/audience-analyze',
+        localProvider: { analyze: () => { throw Error('No model call allowed'); } }, producerOptions: {}, producerInjected: false } })) };
+    require.cache[modules[1].key].exports = { resolveFeeds: config => config.cameras,
+      CloudSensingManager: class {
+        constructor(options) { this.options = options; this.candidates = { offer: () => 'buffered' };
+          this.frameGroupers = new Map(options.loops.map(loop => [loop.name, {}])); }
+        async start() { starts++; throw Error('No live manager start allowed'); }
+      } };
+    require.cache[modules[2].key].exports = { checkRetainedApi: async (_base, feed) => { apiChecks++; return { cameraId: feed.screenId }; } };
+    delete require.cache[require.resolve(path.join(release, 'manager.cjs'))];
+    const { createWebsiteManager } = require(path.join(release, 'manager.cjs'));
+    const config = { apiBaseUrl: 'https://example.invalid', localSensing: { enabled: true, model: 'gemma-update' },
+      cameras: [{ name: 'camera6', screenId: 'screen6' }, { name: 'camera8', screenId: 'screen8' }],
+      pilot: { requiresDetector: true, maxCapturesPerCamera: 100, maxBytesPerCamera: 100000,
+        alertRules: { camera6: { field: 'person_present', mode: 'immediate', durationMs: 0 }, camera8: { field: 'person_present', mode: 'immediate', durationMs: 0 } } },
+      cloudSensing: { candidateBuffer: { continuousReview: { enabled: true, deliveryTarget: 'configured-api', independentUploads: true, reviewWindowMs: 150000 } } } };
+    const before = clone(config);
+    const automatic = clone(config);
+    automatic.pilot = { websiteManaged: true, requiresDetector: true,
+      maxCapturesPerCamera: 100, maxBytesPerCamera: 100000 };
+    const website = await createWebsiteManager(automatic, path.join(directory, 'website-managed'));
+    assert.equal(website.manager.options.maxConcurrentAnalyses, 1);
+    for (const client of website.clients) {
+      const actual = client.captureReviewContext();
+      assert.deepEqual(actual.retainedFieldContract, fieldContext.retainedFieldContract);
+      assert.deepEqual(actual.modelSelection, fieldContext.modelSelection);
+      assert.equal(actual.temporalReviewContract, undefined);
+      assert.equal(client.intervalMs, 500);
+    }
+    for (const pipeline of [false, true]) {
+      const selected = clone(config); if (pipeline) selected.pilot.crossCameraPipelining = true;
+      const runtime = await createWebsiteManager(selected, path.join(directory, pipeline ? 'pipelined' : 'serial'));
+      assert.equal(runtime.manager.options.maxConcurrentAnalyses, pipeline ? 2 : 1);
+      assert.equal(!!runtime.stageScheduler, pipeline);
+      for (const client of runtime.clients) {
+        const actual = client.captureReviewContext();
+        for (const field of ['schema', 'prompt', 'retainedFieldContract', 'producerFields', 'modelSelection', 'operatingPoints', 'regions'])
+          assert.deepEqual(actual[field], fieldContext[field]);
+        assert.equal(client.intervalMs, 500); assert.equal(actual.temporalReviewContract.groupedContinuity.checkIntervalMs, 5000);
+      }
+    }
+    assert.deepEqual(config, before); assert.equal(starts, 0); assert.equal(apiChecks, 6);
+    const incompatible = clone(config); incompatible.pilot.crossCameraPipelining = true;
+    incompatible.cloudSensing.candidateBuffer.continuousReview.overlapMixedReview = true;
+    await assert.rejects(createWebsiteManager(incompatible, path.join(directory, 'rejected')), /isolated two-feed/);
+  } finally {
+    for (const module of modules) require.cache[module.key].exports = module.prior;
+    delete require.cache[require.resolve(path.join(release, 'manager.cjs'))];
+  }
+});
+test('normal website startup resolves thirteen paired cameras with two active profiles and no manual pilot rules', async () => {
+  const directory = fs.mkdtempSync(path.join(require('node:os').tmpdir(), 'normal-website-fixture-'));
+  let opens = 0, models = 0, profiles = 0, capabilities = 0, denied = false;
+  const nonceSet = new Set();
+  const cameras = Array.from({ length: 13 }, (_, i) => ({ name: 'camera-' + i, screenId: 'screen_' + i,
+    deviceToken: 'synthetic-token-' + i, rtspUrl: 'rtsp://fixture.invalid/channel-' + i }));
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1'), cameraId = url.searchParams.get('screen_id');
+    const feed = cameras.find(camera => camera.screenId === cameraId);
+    const nonce = req.headers['x-device-nonce'];
+    if (!feed || req.headers['x-device-token'] !== feed.deviceToken || !nonce
+      || nonceSet.has(nonce) || !Number.isFinite(Number(req.headers['x-device-timestamp']))) {
+      res.writeHead(403).end('{}'); return;
+    }
+    nonceSet.add(nonce);
+    res.setHeader('Content-Type', 'application/json');
+    if (url.pathname.endsWith('/capabilities')) {
+      capabilities++;
+      if (denied) { res.writeHead(403).end('{}'); return; }
+      res.end(JSON.stringify({ retainedReview: true, protocolVersion: 1, lateEvidenceAccepted: true,
+        timedModes: ['any', 'wait_recheck'], cameraId, maxBodyBytes: 2 * 1024 * 1024 })); return;
+    }
+    if (!url.pathname.endsWith('/sensing-profile')) { res.writeHead(405).end('{}'); return; }
+    profiles++;
+    const active = feed === cameras[0] || feed === cameras[1];
+    const field = { field: 'door_open', type: 'boolean', description: 'Check this camera door.' };
+    res.end(JSON.stringify({ success: true, screenId: cameraId, profileState: active ? 'active' : 'inactive',
+      profileName: active ? 'Door profile' : null, profileId: active ? 'door-' + cameraId : null,
+      profileType: active ? 'custom_intent' : null, fields: active ? [field] : [], absenceWatchedFields: [],
+      retainedPilot: { version: 1, reviewFieldSet: 'declared' },
+      fieldRouting: { vlm: active ? [field] : [], producer: [], withheld: [], operatingPoints: {}, alertFocusRegions: [] },
+      modelSelection: active ? { version: 1, selectionId: 'door-' + cameraId,
+        models: [clone(sourceContract.modelSelection.models[0])],
+        fieldOwners: [{ field: 'door_open', modelId: 'gemma_4_e2b' }] } : null }));
+  });
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  try {
+    const config = take('sensingRunMode').configuredWebsiteReview({ apiBaseUrl: 'http://127.0.0.1:' + server.address().port,
+      cameras, localSensing: { enabled: true }, dataDir: directory });
+    const input = { ...config, pilot: { websiteManaged: true, requiresDetector: true } };
+    const { createWebsiteManager } = require('../manager.cjs');
+    const deps = { rtspProviderFactory: () => ({ isOpen: () => false,
+      open: async () => { opens++; throw Error('No capture is authorized by this startup fixture'); } }),
+      localProviderFactory: () => ({ analyze: () => { models++; throw Error('No inference in startup fixture'); } }) };
+    const runtime = await createWebsiteManager(input, path.join(directory, 'state'), deps);
+    assert.equal(runtime.loops.length, 13); assert.equal(capabilities, 13); assert.equal(profiles, 13);
+    assert.equal(runtime.clients.filter(client => client.isReviewActive()).length, 2);
+    assert.equal(runtime.clients.filter(client => !client.isReviewActive()).length, 11);
+    for (const client of runtime.clients.slice(0, 2)) {
+      const captured = client.captureReviewContext();
+      assert.equal(captured.retainedFieldContract.required[0].field, 'door_open');
+      assert.equal(captured.modelSelection.fieldOwners[0].modelId, 'gemma_4_e2b');
+      assert.equal(captured.temporalReviewContract, undefined);
+    }
+    assert.equal(opens, 0); assert.equal(models, 0);
+    denied = true;
+    await assert.rejects(createWebsiteManager(input, path.join(directory, 'denied'), deps), /HTTP 403/);
+    assert.equal(profiles, 13); assert.equal(opens, 0); assert.equal(models, 0);
+  } finally {
+    await new Promise((resolve, reject) => server.close(error => error ? reject(error) : resolve()));
+    fs.rmSync(directory, { recursive: true, force: true });
+  }
+});
+test('native durable spool enforces capture order and one in-flight review per feed, not one for the whole site', () => {
+  const directory = fs.mkdtempSync(path.join(require('node:os').tmpdir(), 'retained-spool-fixture-'));
+  const { DurableVlmCandidateSpool } = take('DurableVlmCandidateSpool');
+  let now = 101000;
+  const spool = new DurableVlmCandidateSpool({ directory, maxFrames: 64, maxBytes: 1000000, maxPerFeed: 32,
+    preserveArchivedPending: true, reviewWindowMs: 150000, retentionMs: 86400000, now: () => now });
+  spool.startRun();
+  const contract = { version: 1, cameraId: 'camera6', field: 'person_present', mode: 'any', minObservations: 1,
+    durationMs: 0, maxGapMs: 2000, unknownPolicy: 'reset_confirmation_keep_alert_latch' };
+  for (const [name, at] of [['camera6', 100000], ['camera6', 100500], ['camera8', 100050], ['camera8', 100550]]) {
+    const id = digest(Buffer.from(name + ':' + at)).slice(0, 32);
+    assert.equal(spool.offer({ name, jpeg: Buffer.from(name + ':' + at), enqueuedAtMs: at,
+      reviewContext: { ...context(), temporalReviewContract: { ...contract, cameraId: name },
+        retainedCapture: { version: 1, id, kind: 'retained_single_capture' } }, retainedId: id }), 'buffered');
+  }
+  const first = spool.take(undefined, 'review'), second = spool.take(undefined, 'review');
+  assert.notEqual(first.name, second.name); assert.equal(spool.peek(undefined, 'review'), null);
+  assert.equal(digest(first.jpeg), digest(Buffer.from(first.name + ':' + first.enqueuedAtMs)));
+  assert.equal(digest(second.jpeg), digest(Buffer.from(second.name + ':' + second.enqueuedAtMs)));
+  spool.retry(first); spool.retry(second);
+  now += 6000; // The native retry backoff is five seconds, not two.
+  const again = spool.take(undefined, 'review'); assert.equal(again.enqueuedAtMs, first.enqueuedAtMs);
+});

package/retained/alert-rule-policy.cjs

@@ -0,0 +1,37 @@
+'use strict';
+const assert=require('assert/strict');
+const {validateTemporalContract}=require('../dist/TemporalReviewJournal');
+const MODES=['immediate','wait_recheck','continuous_duration'];
+/** Website fields own timing. Free text cannot silently choose an alert timer. */
+function parseInstruction(text){
+ assert(typeof text==='string'&&text.trim().length&&text.length<=2000,'An alert instruction is required');
+ throw new Error('Choose an explicit timing mode and duration in the website alert settings; free-text timing is not inferred');
+}
+function validateRule(value){
+ if(typeof value==='string')return parseInstruction(value);
+ assert(value&&typeof value==='object'&&!Array.isArray(value)&&MODES.includes(value.mode),'Invalid alert rule');
+ const durationMs=value.durationMs??0;
+ assert(Number.isSafeInteger(durationMs)&&(value.mode==='immediate'?durationMs===0:durationMs>=500&&durationMs<=600000),'Duration must be 0 for immediate, or 0.5 to 600 seconds for timed rules');
+ const followUpIntervalMs=value.followUpIntervalMs??5000;
+ if(value.mode==='wait_recheck')assert(Number.isSafeInteger(followUpIntervalMs)&&followUpIntervalMs>=500&&followUpIntervalMs<=60000,'Invalid post-alert check interval');
+ else assert(value.followUpIntervalMs===undefined,'Follow-up interval belongs to wait/recheck only');
+ const label=value.mode==='immediate'?'Alert immediately':value.mode==='wait_recheck'?`Wait ${durationMs/1000} seconds, then check again`:`Check duration with intermediate evidence: ${durationMs/1000} seconds`;
+ return {mode:value.mode,durationMs,...(value.mode==='wait_recheck'?{followUpIntervalMs}:{}),source:value.source==='instruction'?'instruction':'explicit',label};
+}
+function contractFor(base,rule){
+ rule=validateRule(rule);const c={...base};delete c.groupedContinuity;delete c.followUpIntervalMs;
+ c.mode=rule.mode==='immediate'?'any':rule.mode==='continuous_duration'?'duration':'wait_recheck';
+ c.minObservations=rule.mode==='immediate'?1:2;c.durationMs=rule.durationMs;
+ c.unknownPolicy=rule.mode==='wait_recheck'?'keep_wait_anchor_retry_unknown':'reset_confirmation_keep_alert_latch';
+ if(rule.mode==='wait_recheck'){c.clearObservations=1;c.followUpIntervalMs=rule.followUpIntervalMs;}
+ else c.groupedContinuity=base.groupedContinuity??{version:1,checkIntervalMs:5000,maxReviewGapMs:Math.max(6000,5000+c.maxGapMs)};
+ validateTemporalContract(c);return c;
+}
+function applyAlertRules(plan,choices){
+ if(choices===null||choices===undefined)return plan; // Explicitly retain the earlier test configuration.
+ assert(choices&&typeof choices==='object'&&!Array.isArray(choices),'Choose alert rules per profile');
+ assert.deepEqual(Object.keys(choices).sort(),plan.profiles.map(p=>p.id).sort(),'Choose exactly the configured profiles');
+ const alertRules=Object.fromEntries(plan.profiles.map(p=>[p.id,validateRule(choices[p.id])]));
+ return {...plan,alertRules,profiles:plan.profiles.map(p=>({...p,alertRule:alertRules[p.id],temporal:contractFor(p.temporal,alertRules[p.id]),temporalComparisons:[]}))};
+}
+module.exports={parseInstruction,validateRule,contractFor,applyAlertRules};