@feng0531/dsh-code-review 0.86.0 → 0.87.0

package/src/service.mjs

@@ -55,16 +55,16 @@ function buildPreviewNotice(snapshot, options, enableRiskPlanning, changesConcur
   return scopeNotice + (snapshot.history?.vcs==='svn'&&options.autoContext===true?'SVN历史autoContext为精确依赖定位读取固定版本父目录有界清单，包含同目录非匹配名字元数据；仅匹配捕获正文发送模型，不扫描全仓，不用工作树替代历史版本。':'') + (options.oldContextPaths !== undefined ? 'oldContextPaths仅为baseline旧侧正文，无目标侧替代；选中变更复用原old身份，旧侧不能证明新侧行为。' : '') + (snapshot.callerDiscovery ? 'callerScopePaths已授权预览读取限定目录内tracked候选正文，包括不匹配文件；非匹配正文不发送模型，匹配捕获上下文会发送。仅字面引用导航，不是函数调用或完整调用覆盖。' : '') + (enableRiskPlanning ? '执行按plan阈值决定风险假设规划，小变更可跳过独立规划但仍主审并复核；计划不是证据，所有阶段共享原预算。' : '') + `执行会向上述模型提供方发送可审查文件两侧内容、预览列出的显式/自动上下文、所选项目规则全文及预览业务需求文本。模型可在该快照范围内多轮只读检索，不读取范围外文件；候选生成后会进行证据与反证复核，两阶段各最多${maxRetrievalRounds}轮检索；独立文件审查链最多${changesConcurrency}条并发，不设插件内部默认时间或总模型调用次数截止，遵循宿主/用户取消；输入字节和检索轮次保护仍保留；复核不能证明缺陷成立。plan.reviewRounds为独立审查工作量，非模型reasoning effort；后续轮不带首轮风险计划，所有轮共享原超时与预算。plan仅预检初始输入，ready不代表已审查；minimumCalls不含后续检索/复核/动态业务综合；多文件可先进行业务分组，分组失败保留原组并记录限制，动态综合数执行前未知，实际预算可能不足。请先向用户展示范围，获得确认后执行。`;
 }
 
-function createSessionReviewService(llm, { capture = captureSnapshot, now = Date.now, ttlMs = 300000, maxPreviews = 8, allowModelSending = false, enableRiskPlanning = false, skipSmallRiskPlans = true, reviewRounds = 1, enableBusinessGrouping = false, enableAnchorCorrection = false, changesConcurrency = 2, maxRetrievalRounds = 3, riskPlanningMode = 'separate', readerBudgetPolicy = 'fixed', optimizeReviewCalls = false, enablePrimarySeeds = false, focusPrimaryContext = false, enableSearchSeeds = false, nativeOutputTools = false, enableGroupPrimary = false, authorize = async () => false } = {}) {
+function createSessionReviewService(llm, { capture = captureSnapshot, now = Date.now, ttlMs = 300000, maxPreviews = 8, allowModelSending = false, enableRiskPlanning = false, skipSmallRiskPlans = true, reviewRounds = 1, enableBusinessGrouping = false, enableAnchorCorrection = false, changesConcurrency = 2, maxRetrievalRounds = 3, riskPlanningMode = 'separate', readerBudgetPolicy = 'fixed', optimizeReviewCalls = false, enablePrimarySeeds = false, focusPrimaryContext = false, enableSearchSeeds = false, nativeOutputTools = false, enableGroupPrimary = false, enableEvidenceContext = false, inlineInteractionRisks = false, enableMigrationContracts = false, enableMigrationRegression = false, enableGroupInteractions = false, enableStageContinuation = false, authorize = async () => false } = {}) {
   for (const value of [ttlMs, maxPreviews]) if (!Number.isSafeInteger(value) || value < 1) throw new Error('Invalid preview limit');
   changesConcurrency = reviewConcurrency(changesConcurrency);
   maxRetrievalRounds = reviewRetrievalRounds(maxRetrievalRounds);
   riskPlanningMode = validateRiskPlanningMode(riskPlanningMode);
   reviewReaderBudget({ files: [] }, readerBudgetPolicy);
-  for (const value of [optimizeReviewCalls, enablePrimarySeeds, focusPrimaryContext, enableSearchSeeds, nativeOutputTools, enableGroupPrimary]) if (typeof value !== 'boolean') throw new Error('Invalid review optimization option');
+  for (const value of [optimizeReviewCalls, enablePrimarySeeds, focusPrimaryContext, enableSearchSeeds, nativeOutputTools, enableGroupPrimary, enableEvidenceContext, inlineInteractionRisks, enableMigrationContracts, enableMigrationRegression, enableGroupInteractions, enableStageContinuation]) if (typeof value !== 'boolean') throw new Error('Invalid review optimization option');
   const lifetime = new AbortController();
   const bind = exec => ({ ...exec, signal: exec.signal ? AbortSignal.any([exec.signal, lifetime.signal]) : lifetime.signal });
-  const resumeOptions = (options, route, rounds) => ({ captureOptions: options, route, runtime: REVIEW_RUNTIME, instructionsHash: hash(REVIEW_INSTRUCTIONS), execution: { rounds, enableRiskPlanning, skipSmallRiskPlans, enableBusinessGrouping, enableAnchorCorrection, changesConcurrency, maxRetrievalRounds, riskPlanningMode, readerBudgetPolicy, optimizeReviewCalls, enablePrimarySeeds, focusPrimaryContext, enableSearchSeeds, nativeOutputTools, enableGroupPrimary } });
+  const resumeOptions = (options, route, rounds) => ({ captureOptions: options, route, runtime: REVIEW_RUNTIME, instructionsHash: hash(REVIEW_INSTRUCTIONS), execution: { rounds, enableRiskPlanning, skipSmallRiskPlans, enableBusinessGrouping, enableAnchorCorrection, changesConcurrency, maxRetrievalRounds, riskPlanningMode, readerBudgetPolicy, optimizeReviewCalls, enablePrimarySeeds, focusPrimaryContext, enableSearchSeeds, nativeOutputTools, enableGroupPrimary, enableEvidenceContext, inlineInteractionRisks, enableMigrationContracts, enableMigrationRegression, enableGroupInteractions, enableStageContinuation } });
   const previews = new Map();
   let busy = false;
   function prune() { for (const [id, p] of previews) if (p.expires <= now()) previews.delete(id); }
@@ -97,7 +97,7 @@ function createSessionReviewService(llm, { capture = captureSnapshot, now = Date
         if (owner(exec).cwd !== current.cwd) throw new Error('Agent directory changed; preview again');
         const resumeState = savedResume === undefined ? undefined : validateResumeState(savedResume, snapshot, resumeOptions(options, current.route, rounds));
         const readerBudget = reviewReaderBudget(snapshot, readerBudgetPolicy);
-        const plan = buildCoveragePlan(snapshot, { enableGroupPrimary, resumeState, focusPrimaryContext, riskPlanningMode, enableRiskPlanning, skipSmallRiskPlans, reviewRounds:rounds, enableBusinessGrouping, instructions: REVIEW_INSTRUCTIONS, scope: configureWireBudget(createRetrievalScope(snapshot, { ...readerBudget, signal: exec.signal }), { nativeOutputTools }), grouping: buildReviewGroups(snapshot.files, inferFileRelations(snapshot.files)), maxInputBytes: 96 * 1024, signal: exec.signal });
+        const plan = buildCoveragePlan(snapshot, { enableEvidenceContext, inlineInteractionRisks, enableMigrationContracts, enableMigrationRegression, enableGroupInteractions, enableStageContinuation, enableGroupPrimary, resumeState, focusPrimaryContext, riskPlanningMode, enableRiskPlanning, skipSmallRiskPlans, reviewRounds:rounds, enableBusinessGrouping, instructions: REVIEW_INSTRUCTIONS, scope: configureWireBudget(createRetrievalScope(snapshot, { ...readerBudget, signal: exec.signal, ...(optimizeReviewCalls ? { reuseResults: true } : {}) }), { nativeOutputTools }), grouping: buildReviewGroups(snapshot.files, inferFileRelations(snapshot.files)), maxInputBytes: 96 * 1024, signal: exec.signal });
         prune();
         while (previews.size >= maxPreviews) previews.delete(previews.keys().next().value);
         const previewId = randomUUID();
@@ -110,8 +110,8 @@ function createSessionReviewService(llm, { capture = captureSnapshot, now = Date
   ...(resumeState ? { resume: resumePreview(resumeState, sourceJobId) } : {}),
   plan,
   snapshotId: snapshot.id,
-  privateArtifacts: { enabled: typeof exec.onModelArtifact === 'function', sourceBearing: true, maxArtifactBytes: 1048576, maxJobBytes: 8388608, maxArtifacts: 64, notice: 'Background jobs retain bounded untrusted model output outside the reviewed workspace; omissions/truncation explicit. Never included in ordinary status or reused as evidence; explicit consent required to read.' },
-  execution: { nativeOutputTools, enableGroupPrimary, fileConcurrency: changesConcurrency, maxRetrievalRounds, ...(optimizeReviewCalls ? { riskPlanningMode, readerBudget: { policy: readerBudgetPolicy, ...readerBudget }, missingContextSeeds: enablePrimarySeeds, focusPrimaryContext, searchContextSeeds: enableSearchSeeds } : {}) },
+  privateArtifacts: { enabled: typeof exec.onModelArtifact === 'function', sourceBearing: true, maxArtifactBytes: 1048576, maxJobBytes: 8388608, maxArtifacts: 4096, notice: 'Background jobs retain bounded untrusted model output outside the reviewed workspace; omissions/truncation explicit. Never included in ordinary status or reused as evidence; explicit consent required to read.' },
+  execution: { nativeOutputTools, enableGroupPrimary, enableEvidenceContext, inlineInteractionRisks, enableMigrationContracts, enableMigrationRegression, enableGroupInteractions, enableStageContinuation, fileConcurrency: changesConcurrency, maxRetrievalRounds, ...(optimizeReviewCalls ? { riskPlanningMode, readerBudget: { policy: readerBudgetPolicy, ...readerBudget }, missingContextSeeds: enablePrimarySeeds, focusPrimaryContext, searchContextSeeds: enableSearchSeeds } : {}) },
   repositoryRoot: snapshot.root,
   vcs: snapshot.vcs,
   ...(snapshot.changeScope ? { changeScope: snapshot.changeScope } : options.changeScope !== undefined ? { changeScope: options.changeScope } : {}),
@@ -141,7 +141,7 @@ function createSessionReviewService(llm, { capture = captureSnapshot, now = Date
   ...(snapshot.callerDiscovery ? { callerDiscovery: snapshot.callerDiscovery } : {}),
   ...(snapshot.autoContext ? { autoContext: snapshot.autoContext } : {}),
   rules: (snapshot.rules ?? []).map(({ path, hash }) => ({ path, hash })),
-  notice: buildPreviewNotice(snapshot, options, enableRiskPlanning, changesConcurrency, maxRetrievalRounds) + (optimizeReviewCalls ? ` 完整正文或覆盖全部精确编辑的单批窗口可将风险问题合并入主审（非独立规划）；仅对批准上下文的确定坐标预取小片段，不代表完整核查。${focusPrimaryContext ? " 主审优先保留主文件全文，仅附带有关联的有界完整上下文；其余批准来源保留目录按需读，不表示不存在或已核查。" : ""}${enableSearchSeeds ? " 可将模型搜索命中的批准原行小片段与搜索结果同轮提供，每阶段最多2次额外读取，共用原预算；不猜测另侧坐标，不增加检索轮次。" : ""}共享检索上限按本次范围计算：${readerBudget.maxCalls}次操作／${readerBudget.maxOutputBytes}字节，所有阶段共用、不逐文件重置；无法取得必要证据的阶段不再无效启动。` : ''),
+  notice: buildPreviewNotice(snapshot, options, enableRiskPlanning, changesConcurrency, maxRetrievalRounds) + (enableMigrationContracts ? ' 迁移契约仅由批准快照的明确旧/新入口与调用绑定产生，无法解析的语言结构保持未解决，不以相似名称推断迁移。' : '') + (enableMigrationRegression ? ' 显式跨文件旧新比较仅在host契约限定来源和本次独立回执齐备时成立，因果仍未证明。' : '') + (enableGroupInteractions ? ' 组主审可附带交互结果，只有当前代全组编辑实读且host校验通过时替代匹配专门阶段；缺失/非法回退，候选仍独立复核。' : '') + (enableStageContinuation ? ' 未完成阶段可在其他阶段释放额度后有限继续，不重置总账或原超时；已验收主审生成可精确续用，但复核重新读取、新回执，不继承旧证据。' : '') + (enableEvidenceContext ? ' 可将本次实际交付过的批准原行按相关性经当前阶段reader有限重新投递；缓存仍计交付字节，不继承历史读取覆盖或复核回执。' : '') + (inlineInteractionRisks ? ' 预算适配的精确跨文件单元可在交互主审同次返回风险假设，省去独立规划；缺失或无效风险不补发、不代表已完成风险核查。' : '') + (optimizeReviewCalls ? ` 完整正文或覆盖全部精确编辑的单批窗口可将风险问题合并入主审（非独立规划）；仅对批准上下文的确定坐标预取小片段，不代表完整核查。${focusPrimaryContext ? " 主审优先保留主文件全文，仅附带有关联的有界完整上下文；其余批准来源保留目录按需读，不表示不存在或已核查。" : ""}${enableSearchSeeds ? " 可将模型搜索命中的批准原行小片段与搜索结果同轮提供，每阶段最多2次额外读取，共用原预算；不猜测另侧坐标，不增加检索轮次。" : ""}共享检索上限按本次范围计算：${readerBudget.maxCalls}次唯一操作结果生成／${readerBudget.maxOutputBytes}交付字节，所有阶段共用、不逐文件重置；同快照相同请求可复用原始结果，每次交付仍计字节并重新签发复核回执；主审、综合及复核按权重预留最低额度，未用额度释放，额度不足仍如实标记未完成。` : ''),
 };
       } finally { busy = false; }
     },
@@ -168,7 +168,7 @@ function createSessionReviewService(llm, { capture = captureSnapshot, now = Date
         exec.signal?.throwIfAborted();
         if (owner(exec).cwd !== current.cwd || JSON.stringify(owner(exec).route) !== JSON.stringify(preview.route)) throw new Error('Agent changed during approval');
         await exec.reviewCheckpoint?.({stage:'approved-manifest',snapshotId:snapshot.id,files:snapshot.files.map(f=>({fileId:f.id,path:f.path,status:f.eligibility==='reviewable'?'pending':f.eligibility}))});
-        const report = await reviewSnapshot(snapshot, createDshModel(llm, preview.route,{correctJson:true,useNativeTools:nativeOutputTools}), { signal: exec.signal, enableRetrieval: true, enableGrouping: true, enableGroupPrimary, nativeOutputTools, enableVerification: true, riskPlanningMode, readerBudgetPolicy, optimizeReviewCalls, enablePrimarySeeds, focusPrimaryContext, enableSearchSeeds, enableRiskPlanning, skipSmallRiskPlans, reviewRounds:preview.rounds, enableBusinessGrouping, enableAnchorCorrection,changesConcurrency,maxRetrievalRounds,correctProtocol:true, onProgress:exec.reviewCheckpoint, resumeState, onModelArtifact: exec.onModelArtifact, onResumeCheckpoint: exec.reviewResumeCheckpoint ? async checkpoint => { await exec.reviewResumeCheckpoint(buildResumeState(snapshot, resumeIdentity, checkpoint)); } : undefined });
+        const report = await reviewSnapshot(snapshot, createDshModel(llm, preview.route,{correctJson:true,useNativeTools:nativeOutputTools}), { signal: exec.signal, enableRetrieval: true, enableGrouping: true, enableGroupPrimary, enableEvidenceContext, inlineInteractionRisks, enableMigrationContracts, enableMigrationRegression, enableGroupInteractions, enableStageContinuation, nativeOutputTools, enableVerification: true, riskPlanningMode, readerBudgetPolicy, optimizeReviewCalls, enablePrimarySeeds, focusPrimaryContext, enableSearchSeeds, enableRiskPlanning, skipSmallRiskPlans, reviewRounds:preview.rounds, enableBusinessGrouping, enableAnchorCorrection,changesConcurrency,maxRetrievalRounds,correctProtocol:true, onProgress:exec.reviewCheckpoint, resumeState, onModelArtifact: exec.onModelArtifact, onResumeCheckpoint: exec.reviewResumeCheckpoint ? async checkpoint => { await exec.reviewResumeCheckpoint(buildResumeState(snapshot, resumeIdentity, checkpoint)); } : undefined });
         report.model = preview.route;
         if (exec.reviewResumeCheckpoint) await exec.reviewResumeCheckpoint(buildResumeState(snapshot, resumeIdentity, report));
         // reviewSnapshot preserves cancelled coverage; do not replace it with a freshness error.

package/src/snapshot-reader.mjs

@@ -21,15 +21,17 @@ function budgetError(kind) {
 }
 
 // This capability reads only caller-approved text entries, never the filesystem.
-export function createSnapshotReader(snapshotId, entries, { maxBytes = 4 * 1024 * 1024, maxCalls = 50, maxOutputBytes = 256 * 1024, signal } = {}) {
+export function createSnapshotReader(snapshotId, entries, { maxBytes = 4 * 1024 * 1024, maxCalls = 50, maxOutputBytes = 256 * 1024, signal, reuseResults = false } = {}) {
   if (typeof snapshotId !== 'string' || !snapshotId || snapshotId.length > 200) throw new Error('Invalid snapshot identity');
   if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 16 * 1024 * 1024) throw new Error('Invalid reader budget');
   if (!Array.isArray(entries) || entries.length > 500) throw new Error('Invalid reader entries');
   for (const [value, cap] of [[maxCalls, 1000], [maxOutputBytes, 4 * 1024 * 1024]]) {
     if (!Number.isSafeInteger(value) || value < 1 || value > cap) throw new Error('Invalid reader budget');
   }
+  if (typeof reuseResults !== 'boolean') throw new Error('Invalid reader reuse option');
   signal?.throwIfAborted();
 
+  let cache = new Map(), cacheBytes = 0, cacheHits = 0, deliveries = 0;
   let calls = 0, outputBytes = 0, inTransaction = false;
   const begin = () => {
     signal?.throwIfAborted();
@@ -103,16 +105,66 @@ export function createSnapshotReader(snapshotId, entries, { maxBytes = 4 * 1024
     return { snapshotId, sourceId: id, hash: source.hash, start, count: selectedCount, text, endOfSource: endOffset === source.text.length };
   };
 
+  const validate = (kind, request) => {
+    if (!request || typeof request !== 'object') throw new Error('Invalid reader request');
+    if (kind === 'read') {
+      if (!sources.has(request.id)) throw new Error('Source not authorized');
+      if (!Number.isSafeInteger(request.start) || request.start < 1 || !Number.isSafeInteger(request.count) || request.count < 1 || request.count > 200) throw new Error('Invalid line range');
+    } else {
+      if (!validQuery(request.query, request.limit === undefined ? 20 : request.limit)) throw new Error('Invalid query request');
+      if (kind === 'search' && request.sourceIds !== undefined && (!Array.isArray(request.sourceIds) || !request.sourceIds.length || request.sourceIds.length > 20 || new Set(request.sourceIds).size !== request.sourceIds.length || request.sourceIds.some(id => !sources.has(id)))) throw new Error('Invalid search source filter');
+    }
+  };
+  const keyOf = (kind, request) => JSON.stringify(kind === 'read' ? [kind, request.id, request.start, request.count] : kind === 'find' ? [kind, request.query, request.limit ?? 20] : [kind, request.query, request.limit ?? 20, request.sourceIds === undefined ? null : [...request.sourceIds].sort()]);
+  const materialize = (kind, request) => kind === 'read' ? read(request) : kind === 'find' ? find(request) : search(request);
+  const deliver = (kind, request, decorate = value => value) => {
+    signal?.throwIfAborted();
+    // Validation is never bypassed by canonicalization (e.g. duplicate filters).
+    if (reuseResults) validate(kind, request);
+    const key = reuseResults ? keyOf(kind, request) : null;
+    const cached = reuseResults && cache.get(key);
+    if (!cached) begin();
+    const raw = cached ? structuredClone(cached.result) : materialize(kind, request);
+    const result = finish(decorate(structuredClone(raw)));
+    if (reuseResults) {
+      deliveries++;
+      if (cached) cacheHits++;
+      else {
+        const size = resultSize(raw);
+        if (cache.size < maxCalls && cacheBytes + size <= maxOutputBytes) { cache.set(key, { result: structuredClone(raw), size }); cacheBytes += size; }
+      }
+    }
+    return result;
+  };
+  const preflight = requests => {
+    signal?.throwIfAborted();
+    if (!Array.isArray(requests) || !requests.length || requests.length > 8) throw new Error('Invalid retrieval batch');
+    const staged = new Map(cache); let stagedBytes = cacheBytes, needed = 0, size = 0, hits = 0;
+    for (const request of requests) {
+      if (!['read', 'find', 'search'].includes(request?.kind)) throw new Error('Unsupported retrieval operation');
+      // Dry-run validates against immutable approved sources; it grants no receipts.
+      validate(request.kind, request);
+      const key = reuseResults ? keyOf(request.kind, request) : null;
+      const raw = reuseResults && staged.has(key) ? staged.get(key).result : materialize(request.kind, request), bytes = resultSize(raw);
+      if (reuseResults && staged.has(key)) hits++;
+      else { needed++; if (reuseResults && staged.size < maxCalls && stagedBytes + bytes <= maxOutputBytes) { staged.set(key, { result: raw, size: bytes }); stagedBytes += bytes; } }
+      size += bytes;
+    }
+    if (calls + needed > maxCalls) throw budgetError('call');
+    if (outputBytes + size > maxOutputBytes) throw budgetError('output');
+    return { calls: needed, outputBytes: size, cacheHits: hits };
+  };
   return Object.freeze({
-    usage: () => ({ calls, outputBytes }),
-    budget: () => ({ maxCalls, maxOutputBytes, remainingCalls: maxCalls - calls, remainingOutputBytes: maxOutputBytes - outputBytes, maxResultBytes: 64 * 1024 }),
+    usage: () => ({ calls, outputBytes, ...(reuseResults ? { cacheHits, deliveries, cacheEntries: cache.size, cacheBytes } : {}) }),
+    budget: () => ({ maxCalls, maxOutputBytes, remainingCalls: maxCalls - calls, remainingOutputBytes: maxOutputBytes - outputBytes, maxResultBytes: 64 * 1024, ...(reuseResults ? { reusableResults: cache.size > 0 } : {}) }),
+    canServe(requests) { try { preflight(requests); return true; } catch { return false; } },
     // A synchronous host-only batch commits its ledger only as a whole. This
     // also covers decorated response bytes that preflight cannot predict.
     // Callers must not publish results/audit records before this returns.
     transaction(execute) {
       signal?.throwIfAborted();
       if (inTransaction || typeof execute !== 'function') throw new Error('Invalid reader transaction');
-      const previousCalls = calls, previousBytes = outputBytes;
+      const previousCalls = calls, previousBytes = outputBytes, previousCache = new Map(cache), previousCacheBytes = cacheBytes, previousHits = cacheHits, previousDeliveries = deliveries;
       inTransaction = true;
       try {
         const result = execute();
@@ -120,29 +172,17 @@ export function createSnapshotReader(snapshotId, entries, { maxBytes = 4 * 1024
         signal?.throwIfAborted();
         return result;
       } catch (error) {
-        calls = previousCalls; outputBytes = previousBytes;
+        calls = previousCalls; outputBytes = previousBytes; cache = previousCache; cacheBytes = previousCacheBytes; cacheHits = previousHits; deliveries = previousDeliveries;
         throw error;
       } finally { inTransaction = false; }
     },
     // Host-only dry run. Validate ALL ranges and sources before charging anything.
     // No evidence or receipts escape this preflight. Decorated reads are still
     // measured by finish; this never reserves or increases the shared budget.
-    preflight(requests) {
-      signal?.throwIfAborted();
-      if (!Array.isArray(requests) || !requests.length || requests.length > 8) throw new Error('Invalid retrieval batch');
-      const results = requests.map(request => {
-        if (request?.kind === 'read') return read(request);
-        if (request?.kind === 'find') return find(request);
-        if (request?.kind === 'search') return search(request);
-        throw new Error('Unsupported retrieval operation');
-      });
-      if (calls + requests.length > maxCalls) throw budgetError('call');
-      const size = results.reduce((sum, result) => sum + resultSize(result), 0);
-      if (outputBytes + size > maxOutputBytes) throw budgetError('output');
-    },
-    find(request) { begin(); return finish(find(request)); },
-    search(request) { begin(); return finish(search(request)); },
-    // decorate is a host-only callback; model requests never supply it.
-    read(request, decorate = value => value) { begin(); return finish(decorate(read(request))); },
+    preflight,
+    find(request) { return deliver('find', request); },
+    search(request) { return deliver('search', request); },
+    // Only immutable raw text is cached; each delivery creates fresh decorations.
+    read(request, decorate) { return deliver('read', request, decorate); },
   });
 }

package/src/stage-continuation.mjs

@@ -0,0 +1,74 @@
+import { createHash } from 'node:crypto';
+const KINDS = new Set(['verification', 'synthesis', 'interaction']);
+const REASONS = new Set(['READER_CALL_BUDGET_EXCEEDED', 'READER_OUTPUT_BUDGET_EXCEEDED', 'STAGE_INTERRUPTED', 'STAGE_CANCELLED', 'STAGE_TIMEOUT', 'STAGE_NO_PROGRESS', 'STAGE_ATTEMPTS_EXHAUSTED', 'STAGE_FAILED']);
+const fail = code => Object.assign(new Error(code), { code });
+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 => createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex');
+const same = (a,b) => JSON.stringify(a) === JSON.stringify(b);
+
+// Host metadata only: accepted generation belongs in the separate owner-bound
+// checkpoint. No read results/receipts are persisted or minted by this machine.
+export function createStageContinuation(snapshot, options, { completedPrimary = [], units = [], checkpoint, maxAttempts = 2 } = {}) {
+  if (!snapshot || typeof snapshot.id !== 'string' || !Array.isArray(snapshot.files) || !Number.isSafeInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 4 || !Array.isArray(units) || units.length > 2000) throw fail('INVALID_STAGE_CONTINUATION');
+  const fileIds = new Set(snapshot.files.filter(f => f.eligibility === 'reviewable').map(f => f.id));
+  if (!Array.isArray(completedPrimary) || new Set(completedPrimary).size !== completedPrimary.length || completedPrimary.some(id => !fileIds.has(id))) throw fail('INVALID_STAGE_PRIMARY');
+  const primary = [...completedPrimary].sort(), states = new Map();
+  for (const unit of units) {
+    if (!unit || typeof unit.id !== 'string' || !unit.id || unit.id.length > 500 || states.has(unit.id) || unit.id.startsWith('primary:') || !KINDS.has(unit.kind) || !Array.isArray(unit.fileIds) || !unit.fileIds.length || new Set(unit.fileIds).size !== unit.fileIds.length || unit.fileIds.some(id => !fileIds.has(id)) || !Array.isArray(unit.dependencies ?? []) || new Set(unit.dependencies ?? []).size !== (unit.dependencies ?? []).length) throw fail('INVALID_STAGE_UNIT');
+    states.set(unit.id, { id: unit.id, kind: unit.kind, fileIds: [...unit.fileIds], dependencies: [...(unit.dependencies ?? [])], status: 'pending', attempts: 0, pendingReason: null, stopped: false });
+  }
+  const visit = (id, visiting = new Set(), visited = new Set()) => {
+    if (visited.has(id)) return;
+    if (visiting.has(id)) throw fail('INVALID_STAGE_DEPENDENCIES');
+    visiting.add(id);
+    for (const dep of states.get(id).dependencies) {
+      if (typeof dep !== 'string' || dep === id) throw fail('INVALID_STAGE_DEPENDENCIES');
+      if (dep.startsWith('primary:')) { if (!fileIds.has(dep.slice(8))) throw fail('INVALID_STAGE_DEPENDENCIES'); }
+      else { if (!states.has(dep)) throw fail('INVALID_STAGE_DEPENDENCIES'); visit(dep, visiting, visited); }
+    }
+    visiting.delete(id); visited.add(id);
+  };
+  const visited = new Set(); for (const id of states.keys()) visit(id, new Set(), visited);
+  const identityHash = digest({ snapshot, options, primary, units: [...states.values()].map(({id,kind,fileIds,dependencies})=>({id,kind,fileIds,dependencies})), maxAttempts });
+  if (checkpoint !== undefined) {
+    if (!checkpoint || checkpoint.schemaVersion !== 1 || checkpoint.snapshotId !== snapshot.id || checkpoint.identityHash !== identityHash || checkpoint.maxAttempts !== maxAttempts || !same(checkpoint.completedPrimary, primary) || !Array.isArray(checkpoint.units) || checkpoint.units.length !== states.size || Object.keys(checkpoint).sort().join(',') !== 'completedPrimary,identityHash,maxAttempts,schemaVersion,snapshotId,units') throw fail('STAGE_CONTINUATION_IDENTITY_MISMATCH');
+    const seen = new Set();
+    for (const saved of checkpoint.units) {
+      const state = states.get(saved?.id);
+      if (!state || seen.has(saved.id) || !same(saved.fileIds,state.fileIds) || !same(saved.dependencies,state.dependencies) || saved.kind !== state.kind || !['pending','running','completed'].includes(saved.status) || !Number.isSafeInteger(saved.attempts) || saved.attempts < 0 || saved.attempts > maxAttempts || typeof saved.stopped !== 'boolean' || saved.pendingReason !== null && !REASONS.has(saved.pendingReason) || Object.keys(saved).sort().join(',') !== 'attempts,dependencies,fileIds,id,kind,pendingReason,status,stopped' || (saved.status !== 'pending' && saved.attempts === 0)) throw fail('INVALID_STAGE_CHECKPOINT');
+      seen.add(saved.id); Object.assign(state, { status: saved.status === 'running' ? 'pending' : saved.status, attempts: saved.attempts, pendingReason: saved.status === 'running' ? 'STAGE_INTERRUPTED' : saved.pendingReason, stopped: saved.stopped });
+    }
+  }
+  const get = id => { const state=states.get(id); if (!state) throw fail('UNKNOWN_STAGE_UNIT'); return state; };
+  const dependenciesReady = state => state.fileIds.every(id => primary.includes(id)) && state.dependencies.every(dep => dep.startsWith('primary:') ? primary.includes(dep.slice(8)) : get(dep).status === 'completed');
+  for (const state of states.values()) {
+    if (state.status === 'completed' && (!dependenciesReady(state) || state.stopped || state.pendingReason !== null)) throw fail('INVALID_STAGE_CHECKPOINT');
+  }
+  const copy = state => structuredClone(state);
+  const api = {
+    ready() { return [...states.values()].filter(s => s.status === 'pending' && !s.stopped && s.attempts < maxAttempts && dependenciesReady(s)).map(copy); },
+    start(id, { signal } = {}) {
+      signal?.throwIfAborted(); const state=get(id);
+      if (state.status !== 'pending' || state.stopped || state.attempts >= maxAttempts || !dependenciesReady(state)) throw fail('STAGE_NOT_READY');
+      state.status='running'; state.attempts++; state.pendingReason=null;
+      return { id, attempt: state.attempts, kind: state.kind, fileIds: [...state.fileIds], boundary: 'stage-start', requiresFreshEvidence: true };
+    },
+    complete(id, attempt, { signal } = {}) {
+      const state=get(id);
+      if (state.status !== 'running' || state.attempts !== attempt) throw fail('STALE_STAGE_ATTEMPT');
+      if (signal?.aborted) { state.status='pending'; state.pendingReason='STAGE_CANCELLED'; state.stopped=true; signal.throwIfAborted(); }
+      state.status='completed'; state.pendingReason=null;
+    },
+    yield(id, reason = 'STAGE_NO_PROGRESS') {
+      const state=get(id); if (state.status !== 'running' || !REASONS.has(reason)) throw fail('INVALID_STAGE_TRANSITION');
+      state.status='pending'; state.pendingReason=state.attempts >= maxAttempts ? 'STAGE_ATTEMPTS_EXHAUSTED' : reason; state.stopped=state.attempts >= maxAttempts;
+    },
+    stop(id, reason = 'STAGE_NO_PROGRESS') {
+      const state=get(id); if (state.status === 'completed' || !REASONS.has(reason)) throw fail('INVALID_STAGE_TRANSITION');
+      state.status='pending'; state.pendingReason=reason; state.stopped=true;
+    },
+    checkpoint() { return { schemaVersion: 1, snapshotId: snapshot.id, identityHash, maxAttempts, completedPrimary: [...primary], units: [...states.values()].map(copy) }; },
+    summary() { const values=[...states.values()]; return { units: values.length, completed: values.filter(s=>s.status==='completed').length, pending: values.filter(s=>s.status==='pending').length, running: values.filter(s=>s.status==='running').length, stopped: values.filter(s=>s.stopped).length, attempts: values.reduce((n,s)=>n+s.attempts,0) }; },
+  };
+  return Object.freeze(api);
+}

package/src/verification-loop.mjs

@@ -1,4 +1,5 @@
-import { VERIFICATION_INSTRUCTIONS } from './prompts.mjs';
+import { prepareMigrationRegression, migrationRegressionMetadata } from './migration-regression.mjs';
+import { VERIFICATION_INSTRUCTIONS, MIGRATION_VERIFICATION_INSTRUCTIONS } from './prompts.mjs';
 import { CONTEXT_SIDE_NOTICE } from './context-identity.mjs';
 import { defectGuidance } from './defect-guidance.mjs';
 import { modelWireBudget } from './model-wire-budget.mjs';
@@ -15,13 +16,17 @@ export { VERIFICATION_INSTRUCTIONS };
 export async function verificationLoop(model, request, candidates, scope, options = {}) {
   request.signal?.throwIfAborted();
   if (!Array.isArray(candidates) || candidates.length > 50) throw new Error('Invalid candidates');
+  if (options.enableMigrationRegression !== undefined && typeof options.enableMigrationRegression !== 'boolean') throw new Error('Invalid migration regression policy');
   if (!candidates.length) return [];
   const ids = candidates.map((_, i) => 'c' + (i + 1));
   const envelope = request.input ? JSON.parse(request.input) : {};
   const rules = envelope.rules ?? [];
-  const input = JSON.stringify({ contextSideNotice:CONTEXT_SIDE_NOTICE, ...(envelope.businessRequirement!==undefined?{businessRequirement:envelope.businessRequirement,requirementNotice:envelope.requirementNotice}:{}), defectGuidance: [...new Set(candidates.map(f => scope.catalog().find(s => s.fileId === f.fileId)?.path).filter(Boolean))].map(path => envelope.file?.path === path && envelope.defectGuidance ? envelope.defectGuidance : envelope.files?.find(f=>f.path===path)?.defectGuidance ?? defectGuidance(path)), rules, candidates: candidates.map((finding, i) => ({ candidateId: ids[i], finding })) });
+  const project = options.migrationSnapshot?.projectScope || options.migrationSnapshot?.files?.some(file => file.reviewMode === 'project') || envelope.file?.reviewMode === 'project';
+  if (options.enableMigrationRegression === true && !project && options.migrationContracts?.length && options.migrationSnapshot?.id !== envelope.snapshotId) throw new Error('Migration verification snapshot mismatch');
+  const migrationContext = options.enableMigrationRegression === true && !project && options.migrationContracts?.length ? prepareMigrationRegression(options.migrationSnapshot, scope, options.migrationContracts, candidates) : undefined;
+  const input = JSON.stringify({ ...(envelope.snapshotId ? { snapshotId: envelope.snapshotId } : {}), ...(migrationContext ? { migrationContracts: migrationRegressionMetadata(migrationContext) } : {}), contextSideNotice:CONTEXT_SIDE_NOTICE, ...(envelope.businessRequirement!==undefined?{businessRequirement:envelope.businessRequirement,requirementNotice:envelope.requirementNotice}:{}), defectGuidance: [...new Set(candidates.map(f => scope.catalog().find(s => s.fileId === f.fileId)?.path).filter(Boolean))].map(path => envelope.file?.path === path && envelope.defectGuidance ? envelope.defectGuidance : envelope.files?.find(f=>f.path===path)?.defectGuidance ?? defectGuidance(path)), rules, candidates: candidates.map((finding, i) => ({ candidateId: ids[i], finding })) });
   const seedReceipts = new Map();
-  const verificationRequest = { ...request, input, instructions:envelope.file?.reviewMode==='project'?VERIFICATION_INSTRUCTIONS+' 本次为当前项目源码审查，空old只是传输占位，不是历史版本。不要要求回归因果；regression.classification用uncertain并说明不适用，仅凭new侧原文核实当前缺陷和反证。':VERIFICATION_INSTRUCTIONS };
+  const verificationRequest = { ...request, input, instructions:envelope.file?.reviewMode==='project'?VERIFICATION_INSTRUCTIONS+' 本次为当前项目源码审查，空old只是传输占位，不是历史版本。不要要求回归因果；regression.classification用uncertain并说明不适用，仅凭new侧原文核实当前缺陷和反证。':VERIFICATION_INSTRUCTIONS + (migrationContext ? ' ' + MIGRATION_VERIFICATION_INSTRUCTIONS : '') };
   // Explicit final-only mode has extra finalization metadata/instructions and
   // permits no retrieval rounds. Do not spend its budget on optional prefetch.
   const initialRetrieved = options.maxRounds === 0 ? [] : verificationSeeds(candidates, scope, {
@@ -39,5 +44,5 @@ export async function verificationLoop(model, request, candidates, scope, option
   // read under this invocation's receipt table and the shared approved budget.
   const response = await retrievalLoop(model, verificationRequest, retrievalScope, { ...options, initialRetrieved });
   request.signal?.throwIfAborted();
-  return validateCandidateVerification(response, ids, scope.read, resolveEvidence, { catalog: scope.catalog(), fileIds: Object.fromEntries(ids.map((id, i) => [id, candidates[i].fileId])) });
+  return validateCandidateVerification(response, ids, scope.read, resolveEvidence, { enableMigrationRegression: options.enableMigrationRegression === true && !project, migrationContext, catalog: scope.catalog(), fileIds: Object.fromEntries(ids.map((id, i) => [id, candidates[i].fileId])) });
 }

package/src/verification-seeds.mjs

@@ -35,8 +35,10 @@ export function verificationSeeds(candidates, scope, { signal, fits, onReceipt =
     const budget = scope.budget?.();
     // At least one exact final validation read per candidate must remain. This
     // reserves no new authority; additional evidence can still exhaust budgets.
-    if (budget && (budget.remainingCalls <= candidates.length || budget.remainingOutputBytes <= finalEvidenceBytes)) break;
+    if (budget && budget.remainingOutputBytes <= finalEvidenceBytes) break;
     try {
+      const cached = budget?.reusableResults === true && scope.preflight?.([request])?.calls === 0 && scope.canServe?.([request]) === true;
+      if (budget && !cached && budget.remainingCalls <= candidates.length) continue;
       // Failed transactions discard their receipt table too, not just the ledger.
       const receipts = createEvidenceReceipts(scope.read, { limit: 1 });
       const item = scope.transaction(() => {
@@ -48,7 +50,22 @@ export function verificationSeeds(candidates, scope, { signal, fits, onReceipt =
         const proposed = [...seeds, { request, result }];
         const nextBudget = scope.budget?.();
         const reserve = finalEvidenceBytes + Buffer.byteLength(JSON.stringify(result)) * references;
+        if (cached) {
+          // Validation reads the actual returned count, not the seed's requested
+          // EOF-clamped count. These are different exact cache keys. Reserve all
+          // final reads explicitly before admitting a zero-call cached seed.
+          let calls = 0;
+          for (const item of proposed) {
+            const validation = { kind: 'read', id: item.result.sourceId, start: item.result.start, count: item.result.count };
+            const cost = scope.preflight([validation]);
+            if (!Number.isSafeInteger(cost?.calls) || cost.calls < 0) throw capacityError();
+            const matching = [...ranges.values()].find(range => JSON.stringify(range.request) === JSON.stringify(item.request));
+            calls += cost.calls * (matching?.references ?? 1);
+          }
+          if (nextBudget && calls > nextBudget.remainingCalls) throw capacityError();
+        }
         if (Buffer.byteLength(JSON.stringify(proposed)) > MAX_SEED_BYTES || !fits(proposed) || (nextBudget && nextBudget.remainingOutputBytes < reserve)) throw capacityError();
+        signal?.throwIfAborted();
         return { request, result };
       });
       // Publish only after the approved reader has committed the transaction.