@feng0531/dsh-code-review 0.86.1 → 0.87.1

package/src/report-summary.mjs

@@ -0,0 +1,59 @@
+const FILE_STATES = ['completed', 'excluded', 'blocked', 'failed', 'cancelled', 'pending'];
+const STATUS_LABELS = { completed: '已完成', partial: '部分完成', failed: '执行失败', cancelled: '已取消', interrupted: '已中断', pending: '待执行', running: '执行中' };
+const safe = value => Array.from(String(value ?? '').slice(0, 240)).map(c => {
+  if (c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127) return ' ';
+  if (c === '&') return '&amp;';
+  if (c === '<') return '&lt;';
+  if (c === '>') return '&gt;';
+  if ('*_[]#|!()\\'.includes(c) || c.charCodeAt(0) === 96) return '\\' + c;
+  return c;
+}).join('');
+const rows = value => Array.isArray(value) ? value : [];
+const validCount = n => Number.isSafeInteger(n) && n >= 0;
+const supported = finding => finding?.verification?.status === 'completed' && finding.verification.verdict === 'supported' && rows(finding.verification.evidence).length > 0 && finding.verification.evidence.every(ref => ref?.status === 'references-validated');
+
+// Presentation consumes host-validated results; it neither re-reads sources nor
+// upgrades model verdicts, reference validation, or reuse into causal proof.
+function comparisonValidated(finding) {
+  const { evidence, regression } = finding.verification ?? {};
+  if (regression?.status !== 'comparison-references-validated' || !Array.isArray(evidence)) return false;
+  const old = regression.oldEvidence, fresh = regression.newEvidence;
+  if (![old, fresh].every(indices => Array.isArray(indices) && indices.length > 0 && indices.length <= 8 && new Set(indices).size === indices.length && indices.every(i => Number.isSafeInteger(i) && i >= 0 && i < evidence.length && evidence[i]?.status === 'references-validated'))) return false;
+  if (old.some(index => fresh.includes(index))) return false;
+  // The comparison validator already checks primary-file identity and sides.
+  // Reject inconsistent copied summaries without guessing sides from source IDs.
+  return old.every(i => typeof evidence[i].sourceId === 'string' && evidence[i].sourceId) && fresh.every(i => typeof evidence[i].sourceId === 'string' && evidence[i].sourceId && old.every(j => evidence[j].sourceId !== evidence[i].sourceId));
+}
+
+export function reportSummaryMarkdown(report = {}) {
+  const findings = rows(report.findings), files = rows(report.files);
+  const counts = { introduced: 0, unresolved: 0, refuted: 0, preexisting: 0, current: 0 };
+  for (const finding of findings) {
+    const verification = finding?.verification;
+    if (verification?.status === 'completed' && verification.verdict === 'refuted' && rows(verification.evidence).length && verification.evidence.every(ref => ref?.status === 'references-validated')) counts.refuted++;
+    else if (!supported(finding)) counts.unresolved++;
+    else if (report.reviewMode === 'project' || report.projectScope || finding.attribution?.causality === 'current-source-only') counts.current++;
+    else if (comparisonValidated(finding) && verification.regression.classification === 'introduced') counts.introduced++;
+    else if (comparisonValidated(finding) && verification.regression.classification === 'preexisting') counts.preexisting++;
+    else counts.unresolved++;
+  }
+  const coverage = Object.fromEntries(FILE_STATES.map(status => [status, validCount(report.coverage?.[status]) ? report.coverage[status] : files.filter(f => f?.status === status).length]));
+  const total = validCount(report.coverage?.total) ? report.coverage.total : files.length;
+  const unfinished = files.filter(file => !['completed', 'excluded'].includes(file?.status) || rows(file.stageFailures).length || file.retrievalLimited || rows(file.windowCoverage?.pending).length || file.synthesisStatus && file.synthesisStatus !== 'completed' || file.verificationStatus && file.verificationStatus !== 'completed' || rows(file.reviewPasses).some(pass => pass?.status !== 'completed') || findings.some(finding => finding?.fileId === file.fileId && finding?.verification?.status !== 'completed'));
+  const incompleteInteractions = rows(report.interactions).filter(item => item?.status !== 'completed');
+  const output = ['', '## 结论摘要', '- 整体状态：' + (STATUS_LABELS[report.status] ?? '未知') + '；完成状态只表示处理进度，不表示代码正确。',
+    '- 已确认新增（独立复核支持、旧新对照引用已校验）：' + counts.introduced + '；未决／证据不足：' + counts.unresolved + '；已反驳候选：' + counts.refuted + '；既有问题（复核支持且旧新对照已校验）：' + counts.preexisting + '。'];
+  if (counts.current) output.push('- 当前源码复核支持：' + counts.current + '；当前源码模式不评估历史新增归因，不计为已确认新增。');
+  output.push('- 以上按候选记录计数，不是去重根因数；“已确认新增”仅指模型复核支持及引用校验成立，因果解释仍未经验证，不是事实或因果证明。');
+  if (findings.some(finding => finding?.reused || finding?.priorRun)) output.push('- 含既往轮次复用发现；保留原复核来源，不表示本轮重新取证。');
+  if (report.outdated) output.push('- 注意：来源已变化或无法复核；这些结论仅对应原批准快照，不能当作当前源码结论。');
+  output.push('- 范围：' + total + ' 个文件；完成 ' + coverage.completed + '，排除 ' + coverage.excluded + '，阻断 ' + coverage.blocked + '，失败 ' + coverage.failed + '，取消 ' + coverage.cancelled + '，待审 ' + coverage.pending + '。排除／阻断不是通过。');
+  if (unfinished.length) {
+    output.push('- 关键未完成范围：' + unfinished.slice(0, 5).map(file => safe(file.path ?? '未命名文件')).join('、') + (unfinished.length > 5 ? '；另有 ' + (unfinished.length - 5) + ' 个文件，见覆盖明细。' : '；阶段和限制见覆盖明细。'));
+  }
+  if (incompleteInteractions.length) output.push('- 跨文件综合未完成：' + incompleteInteractions.length + ' 项；主文件完成不能替代交互覆盖。');
+  if (rows(report.limitations).length) output.push('- 已记录限制：' + report.limitations.length + ' 项；完整内容保留在限制明细，不能据空发现判定通过。');
+  if (total === 0) output.push('- 未选择文件，没有执行代码审核；不能解释为零缺陷结论。');
+  if (!findings.length) output.push(total > 0 && coverage.completed > 0 && report.status === 'completed' && !unfinished.length && !incompleteInteractions.length && !rows(report.limitations).length && !report.outdated ? '- 已审范围内没有候选问题记录；不证明不存在缺陷。' : '- 当前没有候选问题记录；执行状态、未完成范围或限制不支持“审核通过”。');
+  return output;
+}

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-change-map.mjs

@@ -0,0 +1,17 @@
+import { changeMap } from './change-map.mjs';
+import { changeRegion } from './change-region.mjs';
+
+// Canonical review transport coordinates, recomputed solely from approved source.
+// An envelope is a bounded broad region, never an exact edit or causal proof.
+export function reviewChangeMap(before, after) {
+  const changes = changeMap(before, after);
+  if (changes.status !== 'limited') return changes;
+  const region = changeRegion(before, after);
+  if (region.status !== 'changed') return changes;
+  return {
+    status: 'changed', precision: 'envelope',
+    reason: 'Exact diff unavailable; broad region includes potentially unchanged lines, not exact edits or causal proof.',
+    edits: [{ id: 'envelope1', old: region.old, new: region.new }],
+    hunks: [{ id: 'envelope-h1', old: region.old, new: region.new, editIds: ['envelope1'] }],
+  };
+}

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,15 +1,140 @@
 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'); };
+// Private export-only sentinel: never infer capacity from an arbitrary error/code.
+class ResumeStorageCapacityError extends Error {
+  constructor() { super('Resume checkpoint exceeds storage capacity'); this.code = 'RESUME_STORAGE_CAPACITY_EXCEEDED'; }
+}
+const capacity = mode => { if (mode === 'export') throw new ResumeStorageCapacityError(); if (mode !== 'scan') invalid(); };
+export const RESUME_CHECKPOINT_CAPACITY_LIMITATION = '续审检查点容量受限：仅保存适配容量的完整历史单元，未保存部分将重新执行；不影响本次发现或授予证据权限。';
+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, capacityMode } = {}, seen = new Set(), depth = 0, budget = { nodes: 0, bytes: 0 }) {
+  if (depth > 32) invalid();
+  if (++budget.nodes > 300000) capacity(capacityMode);
+  if (typeof value === 'string') { budget.bytes += Buffer.byteLength(value); if (budget.bytes > MAX_BYTES) capacity(capacityMode); 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, capacityMode }, seen, depth + 1, budget);
+  }
+  seen.delete(value);return out;
+}
+function bounded(value, capacityMode) { if (Buffer.byteLength(JSON.stringify(value)) > MAX_BYTES) capacity(capacityMode); return value; }
+
+function exportWithinCapacity(value) {
+  const cloned = bounded(privateClone(value, { stripReceipts: true, capacityMode: 'export' }), 'export');
+  // Accepted-stage import has a stricter aggregate node budget than the wrapper.
+  const stageBudget = { nodes: 0, bytes: 0 };
+  privateClone(cloned.stageGenerations, { capacityMode: 'export' }, new Set(), 0, stageBudget);
+  if (stageBudget.nodes > 200000) throw new ResumeStorageCapacityError();
+  return cloned;
+}
+function capacityFits(value) {
+  try { exportWithinCapacity(value); return true; }
+  catch (error) { if (error instanceof ResumeStorageCapacityError) return false; throw error; }
+}
+function boundedExport(result, report, snapshot) {
+  // Every unit has already passed structural and semantic checks before admission.
+  // Only the serialized storage/node aggregate may degrade; unknown errors escape.
+  if (capacityFits(result)) return prepareV2(exportWithinCapacity(result), snapshot);
+  const next = { schemaVersion: 2, snapshotId: result.snapshotId, identityHash: result.identityHash, completed: [], interactions: [], stageGenerations: [] };
+  exportWithinCapacity(next); // Even an unusable identity shell must fail normally.
+  const omitted = { completed: 0, stageGenerations: 0, interactions: 0, continuation: 0, businessGrouping: 0 };
+  for (const row of result.completed) {
+    const candidate = { ...next, completed: [...next.completed, row] };
+    if (capacityFits(candidate)) next.completed.push(row); else omitted.completed++;
+  }
+  if (result.businessGrouping !== undefined) {
+    if (capacityFits({ ...next, businessGrouping: result.businessGrouping })) next.businessGrouping = result.businessGrouping; else omitted.businessGrouping++;
+  }
+  for (const row of result.stageGenerations) {
+    if (capacityFits({ ...next, stageGenerations: [...next.stageGenerations, row] })) next.stageGenerations.push(row); else omitted.stageGenerations++;
+  }
+  if (result.continuation !== undefined) {
+    // Historical continuation cannot imply completion for a dropped primary unit.
+    if (!omitted.stageGenerations && !omitted.completed && capacityFits({ ...next, continuation: result.continuation })) next.continuation = result.continuation; else omitted.continuation++;
+  }
+  const kept = new Set(next.completed.map(row => row.fileId));
+  for (const row of result.interactions) {
+    if (row.fileIds.every(id => kept.has(id)) && capacityFits({ ...next, interactions: [...next.interactions, row] })) next.interactions.push(row); else omitted.interactions++;
+  }
+  const limitation = { code: 'RESUME_CHECKPOINT_CAPACITY_EXCEEDED', text: RESUME_CHECKPOINT_CAPACITY_LIMITATION, omitted };
+  report.resumeLimitations ??= [];
+  const previous = report.resumeLimitations.findIndex(row => row.code === limitation.code);
+  if (previous < 0) report.resumeLimitations.push(limitation); else report.resumeLimitations[previous] = limitation;
+  report.limitations ??= [];
+  if (!report.limitations.some(row => row.text === limitation.text)) report.limitations.push({ text: limitation.text });
+  return prepareV2(exportWithinCapacity(next), snapshot);
+}
+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
 // neither source authority nor model approval. Exact whole-snapshot binding is
 // deliberately conservative: any changed context/rule/source invalidates reuse.
 export function buildResumeState(snapshot, options, report) {
-  if (typeof snapshot?.id !== 'string' || !Array.isArray(snapshot.files) || !report || !Array.isArray(report.files) || !Array.isArray(report.findings)) throw new Error('Invalid resume checkpoint');
+  if (typeof snapshot?.id !== 'string' || !Array.isArray(snapshot.files) || !report || typeof report !== 'object') throw new Error('Invalid resume checkpoint');
+  if (stageEnabled(options)) {
+    // Scan the entire export payload before any filtering/size admission. Unlike
+    // imports this scan records no storage entitlement, but never executes hooks.
+    if (![Object.prototype, null].includes(Object.getPrototypeOf(report))) invalid();
+    const noticeDescriptor = Object.getOwnPropertyDescriptor(report, 'resumeLimitations');
+    if (noticeDescriptor && (!noticeDescriptor.enumerable || !Object.hasOwn(noticeDescriptor, 'value') || !Array.isArray(noticeDescriptor.value))) invalid();
+    const keys = ['files', 'findings', 'limitations', 'interactions', 'businessGrouping', 'stageGenerations', 'continuationOptions', 'continuation', 'resumeLimitations'];
+    const candidate = {};
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(report, key);
+      if (descriptor) { if (!descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) invalid(); candidate[key] = descriptor.value; }
+    }
+    const safe = privateClone(candidate, { stripReceipts: true, capacityMode: 'scan' });
+    // Preserve mutation target only for explicit capacity notices below.
+    return buildStageResumeState(snapshot, options, safe, report);
+  }
+  return buildStageResumeState(snapshot, options, report, report);
+}
+
+function buildStageResumeState(snapshot, options, report, noticeTarget) {
+  if (!Array.isArray(report.files) || !Array.isArray(report.findings)) throw new Error('Invalid resume checkpoint');
   const approved = new Map(snapshot.files.filter(file => file.eligibility === 'reviewable').map(file => [file.id, file]));
   const completed = [];
   for (const state of report.files) {
@@ -28,12 +153,37 @@ 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;
+    const stageKeys = new Set();
+    result.stageGenerations = (report.stageGenerations ?? []).flatMap(record => {
+      const [row] = prepareStageGenerations(snapshot, [record]);
+      if (stageKeys.has(row.key)) invalid(); stageKeys.add(row.key);
+      return row.phase === 'primary' && !completed.some(item => item.fileId === row.fileId) ? [row] : [];
+    });
+    if (report.continuation !== undefined) result.continuation = continuationState(snapshot, { options: report.continuationOptions, state: report.continuation });
+    // Check every completed chain, including units later omitted for capacity.
+    for (const item of completed) {
+      const file = approved.get(item.fileId);
+      if (!file || !safeFile(item.state) || item.state.fileId !== item.fileId || item.state.path !== item.path ||
+          !Array.isArray(item.findings) || item.findings.some(f => f?.fileId !== item.fileId || f.verification?.status !== 'completed') ||
+          !Array.isArray(item.limitations) || item.limitations.some(row => row?.fileId !== item.fileId)) throw new Error('Invalid completed resume chain');
+    }
+    return boundedExport(result, noticeTarget, 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 +195,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,148 @@
+import { hash } from './content.mjs';
+import { changeMap } from './change-map.mjs';
+import { reviewChangeMap } from './review-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;
+// Host-only accepted generation: member model 50 + group model 50 + host notes 2.
+// This is checkpoint/report metadata, never a wider model response or evidence grant.
+export const MAX_STAGE_LIMITATIONS = 102;
+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();
+    for (const key of ['precision', 'notice', 'causality']) if (raw.attribution?.[key] !== undefined && raw.attribution[key] !== attribution[key]) 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 > MAX_STAGE_LIMITATIONS || g.limitations.some(s => !text(s))) fail();
+    const changes = reviewChangeMap(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;
+}