@trillboards/edge-sdk 0.2.140 → 0.2.150

package/retained/manager.cjs

@@ -0,0 +1,133 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const assert = require('node:assert/strict');
+const take = name => require('../dist/' + name);
+const { checkRetainedApi } = require('./website-api-capability.cjs');
+
+// The normal connector's website entry point. Capability, strict profile and
+// artifact identity still pass before capture; this is not a second installer.
+async function createWebsiteManager(input, stateDirectory, deps = {}) {
+  const config = JSON.parse(JSON.stringify(input));
+  const { buildLocalSensingLoops } = take('localSensing');
+  const { CloudSensingManager, resolveFeeds } = take('CloudSensingManager');
+  const { TemporalReviewClient } = take('TemporalReviewClient');
+  const { TemporalReviewJournal } = take('TemporalReviewJournal');
+  const { RetainedCaptureClient } = require('./RetainedCaptureClient.cjs');
+  const { WaitRecheckCaptureClient } = require('./WaitRecheckCaptureClient.cjs');
+  const { validateRule, contractFor } = require('./alert-rule-policy.cjs');
+  const { retainedReviewApiBase } = take('continuousReview');
+  const options = config.cloudSensing?.candidateBuffer?.continuousReview;
+  assert(options?.enabled === true && options.deliveryTarget === 'configured-api'
+    && options.independentUploads === true && options.reviewWindowMs === 150000, 'Explicit website pilot settings required');
+  const base = retainedReviewApiBase(options, config.apiBaseUrl);
+  assert(base && typeof config.localSensing?.model === 'string' && config.localSensing.model.trim(),
+    'Use the paired API and an explicitly named local model; the artifact pin remains mandatory');
+  assert(config.localSensing.attachEvidenceFrame !== false,
+    'Pilot requires the original evidence image');
+  const feeds = resolveFeeds(config);
+  const websiteManaged = config.pilot?.websiteManaged === true;
+  assert(feeds.length && (websiteManaged || Object.keys(config.pilot?.alertRules ?? {}).length === feeds.length),
+    'Choose one explicit rule per active feed');
+  const capabilities = new Map();
+  // Complete every check before constructing cameras/providers. A failed gate
+  // does not start capture, submit historical images, or change account settings.
+  for (const feed of feeds) capabilities.set(feed.name, await (deps.capabilityCheck ?? checkRetainedApi)(base, feed));
+  fs.mkdirSync(stateDirectory, { recursive: true });
+  const grouping = { mode: 'shadow', separateProfileWork: true, pixelDelta: 12,
+    minChangedPixels: 12, quietIntervalMs: 10000, followUpMs: 1000 };
+  const groupingByFeed = new Map();
+  options.frameGrouping = grouping;
+  const pipeline = config.pilot.crossCameraPipelining === true;
+  assert(config.pilot.crossCameraPipelining === undefined || typeof config.pilot.crossCameraPipelining === 'boolean',
+    'Explicit stage-pipeline choice required');
+  assert(!pipeline || !websiteManaged && feeds.length <= 2 && options.overlapMixedReview !== true && options.parallelModelReview !== true
+    && options.scopedVlmReview !== true && options.detectorCounts !== true && config.pilot.requiresDetector === true,
+    'Stage pipeline is an isolated two-feed mixed-review experiment');
+  const stages = pipeline ? new (require('./ModelStageScheduler.cjs').ModelStageScheduler)() : null;
+  const loops = buildLocalSensingLoops(config, { ...deps, websiteManagedProfiles: websiteManaged,
+    profileClientFactory: deps.profileClientFactory ?? (feed => require('./pilot-profile-client.cjs').createPilotProfileClient(
+      { apiBaseUrl: config.apiBaseUrl, deviceToken: feed.deviceToken, screenId: feed.screenId },
+      { ...take('SensingProfileClient'), ...take('AudienceAnalyzeClient') }, deps.httpPoster)),
+  }), clients = [];
+  for (const loop of loops) {
+    const choice = websiteManaged ? null : config.pilot.alertRules[loop.name];
+    assert(websiteManaged || choice, 'Missing explicit feed rule');
+    // Ordinary website routes continue to own their conditions and delivery.
+    // No local guessed boolean/timer may suppress another saved route. The
+    // explicit rehearsal path retains its captured temporal rule unchanged.
+    const rule = websiteManaged ? { mode: 'immediate' } : validateRule(choice);
+    assert(['immediate', 'wait_recheck'].includes(rule.mode), 'Only immediate and wait/recheck are supported');
+    // Immediate rules need every changed view, not a redundant unchanged
+    // confirmation one second later. The existing temporal policy independently
+    // requires a real periodic review every five seconds. Wait/recheck keeps
+    // its original capture and timer semantics; do not group its observations.
+    const feedGrouping = { ...grouping, followUpMs: rule.mode === 'immediate' ? 5000 : grouping.followUpMs };
+    groupingByFeed.set(loop.name, feedGrouping);
+    let inner = loop.client;
+    await inner.prepareReview();
+    const context = inner.captureReviewContext();
+    const active = context.profileState !== 'inactive';
+    assert(websiteManaged || active, 'The explicitly selected pilot camera has no active profile');
+    assert(!active || context.modelSelection?.models?.length,'The active website profile has no pinned model selection');
+    for(const selected of context.modelSelection?.models ?? []){
+      if(selected.format==='litert-lm')assert(selected.sha256==='ab7838cdfc8f77e54d8ca45eadceb20452d9f01e4bfade03e5dce27911b27e42','Website selected a different Gemma artifact');
+      else assert(selected.format==='onnx'&&selected.modelId==='rfdetr_medium'
+        && selected.sha256==='8e8197112112b79d7cc5d0a94ecef659c05317a658aadc7c7643374c539d7615'
+        && config.pilot.requiresDetector===true,'The selected specialist requires an explicitly prepared runtime');
+    }
+    if (stages) {
+      assert(!context.detectorCounts && !context.scopedVlmReview && context.mixedModelExecution === undefined
+        && context.modelSelection.models.some(m => m.format === 'litert-lm')
+        && context.modelSelection.models.some(m => m.format === 'onnx'),
+        'Stage pipeline requires a complete retained mixed profile before capture starts');
+      inner = stages.wrap(inner);
+    }
+    inner = new (require('./ProfileAuthorityClient.cjs').ProfileAuthorityClient)(inner);
+    const fields = context.retainedFieldContract?.required ?? context.scopedVlmReview?.fields ?? [];
+    if (!websiteManaged && (rule.mode === 'wait_recheck' || fields.some(field => field.type === 'boolean'))) {
+      assert(typeof choice.field === 'string' && fields.some(field => field.field === choice.field && field.type === 'boolean'),
+        'Choose the exact paired boolean field, including its lasso field when applicable');
+      const basic = { version: 1, cameraId: loop.name, field: choice.field, mode: 'any',
+        minObservations: 1, durationMs: 0, maxGapMs: 2000, unknownPolicy: 'reset_confirmation_keep_alert_latch' };
+      // Both modes must go through the policy factory. Skipping it for an
+      // immediate boolean omitted groupedContinuity and queued every frame.
+      const contract = contractFor(basic, rule);
+      const journal = new TemporalReviewJournal(path.join(stateDirectory, 'journal-' + loop.name),100000,{retainAcknowledged:128});
+      journal.recoverAbandonedLocksUnderExclusiveHostLock();
+      inner = new TemporalReviewClient(inner, journal, contract, [], {
+        configuredApiBaseUrl: base, pairedCameraId: capabilities.get(loop.name).cameraId,
+      });
+    }
+    const Capture = rule.mode === 'wait_recheck' ? WaitRecheckCaptureClient : RetainedCaptureClient;
+    const client = new Capture(inner, path.join(stateDirectory, 'archive-' + loop.name), {
+      cameraId: loop.name, configuredApiBaseUrl: base, intervalMs: 500,
+      selectionMode: 'state-change-v1', groupingPolicy: feedGrouping,
+      maxCaptures: config.pilot.maxCapturesPerCamera, maxBytes: config.pilot.maxBytesPerCamera,
+      archiveRetentionMs: config.pilot.archiveRetentionMs ?? 600000,
+      offerWindow: rule.mode === 'wait_recheck' ? 1 : 16, unclearRetryMs: 2000,
+    });
+    loop.client = client; clients.push(client);
+  }
+  const manager = new CloudSensingManager({ loops, retainedApiBaseUrl: base, maxConcurrentAnalyses: pipeline ? 2 : 1, feedStaggerMs: 50,
+    periodicIntervalMs: 3600000, skipPostWhenNoFaces: false, motionGate: { enabled: true, scanIntervalMs: 500 },
+    candidateBuffer: { ...config.cloudSensing.candidateBuffer, diskSpool: {
+      directory: path.join(stateDirectory, 'spool'), maxFrames: 512, maxPerFeed: 128,
+      maxBytes: 512 * 1024 ** 2, preserveArchivedPending: true }, pumpIntervalMs: 50 } });
+  // The native manager constructs a shadow grouper per feed. Match it to the
+  // exact policy recorded in that feed's durable archive before capture starts.
+  const { FrameGroupingShadow } = take('FrameGroupingShadow');
+  assert(manager.frameGroupers instanceof Map, 'Native per-feed frame grouping is required');
+  for (const [name, policy] of groupingByFeed) {
+    assert(manager.frameGroupers.has(name), 'Missing native frame grouper');
+    manager.frameGroupers.set(name, new FrameGroupingShadow(policy));
+  }
+  const originalOffer = manager.candidates.offer.bind(manager.candidates);
+  manager.candidates.offer = candidate => {
+    const result = originalOffer(candidate);
+    loops.find(loop => loop.name === candidate.name).client.offered(candidate, result);
+    return result;
+  };
+  return { manager, clients, loops, ...(stages ? { stageScheduler: stages } : {}) };
+}
+module.exports = { createWebsiteManager };

package/retained/pilot-profile-client.cjs

@@ -0,0 +1,82 @@
+'use strict';
+const assert = require('node:assert/strict');
+const { randomUUID } = require('node:crypto');
+const { transportFailure } = require('./website-api-capability.cjs');
+const delays = [250, 750];
+async function nativeProfileRequest(poster, endpoint, request, body) {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      const result = await poster(endpoint, { ...request, timeoutMs: Math.min(request.timeoutMs || 10000, 10000),
+        headers: { ...request.headers, 'X-Device-Timestamp': String(Date.now()), 'X-Device-Nonce': randomUUID() } }, body);
+      if (result.statusCode < 200 || result.statusCode >= 300) {
+        throw Object.assign(Error('Pilot API profile request failed (HTTP ' + result.statusCode
+          + '). Check pairing/account access or API availability.'), {
+          code: 'PILOT_HTTP_' + result.statusCode, retryable: [500, 502, 503, 504].includes(result.statusCode), safePilotError: true });
+      }
+      return result;
+    } catch (raw) {
+      const error = raw.safePilotError ? raw : transportFailure(raw, 'profile');
+      if (!error.retryable || attempt > delays.length) {
+        error.attempts = attempt;
+        error.message += ' Attempts: ' + attempt + '. No camera was started by this check.';
+        throw error;
+      }
+      await new Promise(resolve => setTimeout(resolve, delays[attempt - 1]));
+    }
+  }
+}
+
+// The native SDK parser still owns field, lasso and model validation. Keep its
+// enterprise-aware HTTP poster: this patch does not bypass proxy or TLS trust.
+function createPilotProfileClient(options, sdk, poster) {
+  const base = options.apiBaseUrl.replace(/\/+$/, '');
+  const url = new URL(base);
+  const loopback = url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname);
+  assert(!url.username && !url.password && !url.search && !url.hash
+    && (url.origin === 'https://api.trillboards.com' || loopback), 'Use the verified SenseAnything API');
+  assert(typeof options.screenId === 'string' && options.screenId, 'A paired camera is required');
+  const original = base + '/v2/earner/cameras/sensing-profile';
+  const endpoint = base + '/v2/earner/cctv-retained/sensing-profile?screen_id=' + encodeURIComponent(options.screenId);
+  const native = poster === undefined || poster === sdk.defaultHttpPoster;
+  poster ??= sdk.defaultHttpPoster;
+  return {
+    getEndpoint: () => endpoint,
+    async fetchProfile() {
+      // Per-fetch error state avoids mixing failures from concurrent callers.
+      let requestError = null;
+      let raw;
+      const client = new sdk.SensingProfileClient(options, async (url, request, body) => {
+        assert(url === original && request.method === 'GET', 'Unexpected pilot profile request');
+        let result;
+        try { result = native ? await nativeProfileRequest(poster, endpoint, request, body) : await poster(endpoint, request, body); }
+        catch (error) { requestError = error; throw error; }
+        if (result.statusCode >= 200 && result.statusCode < 300) {
+          try { raw = JSON.parse(result.body); } catch { throw Error('Invalid experimental profile JSON'); }
+          assert(raw.screenId === options.screenId && raw.retainedPilot?.version === 1
+            && raw.retainedPilot.reviewFieldSet === 'declared', 'The API did not return this camera\'s experimental profile');
+        }
+        return result;
+      });
+      const profile = await client.fetchProfile();
+      if (!profile) {
+        if (requestError) throw requestError;
+        throw Error('The paired API did not resolve this camera profile; no default model was selected');
+      }
+      if (raw.profileState === 'inactive') {
+        assert(raw.profileId === null && raw.profileName === null && raw.profileType === null
+          && Array.isArray(raw.fields) && raw.fields.length === 0 && raw.modelSelection === null
+          && ['vlm', 'producer', 'withheld', 'alertFocusRegions'].every(key =>
+            Array.isArray(raw.fieldRouting?.[key]) && raw.fieldRouting[key].length === 0),
+        'Invalid inactive camera profile');
+        return { ...profile, profileState: 'inactive' };
+      }
+      assert(profile.modelSelection?.models?.length && !profile.modelSelection.invalid,
+        'The API did not supply a valid pinned selection');
+      assert(profile.retainedFieldContract?.required?.length,
+        'The API did not supply complete field ownership');
+      assert(profile.alertFocusRegionsValid !== false, 'The API supplied an invalid or missing camera area');
+      return { ...profile, profileState: 'active', websiteProfileType: profile.profileType, profileType: 'custom_intent' };
+    },
+  };
+}
+module.exports = { createPilotProfileClient };

package/retained/temporal-grouping.cjs

@@ -0,0 +1,78 @@
+'use strict';
+const assert=require('node:assert/strict'),fs=require('node:fs'),crypto=require('node:crypto');
+const hash=x=>crypto.createHash('sha256').update(x).digest('hex');
+const contextHash=c=>hash(JSON.stringify(c));
+
+// Selection is capture-time work. It never invents a model answer for grouped images.
+function selectTemporal(candidate,grouped,previous,lastSelected){
+ const context=candidate.reviewContext,contract=context.temporalReviewContract;
+ const policy=contract.groupedContinuity,at=candidate.enqueuedAtMs;
+ assert(policy.version===1 && policy.checkIntervalMs>=500 && policy.checkIntervalMs<=30000);
+ assert(policy.maxReviewGapMs>=policy.checkIntervalMs+contract.maxGapMs);
+ const rules=[contract,...(context.temporalComparisonContracts??[])];
+ assert(rules.every(r=>JSON.stringify(r.groupedContinuity)===JSON.stringify(policy)),'Temporal rules disagree on grouping');
+ const same=previous&&contextHash(previous.candidate.reviewContext)===contextHash(context);
+ const captureGap=!previous || at-previous.capturedAt>Math.min(...rules.map(r=>r.maxGapMs));
+ const scopes=candidate.groupingShadow?.scopes??[];
+ const valid=grouped.selectionReason==='group_selected'||grouped.selectionReason==='unchanged_with_saved_reference';
+ const comparisonUncertain=valid&&scopes.some(s=>s.reason==='uncertain');
+ const uncertain=!valid||comparisonUncertain;
+ const newSegment=!same||captureGap||uncertain||scopes.some(s=>['initial','changed'].includes(s.reason));
+ const segmentStartAtMs=newSegment?at:previous.temporalSchedule?.segmentStartAtMs??at;
+ const temporalSchedule={version:1,segmentStartAtMs};
+ // Missing grouping falls back to fresh reviews under the original timer rules.
+ // It cannot justify a coverage bridge, but definite, contiguous AI observations remain valid.
+ const base={temporalSchedule,temporalContinuityBroken:!same||captureGap||comparisonUncertain,temporalCoverageEligible:valid&&!comparisonUncertain};
+ const select=reason=>({...base,selected:true,disposition:'pending_review',selectionReason:reason});
+ if(!same||captureGap)return select('temporal_capture_or_context_boundary');
+ if(uncertain)return select('temporal_uncertain_comparison');
+ if(grouped.selected)return {...grouped,...base};
+ if(!lastSelected)return select('temporal_initial');
+ // Retain real model confirmations for entry and the existing clear/re-arm count.
+ const bootstrapCount=Math.max(...rules.map(r=>Math.max(r.minObservations,r.clearObservations??1)));
+ if(at<=segmentStartAtMs+(bootstrapCount-1)*500 && at-lastSelected.capturedAt>=500)
+  return select('temporal_confirmation');
+ if(rules.some(r=>r.mode==='duration'&&at>=segmentStartAtMs+r.durationMs&&lastSelected.capturedAt<segmentStartAtMs+r.durationMs))
+  return select('temporal_duration_checkpoint');
+ if(at-lastSelected.capturedAt>=policy.checkIntervalMs)return select('temporal_periodic_check');
+ return {...grouped,...base};
+}
+
+// Rebuild coverage from immutable capture records at review time, including after restart.
+// It is local evidence, never an API-provided assertion or a reused AI answer.
+function resolveTemporalCoverage(archive,current,contract){
+ if(!contract.groupedContinuity||!current.temporalCoverageEligible||current.temporalContinuityBroken||!current.previousSelectedId)return undefined;
+ const load=id=>{
+  assert(/^[a-f0-9]{32}$/.test(id),'Invalid coverage reference');
+  const r=JSON.parse(fs.readFileSync(archive.file(id),'utf8'));
+  assert(r.id===id&&r.cameraId===current.cameraId,'Coverage camera/identity mismatch');
+  assert(hash(fs.readFileSync(archive.image(r)))===r.imageSha256,'Coverage image missing or changed');
+  assert(contextHash(r.candidate.reviewContext)===contextHash(current.candidate.reviewContext),'Coverage context changed');
+  return r;
+ };
+ const from=load(current.previousSelectedId);
+ assert(from.selected&&from.capturedAt<current.capturedAt,'Invalid prior selected capture');
+ if(current.capturedAt-from.capturedAt>contract.groupedContinuity.maxReviewGapMs)return undefined;
+ const records=[current];let id=current.previousCaptureId;
+ while(id!==from.id){
+  assert(records.length<=128,'Coverage chain exceeds bounded window');
+  const r=load(id);
+  assert(!r.selected&&r.previousSelectedId===from.id,'Coverage crossed another selected review');
+  if(r.disposition!=='archived_grouped_unchanged'||r.temporalContinuityBroken)return undefined;
+  const verified=archive.groupingChoice(r.candidate,r.imageSha256);
+  assert(!verified.selected&&verified.selectionReason==='unchanged_with_saved_reference','Invalid grouped coverage');
+  records.push(r);id=r.previousCaptureId;
+ }
+ records.push(from);records.reverse();
+ let maxCaptureGapMs=0;
+ for(let i=1;i<records.length;i++){
+  const gap=records[i].capturedAt-records[i-1].capturedAt;
+  assert(gap>0,'Coverage capture order invalid');maxCaptureGapMs=Math.max(maxCaptureGapMs,gap);
+ }
+ if(maxCaptureGapMs>contract.maxGapMs)return undefined;
+ return {version:1,basis:'visually_unchanged_captures',fromEvidenceId:from.id,fromImageSha256:from.imageSha256,
+  fromCapturedAtMs:from.capturedAt,toCapturedAtMs:current.capturedAt,contextSha256:contextHash(current.candidate.reviewContext),
+  groupedCaptures:records.length-2,maxCaptureGapMs,
+  recordsSha256:hash(JSON.stringify(records.map(r=>({id:r.id,imageSha256:r.imageSha256,capturedAt:r.capturedAt,selected:r.selected,previousCaptureId:r.previousCaptureId,previousSelectedId:r.previousSelectedId}))))};
+}
+module.exports={selectTemporal,resolveTemporalCoverage};

package/retained/website-api-capability.cjs

@@ -0,0 +1,122 @@
+'use strict';
+const assert = require('node:assert/strict');
+const { randomUUID } = require('node:crypto');
+const http = require('node:http');
+const https = require('node:https');
+
+function endpoint(base) {
+  const url = new URL(base);
+  const local = ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname);
+  assert(!url.username && !url.password && !url.search && !url.hash
+    && (url.protocol === 'https:' || local && url.protocol === 'http:'), 'Invalid paired API URL');
+  return base.replace(/\/+$/, '') + '/v2/earner/cctv-retained/capabilities';
+}
+const TIMEOUT_MS = 10000;
+const RETRY_DELAYS_MS = [250, 750];
+const TRANSIENT_CODES = new Set(['ETIMEDOUT', 'ECONNRESET', 'ECONNREFUSED',
+  'ECONNABORTED', 'EPIPE', 'EAI_AGAIN', 'ENOTFOUND', 'ENETUNREACH', 'EHOSTUNREACH']);
+function failure(message, code, retryable = false) {
+  return Object.assign(Error(message), { code, retryable });
+}
+function transportFailure(error, label = 'capability') {
+  const nested = Array.isArray(error?.errors) ? error.errors.slice(0, 8) : [];
+  const codes = [...new Set([error?.code, error?.cause?.code,
+    ...(error?.failureClass === 'timeout' ? ['ETIMEDOUT'] : []), ...nested.map(item => item?.code)]
+    .filter(code => typeof code === 'string' && /^[A-Z0-9_]{1,64}$/.test(code)))];
+  if (!codes.length) codes.push('UNKNOWN_TRANSPORT_ERROR');
+  const tlsFailure = error?.failureClass?.startsWith('tls_') || codes.some(code => /TLS|CERT|SELF_SIGNED|UNABLE_TO_VERIFY|DEPTH_ZERO/.test(code));
+  const guidance = tlsFailure ? 'Check certificate trust and the computer clock; TLS verification was not bypassed.'
+    : 'Check network/DNS connectivity to api.trillboards.com.';
+  return failure('Pilot API ' + label + ' request failed (' + codes.join(', ') + '). ' + guidance,
+    codes[0], !tlsFailure && codes.some(code => TRANSIENT_CODES.has(code)));
+}
+
+// Bounded authenticated GETs before capture. Never print tokens, HTTP bodies or
+// raw error messages, follow redirects, or weaken account/TLS/contract checks.
+function requestCapability(url, feed) {
+  return new Promise((resolve, reject) => {
+    let settled = false, deadline;
+    const finish = (error, result) => {
+      if (settled) return;
+      settled = true; clearTimeout(deadline);
+      if (error) reject(error); else resolve(result);
+    };
+    let request;
+    try {
+      request = (url.protocol === 'https:' ? https : http).request(url, {
+        // Use the same enterprise proxy/trust transport as profiles/uploads,
+        // including SDK embedders that have not installed a global agent.
+        ...(url.protocol === 'https:' ? {
+          agent: require('../dist/enterpriseNetwork.js').getEnterpriseAgent(),
+        } : {}),
+        // Each retry gets a fresh timestamp and nonce.
+        method: 'GET', headers: { 'X-Device-Token': feed.deviceToken,
+          'X-Trillboard-Device-Token': feed.deviceToken,
+          'X-Device-Timestamp': String(Date.now()), 'X-Device-Nonce': randomUUID() },
+      }, response => {
+        let text = '', bytes = 0;
+        response.on('data', chunk => {
+          bytes += chunk.length;
+          if (bytes > 16384) {
+            finish(failure('Pilot API capability response too large', 'PILOT_RESPONSE_TOO_LARGE'));
+            response.destroy(); request.destroy();
+          } else text += chunk;
+        });
+        response.on('error', error => finish(transportFailure(error)));
+        response.on('aborted', () => finish(transportFailure({ code: 'ECONNRESET' })));
+        response.on('end', () => {
+          if (settled) return;
+          if (response.statusCode !== 200) {
+            const status = response.statusCode;
+            finish(failure('Pilot API is not enabled for this paired camera (HTTP ' + status
+              + '). Check pairing/account access or API availability.', 'PILOT_HTTP_' + status,
+              [500, 502, 503, 504].includes(status)));
+            return;
+          }
+          try {
+            let body;
+            try { body = JSON.parse(text); } catch { throw Error('Invalid pilot API capability JSON'); }
+            assert(body && body.retainedReview === true && body.protocolVersion === 1
+              && body.lateEvidenceAccepted === true && Array.isArray(body.timedModes)
+              && body.timedModes.includes('any') && body.timedModes.includes('wait_recheck')
+              && /^[A-Za-z0-9_-]{1,128}$/.test(body.cameraId)
+              && body.maxBodyBytes === 2 * 1024 * 1024, 'Unsupported pilot API capability');
+            assert(String(feed.screenId) === body.cameraId, 'Paired camera identity differs');
+            finish(null, { cameraId: body.cameraId, protocolVersion: 1 });
+          } catch (error) { finish(failure(error.message, 'PILOT_CAPABILITY_CONTRACT')); }
+        });
+      });
+    } catch (error) { finish(transportFailure(error)); return; }
+    const timeout = () => {
+      finish(transportFailure({ code: 'ETIMEDOUT' }));
+      request.destroy();
+    };
+    // A wall-clock deadline also covers DNS/TLS, not just socket inactivity.
+    deadline = setTimeout(timeout, TIMEOUT_MS);
+    request.setTimeout(TIMEOUT_MS, timeout);
+    request.on('error', error => finish(transportFailure(error)));
+    request.end();
+  });
+}
+function checkRetainedApi(base, feed) {
+  assert(typeof feed.deviceToken === 'string' && feed.deviceToken.length, 'Missing paired camera token');
+  assert(typeof feed.screenId === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(feed.screenId),
+    'Missing or invalid paired camera identity');
+  const url = new URL(endpoint(base));
+  // Device authentication requires URL binding; token-only identity is invalid.
+  url.searchParams.set('screen_id', feed.screenId);
+  return (async () => {
+    for (let attempt = 1; ; attempt++) {
+      try { return await requestCapability(url, feed); }
+      catch (error) {
+        if (!error.retryable || attempt > RETRY_DELAYS_MS.length) {
+          error.attempts = attempt;
+          error.message += ' Attempts: ' + attempt + '. No camera was started by this check.';
+          throw error;
+        }
+        await new Promise(resolve => setTimeout(resolve, RETRY_DELAYS_MS[attempt - 1]));
+      }
+    }
+  })();
+}
+module.exports = { checkRetainedApi, endpoint, transportFailure };