@feng0531/dsh-code-review 0.86.1 → 0.87.0

package/src/retrieval-loop.mjs

@@ -46,11 +46,13 @@ function roundBudgetError() {
   return error;
 }
 
-export async function retrievalLoop(model, request, scope, { correctProtocol = false, maxRounds = Number.MAX_SAFE_INTEGER, maxInputBytes = 96 * 1024, beforeCall = () => {}, onTruncated = () => {}, onRetrieved = () => {}, onBudgetLimited = () => {}, initialRetrieved = [], allowExhaustedInitial = false, enableSearchSeeds = false } = {}) {
+export async function retrievalLoop(model, request, scope, { correctProtocol = false, maxRounds = Number.MAX_SAFE_INTEGER, maxInputBytes = 96 * 1024, beforeCall = () => {}, onTruncated = () => {}, onRetrieved = () => {}, onBudgetLimited = () => {}, initialRetrieved = [], initialContext, yieldOnBudget = false, allowExhaustedInitial = false, enableSearchSeeds = false } = {}) {
   if (!Number.isSafeInteger(maxRounds) || maxRounds < 0 || !Number.isSafeInteger(maxInputBytes) || maxInputBytes < 1) throw new Error('Invalid retrieval loop budget');
   // Only internal callers can seed this loop; the public model response cannot supply it.
   const allowedSeeds = new Set(scope.catalog().map(item => item.id));
-  if (!Array.isArray(initialRetrieved) || initialRetrieved.length > 50 || initialRetrieved.some(item => item?.request?.kind !== 'read' || !allowedSeeds.has(item.request.id) || item.result?.sourceId !== item.request.id || typeof item.result?.text !== 'string')) throw new Error('Invalid initial retrieval evidence');
+  const validateSeeds = items => { if (!Array.isArray(items) || items.length > 50 || items.some(item => item?.request?.kind !== 'read' || !allowedSeeds.has(item.request.id) || item.result?.sourceId !== item.request.id || typeof item.result?.text !== 'string')) throw new Error('Invalid initial retrieval evidence'); };
+  validateSeeds(initialRetrieved);
+  if (initialContext !== undefined && typeof initialContext !== 'function') throw new Error('Invalid initial evidence context producer');
   const retrieved = structuredClone(initialRetrieved);
   if (retrieved.length) {
     const seeded = retrievalRequest(request, scope, retrieved);
@@ -60,6 +62,7 @@ export async function retrievalLoop(model, request, scope, { correctProtocol = f
   const delivered = new Set();
   let protocolCorrection, finalization, searchSeedAttempts = 0, currentRound = 0;
   const finalize = async error => {
+    if (yieldOnBudget && ['READER_CALL_BUDGET_EXCEEDED', 'READER_OUTPUT_BUDGET_EXCEEDED'].includes(error.code)) throw error;
     finalization = { code: error.code, reason: error.message, ...(scope.budget ? { budget: scope.budget() } : {}) };
     await onBudgetLimited(finalization);
     await request.onProtocolEvent?.({ action: 'retrieval-budget-finalization', ...finalization });
@@ -100,6 +103,16 @@ export async function retrievalLoop(model, request, scope, { correctProtocol = f
     request.signal?.throwIfAborted();
     beforeCall();
     request.signal?.throwIfAborted();
+    // Optional redelivery starts only after model-call admission. Never spend a
+    // stage's reader budget on a call already vetoed by the shared model gate.
+    if (round === 0 && !finalization && initialContext) {
+      const seeds = initialContext(retrieved, records => ({ ...request, ...nextRequest(records) }));
+      validateSeeds(seeds);
+      retrieved.push(...seeds);
+      ({ input, instructions } = nextRequest(retrieved));
+      if (!fits({ ...request, input, instructions })) throw new Error('Retrieval input budget exceeded');
+      request.signal?.throwIfAborted();
+    }
     for (const item of retrieved) {
       if (!item.result.omitted && !delivered.has(item)) {
         recordRetrieval(item.request, item.result, onTruncated, onRetrieved);
@@ -132,7 +145,7 @@ export async function retrievalLoop(model, request, scope, { correctProtocol = f
       batch = scope.transaction ? scope.transaction(execute) : execute();
     } catch (error) {
       request.signal?.throwIfAborted();
-      if (!finalization && budgetFailure(error)) { await finalize(error); continue; }
+      if (!finalization && budgetFailure(error)) { if (yieldOnBudget) throw Object.assign(error, { pendingRequests: parseRetrievalResponse(parsed) }); await finalize(error); continue; }
       if (finalization || !correctProtocol || protocolCorrection || !(/Invalid retrieval batch|Invalid read request|Invalid search request|Invalid find request|Invalid line range|Line range outside source/.test(error.message))) throw error;
       protocolCorrection = { code: error.code ?? 'MODEL_INVALID_RETRIEVAL' };
       await request.onProtocolEvent?.({ action: 'retrieval-protocol-correction', code: protocolCorrection.code });

package/src/review-reader-allocation.mjs

@@ -1,7 +1,9 @@
 // Per-stage admission over ONE approved root ledger, not independent readers.
 // Fixed proportional floors protect future stages; released unused floors become
 // shared capacity. No content/source identifiers are emitted by summary().
-export function createReviewReaderAllocation(root, units) {
+export function createReviewReaderAllocation(root, units, { maxResumeAttempts = 2 } = {}) {
+  if (!Number.isSafeInteger(maxResumeAttempts) || maxResumeAttempts < 1 || maxResumeAttempts > 4) throw new Error('Invalid reader resume attempts');
+  let releaseRevision = 0; const yielded = [];
   if (!root || !['budget', 'usage', 'preflight', 'transaction', 'read', 'find', 'search', 'catalog'].every(key => typeof root[key] === 'function')) throw new Error('Invalid root reader allocation');
   if (!Array.isArray(units) || units.length > 2000) throw new Error('Invalid reader allocation units');
   const budget = root.budget();
@@ -9,7 +11,7 @@ export function createReviewReaderAllocation(root, units) {
   const states = new Map(); let totalWeight = 0;
   for (const unit of units) {
     if (!unit || typeof unit.id !== 'string' || !unit.id || unit.id.length > 500 || states.has(unit.id) || !Number.isSafeInteger(unit.weight) || unit.weight < 1 || unit.weight > 1000000) throw new Error('Invalid reader allocation unit');
-    states.set(unit.id, { weight: unit.weight, calls: 0, outputBytes: 0, cacheHits: 0, released: false, inTransaction: false });
+    states.set(unit.id, { weight: unit.weight, calls: 0, outputBytes: 0, cacheHits: 0, released: false, inTransaction: false, yielded: false, resumeAttempts: 0, yieldRevision: 0, pendingReason: null });
     totalWeight += unit.weight;
   }
   for (const state of states.values()) {
@@ -17,7 +19,7 @@ export function createReviewReaderAllocation(root, units) {
     state.byteFloor = Math.floor(budget.remainingOutputBytes * state.weight / totalWeight);
   }
   const fail = kind => { const error = new Error('Reader allocation ' + kind + ' budget exceeded'); error.code = kind === 'call' ? 'READER_CALL_BUDGET_EXCEEDED' : 'READER_OUTPUT_BUDGET_EXCEEDED'; throw error; };
-  const live = id => { const state = states.get(id); if (!state || state.released) throw new Error('Reader allocation unit unavailable'); return state; };
+  const live = id => { const state = states.get(id); if (!state || state.released || state.yielded) throw new Error('Reader allocation unit unavailable'); return state; };
   const available = state => {
     const remaining = root.budget(); let protectedCalls = 0, protectedBytes = 0;
     for (const other of states.values()) {
@@ -28,6 +30,25 @@ export function createReviewReaderAllocation(root, units) {
     return { ...remaining, remainingCalls: Math.max(0, remaining.remainingCalls - protectedCalls), remainingOutputBytes: Math.max(0, remaining.remainingOutputBytes - protectedBytes) };
   };
   const check = (state, cost) => { const remaining = available(state); if (cost.calls > remaining.remainingCalls) fail('call'); if (cost.outputBytes > remaining.remainingOutputBytes) fail('output'); };
+  const resumeWithCost = (id, costForAttempt) => {
+    const state = states.get(id);
+    if (!state || state.released || !state.yielded) throw new Error('Reader allocation unit unavailable');
+    if (state.resumeAttempts >= maxResumeAttempts) return { resumed: false, reason: 'READER_RESUME_ATTEMPTS_EXHAUSTED', attempts: state.resumeAttempts };
+    const head = yielded.find(key => { const row = states.get(key); return row && !row.released && row.yielded && row.resumeAttempts < maxResumeAttempts && row.yieldRevision < releaseRevision; });
+    if (head !== id || state.yieldRevision >= releaseRevision) return { resumed: false, reason: 'READER_RESUME_WAITING', attempts: state.resumeAttempts };
+    state.resumeAttempts++; state.yieldRevision = releaseRevision;
+    yielded.splice(yielded.indexOf(id), 1); yielded.push(id);
+    try {
+      const cost = costForAttempt();
+      if (!cost || !Number.isSafeInteger(cost.calls) || cost.calls < 0 || !Number.isSafeInteger(cost.outputBytes) || cost.outputBytes < 0) throw new Error('Reader allocation preflight unavailable');
+      check(state, cost);
+      state.yielded = false; state.pendingReason = null; yielded.splice(yielded.indexOf(id), 1);
+      return { resumed: true, reason: null, attempts: state.resumeAttempts };
+    } catch (error) {
+      if (!['READER_CALL_BUDGET_EXCEEDED', 'READER_OUTPUT_BUDGET_EXCEEDED'].includes(error?.code)) throw error;
+      return { resumed: false, reason: error.code, attempts: state.resumeAttempts };
+    }
+  };
   const scopes = new Map();
   return Object.freeze({
     scope(id) {
@@ -69,7 +90,28 @@ export function createReviewReaderAllocation(root, units) {
       });
       scopes.set(id, scope); return scope;
     },
-    release(id) { const state = states.get(id); if (!state) return; if (state.inTransaction) throw new Error('Reader allocation transaction active'); state.released = true; },
+    // Yield retains this unit's floor; only the host owning a terminal stage may
+    // release it. Pausing a peer never grants permission to steal its reserve.
+    yield(id, { reason = 'READER_CALL_BUDGET_EXCEEDED' } = {}) {
+      const state = live(id);
+      if (state.inTransaction) throw new Error('Reader allocation transaction active');
+      if (!['READER_CALL_BUDGET_EXCEEDED', 'READER_OUTPUT_BUDGET_EXCEEDED'].includes(reason)) throw new Error('Invalid reader yield reason');
+      state.yielded = true; state.yieldRevision = releaseRevision; state.pendingReason = reason; yielded.push(id);
+      return { yielded: true, attempts: state.resumeAttempts };
+    },
+    resume(id, requests = []) {
+      const state = states.get(id);
+      if (!state || state.released || !state.yielded) throw new Error('Reader allocation unit unavailable');
+      if (!Array.isArray(requests) || !requests.length) return { resumed: false, reason: 'READER_RESUME_REQUESTS_REQUIRED', attempts: state.resumeAttempts };
+      return resumeWithCost(id, () => root.preflight(requests));
+    },
+    // Scalar admission is only a retry opportunity, never authority to read.
+    // Every actual read still goes through exact preflight and root accounting.
+    resumeBudget(id, { requiredCalls = 1, requiredOutputBytes = 1 } = {}) {
+      if (![requiredCalls, requiredOutputBytes].every(value => Number.isSafeInteger(value) && value >= 0) || requiredCalls + requiredOutputBytes === 0) throw new Error('Invalid reader resume budget');
+      return resumeWithCost(id, () => ({ calls: requiredCalls, outputBytes: requiredOutputBytes }));
+    },
+    release(id) { const state = states.get(id); if (!state) return; if (state.inTransaction) throw new Error('Reader allocation transaction active'); if (!state.released) { state.released = true; releaseRevision++; } },
     summary() { const usage = root.usage(); return { units: states.size, releasedUnits: [...states.values()].filter(state => state.released).length, calls: usage.calls, outputBytes: usage.outputBytes, ...(usage.cacheHits !== undefined ? { cacheHits: usage.cacheHits } : {}) }; },
   });
 }

package/src/review-resume.mjs

@@ -1,8 +1,59 @@
 import { hash } from './content.mjs';
 import { validateBusinessGroups } from './business-groups.mjs';
+import { prepareStageGenerations } from './review-stage-state.mjs';
+import { createStageContinuation } from './stage-continuation.mjs';
 
 const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().filter(key => value[key] !== undefined).map(key => [key, canonical(value[key])])) : value;
 const digest = value => hash(JSON.stringify(canonical(value)));
+
+const MAX_BYTES = 8 * 1024 * 1024;
+const stageEnabled = options => options?.execution?.enableStageContinuation === true || options?.enableStageContinuation === true;
+const invalid = () => { throw new Error('Invalid stage resume checkpoint'); };
+const exact = (value, keys) => { if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(k => !keys.includes(k))) invalid(); };
+const RECEIPT_KEYS = new Set(['receiptId', 'receipts', 'retrievalAudit', 'retrieved', 'resolveEvidence']);
+function privateClone(value, { stripReceipts = false } = {}, seen = new Set(), depth = 0, budget = { nodes: 0, bytes: 0 }) {
+  if (++budget.nodes > 300000 || depth > 32) invalid();
+  if (typeof value === 'string') { budget.bytes += Buffer.byteLength(value); if (budget.bytes > MAX_BYTES) invalid(); return value; }
+  if (value === null || typeof value === 'boolean' || typeof value === 'number' && Number.isFinite(value)) return value;
+  if (!value || typeof value !== 'object' || seen.has(value) || ![Object.prototype, Array.prototype, null].includes(Object.getPrototypeOf(value))) invalid();
+  if (Array.isArray(value) && (value.length > 100000 || Object.keys(value).length !== value.length)) invalid();
+  seen.add(value); const out = Array.isArray(value) ? [] : {};
+  for (const key of Reflect.ownKeys(value)) {
+    if (Array.isArray(value) && key === 'length') continue;
+    if (typeof key !== 'string' || ['__proto__', 'constructor', 'toJSON', 'prototype'].includes(key)) invalid();
+    const d = Object.getOwnPropertyDescriptor(value, key); if (!d.enumerable || !Object.hasOwn(d, 'value')) invalid();
+    // Host report objects use optional undefined fields; normalize only exports.
+    // Imported checkpoints remain JSON-only and reject undefined explicitly.
+    if (stripReceipts && !Array.isArray(value) && d.value === undefined) continue;
+    if (RECEIPT_KEYS.has(key)) { if (stripReceipts) continue; invalid(); }
+    out[key] = privateClone(d.value, { stripReceipts }, seen, depth + 1, budget);
+  }
+  seen.delete(value);return out;
+}
+function bounded(value) { if (Buffer.byteLength(JSON.stringify(value)) > MAX_BYTES) invalid(); return value; }
+function continuationState(snapshot, wrapper) {
+  exact(wrapper, ['options', 'state']);
+  const o = wrapper.options, cp = wrapper.state;
+  exact(o, ['rounds', 'maxInputBytes', 'enableMigrationContracts', 'enableMigrationRegression']);
+  if (!Number.isSafeInteger(o.rounds) || o.rounds < 1 || o.rounds > 50 || !Number.isSafeInteger(o.maxInputBytes) || o.maxInputBytes < 1 || o.maxInputBytes > 16 * 1024 * 1024 || typeof o.enableMigrationContracts !== 'boolean' || typeof o.enableMigrationRegression !== 'boolean' || !Array.isArray(cp?.units)) invalid();
+  const units = cp.units.map(({ id, kind, fileIds, dependencies }) => ({ id, kind, fileIds, dependencies }));
+  const machine = createStageContinuation(snapshot, o, { completedPrimary: cp.completedPrimary, units, maxAttempts: cp.maxAttempts, checkpoint: cp });
+  // Keep the original checkpoint (not the machine's running->pending projection).
+  // This is historical bookkeeping only, never automatically applied to a new run.
+  machine.summary();
+  return { options: structuredClone(o), state: structuredClone(cp) };
+}
+function prepareV2(value, snapshot) {
+  exact(value, ['schemaVersion', 'snapshotId', 'identityHash', 'completed', 'businessGrouping', 'interactions', 'stageGenerations', 'continuation']);
+  if (!Array.isArray(value.stageGenerations)) invalid();
+  const generations = prepareStageGenerations(snapshot, value.stageGenerations);
+  const done = new Set(value.completed.map(item => item.fileId));
+  if (generations.some(row => row.phase !== 'primary' || done.has(row.fileId) || row.needsFreshProvenance)) invalid();
+  const result = { ...value, stageGenerations: generations };
+  if (value.continuation !== undefined) result.continuation = continuationState(snapshot, value.continuation);
+  return bounded(result);
+}
+
 const safeFile = file => !file?.stageFailures?.length && !file?.reviewPasses?.some(pass => pass.status !== 'completed') && !file?.windowCoverage?.pending?.length && file?.status === 'completed' && file.resumeEligible === true && !file.retrievalLimited && (!file.synthesisStatus || file.synthesisStatus === 'completed') && (!file.verificationStatus || !['pending', 'failed'].includes(file.verificationStatus));
 
 // Host-private, schema-versioned completed-chain state. A previous result grants
@@ -28,12 +79,25 @@ export function buildResumeState(snapshot, options, report) {
   const interactions = structuredClone((report.interactions ?? []).filter(item => Array.isArray(item.fileIds) && item.fileIds.length && item.status === 'completed' && item.fileIds.every(id => completed.some(row => row.fileId === id))));
   const identity = digest({ snapshot, options });
   const result = { schemaVersion: 1, snapshotId: snapshot.id, identityHash: identity, completed, ...(businessGrouping ? { businessGrouping } : {}), interactions };
+  if (stageEnabled(options)) {
+    result.schemaVersion = 2;
+    result.stageGenerations = prepareStageGenerations(snapshot, report.stageGenerations ?? []).filter(row => row.phase === 'primary' && !completed.some(item => item.fileId === row.fileId));
+    if (report.continuation !== undefined) result.continuation = continuationState(snapshot, privateClone({ options: report.continuationOptions, state: report.continuation }));
+    return prepareV2(bounded(privateClone(result, { stripReceipts: true })), snapshot);
+  }
   if (Buffer.byteLength(JSON.stringify(result)) > 8 * 1024 * 1024) throw new Error('Resume checkpoint exceeds storage limit');
   return result;
 }
 
 export function validateResumeState(value, snapshot, options) {
-  if (!value || value.schemaVersion !== 1 || value.snapshotId !== snapshot?.id || value.identityHash !== digest({ snapshot, options }) || !Array.isArray(value.completed) || value.completed.length > snapshot.files.length) throw new Error('Resume identity mismatch; capture a fresh independent review');
+  // Select the version without invoking a caller-supplied accessor or inherited
+  // schema property before the strict schema-two descriptor scan.
+  if (!value || typeof value !== 'object') invalid();
+  const version = Object.getOwnPropertyDescriptor(value, 'schemaVersion');
+  if (!version || !Object.hasOwn(version, 'value')) invalid();
+  const v2 = version.value === 2;
+  if (v2) { if (!stageEnabled(options)) invalid(); value = bounded(privateClone(value)); }
+  if (!value || ![1, ...(stageEnabled(options) ? [2] : [])].includes(value.schemaVersion) || value.snapshotId !== snapshot?.id || value.identityHash !== digest({ snapshot, options }) || !Array.isArray(value.completed) || value.completed.length > snapshot.files.length) throw new Error('Resume identity mismatch; capture a fresh independent review');
   const seen = new Set();
   for (const item of value.completed) {
     const source = snapshot.files.find(file => file.id === item?.fileId && file.path === item.path && file.eligibility === 'reviewable');
@@ -45,9 +109,10 @@ export function validateResumeState(value, snapshot, options) {
     validateBusinessGroups({ groups: value.businessGrouping.groups.map(group => ({ fileIds: group.fileIds, reason: group.reason })) }, snapshot.files);
   }
   if (!Array.isArray(value.interactions) || value.interactions.some(item => !Array.isArray(item?.fileIds) || !item.fileIds.length || item.status !== 'completed' || item.fileIds.some(id => !seen.has(id)))) throw new Error('Invalid resume interactions');
-  return structuredClone(value);
+  return v2 ? prepareV2(value, snapshot) : structuredClone(value);
 }
 
 export function resumePreview(state, sourceJobId) {
+  if (state.schemaVersion === 2) return { sourceJobId, reusableFiles: state.completed.length, fileIds: state.completed.map(item => item.fileId), reusableGenerations: state.stageGenerations.length, stageFileIds: [...new Set(state.stageGenerations.map(item => item.fileId))], notice: 'Exact-identity accepted primary generations may skip generation only. Pending chains are not completed reviews. Verification always runs again with fresh independent receipts; secondary stages restart at a fresh provenance boundary. Saved continuation is historical bookkeeping, not fresh completion or a new attempt allowance. Fresh preview confirmation and model authorization remain required.' };
   return { sourceJobId, reusableFiles: state.completed.length, fileIds: state.completed.map(item => item.fileId), notice: 'Only exact-identity completed file chains are reusable. Pending/interrupted stages run again; old findings retain prior-run provenance, not fresh model evidence. Fresh preview confirmation and model authorization are still required.' };
 }

package/src/review-stage-state.mjs

@@ -0,0 +1,143 @@
+import { hash } from './content.mjs';
+import { changeMap } from './change-map.mjs';
+import { changeWindows } from './change-windows.mjs';
+import { sourceSegments } from './source-segments.mjs';
+import { validateWindowFindings } from './window-findings.mjs';
+import { validateAttribution } from './attribution.mjs';
+
+const LIMIT = 8 * 1024 * 1024;
+const PHASES = ['primary', 'window-synthesis', 'file-interaction'];
+const DROP = ['verification', 'regression', 'priorRun', 'retrievalAudit', 'receipts', 'receiptId'];
+const fail = () => { throw Object.assign(new Error('Invalid accepted stage generation'), { code: 'INVALID_STAGE_GENERATION' }); };
+const text = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 8000;
+const identity = value => typeof value === 'string' && value.length > 0 && value.length <= 1000 && !/[\x00-\x1f]/.test(value);
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+function exact(value, allowed) { if (!object(value) || Object.keys(value).some(key => !allowed.includes(key))) fail(); }
+// Private checkpoints are still imported data. Inspect descriptors before JSON
+// serialization: getters/toJSON/prototypes must never execute during validation.
+function clone(value, seen = new Set(), depth = 0, budget = { nodes: 0, bytes: 0 }) {
+  if (++budget.nodes > 200000 || depth > 24) fail();
+  if (typeof value === 'string') { budget.bytes += Buffer.byteLength(value); if (budget.bytes > LIMIT) fail(); return value; }
+  if (value === null || typeof value === 'boolean') return value;
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (!value || typeof value !== 'object' || seen.has(value)) fail();
+  if (Object.getPrototypeOf(value) !== (Array.isArray(value) ? Array.prototype : Object.prototype) && Object.getPrototypeOf(value) !== null) fail();
+  if (Array.isArray(value) && (value.length > 100000 || Object.keys(value).length !== value.length || Object.keys(value).some((key, index) => key !== String(index)))) fail();
+  seen.add(value);
+  const output = Array.isArray(value) ? [] : {};
+  for (const key of Reflect.ownKeys(value)) {
+    if (Array.isArray(value) && key === 'length') continue;
+    if (typeof key !== 'string' || ['__proto__', 'constructor', 'prototype', 'toJSON'].includes(key)) fail();
+    const d = Object.getOwnPropertyDescriptor(value, key);
+    if (!d.enumerable || !Object.hasOwn(d, 'value')) fail();
+    output[key] = clone(d.value, seen, depth + 1, budget);
+  }
+  seen.delete(value);
+  return output;
+}
+
+export function stageKey(fileId, { phase, round = 1, windowIds = [], groupId } = {}) {
+  if (!identity(fileId) || !PHASES.includes(phase) || !Number.isSafeInteger(round) || round < 1 || round > 50 || !Array.isArray(windowIds) || windowIds.length > 100000 || windowIds.some(id => !identity(id)) || new Set(windowIds).size !== windowIds.length || (groupId !== undefined && !identity(groupId)) || (phase === 'file-interaction' && !groupId)) fail();
+  return JSON.stringify([fileId, phase, round, [...windowIds].sort(), groupId ?? null]);
+}
+
+function normalizeFinding(raw, file, changes, phase, files) {
+  exact(raw, ['id', 'fileId', 'path', 'severity', 'title', 'evidence', 'trigger', 'impact', 'suggestion', 'anchor', 'attribution', 'interaction', 'reviewRound', ...DROP]);
+  if (raw.fileId !== file.id || (raw.path !== undefined && raw.path !== file.path) || !['critical', 'high', 'medium', 'low'].includes(raw.severity)) fail();
+  for (const key of ['title', 'evidence', 'trigger', 'impact', 'suggestion']) if (!text(raw[key])) fail();
+  const a = raw.anchor;
+  if (!object(a) || !['line', 'property', 'file'].includes(a.kind)) fail();
+  if (file.reviewMode === 'project' && (a.side === 'old' || a.kind === 'property')) fail();
+  let anchor;
+  if (a.kind === 'line') {
+    exact(a, ['kind', 'side', 'start', 'end', 'snippet']);
+    const side = a.side === 'old' ? file.left : a.side === 'new' ? file.right : null;
+    if (!side || typeof side.text !== 'string' || !Number.isSafeInteger(a.start) || !Number.isSafeInteger(a.end) || a.start < 1 || a.end < a.start || !text(a.snippet)) fail();
+    const lines = side.text.replaceAll('\r\n', '\n').split('\n');
+    if (a.end > lines.length || lines.slice(a.start - 1, a.end).join('\n') !== a.snippet.replaceAll('\r\n', '\n')) fail();
+    anchor = { kind: 'line', side: a.side, start: a.start, end: a.end, snippet: a.snippet };
+  } else if (a.kind === 'property') {
+    exact(a, ['kind', 'name']);
+    if (!file.properties?.some(p => p.name === a.name && p.old !== p.new)) fail();
+    anchor = { kind: 'property', name: a.name };
+  } else { exact(a, ['kind']); anchor = { kind: 'file' }; }
+  let attribution;
+  if (raw.attribution !== undefined) exact(raw.attribution, ['status', 'causality', 'precision', 'notice', 'editIds', 'properties', 'beforeBehavior', 'afterBehavior', 'reason']);
+  if (file.reviewMode === 'project') {
+    if (raw.attribution !== undefined && (raw.attribution.status !== 'not-applicable' || raw.attribution.causality !== 'current-source-only')) fail();
+    attribution = { status: 'not-applicable', causality: 'current-source-only' };
+  } else {
+    const value = raw.attribution?.status === 'missing' ? undefined : raw.attribution;
+    if (raw.attribution?.status === 'missing' && Object.keys(raw.attribution).some(k => !['status', 'causality'].includes(k))) fail();
+    attribution = validateAttribution(value, { ...file, properties: file.properties ?? [] }, changes);
+    if (raw.attribution?.status !== undefined && raw.attribution.status !== attribution.status) fail();
+  }
+  const result = { fileId: file.id, path: file.path, severity: raw.severity, anchor, attribution };
+  for (const key of ['title', 'evidence', 'trigger', 'impact', 'suggestion']) result[key] = raw[key];
+  const id = hash(JSON.stringify(result));
+  if (raw.id !== undefined && raw.id !== id) fail();
+  if (raw.interaction !== undefined) {
+    if (phase !== 'file-interaction') fail();
+    exact(raw.interaction, ['status', 'causality', 'editRefs']);
+    const refs = raw.interaction.editRefs;
+    if (!Array.isArray(refs) || refs.length < 2 || refs.length > 50) fail();
+    for (const ref of refs) {
+      exact(ref, ['fileId', 'editId']);
+      const target = files.get(ref.fileId);
+      if (!target || target.reviewMode === 'project') fail();
+      const edits = changeMap(target.left.text, target.right.text);
+      if (edits.precision !== 'exact' || !edits.edits.some(e => e.id === ref.editId)) fail();
+    }
+    if (new Set(refs.map(r => r.fileId)).size < 2 || new Set(refs.map(r => JSON.stringify([r.fileId, r.editId]))).size !== refs.length) fail();
+    const primary = refs.filter(r => r.fileId === file.id).map(r => r.editId);
+    if (attribution.status !== 'references-validated' || !primary.length || primary.some(id => !attribution.editIds.includes(id)) || attribution.editIds.some(id => !primary.includes(id)) || anchor.kind !== 'line' || !changes.edits.some(e => primary.includes(e.id) && e[anchor.side].count > 0 && anchor.start < e[anchor.side].start + e[anchor.side].count && anchor.end >= e[anchor.side].start)) fail();
+    result.interaction = { status: 'references-validated', causality: 'unverified', editRefs: refs.map(r => ({ ...r })) };
+  } else if (phase === 'file-interaction') fail();
+  return { id, ...result };
+}
+
+// Returns accepted generation payloads, NOT completed review stages. In particular,
+// old verification and read delivery records never authorize a new verification.
+// The enclosing resume state must bind the entire snapshot and execution options.
+export function prepareStageGenerations(snapshot, records, { maxBytes = LIMIT, validateGeneration } = {}) {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > LIMIT || (validateGeneration !== undefined && typeof validateGeneration !== 'function') || !Array.isArray(snapshot?.files) || !Array.isArray(records) || records.length > 100000) fail();
+  const safe = clone(records);
+  if (Buffer.byteLength(JSON.stringify(safe)) > maxBytes) fail();
+  const files = new Map(), allIds = new Set();
+  for (const file of snapshot.files) {
+    if (!identity(file?.id) || allIds.has(file.id)) fail();
+    allIds.add(file.id);
+    if (file.eligibility === 'reviewable') files.set(file.id, file);
+  }
+  const seen = new Set();
+  const output = safe.map(record => {
+    exact(record, ['key', 'fileId', 'path', 'phase', 'round', 'windowIds', 'groupId', 'generation', 'needsFreshProvenance', ...DROP]);
+    const file = files.get(record.fileId);
+    if (!file || (record.path !== undefined && record.path !== file.path)) fail();
+    const { phase, round = 1, windowIds = [], groupId } = record;
+    const key = stageKey(file.id, { phase, round, windowIds, groupId });
+    if (record.key !== key || seen.has(key) || (phase === 'file-interaction' && windowIds.length)) fail();
+    seen.add(key);
+    exact(record.generation, ['findings', 'limitations', ...DROP]);
+    const g = record.generation;
+    if (!Array.isArray(g.findings) || g.findings.length > 50 || !Array.isArray(g.limitations) || g.limitations.length > 50 || g.limitations.some(s => !text(s))) fail();
+    const changes = changeMap(file.left.text, file.right.text);
+    const findings = g.findings.map(raw => {
+      if (raw.reviewRound !== undefined && raw.reviewRound !== round) fail();
+      return normalizeFinding(raw, file, changes, phase, files);
+    });
+    const generation = { findings: [...new Map(findings.map(f => [f.id, f])).values()], limitations: [...g.limitations] };
+    if (windowIds.length || phase === 'window-synthesis') {
+      const windows = sourceSegments(changeWindows(file, changes) ?? []);
+      const selected = windows.filter(w => windowIds.includes(w.id));
+      if (!windowIds.length || selected.length !== windowIds.length) fail();
+      validateWindowFindings(generation.findings, selected, phase === 'window-synthesis');
+    }
+    const normalized = { key, fileId: file.id, path: file.path, phase, round, windowIds: [...windowIds].sort(), ...(groupId !== undefined ? { groupId } : {}), generation, needsFreshProvenance: phase !== 'primary' };
+    const checked = validateGeneration?.(clone(generation), file, clone(normalized));
+    if (checked === false || checked?.then) fail();
+    return normalized;
+  });
+  if (Buffer.byteLength(JSON.stringify(output)) > maxBytes) fail();
+  return output;
+}