@trillboards/edge-sdk 0.2.140 → 0.2.150

package/dist/DurableVlmCandidateSpool.js

@@ -38,6 +38,9 @@ const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const VlmCandidateBuffer_1 = require("./VlmCandidateBuffer");
+const ReviewPriority_1 = require("./ReviewPriority");
+const UrgentReviewTriage_1 = require("./UrgentReviewTriage");
+const ProfileReviewWork_1 = require("./ProfileReviewWork");
 const RECORD_VERSION = 1;
 const DEFAULT_MAX_FRAMES = 4096;
 const DEFAULT_MAX_PER_FEED = 128;
@@ -67,10 +70,24 @@ const DEFAULT_RETRY_MAX_MS = 5 * 60 * 1000;
  */
 class DurableVlmCandidateSpool {
     constructor(options) {
+        this.triageEligible = new Set();
+        this.triageFinished = new Set();
+        this.triagePositive = new Set();
+        this.triageOrder = new Map();
+        this.triageTick = 0;
+        this.priorityTurns = 0;
+        this.deliveryPriorityTurns = 0;
+        // At most one direct answer per camera, and 64 cameras total (under 8 MiB).
+        // No JPEGs, no chained reuse, no persistence or TTL renewal for this cache.
+        this.recentAnswers = new Map();
+        this.reusePrepared = 0;
+        this.capacityRejected = 0;
         this.feeds = new Map();
         this.inFlight = new Map();
         this.serveOrder = new Map();
         this.serveTick = 0;
+        this.deliveryServeTick = 0;
+        this.deliveryServeOrder = new Map();
         this.queued = 0;
         this.persisted = 0;
         this.persistedBytes = 0;
@@ -91,7 +108,26 @@ class DurableVlmCandidateSpool {
         this.maxPerEpisode = Math.min(this.maxPerFeed, Math.max(1, Math.trunc(options.maxPerEpisode ?? VlmCandidateBuffer_1.DEFAULT_CANDIDATES_PER_EPISODE)));
         this.episodeGapMs = Math.max(1, Math.trunc(options.episodeGapMs ?? VlmCandidateBuffer_1.DEFAULT_CANDIDATE_EPISODE_GAP_MS));
         this.maxBytes = Math.max(1, Math.trunc(options.maxBytes ?? DEFAULT_MAX_BYTES));
-        this.retentionMs = Math.max(1, Math.trunc(options.retentionMs ?? DEFAULT_RETENTION_MS));
+        this.retentionMs = Math.max(1, Math.trunc(options.retentionMs ??
+            (options.reviewWindowMs === undefined ? DEFAULT_RETENTION_MS : 86400000)));
+        this.reviewWindowMs = options.reviewWindowMs ?? null;
+        if (options.preserveArchivedPending && this.reviewWindowMs === null)
+            throw Error('Archived pending protection requires continuous review');
+        this.preserveArchivedPending = options.preserveArchivedPending === true;
+        if (options.priorityScheduling && this.reviewWindowMs === null) {
+            throw Error('Priority scheduling requires continuous review');
+        }
+        this.priorityScheduling = options.priorityScheduling === true;
+        if (options.urgentTriagePolicies && !this.priorityScheduling)
+            throw Error('Urgent triage requires priority scheduling');
+        this.urgentTriagePolicies = JSON.parse(JSON.stringify(options.urgentTriagePolicies ?? {}));
+        this.reuseExactPendingImages = this.reviewWindowMs !== null && options.reuseExactPendingImages === true;
+        this.reuseExactRecentImages = this.reviewWindowMs !== null && options.reuseExactRecentImages === true;
+        if (this.reviewWindowMs !== null && (!Number.isFinite(this.reviewWindowMs) || this.reviewWindowMs < 1 ||
+            this.retentionMs < this.reviewWindowMs ||
+            [this.retentionMs, this.maxFrames, this.maxPerFeed, this.maxBytes]
+                .some(value => !Number.isFinite(value) || value < 1)))
+            throw new Error('Invalid continuous review storage limits');
         this.retryInitialMs = Math.max(1, Math.trunc(options.retryInitialMs ?? DEFAULT_RETRY_INITIAL_MS));
         this.retryMaxMs = Math.max(this.retryInitialMs, Math.trunc(options.retryMaxMs ?? DEFAULT_RETRY_MAX_MS));
         this.now = options.now ?? Date.now;
@@ -119,7 +155,63 @@ class DurableVlmCandidateSpool {
         const now = nowMs ?? this.now();
         this.expire(now);
         const byteLength = candidate.jpeg.length;
+        if (candidate.reviewPriority !== undefined && !(0, ReviewPriority_1.isReviewPriority)(candidate.reviewPriority)) {
+            this.writeFailed++;
+            return 'rejected';
+        }
+        const contextBytes = candidate.reviewContext ? Buffer.byteLength(JSON.stringify(candidate.reviewContext)) : 0;
+        const groupingBytes = candidate.groupingShadow ? Buffer.byteLength(JSON.stringify(candidate.groupingShadow)) : 0;
+        const reservedResultBytes = this.reviewWindowMs === null ? 0 : 64 * 1024;
+        const profileWork = candidate.profileWork && candidate.groupingShadow
+            ? this.resolveProfileWork({ ...candidate, jpegSha256: crypto.createHash('sha256').update(candidate.jpeg).digest('hex'),
+                enqueuedAtMs: candidate.enqueuedAtMs ?? now }) : undefined;
+        // Separate experimental plans/results reserve 32 KiB each, without borrowing
+        // the normal full-result budget or duplicating the JPEG.
+        const profileBytes = profileWork ? 64 * 1024 : 0;
+        const configuredTriage = this.urgentTriagePolicies[candidate.name];
+        const urgentTriagePolicy = configuredTriage && candidate.reviewPriority === 'urgent'
+            && configuredTriage.contextSha256 === (0, UrgentReviewTriage_1.triageHash)(candidate.reviewContext) ? configuredTriage : undefined;
+        const admissionBytes = byteLength + contextBytes + groupingBytes + reservedResultBytes + profileBytes
+            + (urgentTriagePolicy ? UrgentReviewTriage_1.TRIAGE_RESERVED_BYTES : 0);
+        if (contextBytes > 64 * 1024) {
+            this.writeFailed++;
+            return 'rejected';
+        }
+        if (groupingBytes > 16 * 1024) {
+            this.writeFailed++;
+            return 'rejected';
+        }
         const feed = this.feedQueue(candidate.name);
+        const pending = [...feed.items, ...this.inFlight.values()].filter(e => e.name === candidate.name);
+        const digest = crypto.createHash('sha256').update(candidate.jpeg).digest('hex');
+        if (candidate.retainedId !== undefined) {
+            if (this.reviewWindowMs === null || !/^[a-f0-9]{32}$/.test(candidate.retainedId)
+                || (candidate.reviewContext?.orderedSequence?.id !== candidate.retainedId && !(candidate.reviewContext?.retainedCapture?.version === 1 && candidate.reviewContext?.retainedCapture?.kind === 'retained_single_capture' && candidate.reviewContext?.retainedCapture?.id === candidate.retainedId)))
+                return 'rejected';
+            const old = pending.find(e => e.id === candidate.retainedId);
+            if (old) {
+                if (old.jpegSha256 !== digest || old.enqueuedAtMs !== candidate.enqueuedAtMs
+                    || JSON.stringify(old.reviewContext) !== JSON.stringify(candidate.reviewContext))
+                    return 'rejected';
+                return 'coalesced';
+            }
+        }
+        // Temporal rehearsal retains each captured timestamp, even for identical JPEGs.
+        // Otherwise a still-open door loses the observations needed to measure duration.
+        if (this.reviewWindowMs !== null && !candidate.reviewContext?.temporalReviewContract && !candidate.reviewContext?.orderedSequence && !candidate.reviewContext?.retainedCapture && pending.some(e => e.jpegSha256 === digest &&
+            (0, ReviewPriority_1.reviewPriorityRank)(e.reviewPriority) === (0, ReviewPriority_1.reviewPriorityRank)(candidate.reviewPriority) &&
+            JSON.stringify(e.reviewContext) === JSON.stringify(candidate.reviewContext) &&
+            (candidate.reviewKind === 'sample' ? e.reviewKind === 'sample' : now - e.enqueuedAtMs < 1000))) {
+            feed.coalesced++;
+            this.coalesced++;
+            return 'coalesced';
+        }
+        // Preserve admitted evidence under pressure; count rejected new arrivals.
+        if (this.reviewWindowMs !== null && (pending.length >= this.maxPerFeed || this.persisted >= this.maxFrames ||
+            this.persistedBytes + admissionBytes > this.maxBytes)) {
+            this.capacityRejected++;
+            return 'rejected';
+        }
         if (byteLength > this.maxBytes) {
             feed.evicted++;
             this.evicted++;
@@ -131,9 +223,12 @@ class DurableVlmCandidateSpool {
         const episodeStartedAtMs = startsNewEpisode
             ? enqueuedAtMs
             : feed.episodeStartedAtMs ?? enqueuedAtMs;
-        const episodeEntries = this.currentEpisodeEntries(feed, episodeStartedAtMs)
-            .sort((a, b) => a.enqueuedAtMs - b.enqueuedAtMs || a.id.localeCompare(b.id));
-        const episodeAtCapacity = episodeEntries.length >= this.maxPerEpisode;
+        const episodeEntries = this.reviewWindowMs !== null ? [] :
+            this.currentEpisodeEntries(feed, episodeStartedAtMs)
+                .sort((a, b) => a.enqueuedAtMs - b.enqueuedAtMs || a.id.localeCompare(b.id));
+        // A later frame can contain a new short-lived action. Only legacy mode
+        // coalesces a whole motion episode to its first frames.
+        const episodeAtCapacity = this.reviewWindowMs === null && episodeEntries.length >= this.maxPerEpisode;
         feed.episodeStartedAtMs = episodeStartedAtMs;
         feed.lastCandidateAtMs = enqueuedAtMs;
         if (episodeAtCapacity) {
@@ -149,7 +244,7 @@ class DurableVlmCandidateSpool {
         }
         const entry = {
             version: RECORD_VERSION,
-            id: crypto.randomUUID().replace(/-/g, ''),
+            id: candidate.retainedId ?? crypto.randomUUID().replace(/-/g, ''),
             name: candidate.name,
             enqueuedAtMs,
             availableAtMs: now,
@@ -159,10 +254,22 @@ class DurableVlmCandidateSpool {
             imageWidth: candidate.imageWidth,
             imageHeight: candidate.imageHeight,
             byteLength,
-            jpegSha256: crypto.createHash('sha256').update(candidate.jpeg).digest('hex'),
+            jpegSha256: digest,
             attempts: 0,
             ...(candidate.detectorShadow ? { detectorShadow: candidate.detectorShadow } : {}),
+            ...(candidate.reviewKind ? { reviewKind: candidate.reviewKind } : {}),
+            ...(candidate.reviewPriority ? { reviewPriority: candidate.reviewPriority } : {}),
+            ...(candidate.reviewContext ? { reviewContext: candidate.reviewContext, contextBytes } : {}),
+            ...(candidate.groupingShadow ? { groupingShadow: candidate.groupingShadow, groupingBytes } : {}),
+            ...(reservedResultBytes ? { reservedResultBytes } : {}),
+            ...(profileWork ? { profileWork } : {}),
+            ...(urgentTriagePolicy ? { urgentTriagePolicy } : {}),
         };
+        const recentAnswer = this.exactRecentAnswer(entry, now);
+        if (recentAnswer) {
+            entry.cachedAnalysis = recentAnswer;
+            entry.resultBytes = Buffer.byteLength(JSON.stringify(recentAnswer));
+        }
         // Persist first. If the disk is unavailable, existing evidence remains
         // untouched and the caller gets a counted rejection instead of a false
         // claim that the event is durable.
@@ -172,7 +279,9 @@ class DurableVlmCandidateSpool {
             return 'rejected';
         }
         this.persisted++;
-        this.persistedBytes += byteLength;
+        this.persistedBytes += this.entryBytes(entry);
+        if (recentAnswer)
+            this.reusePrepared++;
         // A busy camera pays its own pressure first. Global pressure then evicts
         // from the fullest queued feed; in-flight evidence is never deleted.
         while (feed.items.length >= this.maxPerFeed)
@@ -185,29 +294,30 @@ class DurableVlmCandidateSpool {
         if (this.persisted > this.maxFrames || this.persistedBytes > this.maxBytes) {
             this.deletePair(entry);
             this.persisted--;
-            this.persistedBytes -= byteLength;
+            this.persistedBytes -= this.entryBytes(entry);
             feed.evicted++;
             this.evicted++;
             return 'rejected';
         }
         feed.items.push(entry);
+        this.restoreTriage(entry);
         this.sortFeed(feed);
         this.queued++;
         this.enqueued++;
         feed.enqueued++;
         return 'buffered';
     }
-    peek(nowMs) {
+    peek(nowMs, stage, accept) {
         const now = nowMs ?? this.now();
         this.expire(now);
-        const selected = this.nextEligible(now);
+        const selected = this.nextEligible(now, stage, accept);
         return selected ? this.asCandidate(selected.entry, Buffer.alloc(0)) : null;
     }
-    take(nowMs) {
+    take(nowMs, stage, accept) {
         const now = nowMs ?? this.now();
         this.expire(now);
         for (;;) {
-            const selected = this.nextEligible(now);
+            const selected = this.nextEligible(now, stage, accept);
             if (!selected)
                 return null;
             const { feed, index, entry } = selected;
@@ -237,7 +347,18 @@ class DurableVlmCandidateSpool {
             this.inFlight.set(entry.id, entry);
             feed.served++;
             this.served++;
-            this.serveOrder.set(feed.name, ++this.serveTick);
+            if (stage === 'delivery')
+                this.deliveryServeOrder.set(feed.name, ++this.deliveryServeTick);
+            else
+                this.serveOrder.set(feed.name, ++this.serveTick);
+            // Only a successful take spends a turn. peek(), blocked feeds and retry
+            // backoff never advance either independent lane's fairness state.
+            if (this.priorityScheduling) {
+                if (stage === 'delivery')
+                    this.deliveryPriorityTurns = (this.deliveryPriorityTurns + 1) % (ReviewPriority_1.PRIORITY_BURST + 1);
+                else
+                    this.priorityTurns = (this.priorityTurns + 1) % (ReviewPriority_1.PRIORITY_BURST + 1);
+            }
             return this.asCandidate(entry, jpeg);
         }
     }
@@ -253,8 +374,247 @@ class DurableVlmCandidateSpool {
         this.removePersisted(entry);
         this.completed++;
     }
+    /** Commit a model result before upload, so network retries do not repeat inference. */
+    checkpoint(candidate, result) {
+        const entry = candidate.spoolId ? this.inFlight.get(candidate.spoolId) : undefined;
+        if (!entry)
+            throw new Error('Evidence is not in flight');
+        const bytes = Buffer.byteLength(JSON.stringify(result));
+        const delta = entry.reservedResultBytes ? 0 : bytes - (entry.resultBytes ?? 0);
+        if (bytes > 64 * 1024 || this.persistedBytes + delta > this.maxBytes) {
+            this.writeFailed++;
+            throw new Error('Evidence result exceeds the storage budget');
+        }
+        entry.cachedAnalysis = result;
+        delete entry.scopedVlmProgress;
+        entry.resultBytes = bytes;
+        this.persistedBytes += delta;
+        if (!this.writeMetadata(entry)) {
+            // Keep the answer in memory while disk recovers. The client retries
+            // this checkpoint before uploading, without spending another model call.
+            throw new Error('Could not persist the model result');
+        }
+        this.prepareExactPendingAnswers(entry, result);
+        this.rememberDirectAnswer(entry, result);
+    }
+    /** Partial scope work uses the already reserved result budget, never upload eligibility. */
+    checkpointScopedReview(candidate, progress) {
+        const entry = candidate.spoolId ? this.inFlight.get(candidate.spoolId) : undefined;
+        if (!entry || entry.cachedAnalysis || !entry.reviewContext?.scopedVlmReview || entry.reservedResultBytes !== 64 * 1024) {
+            throw Error('Scoped checkpoint requires unreviewed durable evidence');
+        }
+        if (Buffer.byteLength(JSON.stringify(progress)) > entry.reservedResultBytes) {
+            this.writeFailed++;
+            throw Error('Scoped checkpoint exceeds the reserved result budget');
+        }
+        entry.scopedVlmProgress = JSON.parse(JSON.stringify(progress));
+        if (!this.writeMetadata(entry))
+            throw Error('Could not persist scoped review progress');
+    }
+    /** Revalidate group references against committed evidence, then commit the job selection. */
+    prepareProfileWork(candidate) {
+        const entry = candidate.spoolId ? this.inFlight.get(candidate.spoolId) : undefined;
+        if (!entry?.profileWork || !entry.reviewContext)
+            throw Error('No durable profile work');
+        const work = this.resolveProfileWork(entry);
+        if (!work)
+            throw Error('Invalid durable profile work');
+        entry.profileWork = work;
+        if (!this.writeMetadata(entry))
+            throw Error('Could not persist profile work selection');
+        return JSON.parse(JSON.stringify(work));
+    }
+    /** Rehearsal output is never cachedAnalysis and cannot become a delivery job. */
+    checkpointProfileWork(candidate, result) {
+        const entry = candidate.spoolId ? this.inFlight.get(candidate.spoolId) : undefined;
+        const work = entry?.profileWork;
+        if (!entry || !work || !entry.reviewContext || result.version !== 1 || result.kind !== 'profile_work_rehearsal' ||
+            result.evidenceId !== entry.id || result.imageSha256 !== entry.jpegSha256 || result.contextSha256 !== work.contextSha256 ||
+            result.capturedAtMs !== entry.enqueuedAtMs || !Number.isFinite(result.reviewedAtMs) ||
+            JSON.stringify(result.selectedFields) !== JSON.stringify(work.items.filter(i => i.selected).map(i => i.field)) ||
+            JSON.stringify(result.unreviewedFields) !== JSON.stringify(work.items.filter(i => !i.selected).map(i => i.field)) ||
+            !result.structured || typeof result.structured !== 'object' || Array.isArray(result.structured) ||
+            Object.keys(result.structured).some(f => !result.selectedFields.includes(f)) ||
+            !Array.isArray(result.unresolvedFields) || result.unresolvedFields.some(f => !result.selectedFields.includes(f)) ||
+            Buffer.byteLength(JSON.stringify(result)) > 32 * 1024)
+            throw Error('Invalid profile work result');
+        entry.profileWorkResult = JSON.parse(JSON.stringify(result));
+        if (!this.writeMetadata(entry))
+            throw Error('Could not persist profile work result');
+    }
+    resolveProfileWork(entry) {
+        if (!entry.reviewContext || !entry.groupingShadow || !entry.jpegSha256)
+            return undefined;
+        const work = (0, ProfileReviewWork_1.planProfileReview)(entry.reviewContext, entry.groupingShadow);
+        if (!work)
+            return undefined;
+        try {
+            (0, ProfileReviewWork_1.validateProfileWork)(work, entry.reviewContext, entry.jpegSha256, entry.enqueuedAtMs);
+        }
+        catch {
+            return undefined;
+        }
+        const pending = [...(this.feeds.get(entry.name)?.items ?? []), ...this.inFlight.values()];
+        for (const item of work.items.filter(i => !i.selected)) {
+            const source = pending.find(e => e.name === entry.name && e.enqueuedAtMs === item.referenceCapturedAtMs &&
+                e.enqueuedAtMs < entry.enqueuedAtMs && e.jpegSha256 === item.referenceSha256 &&
+                e.profileWork?.contextSha256 === work.contextSha256 && Array.isArray(e.profileWork.items) &&
+                e.profileWork.items.some(i => i.field === item.field && i.selected) &&
+                fs.existsSync(this.metadataPath(e.id)) && fs.existsSync(this.jpegPath(e.id)));
+            if (source)
+                item.referenceEvidenceId = source.id;
+            else {
+                item.selected = true;
+                item.reason = 'missing_durable_reference';
+                delete item.referenceSha256;
+                delete item.referenceCapturedAtMs;
+            }
+        }
+        (0, ProfileReviewWork_1.promoteProfileDependencies)(work);
+        return Buffer.byteLength(JSON.stringify(work)) <= 32 * 1024 ? work : undefined;
+    }
+    /** Read-only test/audit surface; no reference is exposed before writePair commits. */
+    inspectProfileWork(name, capturedAtMs, sha256) {
+        const entry = [...(this.feeds.get(name)?.items ?? []), ...this.inFlight.values()].find(e => e.name === name && e.enqueuedAtMs === capturedAtMs && e.jpegSha256 === sha256 && e.profileWork);
+        return entry ? { evidenceId: entry.id, work: JSON.parse(JSON.stringify(entry.profileWork)) } : null;
+    }
+    /** A raw archive ID names this receipt, not a different visual question.
+     * Keep all selected IDs and original timestamps; share only the exact answer.
+     * Temporal/ordered observations still have no answer-reuse permission.
+     */
+    exactAnswerContext(entry) {
+        const context = entry.reviewContext;
+        if (!context || context.temporalReviewContract || context.orderedSequence || context.orderedCaptureContract)
+            return undefined;
+        if (context.retainedCapture === undefined)
+            return context;
+        const ref = context.retainedCapture;
+        if (ref?.version !== 1 || ref.kind !== 'retained_single_capture' || ref.id !== entry.id ||
+            Object.keys(ref).sort().join(',') !== 'id,kind,version')
+            return undefined;
+        const normalized = { ...context };
+        delete normalized.retainedCapture;
+        return normalized;
+    }
+    rememberDirectAnswer(source, result) {
+        const sourceContext = this.exactAnswerContext(source);
+        if (!sourceContext)
+            return;
+        if (!this.reuseExactRecentImages || !source.reviewContext || !source.jpegSha256 ||
+            result.version !== 1 || result.evidenceSha256 !== source.jpegSha256 ||
+            result.reusedFromEvidenceId !== undefined || result.reuseMethod !== undefined ||
+            typeof result.reviewedAtMs !== 'number' || !Number.isFinite(result.reviewedAtMs) ||
+            result.reviewedAtMs < source.enqueuedAtMs || result.reviewedAtMs > this.now() ||
+            this.now() - source.enqueuedAtMs > this.reviewWindowMs)
+            return;
+        this.recentAnswers.delete(source.name);
+        this.recentAnswers.set(source.name, {
+            id: source.id, capturedAtMs: source.enqueuedAtMs, reviewedAtMs: result.reviewedAtMs,
+            jpegSha256: source.jpegSha256, imageWidth: source.imageWidth, imageHeight: source.imageHeight,
+            context: JSON.stringify(sourceContext), result,
+        });
+        if (this.recentAnswers.size > 64)
+            this.recentAnswers.delete(this.recentAnswers.keys().next().value);
+    }
+    exactRecentAnswer(entry, now) {
+        const entryContext = this.exactAnswerContext(entry);
+        if (!entryContext)
+            return undefined;
+        if (!this.reuseExactRecentImages || !entry.reviewContext)
+            return undefined;
+        for (const [name, answer] of this.recentAnswers) {
+            if (now - answer.capturedAtMs > this.reviewWindowMs)
+                this.recentAnswers.delete(name);
+        }
+        const source = this.recentAnswers.get(entry.name);
+        if (!source || entry.enqueuedAtMs < source.reviewedAtMs || entry.enqueuedAtMs > now ||
+            now < source.reviewedAtMs || entry.enqueuedAtMs - source.capturedAtMs > this.reviewWindowMs ||
+            entry.jpegSha256 !== source.jpegSha256 || entry.imageWidth !== source.imageWidth ||
+            entry.imageHeight !== source.imageHeight || JSON.stringify(entryContext) !== source.context)
+            return undefined;
+        const answer = { ...source.result, analyzeMs: 0, reviewedAtMs: now,
+            reusedFromEvidenceId: source.id, reuseMethod: 'exact_recent',
+            sourceCapturedAtMs: source.capturedAtMs, sourceReviewedAtMs: source.reviewedAtMs };
+        return Buffer.byteLength(JSON.stringify(answer)) <= 64 * 1024 ? answer : undefined;
+    }
+    /**
+     * Share a completed answer, never discard a visually similar frame. Every
+     * recipient remains a separate durable candidate until its own receiver ack.
+     * This pending-only path excludes future captures, and profile/camera boundaries
+     * are never crossed. A changed JPEG, however small the change, is ineligible.
+     */
+    prepareExactPendingAnswers(source, result) {
+        const sourceContext = this.exactAnswerContext(source);
+        if (!sourceContext)
+            return;
+        if (!this.reuseExactPendingImages || !source.reviewContext || !source.jpegSha256 ||
+            result.version !== 1 || result.evidenceSha256 !== source.jpegSha256 ||
+            result.reusedFromEvidenceId !== undefined || typeof result.reviewedAtMs !== 'number' ||
+            !Number.isFinite(result.reviewedAtMs) || result.reviewedAtMs < source.enqueuedAtMs)
+            return;
+        const context = JSON.stringify(sourceContext);
+        const answer = { ...result, reusedFromEvidenceId: source.id };
+        const bytes = Buffer.byteLength(JSON.stringify(answer));
+        if (bytes > 64 * 1024)
+            return; // The original result still remains usable.
+        for (const pending of this.feeds.get(source.name)?.items ?? []) {
+            if (pending.cachedAnalysis || pending.jpegSha256 !== source.jpegSha256 ||
+                pending.enqueuedAtMs > result.reviewedAtMs ||
+                Math.abs(pending.enqueuedAtMs - source.enqueuedAtMs) > this.reviewWindowMs ||
+                pending.imageWidth !== source.imageWidth || pending.imageHeight !== source.imageHeight ||
+                JSON.stringify(this.exactAnswerContext(pending)) !== context)
+                continue;
+            const delta = pending.reservedResultBytes ? 0 : bytes - (pending.resultBytes ?? 0);
+            if (this.persistedBytes + delta > this.maxBytes)
+                continue;
+            pending.cachedAnalysis = answer;
+            delete pending.scopedVlmProgress;
+            pending.resultBytes = bytes;
+            this.persistedBytes += delta;
+            // If disk fails, keep the answer in memory. Serving this candidate retries
+            // its own checkpoint before upload; recovery can safely recompute it.
+            if (this.writeMetadata(pending))
+                this.reusePrepared++;
+        }
+    }
+    /** Move a committed answer to the independent delivery lane. */
+    readyForDelivery(candidate) {
+        const entry = candidate.spoolId ? this.inFlight.get(candidate.spoolId) : undefined;
+        if (!entry?.cachedAnalysis)
+            throw new Error('Delivery requires a saved model result');
+        if (!this.reviewComplete(entry))
+            throw new Error('Temporal decision must be committed before delivery');
+        // Commit before changing ownership. A failed write leaves this in flight so
+        // the caller can retry the same result; it never becomes an acknowledged alert.
+        entry.availableAtMs = this.now();
+        entry.attempts = 0;
+        if (!this.writeMetadata(entry))
+            throw new Error('Could not persist delivery handoff');
+        this.inFlight.delete(entry.id);
+        const feed = this.feedQueue(entry.name);
+        feed.items.push(entry);
+        this.sortFeed(feed);
+        this.queued++;
+    }
     /** Keep the same evidence and retry it after bounded exponential backoff. */
     retry(candidate, nowMs) {
+        this.requeue(candidate, nowMs, false);
+    }
+    /**
+     * Retry a saved answer after a short connectivity probe interval. The manager
+     * shares this pause across its single upload lane, so a large offline queue
+     * cannot turn one connection failure into one request per saved image.
+     */
+    retryDelivery(candidate, nowMs) {
+        const entry = candidate.spoolId ? this.inFlight.get(candidate.spoolId) : undefined;
+        if (this.reviewWindowMs === null || !entry?.cachedAnalysis) {
+            throw new Error('Delivery retry requires a saved continuous-review answer');
+        }
+        const now = nowMs ?? this.now();
+        this.requeue(candidate, now, true);
+        return now + this.retryInitialMs;
+    }
+    requeue(candidate, nowMs, delivery) {
         const id = candidate.spoolId;
         if (!id)
             return;
@@ -263,7 +623,7 @@ class DurableVlmCandidateSpool {
             return;
         this.inFlight.delete(id);
         entry.attempts += 1;
-        const delay = Math.min(this.retryMaxMs, this.retryInitialMs * Math.pow(2, Math.min(16, entry.attempts - 1)));
+        const delay = delivery ? this.retryInitialMs : Math.min(this.retryMaxMs, this.retryInitialMs * Math.pow(2, Math.min(16, entry.attempts - 1)));
         entry.availableAtMs = (nowMs ?? this.now()) + delay;
         this.writeMetadata(entry);
         const feed = this.feedQueue(entry.name);
@@ -278,6 +638,15 @@ class DurableVlmCandidateSpool {
         for (const feed of this.feeds.values()) {
             for (let i = feed.items.length - 1; i >= 0; i--) {
                 const entry = feed.items[i];
+                // A completed review is pending delivery, even after the evidence age
+                // target. Refuse new work at capacity rather than erase an unsent result.
+                if (this.reviewWindowMs !== null && entry.cachedAnalysis)
+                    continue;
+                const archiveRef = entry.reviewContext?.retainedCapture;
+                if (this.preserveArchivedPending && archiveRef?.version === 1 &&
+                    archiveRef.kind === 'retained_single_capture' && archiveRef.id === entry.id &&
+                    Object.keys(archiveRef).sort().join(',') === 'id,kind,version')
+                    continue;
                 if (now - entry.enqueuedAtMs <= this.retentionMs)
                     continue;
                 feed.items.splice(i, 1);
@@ -337,15 +706,93 @@ class DurableVlmCandidateSpool {
             writeFailed: this.writeFailed,
             readFailed: this.readFailed,
             deleteFailed: this.deleteFailed,
+            reusePrepared: this.reusePrepared,
+            ...(this.reviewWindowMs === null ? {} : {
+                reviewWindowMs: this.reviewWindowMs,
+                delayed: [...this.feeds.values()].reduce((n, f) => n + f.items.filter(e => now - e.enqueuedAtMs > this.reviewWindowMs).length, 0),
+                capacityRejected: this.capacityRejected,
+            }),
         };
     }
+    /** One read-only advisory look. It never takes/removes a review or reserves a GPU slot. */
+    nextTriage() {
+        let selected;
+        let order = Infinity;
+        for (const feed of this.feeds.values()) {
+            let item;
+            for (let i = feed.items.length - 1; i >= 0; i--) {
+                const entry = feed.items[i];
+                if (!entry.cachedAnalysis && this.triageEligible.has(entry.id) && !this.triageFinished.has(entry.id)) {
+                    item = entry;
+                    break;
+                }
+            }
+            const feedOrder = this.triageOrder.get(feed.name) ?? 0;
+            if (item && feedOrder < order) {
+                selected = item;
+                order = feedOrder;
+            }
+        }
+        if (!selected)
+            return null;
+        this.triageOrder.set(selected.name, ++this.triageTick);
+        // Corrupt/unreadable bytes are a visible error, never an advisory-negative deletion.
+        const jpeg = fs.readFileSync(this.jpegPath(selected.id));
+        if (jpeg.length !== selected.byteLength || crypto.createHash('sha256').update(jpeg).digest('hex') !== selected.jpegSha256) {
+            throw Error('Urgent triage evidence hash mismatch');
+        }
+        return { candidate: this.asCandidate(selected, jpeg), policy: { ...selected.urgentTriagePolicy } };
+    }
+    checkpointTriage(result) {
+        const entry = this.inFlight.get(result.evidenceId) ?? [...this.feeds.values()]
+            .flatMap(feed => feed.items).find(item => item.id === result.evidenceId);
+        if (!entry || entry.cachedAnalysis || !this.triageEligible.has(entry.id)
+            || this.triageFinished.has(entry.id) || !(0, UrgentReviewTriage_1.validTriageResult)(result, entry, entry.urgentTriagePolicy))
+            return false;
+        const previous = entry.urgentTriageResult;
+        const previousBytes = this.entryBytes(entry);
+        entry.urgentTriageResult = JSON.parse(JSON.stringify(result));
+        if (!this.writeMetadata(entry)) {
+            entry.urgentTriageResult = previous;
+            return false;
+        }
+        this.persistedBytes += this.entryBytes(entry) - previousBytes;
+        this.restoreTriage(entry);
+        return true;
+    }
+    restoreTriage(entry) {
+        const policy = this.urgentTriagePolicies[entry.name];
+        if (!policy || entry.reviewPriority !== 'urgent' || policy.contextSha256 !== (0, UrgentReviewTriage_1.triageHash)(entry.reviewContext)
+            || (0, UrgentReviewTriage_1.triageHash)(policy) !== (0, UrgentReviewTriage_1.triageHash)(entry.urgentTriagePolicy))
+            return;
+        this.triageEligible.add(entry.id);
+        // Damaged optional hints do not invalidate the underlying evidence record.
+        if ((0, UrgentReviewTriage_1.validTriageResult)(entry.urgentTriageResult, entry, policy)) {
+            this.triageFinished.add(entry.id);
+            if (entry.urgentTriageResult.status === 'positive')
+                this.triagePositive.add(entry.id);
+        }
+    }
     clearQueuedState() {
+        this.triageEligible.clear();
+        this.triageFinished.clear();
+        this.triagePositive.clear();
+        this.triageOrder.clear();
+        this.triageTick = 0;
+        for (const entry of this.inFlight.values())
+            this.restoreTriage(entry);
+        this.recentAnswers.clear();
         this.feeds.clear();
         this.serveOrder.clear();
         this.serveTick = 0;
+        this.deliveryServeOrder.clear();
+        this.deliveryServeTick = 0;
+        this.priorityTurns = 0;
+        this.deliveryPriorityTurns = 0;
         this.queued = 0;
         this.persisted = this.inFlight.size;
-        this.persistedBytes = [...this.inFlight.values()].reduce((n, e) => n + e.byteLength, 0);
+        this.persistedBytes = [...this.inFlight.values()].reduce((n, e) => n + this.entryBytes(e), 0);
+        this.capacityRejected = 0;
         this.enqueued = 0;
         this.served = 0;
         this.coalesced = 0;
@@ -357,6 +804,7 @@ class DurableVlmCandidateSpool {
         this.writeFailed = 0;
         this.readFailed = 0;
         this.deleteFailed = 0;
+        this.reusePrepared = 0;
     }
     ensureDirectory() {
         fs.mkdirSync(this.directory, { recursive: true, mode: 0o700 });
@@ -386,7 +834,7 @@ class DurableVlmCandidateSpool {
             let entry = null;
             try {
                 const raw = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
-                if (!this.validRecord(raw))
+                if (!this.validRecord(raw) || raw.id !== name.slice(0, -5))
                     throw new Error('invalid record');
                 const jpegStat = fs.statSync(this.jpegPath(raw.id));
                 if (!jpegStat.isFile() || jpegStat.size !== raw.byteLength)
@@ -394,29 +842,34 @@ class DurableVlmCandidateSpool {
                 entry = raw;
             }
             catch {
+                this.readFailed++;
                 const id = name.slice(0, -5);
                 this.deletePairById(id);
                 continue;
             }
             if (this.inFlight.has(entry.id))
                 continue;
+            this.restoreTriage(entry);
             const feed = this.feedQueue(entry.name);
             feed.items.push(entry);
             feed.enqueued++;
             this.queued++;
             this.persisted++;
-            this.persistedBytes += entry.byteLength;
+            this.persistedBytes += this.entryBytes(entry);
             this.enqueued++;
             this.recovered++;
         }
         for (const feed of this.feeds.values()) {
             this.sortFeed(feed);
-            this.coalesceRecoveredEpisodes(feed);
-            while (feed.items.length > this.maxPerFeed)
-                this.evictOldestOf(feed);
+            if (this.reviewWindowMs === null)
+                this.coalesceRecoveredEpisodes(feed);
+            if (this.reviewWindowMs === null) {
+                while (feed.items.length > this.maxPerFeed)
+                    this.evictOldestOf(feed);
+            }
         }
         this.expire(this.now());
-        while (this.persisted > this.maxFrames || this.persistedBytes > this.maxBytes) {
+        while (this.reviewWindowMs === null && (this.persisted > this.maxFrames || this.persistedBytes > this.maxBytes)) {
             if (!this.evictFromFullestFeed())
                 break;
         }
@@ -443,15 +896,25 @@ class DurableVlmCandidateSpool {
             typeof value.reason === 'string' &&
             Number.isFinite(value.byteLength) && value.byteLength > 0 &&
             (value.jpegSha256 === undefined || /^[a-f0-9]{64}$/.test(value.jpegSha256)) &&
+            (value.reviewKind === undefined || value.reviewKind === 'event' || value.reviewKind === 'sample') &&
+            (value.reservedResultBytes === undefined || value.reservedResultBytes === 64 * 1024) &&
+            (value.reviewContext === undefined ? value.contextBytes === undefined : (value.reviewContext !== null && typeof value.reviewContext === 'object' &&
+                !Array.isArray(value.reviewContext) &&
+                value.contextBytes === Buffer.byteLength(JSON.stringify(value.reviewContext)) &&
+                value.contextBytes <= 64 * 1024)) &&
+            (value.cachedAnalysis === undefined ? value.resultBytes === undefined : (value.cachedAnalysis !== null && typeof value.cachedAnalysis === 'object' &&
+                !Array.isArray(value.cachedAnalysis) &&
+                value.resultBytes === Buffer.byteLength(JSON.stringify(value.cachedAnalysis)) &&
+                value.resultBytes <= 64 * 1024)) &&
             Number.isFinite(value.attempts) && value.attempts >= 0);
     }
     writePair(entry, jpeg) {
         const jpegPath = this.jpegPath(entry.id);
         const metadataPath = this.metadataPath(entry.id);
         try {
-            fs.writeFileSync(`${jpegPath}.tmp`, jpeg, { flag: 'wx', mode: 0o600 });
+            this.writeFile(`${jpegPath}.tmp`, jpeg, 'wx');
             fs.renameSync(`${jpegPath}.tmp`, jpegPath);
-            fs.writeFileSync(`${metadataPath}.tmp`, JSON.stringify(entry), { flag: 'wx', mode: 0o600 });
+            this.writeFile(`${metadataPath}.tmp`, JSON.stringify(entry), 'wx');
             fs.renameSync(`${metadataPath}.tmp`, metadataPath);
             return true;
         }
@@ -461,6 +924,32 @@ class DurableVlmCandidateSpool {
             return false;
         }
     }
+    entryBytes(entry) {
+        // Recompute diagnostic bytes on recovery; bad optional audit metadata must
+        // neither discard the JPEG nor evade the admission byte budget.
+        return entry.byteLength + (entry.contextBytes ?? 0) +
+            Math.max(entry.urgentTriagePolicy ? UrgentReviewTriage_1.TRIAGE_RESERVED_BYTES : 0, (entry.urgentTriagePolicy ? Buffer.byteLength(JSON.stringify(entry.urgentTriagePolicy)) : 0)
+                + (entry.urgentTriageResult ? Buffer.byteLength(JSON.stringify(entry.urgentTriageResult)) : 0)) +
+            (entry.groupingShadow ? Buffer.byteLength(JSON.stringify(entry.groupingShadow)) : 0) +
+            (entry.profileWork ? Math.max(64 * 1024, Buffer.byteLength(JSON.stringify(entry.profileWork)) +
+                (entry.profileWorkResult ? Buffer.byteLength(JSON.stringify(entry.profileWorkResult)) : 0)) :
+                entry.profileWorkResult ? Buffer.byteLength(JSON.stringify(entry.profileWorkResult)) : 0) +
+            Math.max(entry.reservedResultBytes ?? entry.resultBytes ?? 0, entry.scopedVlmProgress ? Buffer.byteLength(JSON.stringify(entry.scopedVlmProgress)) : 0);
+    }
+    writeFile(file, data, flag = 'w') {
+        if (this.reviewWindowMs === null) {
+            fs.writeFileSync(file, data, { flag, mode: 0o600 });
+            return;
+        }
+        const fd = fs.openSync(file, flag, 0o600);
+        try {
+            fs.writeFileSync(fd, data);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
     writeMetadata(entry) {
         const metadataPath = this.metadataPath(entry.id);
         const tmp = `${metadataPath}.tmp`;
@@ -469,8 +958,9 @@ class DurableVlmCandidateSpool {
                 fs.unlinkSync(tmp);
             }
             catch { /* absent is normal */ }
-            fs.writeFileSync(tmp, JSON.stringify(entry), { mode: 0o600 });
+            this.writeFile(tmp, JSON.stringify(entry));
             fs.renameSync(tmp, metadataPath);
+            return true;
         }
         catch {
             this.writeFailed++;
@@ -478,6 +968,7 @@ class DurableVlmCandidateSpool {
                 fs.unlinkSync(tmp);
             }
             catch { /* best-effort */ }
+            return false;
         }
     }
     asCandidate(entry, jpeg) {
@@ -492,6 +983,15 @@ class DurableVlmCandidateSpool {
             imageHeight: entry.imageHeight,
             spoolId: entry.id,
             jpegSha256: entry.jpegSha256,
+            ...(entry.reviewKind ? { reviewKind: entry.reviewKind } : {}),
+            ...((0, ReviewPriority_1.isReviewPriority)(entry.reviewPriority) ? { reviewPriority: entry.reviewPriority } : {}),
+            ...(entry.cachedAnalysis ? { cachedAnalysis: entry.cachedAnalysis } : {}),
+            ...(entry.scopedVlmProgress ? { scopedVlmProgress: JSON.parse(JSON.stringify(entry.scopedVlmProgress)) } : {}),
+            ...(entry.reviewContext ? { reviewContext: entry.reviewContext } : {}),
+            ...(entry.profileWork ? { profileWork: JSON.parse(JSON.stringify(entry.profileWork)) } : {}),
+            ...(entry.profileWorkResult ? { profileWorkResult: JSON.parse(JSON.stringify(entry.profileWorkResult)) } : {}),
+            ...(entry.groupingShadow?.mode === 'shadow' && entry.groupingShadow?.version === 1 &&
+                Array.isArray(entry.groupingShadow.scopes) ? { groupingShadow: entry.groupingShadow } : {}),
             ...(entry.detectorShadow ? { detectorShadow: entry.detectorShadow } : {}),
         };
     }
@@ -516,20 +1016,83 @@ class DurableVlmCandidateSpool {
     sortFeed(feed) {
         feed.items.sort((a, b) => a.enqueuedAtMs - b.enqueuedAtMs || a.id.localeCompare(b.id));
     }
-    nextEligible(now) {
+    reviewComplete(entry) {
+        if (!entry.cachedAnalysis)
+            return false;
+        if (entry.reviewContext?.orderedSequence) {
+            const decision = entry.cachedAnalysis.orderedReview;
+            return decision?.version === 1 && decision.kind === 'ordered_frame_rehearsal'
+                && decision.sequenceId === entry.id && decision.anchorSha256 === entry.jpegSha256
+                && decision.capturedAtMs === entry.enqueuedAtMs;
+        }
+        if (!entry.reviewContext?.temporalReviewContract)
+            return true;
+        const decision = entry.cachedAnalysis.temporalReview;
+        return decision?.version === 1 && decision.kind === 'temporal_rehearsal'
+            && decision.evidenceId === entry.id && decision.imageSha256 === entry.jpegSha256
+            && decision.capturedAtMs === entry.enqueuedAtMs;
+    }
+    nextEligible(now, stage, accept) {
+        // Crossing the fresh/delayed boundary never changes order. The opt-in
+        // capture-time priority gives urgent work preference, with every fifth
+        // successful take using ordinary fair-camera/FIFO order. Thus a sustained
+        // urgent stream cannot indefinitely bypass a ready ordinary camera/item.
+        // A fairness turn is work-conserving: it never waits for an empty class.
+        const orderByFeed = stage === 'delivery' ? this.deliveryServeOrder : this.serveOrder;
+        const preference = this.priorityScheduling &&
+            (stage === 'delivery' ? this.deliveryPriorityTurns : this.priorityTurns) < ReviewPriority_1.PRIORITY_BURST;
+        const inStage = (entry) => stage === undefined ||
+            (stage === 'delivery' ? this.reviewComplete(entry) : !this.reviewComplete(entry));
+        const eligible = (entry) => inStage(entry) && entry.availableAtMs <= now;
+        const priorityRank = (entry) => (0, ReviewPriority_1.reviewPriorityRank)(entry.reviewPriority) * 2
+            + (stage === 'review' && this.triagePositive.has(entry.id) ? 1 : 0);
+        // One upload and one review may work on different images from the same
+        // camera. A blocked network must not block that camera's next model call.
+        const busy = new Set([...this.inFlight.values()].filter(inStage).map(e => e.name));
         let best = null;
         let bestOrder = Infinity;
+        let bestRank = -1;
         for (const feed of this.feeds.values()) {
-            const index = feed.items.findIndex((entry) => entry.availableAtMs <= now);
+            if (this.reviewWindowMs !== null &&
+                busy.has(feed.name))
+                continue;
+            // Keep FIFO within each class. A newly urgent item on the same feed can
+            // pass older normal work; the fairness turn still serves that older work.
+            let index = -1;
+            // Temporal comparisons need capture order within a camera. An older retry
+            // must finish before a later observation, even when the latter is urgent.
+            // Other cameras and already committed upload work remain independent.
+            const temporalFeed = stage === 'review' && feed.items.some(e => e.reviewContext?.temporalReviewContract);
+            for (let i = 0; i < feed.items.length; i++) {
+                if (temporalFeed && inStage(feed.items[i])) {
+                    if (eligible(feed.items[i]))
+                        index = i;
+                    break;
+                }
+                if (!eligible(feed.items[i]))
+                    continue;
+                if (index < 0 || preference &&
+                    priorityRank(feed.items[i]) > priorityRank(feed.items[index]))
+                    index = i;
+                if (!preference)
+                    break;
+            }
             if (index < 0)
                 continue;
             const entry = feed.items[index];
-            const order = this.serveOrder.get(feed.name) ?? 0;
+            // Check the feed's already-selected head, not every later item: a new
+            // profile cannot jump older work merely because its model is free.
+            if (accept && !accept(this.asCandidate(entry, Buffer.alloc(0))))
+                continue;
+            const order = orderByFeed.get(feed.name) ?? 0;
+            const rank = preference ? priorityRank(entry) : 0;
             if (best === null ||
-                order < bestOrder ||
-                (order === bestOrder && entry.enqueuedAtMs < best.entry.enqueuedAtMs)) {
+                rank > bestRank ||
+                (rank === bestRank && (order < bestOrder ||
+                    (order === bestOrder && entry.enqueuedAtMs < best.entry.enqueuedAtMs)))) {
                 best = { feed, index, entry };
                 bestOrder = order;
+                bestRank = rank;
             }
         }
         return best;
@@ -611,9 +1174,12 @@ class DurableVlmCandidateSpool {
         this.removePersisted(entry);
     }
     removePersisted(entry) {
+        this.triageEligible.delete(entry.id);
+        this.triageFinished.delete(entry.id);
+        this.triagePositive.delete(entry.id);
         this.deletePair(entry);
         this.persisted = Math.max(0, this.persisted - 1);
-        this.persistedBytes = Math.max(0, this.persistedBytes - entry.byteLength);
+        this.persistedBytes = Math.max(0, this.persistedBytes - this.entryBytes(entry));
     }
     deletePair(entry) {
         this.deletePairById(entry.id);