@feng0531/dsh-code-review 0.84.0 → 0.85.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 本文件介绍对使用者有意义的变化。安装与参数见 [README](README.md)，本次发布正文见 [发布说明](RELEASE-NOTES.md)。历史提交和安装包保留在 [GitHub Releases](https://github.com/f-e-n-g-0531/dsh-code-review/releases)；本文不把开发日志当作功能介绍。
 
+## 0.85.1 — 模型失败诊断与定向纠正
+
+- 修复宿主 error 终态详情读取位置，保留实际 `finish.reason.failure` 中的已知错误码、HTTP 状态和有效重试间隔，便于区分服务失败类别；不新增对鉴权、额度或取消的盲目重试。
+- 非法 JSON 记录固定语法分类、可用的行列位置及响应指纹，按最近一次分类定向请求重新生成；不回放错误原文，不自动修补 JSON，最多两次纠正且继续遵循原调用预算。
+- 新增诊断不保存模型响应片段或提供方原始 message，未知错误码和请求 ID 仅保留哈希；隔离进度回调对纠正诊断的修改，保持异常身份和 CR/LF/CRLF 定位一致。
+- 当前宿主没有原生 JSON mode／response schema 接口，本版不声称保证模型始终输出合法 JSON，也不以离线验证替代真实模型失败率复测。
+
+## 0.85.0 — 审查失败恢复与全项目提速
+
+- 全项目独立批次默认 3 路并行，插件配置 projectConcurrency 支持 1～8；预览/报告显示并发数，结果仍按原批次顺序合并，保持共享调用上限和取消后等待全部清理。批内主审与复核不跳过，预算竞争时未完成文件仍待处理。
+- 无效 JSON 最多两次显式纠正，记录所有尝试的脱敏诊断与实际调用次数；不修补响应，不重试取消、提供方失败或不完整输出。纠正结果不再插入可能破坏阶段 schema 的元数据。
+- 主审身份、严重性、字段或行证据校验失败可请求一次新响应，仍严格验证，不自动改身份、映射严重性或伪造证据。全项目模式支持同文件当前侧唯一精确文本的行号修正，保留原候选并继续窗口校验。
+- 向模型提供剩余检索预算；预检整批动态读取范围及预算，避免无效批次部分消耗。预算不足仅给一次受限最终答复，文件仍未完成，不把审查失败当缺陷或通过。
+
 ## 0.84.0 — 暂存区与未暂存审查范围
 
 新增 Git `changeScope`：`staged` 只审查 HEAD 到索引的已暂存内容，工作区里尚未暂存的修改不作为变更正文参与或发送（上下文与规则文件仍按工作区读取）；`unstaged` 只审查索引到工作区的未暂存改动，已暂存内容仅作旧侧基线。省略时仍是 HEAD 到工作区的净变化。两个范围只用于 Git 工作副本，不能与历史版本、SVN 参数或全项目模式混用；未跟踪文件仍默认排除。预览与报告会标明实际比较范围，执行前重新核验对应内容。

package/DEVELOPMENT.md

@@ -18,6 +18,22 @@
 
 项目捕获最多10000清单节点、1000选择节点、16MiB，不设默认总模型调用次数或执行秒表，初次捕获/复核均遵循宿主与用户取消。SVN项目模式拒绝不支持节点属性，不隐式继承固定历史审查的网络权限。
 
+## 全项目并发与离线速度对照
+
+插件配置 `projectConcurrency` 默认为 3，范围 1～8；1 为串行回退。仅独立批准批次并行，各批仍有独立检索来源和账本，所有调用与 JSON 纠正共享原执行计数。该上限按单次执行生效，不是全宿主 RPM/TPM 限流器；提供方不支持并发或遇到 429 时应调低。取消/致命检查点错误必须等待全部在途模型清理后释放会话锁，后台 checkpoint 继续使用原串行持久化队列。
+
+运行 `node scripts/review-speed-benchmark.mjs` 比较相同 12 个 mock 批次在串行与 3 路并发下的耗时；脚本模拟每次模型调用 40ms 延迟，不访问网络、不证明真实模型速度或质量。核对工作量、调用数、完成数和输出顺序一致，不把降低覆盖作为加速。
+
+## 模型响应失败与诊断
+
+当前核验的 DSH `llm.stream` 接口没有原生 JSON mode／response schema 参数；插件不发送会被忽略的 `responseFormat`，也不把工具参数 schema 当作结构化输出保证。先要求纯 JSON，再做本地解析和阶段 schema、证据校验。
+
+正常 stop 后的非法 JSON 最多重新生成两次，共享原调用预算与取消信号；纠正请求只带固定语法分类和可用的行列位置，不回放错误响应、不自动修补 JSON、不删减发现来换取通过。语法位置相对于去掉外层空白及完整代码围栏后的 JSON 正文，偏移单位为 UTF-16 code unit；未知运行时错误文本回退到通用分类，不推测位置。
+
+失败结果的 `protocolDiagnostic` 保留语法分类、行列位置（可用时）和响应 SHA-256 指纹，不存储响应片段或原生解析异常文本。宿主服务错误从 `finish.reason.failure` 读取，保留已知错误码、HTTP 状态、有效重试间隔和请求 ID 的哈希；未知码只存分类及哈希，不存提供方 message、原始 ID、URL、headers 或 body。已有工具链直接抛出的异常仍保持身份，不新增自动网络重试；AUTH、QUOTA、取消及 error 终态不能按格式错误重发。指纹只是对照线索，不是原文备份，也不构成跨模型确定性保证。
+
+执行 `node --test test/model-diagnostics.test.mjs test/model-json-correction.test.mjs test/model-protocol-diagnostics.test.mjs test/dsh-model.test.mjs` 可验证本地纠正、失败归类和脱敏；宿主检查另覆盖真实 ToolRuntime 的纠正和服务失败事件，均为受控离线模型，不证明真实服务失败率下降。
+
 ## 审查预算
 
 除 README 中的文件和输入上限外：

package/README.md

@@ -256,6 +256,8 @@ Git / SVN 历史审查也能使用这些参数；依赖和调用方按对应版
 
 清单上限10000节点，单次选择最多1000节点/16MiB，12节点一批，单文件256KiB；超限明确拒绝，缩小选择后必须重新预览。单次采集共享8MiB元数据内存保护，不按命令条数、插件秒表或模型调用次数中断；耗时受宿主/模型提供方限制，用户可随时取消。SVN为本地已观察清单，稀疏/外部/链接及不支持属性显示限制；不证明仓库远端完整覆盖。
 
+全项目审查默认最多 **3 个独立批次并行**，每批内主审、检索、复核仍按依赖顺序执行；预览和报告的 `execution.batchConcurrency` 显示实际配置。插件配置 `projectConcurrency` 可设为 1～8，设 1 回退串行；遇到模型提供方并发限制或 429，应降低并发。该设置不是 preview 参数，不扩大来源或共享模型调用预算，也不减少模型调用量或承诺 token 成本下降。仅一个批次时不会获得批间加速；实际提速受提供方吞吐、批次均衡及检查点写入影响。
+
 对外只交付一份统一最终报告，给出总数、completed、excluded、blocked、pending、去重后的发现及未完成综合阶段；内部批次快照仅供证据追溯，不需要用户拼接报告。completed只表示所选捕获文件已处理，不代表代码正确；排除与阻断从不算完成。代码或清单变化会拒绝旧预览，运行后无法复核则标记outdated。
 
 ## 工具调用流程（给需要精确指定参数的人）
@@ -283,6 +285,12 @@ Git / SVN 历史审查也能使用这些参数；依赖和调用方按对应版
 
 每个候选问题会保留位置、触发条件、影响和复核结果。复核可能支持、反驳、无法确定或未完成；引用原文匹配也不等于缺陷一定成立。**没有发现问题不证明没有缺陷，读取过上下文也不等于审查了整个项目。**
 
+### 模型协议错误与读取预算恢复
+
+已启用的模型桥接对完整结束但 JSON 无效的响应最多请求两次明确纠正（共最多三次调用），不会修补损坏 JSON；取消、提供方错误、不完整结束或输出超限不作此类重试。主审响应中的文件身份、严重性、必填字段或行证据校验失败时，最多请求一次完整响应纠正，仍按原快照、输入及调用预算严格验证。每次额外调用和纠正事件都会计数记录，恢复失败仍标为失败，不代表发现了缺陷。
+
+全项目模式可将行号错位的证据重新定位到同文件当前侧的唯一精确文本；不跨文件、跨版本或模糊匹配，原候选保留供审计，窗口范围仍须通过校验。模型会收到共享检索预算余量；预算耗尽或请求超过余量时仅给一次不再检索的最终答复机会，不扩大读取权限。预算受限的文件仍列为未完成，已有有效候选保留，不会因返回空 findings 就算审查通过。
+
 ## 常见问题
 
 | 遇到的问题 | 处理方法 |

package/RELEASE-NOTES.md

@@ -1,13 +1,19 @@
-# v0.84.0 发布说明
+# v0.85.1 发布说明
 
-## 新增 Git 暂存区 / 未暂存审查范围
+## 更可定位的模型失败
 
-本次新增 `changeScope` 参数，用于把 Git 工作副本审查限定到更精确的比较范围：
+修复宿主服务错误详情读取位置：从实际的 `finish.reason.failure` 取得已知错误码、HTTP 状态及有效重试间隔，不再因读取错字段而只留下 `Model did not complete: error`。提供方没有返回的细节仍不可推断；本版不新增自动网络重试。
 
-- `staged`：比较 HEAD 与索引，只审查已暂存内容。工作区里尚未 `git add` 的修改不会出现在右侧，也不会作为变更正文发送给模型。
-- `unstaged`：比较索引与工作区，只审查未暂存改动。已暂存内容只作为左侧基线，不代表由本次改动引入。
-- 省略该参数时行为不变，仍是 HEAD 到工作区的净变化。
+## 针对语法问题的有界纠正
 
-预览会展示实际比较范围与目标模型；报告会注明审查范围。`staged` 模式下上下文、自动依赖、调用方候选和规则文件仍按工作区当前内容读取，可能包含未暂存修改，预览会列出这些文件。执行前重新采集并核对两侧内容，预览之后暂存区或相关工作区内容变化会使旧预览失效。两个新值只支持 Git 工作副本，不能与 `commit`、`baseRevision`、`targetRevision`、SVN 参数或 `reviewMode:"project"` 混用；未跟踪文件仍默认排除，只有显式 `selectedPaths` 才会在 `worktree` / `unstaged` 中纳入。
+正常 stop 后的非法 JSON 现在记录固定语法分类、可用的正文行列位置和 SHA-256 响应指纹，并根据最近一次分类给出定向重新生成提示。偏移使用 JSON 正文的 UTF-16 单位，支持 CR、LF、CRLF；运行时未提供位置时明确不填，不虚构错误位置。
 
-用法和参数示例见 [README](README.md)。本版本不改变默认审查范围，也不提供真实模型缺陷率保证。
+仍最多重新生成两次，继续共享原调用预算和取消信号；不回放错误响应，不正则修补 JSON，不删除发现来换取格式通过，最终结果仍必须通过阶段 schema 与证据校验。进度回调拿到独立诊断副本，不能改变下一次纠正提示；异常访问器或 Proxy 不替换原始提供方异常。
+
+## 安全与验证边界
+
+新增诊断不保存模型响应片段、原生解析异常原文或提供方原始 message；未知错误码与请求 ID 仅保存哈希。已有直接抛出的异常仍保持身份，不把诊断扩展描述为全局日志脱敏。
+
+已增加语法定位、定向纠正、真实宿主终态字段、脱敏、预算、取消及回调隔离回归，并由真实宿主 ToolRuntime 配合受控离线模型验证。当前宿主没有公开原生 JSON mode／response schema 能力，本版本不通过虚构参数绕过该限制；不保证模型永不出错，也没有把离线测试说成真实服务失败率已经下降。
+
+用法见 [README](README.md)，诊断字段与验证方式见 [DEVELOPMENT](DEVELOPMENT.md)。发布不自动安装、升级或重启 DSH；需要用户更新并重新加载插件。

package/index.mjs

@@ -13,7 +13,7 @@ const EXECUTE_PARAMETERS = { type: 'object', additionalProperties: false, proper
 export function apply(ctx, config = {}) {
   // This entry runs only when the host invokes the registered tool.
   // Host tool policy owns permission; do not request a second approval here.
-  const service = createReviewService(ctx.llm, { allowModelSending: true, enableRiskPlanning: true, enableBusinessGrouping: true, enableAnchorCorrection: true, authorize: async () => true });
+  const service = createReviewService(ctx.llm, { allowModelSending: true, enableRiskPlanning: true, enableBusinessGrouping: true, enableAnchorCorrection: true, projectConcurrency: config.projectConcurrency ?? 3, authorize: async () => true });
   ctx.tools.register({
     name: 'code_review_preview', description: PREVIEW_DESCRIPTION, parameters: PREVIEW_PARAMETERS, output: reviewToolOutput,
     async execute(args, exec) { const preview = await service.preview(args, exec); return { json: JSON.stringify(preview), markdown: '' }; },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feng0531/dsh-code-review",
-  "version": "0.84.0",
+  "version": "0.85.1",
   "private": false,
   "license": "SEE LICENSE IN LICENSE",
   "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },

package/src/anchor-correction.mjs

@@ -6,13 +6,15 @@ export function correctAnchor(raw, file, changes, {signal}={}) {
  const text=(a.side==='old'?file.left:file.right)?.text;if(typeof text!=='string'||Buffer.byteLength(text)>256*1024)return result('not-applicable','source-limit');
  const source=text.replaceAll('\r\n','\n').split('\n'),snippet=a.snippet.replaceAll('\r\n','\n').split('\n');
  if(source.slice(a.start-1,a.end).join('\n')===snippet.join('\n'))return result('unchanged','already-exact');
- if(changes?.status!=='changed'||changes.precision!=='exact'||!Array.isArray(raw.attribution?.editIds)||!raw.attribution.editIds.length)return result('rejected','missing-exact-edit');
- const edits=changes.edits.filter(e=>raw.attribution.editIds.includes(e.id));if(edits.length!==raw.attribution.editIds.length)return result('rejected','unknown-or-duplicate-edit');
+ const currentSource = file.reviewMode === 'project' && a.side === 'new';
+ if(file.reviewMode === 'project' && !currentSource)return result('rejected','project-requires-new-side');
+ if(!currentSource&&(changes?.status!=='changed'||changes.precision!=='exact'||!Array.isArray(raw.attribution?.editIds)||!raw.attribution.editIds.length))return result('rejected','missing-exact-edit');
+ const edits=currentSource?[]:changes.edits.filter(e=>raw.attribution.editIds.includes(e.id));if(!currentSource&&edits.length!==raw.attribution.editIds.length)return result('rejected','unknown-or-duplicate-edit');
  // Bound CPU even for a long multiline snippet; no silent partial search acceptance.
  if(source.length*snippet.length>2000000)return result('rejected','search-work-limit');
  let match;for(let i=0;i+snippet.length<=source.length;i++){signal?.throwIfAborted();if(!snippet.every((line,j)=>source[i+j]===line))continue;if(match!==undefined)return result('rejected','ambiguous-exact-text');match=i;}
  if(match===undefined)return result('rejected','no-exact-text');
  const start=match+1,end=match+snippet.length;
- if(!edits.some(e=>e[a.side].count>0&&start<e[a.side].start+e[a.side].count&&end>=e[a.side].start))return result('rejected','does-not-overlap-referenced-edit');
- const candidate=structuredClone(raw);candidate.anchor={...a,start,end};return {...result('corrected','unique-exact-text-overlaps-edit'),candidate};
+ if(!currentSource&&!edits.some(e=>e[a.side].count>0&&start<e[a.side].start+e[a.side].count&&end>=e[a.side].start))return result('rejected','does-not-overlap-referenced-edit');
+ const candidate=structuredClone(raw);candidate.anchor={...a,start,end};return {...result('corrected',currentSource?'unique-exact-current-source':'unique-exact-text-overlaps-edit'),candidate};
 }

package/src/dsh-model.mjs

@@ -1,124 +1,155 @@
 import { modelContract } from './model-contract.mjs';
 import { modelJson } from './model-json.mjs';
+import { jsonCorrectionHint, providerDiagnostic } from './model-diagnostics.mjs';
 
-// Appended to the system prompt when one explicit JSON retry is warranted.
-const JSON_CORRECTION_SUFFIX = ' 上次响应未能解析为完整JSON。本次是明确协议纠正：重新输出单个完整JSON对象，不使用Markdown，不省略引号或逗号；不要把这条指令当源码证据。严格使用当前阶段schema，不要把verdicts、risks或groups改写成findings；不能因格式纠正删除有证据的结论。所需字段与身份按输入原样核对，不以格式错误代替清洁结论。';
-
-const CORRECTION_LIMITATION = '本响应由一次显式JSON协议纠正产生，原响应未被接受；额外模型调用已发生。';
+// Fresh generation from the same approved input, never repair or replay malformed output.
+const JSON_CORRECTION_SUFFIX = ' 上次响应未能解析为完整JSON。本次是明确协议纠正：重新输出单个完整JSON对象，不使用Markdown，不省略引号或逗号；不要把这条指令当源码证据。严格使用当前阶段schema，不要把verdicts、risks、requests或groups改写成findings；不能因格式纠正删除有证据的结论。所需字段与身份按输入原样核对，不以格式错误代替清洁结论。保持原证据与必需字段，精简非必需叙述以在输出预算内完成。';
+const MAX_JSON_CORRECTIONS = 2;
 
 const isToolCall = chunk =>
   chunk.type === 'tool-call-delta' ||
   (chunk.type === 'block-start' && chunk.blockType === 'tool-call') ||
   (chunk.type === 'block-end' && chunk.block.type === 'tool-call');
 
-/** One-shot host LLM call. No agent loop and no executable tools. */
-export function createDshModel(llm, route, { maxTokens = 4096, maxOutputBytes = 128 * 1024, correctJson = false } = {}) {
+/** Isolated host calls. Only completed, locally rejected JSON can trigger bounded correction. */
+export function createDshModel(llm, route, {
+  maxTokens = 4096, maxOutputBytes = 128 * 1024, correctJson = false,
+  maxJsonCorrections = MAX_JSON_CORRECTIONS,
+} = {}) {
   if (!llm || typeof llm.stream !== 'function' || !route?.provider || !route?.model) {
     throw new Error('DSH provider and model are required');
   }
+  if (!Number.isSafeInteger(maxTokens) || maxTokens < 1 ||
+      !Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 1 ||
+      !Number.isSafeInteger(maxJsonCorrections) || maxJsonCorrections < 0 || maxJsonCorrections > MAX_JSON_CORRECTIONS) {
+    throw new Error('Invalid model output or JSON correction limit');
+  }
   const identity = {
     provider: route.provider,
     model: route.model,
     ...(route.reasoningEffort ? { reasoningEffort: route.reasoningEffort } : {}),
   };
+  // Provider failures with a coincidentally identical code are not format failures.
+  const invalidJsonErrors = new WeakSet();
+  const failureMetadata = new WeakMap();
 
-  async function once({ instructions, input, signal }) {
+  async function once({ instructions, input, signal }, contract) {
     signal?.throwIfAborted();
     let output = '';
     let size = 0;
     let finished = false;
     let finishKind = 'missing';
-
     const diagnostic = () => ({
-      visibleBytes: Buffer.byteLength(output),
-      totalOutputBytes: size,
-      finishKind,
-      inputBytes: Buffer.byteLength(input),
-      requestedMaxTokens: maxTokens,
-    });
-
-    const providerCode = reason =>
-      typeof reason.error?.code === 'string' ? reason.error.code
-        : typeof reason.code === 'string' ? reason.code
-        : undefined;
-
-    const stream = llm.stream({
-      ...identity,
-      system: instructions + '\n' + modelContract(input, instructions),
-      messages: [{ role: 'user', content: [{ type: 'text', text: input }] }],
-      tools: [],
-      maxTokens,
-      signal,
+      visibleBytes: Buffer.byteLength(output), totalOutputBytes: size, finishKind,
+      inputBytes: Buffer.byteLength(input), requestedMaxTokens: maxTokens, maxOutputBytes,
     });
-
-    for await (const chunk of stream) {
-      signal?.throwIfAborted();
-      if (finished) throw new Error('Model emitted data after finish');
-      if (isToolCall(chunk)) throw new Error('Review model attempted a tool call');
-
-      if (chunk.type === 'text-delta' || chunk.type === 'reasoning-delta') {
-        size += Buffer.byteLength(chunk.text);
-        if (size > maxOutputBytes) throw new Error('Model output limit exceeded');
-        if (chunk.type === 'text-delta') output += chunk.text;
-      }
-
-      if (chunk.type === 'finish') {
-        finishKind = chunk.reason.kind;
-        if (finishKind !== 'stop') {
-          throw Object.assign(new Error('Model did not complete: ' + finishKind), {
-            code: 'MODEL_INCOMPLETE_OUTPUT',
-            diagnostic: { ...diagnostic(), providerCode: providerCode(chunk.reason) },
-          });
+    const failure = (message, code) => {
+      const error = Object.assign(new Error(message), { code, diagnostic: diagnostic() });
+      failureMetadata.set(error, { code, diagnostic: error.diagnostic });
+      return error;
+    };
+    try {
+      const stream = llm.stream({
+        ...identity,
+        system: instructions + '\n' + contract,
+        messages: [{ role: 'user', content: [{ type: 'text', text: input }] }],
+        tools: [], maxTokens, signal,
+      });
+      for await (const chunk of stream) {
+        signal?.throwIfAborted();
+        if (finished) throw failure('Model emitted data after finish', 'MODEL_PROTOCOL_ERROR');
+        if (isToolCall(chunk)) throw failure('Review model attempted a tool call', 'MODEL_PROTOCOL_ERROR');
+        if (chunk.type === 'text-delta' || chunk.type === 'reasoning-delta') {
+          size += Buffer.byteLength(chunk.text);
+          if (size > maxOutputBytes) throw failure('Model output limit exceeded', 'MODEL_OUTPUT_LIMIT');
+          if (chunk.type === 'text-delta') output += chunk.text;
+        }
+        if (chunk.type === 'finish') {
+          finishKind = chunk.reason.kind;
+          if (finishKind !== 'stop') {
+            const error = failure('Model did not complete: ' + finishKind, 'MODEL_INCOMPLETE_OUTPUT');
+            Object.assign(error.diagnostic, providerDiagnostic(chunk.reason));
+            throw error;
+          }
+          finished = true;
         }
-        finished = true;
       }
-    }
-
-    if (!finished) {
-      throw Object.assign(new Error('Model stream ended without finish'), {
-        code: 'MODEL_INCOMPLETE_OUTPUT',
-        diagnostic: diagnostic(),
-      });
-    }
-
-    try {
-      return modelJson(output);
     } catch (error) {
-      error.diagnostic = diagnostic();
+      // Keep thrown provider/cancellation identity, including frozen and primitive values.
+      // Only add safe structured metadata when the error permits it.
+      if (error && (typeof error === 'object' || typeof error === 'function') && !failureMetadata.has(error)) {
+        const safeDiagnostic = { ...diagnostic(), ...providerDiagnostic(error) };
+        failureMetadata.set(error, { code: safeDiagnostic.providerCode, diagnostic: safeDiagnostic });
+        try {
+          if (Object.isExtensible(error) && !Object.hasOwn(error, 'diagnostic')) {
+            Object.defineProperty(error, 'diagnostic', { value: structuredClone(safeDiagnostic), configurable: true, enumerable: true, writable: true });
+          }
+        } catch { /* Diagnostic accessors/proxies must not replace the primary failure. */ }
+      }
       throw error;
     }
-  }
-
-  async function retryOnceCorrected(request, firstError) {
-    await request.onProtocolCorrection?.({
-      code: firstError.code,
-      diagnostic: firstError.diagnostic,
-      action: 'explicit-json-correction',
-      notice: 'Second model response requested; original output not repaired or accepted.',
-    });
-    let value;
+    // Cancellation during iterator cleanup/end must not become an invalid-JSON correction.
+    signal?.throwIfAborted();
+    if (!finished) throw failure('Model stream ended without finish', 'MODEL_INCOMPLETE_OUTPUT');
     try {
-      value = JSON.parse(await once({ ...request, instructions: request.instructions + JSON_CORRECTION_SUFFIX }));
-    } catch (second) {
-      second.attempts = [
-        { attempt: 1, code: firstError.code, diagnostic: firstError.diagnostic },
-        { attempt: 2, code: second.code, diagnostic: second.diagnostic },
-      ];
-      throw second;
-    }
-    if (value && typeof value === 'object' && !Array.isArray(value)) {
-      if (Array.isArray(value.limitations)) value.limitations.push(CORRECTION_LIMITATION);
+      return { text: modelJson(output), diagnostic: diagnostic() };
+    } catch (error) {
+      error.diagnostic = { ...diagnostic(), ...error.diagnostic };
+      invalidJsonErrors.add(error);
+      failureMetadata.set(error, { code: error.code, diagnostic: error.diagnostic });
+      throw error;
     }
-    return JSON.stringify(value);
   }
 
   return async function invoke(request) {
-    try {
-      return await once(request);
-    } catch (error) {
-      if (!correctJson || error.code !== 'MODEL_INVALID_JSON') throw error;
-      request.signal?.throwIfAborted();
-      return retryOnceCorrected(request, error);
+    // Snapshot these before an async budget/progress hook can mutate the request.
+    const original = { instructions: request.instructions, input: request.input, signal: request.signal };
+    const contract = modelContract(original.input, original.instructions);
+    const correctionLimit = correctJson ? maxJsonCorrections : 0;
+    const attempts = [];
+    for (let attempt = 1; ; attempt++) {
+      let result;
+      try {
+        result = await once({ ...original, instructions: original.instructions +
+          (attempt > 1 ? JSON_CORRECTION_SUFFIX + jsonCorrectionHint(attempts.at(-1)?.diagnostic) + ' 纠正次数：' + (attempt - 1) + '/' + correctionLimit + '。' : '') }, contract);
+      } catch (error) {
+        const metadata = failureMetadata.get(error) ?? {};
+        failureMetadata.delete(error);
+        attempts.push({ attempt, ...structuredClone(metadata) });
+        const invalidJson = invalidJsonErrors.delete(error);
+        if (!invalidJson || attempt > correctionLimit) {
+          try {
+            if (attempts.length > 1 && error && typeof error === 'object' && Object.isExtensible(error)) {
+              Object.defineProperty(error, 'attempts', { value: structuredClone(attempts), configurable: true, enumerable: true, writable: true });
+              if (invalidJson) {
+                error.message = 'Model response is not complete JSON after ' + (attempt - 1) +
+                  ' explicit JSON correction(s) (' + attempt + ' model calls); correction budget exhausted; no malformed output accepted';
+              }
+            }
+          } catch { /* Preserve provider identity even with hostile accessors/proxies. */ }
+          throw error;
+        }
+        original.signal?.throwIfAborted();
+        // Exactly one reservation per extra call; a thrown budget/cancellation veto is final.
+        await request.onProtocolCorrection?.({
+          ...structuredClone(metadata), attempts: structuredClone(attempts),
+          action: 'explicit-json-correction', attempt: attempt + 1,
+          correction: attempt, maxJsonCorrections: correctionLimit,
+          notice: 'Additional model response requested; original output not repaired or accepted.',
+        });
+        original.signal?.throwIfAborted();
+        continue;
+      }
+      if (attempt > 1) {
+        // Out-of-band audit only: never inject metadata into stage-specific model schemas.
+        await request.onProtocolEvent?.({
+          action: 'json-correction-complete', attempt, corrections: attempt - 1,
+          attempts: structuredClone([...attempts, { attempt, diagnostic: result.diagnostic }]),
+          notice: 'Fresh complete JSON accepted; malformed outputs discarded; extra model calls occurred.',
+        });
+        original.signal?.throwIfAborted();
+      }
+      return result.text;
     }
   };
 }

package/src/model-contract.mjs

@@ -3,12 +3,9 @@ const VERDICT_CONTRACT = '本阶段必须返回 {"verdicts":[{"candidateId":"c1"
 const GROUPS_CONTRACT = '本阶段返回groups数组，每项含fileIds和reason，文件身份必须来自输入，不是findings响应。';
 const RISK_CONTRACT = '本阶段返回 {"risks":[]} 或原指令要求的风险条目，不是findings。';
 const INTERACTION_CONTRACT = '本阶段返回 {"findings":[],"limitations":[]}；发现必须包含原指令全部字段和跨文件interaction.editRefs。无足够跨文件证据时说明limitations，不编造。';
-const FINDINGS_CONTRACT = '本阶段最终返回 {"findings":[],"limitations":[]}。每项finding必须含fileId、severity（critical/high/medium/low）、title、evidence、trigger、impact、suggestion和anchor；fileId原样复制file.id，不用文件名替代。anchor.line用side/start/end/snippet且精确匹配原行；需要更多证据可按检索协议先返回requests。';
+const FINDINGS_CONTRACT = '本阶段最终返回 {"findings":[],"limitations":[]}。每项finding必须含fileId、severity（critical/high/medium/low）、title、evidence、trigger、impact、suggestion和anchor；fileId原样复制file.id，不用文件名替代。行定位写成 anchor:{kind:"line",side:"new",start:1,end:1,snippet:"逐行原文"}（仅为形状示例，不是证据）；start/end用原来源一基行号而非窗口内序号，精确匹配原行；old/new按当前阶段允许侧选择，示例不改变授权；仅当没有retrievalFinalization且仍有检索余量时，需要更多证据可按检索协议先返回requests。';
 
-export function modelContract(input, instructions = '') {
-  let p;
-  try { p = JSON.parse(input); } catch { return ''; }
-  if (!p || typeof p !== 'object' || Array.isArray(p)) return '';
+function stageContract(p, instructions) {
   if (Array.isArray(p.candidates)) return VERDICT_CONTRACT;
   if (/返回\{groups:/.test(instructions)) return GROUPS_CONTRACT;
   if (/仅制定审查计划/.test(instructions)) return RISK_CONTRACT;
@@ -16,3 +13,11 @@ export function modelContract(input, instructions = '') {
   if (p.file) return FINDINGS_CONTRACT;
   return '';
 }
+
+export function modelContract(input, instructions = '') {
+  let p;
+  try { p = JSON.parse(input); } catch { return ''; }
+  if (!p || typeof p !== 'object' || Array.isArray(p)) return '';
+  const contract = stageContract(p, instructions);
+  return contract + (p.retrievalFinalization ? ' 本次检索已受限：只返回当前阶段最终schema，禁止requests；不能将缺证据声称为无问题或完整覆盖。' : '');
+}

package/src/model-diagnostics.mjs

@@ -0,0 +1,62 @@
+import { createHash } from 'node:crypto';
+
+// Never persist provider messages, response excerpts, headers, URLs or raw request IDs.
+const digest = text => createHash('sha256').update(text).digest('hex');
+const own = (value, key) => {
+  try { const d = value != null ? Object.getOwnPropertyDescriptor(value, key) : undefined; return d && 'value' in d ? d.value : undefined; }
+  catch { return undefined; }
+};
+const PROVIDER_CODES = new Set(['RATE_LIMIT','CONTEXT_WINDOW_EXCEEDED','QUOTA','ACCOUNT_QUOTA','AUTH','AUTHENTICATION','INVALID_CREDENTIAL','MISSING_CREDENTIAL','PERMISSION','TIMEOUT','NETWORK','SERVER_ERROR','SERVER','SERVICE_UNAVAILABLE','INVALID_ARGS','INVALID_REQUEST','BAD_REQUEST','EMPTY_RESPONSE','UNKNOWN','NO_ADAPTER','ABORTED','CANCELLED']);
+export function providerDiagnostic(value) {
+  const carried = own(value, 'failure');
+  const code = own(carried, 'code') ?? own(value, 'code');
+  const status = own(carried, 'status') ?? own(value, 'status');
+  const retry = own(carried, 'providerRetryAfterMs') ?? own(value, 'providerRetryAfterMs');
+  const requestId = own(carried, 'requestId') ?? own(value, 'requestId');
+  return {
+    ...(typeof code === 'string' && code.length > 0 && code.length <= 256 ? { providerCode: PROVIDER_CODES.has(code) ? code : 'UNRECOGNIZED', ...(PROVIDER_CODES.has(code) ? {} : { providerCodeHash: digest(code) }) } : {}),
+    ...(Number.isInteger(status) && status >= 100 && status <= 599 ? { providerStatus: status } : {}),
+    ...(Number.isFinite(retry) && retry > 0 && retry <= 86400000 ? { providerRetryAfterMs: retry } : {}),
+    ...(typeof requestId === 'string' && requestId.length > 0 && requestId.length <= 512 ? { providerRequestIdHash: digest(requestId) } : {}),
+  };
+}
+
+const SYNTAX_HINTS = {
+  'property-name': '对象属性名必须使用双引号，不允许单引号、裸键或尾逗号。',
+  colon: '属性名与值之间必须有冒号。',
+  separator: '相邻属性或数组元素之间必须有逗号，结束处不可多加逗号。',
+  'invalid-escape': 'JSON 字符串中的反斜杠必须合法转义；换行、引号和路径须按 JSON 编码。',
+  'control-character': 'JSON 字符串中不能包含裸换行或控制字符，必须正确转义。',
+  'unterminated-string': '字符串必须闭合；不要用多行裸文本或截断字符串。',
+  'unexpected-end': '只输出一个语法完整且闭合的对象，不省略结尾。',
+  'trailing-content': 'JSON 对象结束后不得附加解释、第二个对象或 Markdown。',
+  syntax: '逐项检查双引号、转义、冒号、逗号和括号，输出完整严格 JSON。',
+};
+export function jsonSyntaxDiagnostic(body, error) {
+  const message = error instanceof SyntaxError ? error.message : '';
+  let category = 'syntax';
+  if (/^Expected (?:property name|double-quoted property name)/.test(message)) category = 'property-name';
+  else if (/^Expected ':'/.test(message)) category = 'colon';
+  else if (/^Expected ','/.test(message)) category = 'separator';
+  else if (/^Bad (?:escaped character|Unicode escape)/.test(message)) category = 'invalid-escape';
+  else if (/^Bad control character/.test(message)) category = 'control-character';
+  else if (/^Unterminated string/.test(message)) category = 'unterminated-string';
+  else if (/^Unexpected end of JSON input/.test(message)) category = 'unexpected-end';
+  else if (/^Unexpected non-whitespace character after JSON/.test(message)) category = 'trailing-content';
+  const match = / at position ([0-9]+)(?: \(line [0-9]+ column [0-9]+\))?$/.exec(message);
+  const offset = match ? Number(match[1]) : category === 'unexpected-end' ? body.length : undefined;
+  let location = {};
+  if (Number.isSafeInteger(offset) && offset >= 0 && offset <= body.length) {
+    const before = body.slice(0, offset);
+    const lines = before.split(/\r\n|\r|\n/);
+    location = { offset, line: lines.length, column: lines.at(-1).length + 1 };
+  }
+  return { syntaxCategory: category, ...location, offsetUnit: 'utf16-code-unit-in-json-body', responseHash: digest(body) };
+}
+export function jsonCorrectionHint(diagnostic) {
+  const category = diagnostic?.syntaxCategory;
+  if (typeof category !== 'string' || !Object.hasOwn(SYNTAX_HINTS, category)) return '';
+  const { line, column } = diagnostic;
+  const location = Number.isSafeInteger(line) && line > 0 && Number.isSafeInteger(column) && column > 0 ? '，JSON正文第' + line + '行第' + column + '列' : '';
+  return ' 本地解析诊断（不含原响应）：' + category + location + '。' + SYNTAX_HINTS[category];
+}

package/src/model-json.mjs

@@ -1,13 +1,21 @@
+import { jsonSyntaxDiagnostic } from './model-diagnostics.mjs';
+
 // Accept one complete JSON value, optionally inside one exact Markdown fence.
+// This parser never repairs bytes or invokes a model; orchestration owns corrections.
 export function modelJson(text) {
- const bytes=Buffer.byteLength(text);
- const trimmed=text.trim();
- const fence=/^```(?:json)?\r?\n([\s\S]*)\r?\n```$/.exec(trimmed);
- const body=fence?fence[1]:trimmed;
- try { JSON.parse(body); } catch {
-  const shape = !trimmed ? 'empty' : trimmed.startsWith('```') && !fence ? 'non-exact-fence' : /^[{\[]/.test(body) ? 'json-like-invalid' : 'non-json-leading';
-  const error=new Error('Model response is not complete JSON (bytes='+bytes+', envelope='+(fence?'json-fence':'plain')+', shape='+shape+'); no repair or retry performed');
-  error.code='MODEL_INVALID_JSON';throw error;
- }
- return body;
+  const bytes = Buffer.byteLength(text);
+  const trimmed = text.trim();
+  const fence = /^```(?:json)?\r?\n([\s\S]*)\r?\n```$/.exec(trimmed);
+  const body = fence ? fence[1] : trimmed;
+  try {
+    JSON.parse(body);
+  } catch (parseError) {
+    const envelope = fence ? 'json-fence' : 'plain';
+    const shape = !trimmed ? 'empty' : trimmed.startsWith('```') && !fence ? 'non-exact-fence' : /^[{\[]/.test(body) ? 'json-like-invalid' : 'non-json-leading';
+    const error = new Error('Model response is not complete JSON (bytes=' + bytes + ', envelope=' + envelope + ', shape=' + shape + '); no repair or retry performed by JSON parser');
+    error.code = 'MODEL_INVALID_JSON';
+    error.diagnostic = { jsonBytes: bytes, envelope, shape, ...jsonSyntaxDiagnostic(body, parseError) };
+    throw error;
+  }
+  return body;
 }

package/src/project-execution.mjs

@@ -0,0 +1,40 @@
+import { reviewSnapshot } from './review.mjs';
+
+export const DEFAULT_PROJECT_CONCURRENCY = 3;
+export function projectConcurrency(value = DEFAULT_PROJECT_CONCURRENCY) {
+  if (!Number.isSafeInteger(value) || value < 1 || value > 8) throw new Error('Project concurrency must be an integer from 1 to 8');
+  return value;
+}
+
+// Parallelize independent approved snapshots, never dependent stages within a batch.
+// Admission and the shared call reservation are synchronous; completion order is not report order.
+export async function reviewProjectBatches(batches, model, { concurrency = DEFAULT_PROJECT_CONCURRENCY, remainingCalls, signal, onProgress } = {}) {
+  projectConcurrency(concurrency);
+  if (!Array.isArray(batches) || typeof remainingCalls !== 'function') throw new Error('Invalid project execution');
+  const controller = new AbortController();
+  const batchSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+  const results = new Array(batches.length);
+  let next = 0, failed = false, failure;
+  const unstarted = batch => ({ snapshotId: batch.id, status: 'partial', files: batch.files.map(f => ({ fileId: f.id, path: f.path, status: f.eligibility === 'reviewable' ? 'pending' : f.eligibility, reason: 'Session project budget exhausted or cancelled' })), findings: [], limitations: [] });
+  const worker = async () => {
+    while (!failed) {
+      const index = next++;
+      if (index >= batches.length) return;
+      const batch = batches[index];
+      try {
+        if (batchSignal.aborted || remainingCalls() <= 0) { results[index] = unstarted(batch); continue; }
+        results[index] = await reviewSnapshot(batch, model, {
+          signal: batchSignal, maxCalls: remainingCalls(), remainingCalls, enableRetrieval: true, enableVerification: true,
+          enableAnchorCorrection: true, correctProtocol: true,
+          onProgress: onProgress ? event => onProgress({ ...event, snapshotId: batch.id, batchIndex: index }) : undefined,
+        });
+      } catch (error) {
+        if (!failed) { failed = true; failure = error; controller.abort(error); }
+      }
+    }
+  };
+  // Never release service ownership while a sibling model/cleanup is still running.
+  await Promise.all(Array.from({ length: Math.min(concurrency, batches.length) }, worker));
+  if (failed) throw failure;
+  return results;
+}

package/src/project-review-service.mjs

@@ -5,10 +5,10 @@ import { hash } from './content.mjs';
 import { resolveWorkspaceRepository } from './workspace-repository.mjs';
 import { detectVcs } from './snapshot.mjs';
 import { projectInventory, captureProjectBatch } from './project-snapshot.mjs';
-import { reviewSnapshot } from './review.mjs';
+import { reviewProjectBatches, projectConcurrency as validateProjectConcurrency } from './project-execution.mjs';
 import { createDshModel } from './dsh-model.mjs';
 
-const PREVIEW_NOTICE_SUFFIX = ' Full current source audit, not regression-only diff. Shared session execution budget: no internal elapsed-time or model-call cutoff, 16MiB capture memory protection. Blocked/excluded/pending files are not reviewed successfully. No untracked/ignored/external bodies; no complete semantic call graph. Show scope and model before confirmed execute.';
+const PREVIEW_NOTICE_SUFFIX = ' Full current source audit, not regression-only diff. Shared session execution budget: no internal elapsed-time or model-call cutoff, 16MiB capture memory protection. Blocked/excluded/pending files are not reviewed successfully. No untracked/ignored/external bodies; no complete semantic call graph. Independent approved batches run with bounded concurrency; per-batch evidence and global model-call budgets remain enforced. Show scope and model before confirmed execute.';
 const REPORT_NOTICE_SUFFIX = ' Coverage counts processing of selected tracked files only, not proof of correctness. Excluded and blocked are never completed. No cross-batch whole-program semantic coverage is claimed.';
 
 function owner(exec) {
@@ -66,10 +66,11 @@ async function captureProject(cwd, args, signal) {
   return { ...result, id: hash(JSON.stringify(result)) };
 }
 
-export function createProjectReviewService(llm, { allowModelSending = false, authorize = async () => false, now = Date.now, ttlMs = 300000, maxPreviews = 8, projectMaxCalls = Number.MAX_SAFE_INTEGER } = {}) {
+export function createProjectReviewService(llm, { allowModelSending = false, authorize = async () => false, now = Date.now, ttlMs = 300000, maxPreviews = 8, projectMaxCalls = Number.MAX_SAFE_INTEGER, projectConcurrency = 3 } = {}) {
   for (const n of [ttlMs, maxPreviews]) if (!Number.isSafeInteger(n) || n < 1) throw new Error('Invalid project preview limit');
   if (!Number.isSafeInteger(projectMaxCalls) || projectMaxCalls < 1) throw new Error('Invalid project model call limit');
 
+  validateProjectConcurrency(projectConcurrency);
   const previews = new Map();
   const lifetime = new AbortController();
   let busy = false;
@@ -96,6 +97,7 @@ export function createProjectReviewService(llm, { allowModelSending = false, aut
           model: current.route, modelSendingEnabled: allowModelSending,
           totalTrackedNodes: s.totalTrackedNodes, selectedFiles: s.selectedFiles, selectionComplete: s.selectionComplete,
           inventoryComplete: s.inventoryComplete, batches: s.batches.length,
+          execution: { batchConcurrency: projectConcurrency },
           files: s.batches.flatMap(b => b.files.map(f => ({ path: f.path, eligibility: f.eligibility, reason: f.reason }))),
           notice: s.notice + PREVIEW_NOTICE_SUFFIX,
         };
@@ -127,23 +129,19 @@ export function createProjectReviewService(llm, { allowModelSending = false, aut
         let calls = 0;
         const adapter = createDshModel(llm, p.route, { correctJson: true });
         const model = request => {
-          if (calls >= projectMaxCalls) throw new Error('Shared project model call limit exceeded');
+          if (calls >= projectMaxCalls) throw Object.assign(new Error('Shared project model call limit exceeded'), { code: 'PROJECT_MODEL_CALL_LIMIT' });
           calls++;
           return adapter({ ...request, onProtocolCorrection: async info => {
-            if (calls >= projectMaxCalls) throw new Error('Shared project model call limit exceeded');
+            if (calls >= projectMaxCalls) throw Object.assign(new Error('Shared project model call limit exceeded'), { code: 'PROJECT_MODEL_CALL_LIMIT' });
             calls++;
             await request.onProtocolCorrection?.(info);
           }});
         };
 
-        const results = [];
-        for (const b of s.batches) {
-          if (signal.aborted || calls >= projectMaxCalls) {
-            results.push({ snapshotId: b.id, status: 'partial', files: b.files.map(f => ({ fileId: f.id, path: f.path, status: f.eligibility === 'reviewable' ? 'pending' : f.eligibility, reason: 'Session project budget exhausted or cancelled' })), findings: [], limitations: [] });
-            continue;
-          }
-          results.push(await reviewSnapshot(b, model, { signal, maxCalls: projectMaxCalls - calls, enableRetrieval: true, enableVerification: true, correctProtocol: true, onProgress: exec.reviewCheckpoint }));
-        }
+        const results = await reviewProjectBatches(s.batches, model, {
+          concurrency: projectConcurrency, signal, remainingCalls: () => projectMaxCalls - calls,
+          onProgress: exec.reviewCheckpoint,
+        });
 
         const files = results.flatMap(r => r.files.map(f => ({ ...f, batchSnapshotId: r.snapshotId })));
         const coverage = {
@@ -164,6 +162,7 @@ export function createProjectReviewService(llm, { allowModelSending = false, aut
           repositoryRoot: s.root, vcs: s.vcs, model: p.route, modelCalls: calls, maxModelCalls: projectMaxCalls,
           totalTrackedNodes: s.totalTrackedNodes, selectionComplete: s.selectionComplete, inventoryComplete: s.inventoryComplete,
           coverage, files, findings, batches: results,
+          execution: { batchConcurrency: projectConcurrency },
           notice: s.notice + REPORT_NOTICE_SUFFIX,
         };
 

package/src/response-correction.mjs

@@ -0,0 +1,28 @@
+// Ask for one new response; never normalize identities, severities or evidence locally.
+const GUIDANCE = {
+  MODEL_INVALID_REVIEW_RESPONSE: '返回含 findings 和 limitations 数组的当前阶段完整对象。',
+  MODEL_INVALID_FINDING_IDENTITY: 'fileId 必须原样复制本次主 file.id，不使用路径、候选编号或其他文件身份。',
+  MODEL_INVALID_FINDING_SEVERITY: 'severity 仅允许 critical、high、medium、low，不使用 P1/P2、数字或翻译标签。',
+  MODEL_MISSING_FINDING_FIELD: '每个发现必须包含非空 title/evidence/trigger/impact/suggestion。',
+  MODEL_INVALID_ANCHOR: 'anchor 必须使用当前阶段允许的 kind、side、整数 start/end 及精确 snippet。',
+  MODEL_ANCHOR_MISMATCH: 'snippet 必须逐行精确复制批准来源，start/end 是该来源的原始一基行号，不能使用展示窗口的相对行号。不得模糊匹配、改写源码或用 file anchor 隐藏定位失败。',
+};
+
+export async function correctedResponse(generate, validate, request, { enabled = false, canCorrect = () => true, onCorrection = async () => {} } = {}) {
+  const approved = { ...request };
+  const original = await generate({ ...approved });
+  try { return validate(original); } catch (error) {
+    approved.signal?.throwIfAborted();
+    if (!enabled || !Object.hasOwn(GUIDANCE, error?.code) || !canCorrect()) throw error;
+    await onCorrection({ action: 'review-response-correction', code: error.code, notice: 'Original response rejected; requesting one new response under the same approved scope and shared budgets.' });
+    approved.signal?.throwIfAborted();
+    const instructions = approved.instructions + '\n本次是一次明确的主审响应协议纠正：' + GUIDANCE[error.code] + ' 重新核对原批准源码并返回完整当前阶段 schema；不得把格式错误当成无缺陷，不得为通过校验编造证据或静默删除有证据的候选。原响应未被接受，纠正后仍需全部严格校验。';
+    // generate enforces the same input/call/reader limits and enclosing signal.
+    const response = await generate({ ...approved, instructions });
+    approved.signal?.throwIfAborted();
+    try { return validate(response); } catch (second) {
+      second.responseAttempts = [{ code: error.code }, { code: second.code ?? 'REVIEW_EXECUTION_FAILED' }];
+      throw second;
+    }
+  }
+}

package/src/retrieval-loop.mjs

@@ -1,5 +1,5 @@
 import { RETRIEVAL_INSTRUCTIONS } from './prompts.mjs';
-import { executeRetrievalBatch } from './retrieval-protocol.mjs';
+import { executeRetrievalBatch, parseRetrievalResponse } from './retrieval-protocol.mjs';
 
 export { RETRIEVAL_INSTRUCTIONS };
 
@@ -18,7 +18,7 @@ function compactFollowup(input) {
 }
 
 export function retrievalRequest(request, scope, retrieved = []) {
-  return { ...request, instructions: request.instructions + '\n' + RETRIEVAL_INSTRUCTIONS, input: JSON.stringify({ ...JSON.parse(request.input), catalog: scope.catalog(), retrieved }) };
+  return { ...request, instructions: request.instructions + '\n' + RETRIEVAL_INSTRUCTIONS + BUDGET_SUFFIX, input: JSON.stringify({ ...JSON.parse(request.input), catalog: scope.catalog(), retrieved, ...(scope.budget ? { retrievalBudget: scope.budget() } : {}) }) };
 }
 
 function recordRetrieval(operation, result, onTruncated, onRetrieved) {
@@ -34,50 +34,95 @@ function recordRetrieval(operation, result, onTruncated, onRetrieved) {
 
 const CORRECTION_SUFFIX = ' 本次是检索协议纠正：上次请求整批未执行。只返回requests数组，不带findings/limitations；read使用catalog的id和整数start/count，不用path/end。或直接返回当前阶段最终schema。不得扩大批准来源。';
 
-export async function retrievalLoop(model, request, scope, { correctProtocol = false, maxRounds = Number.MAX_SAFE_INTEGER, maxInputBytes = 96 * 1024, beforeCall = () => {}, onTruncated = () => {}, onRetrieved = () => {} } = {}) {
+const BUDGET_SUFFIX = ' retrievalBudget为宿主共享检索预算的当前余量，不是新授权。每项操作消耗一次call及实际序列化输出字节；不要请求超过余量的整批操作。预算将尽请及时按本阶段schema最终答复，只引用已提供证据，证据不足须保留限制或uncertain。';
+const FINAL_SUFFIX = ' 检索预算最终答复：本次仅有一次最终schema答复机会，不得再返回requests。不得把缺证据变成无问题/已核查；只保留已提供且可严格验证的证据，其余说明限制或uncertain。不增加reader、模型调用、输入或超时预算。';
+const budgetFailure = error => ['READER_CALL_BUDGET_EXCEEDED', 'READER_OUTPUT_BUDGET_EXCEEDED', 'RETRIEVAL_ROUND_BUDGET_EXCEEDED'].includes(error?.code);
+
+function roundBudgetError() {
+  const error = new Error('Retrieval round budget exceeded');
+  error.code = 'RETRIEVAL_ROUND_BUDGET_EXCEEDED';
+  return error;
+}
+
+export async function retrievalLoop(model, request, scope, { correctProtocol = false, maxRounds = Number.MAX_SAFE_INTEGER, maxInputBytes = 96 * 1024, beforeCall = () => {}, onTruncated = () => {}, onRetrieved = () => {}, onBudgetLimited = () => {} } = {}) {
   if (!Number.isSafeInteger(maxRounds) || maxRounds < 0 || !Number.isSafeInteger(maxInputBytes) || maxInputBytes < 1) throw new Error('Invalid retrieval loop budget');
   const retrieved = [];
-  let protocolCorrection;
+  let protocolCorrection, finalization;
+  const finalize = async error => {
+    finalization = { code: error.code, reason: error.message, ...(scope.budget ? { budget: scope.budget() } : {}) };
+    await onBudgetLimited(finalization);
+    await request.onProtocolEvent?.({ action: 'retrieval-budget-finalization', ...finalization });
+  };
+  const checkExhausted = async round => {
+    const budget = scope.budget?.();
+    if (!finalization && budget && (budget.remainingCalls === 0 || budget.remainingOutputBytes === 0)) {
+      const error = new Error(budget.remainingCalls === 0 ? 'Reader call budget exceeded' : 'Reader output budget exceeded');
+      error.code = budget.remainingCalls === 0 ? 'READER_CALL_BUDGET_EXCEEDED' : 'READER_OUTPUT_BUDGET_EXCEEDED';
+      await finalize(error);
+    } else if (!finalization && round >= maxRounds) await finalize(roundBudgetError());
+  };
+  const nextRequest = records => {
+    const next = retrievalRequest(request, scope, records);
+    if (finalization) next.input = JSON.stringify({ ...JSON.parse(next.input), retrievalFinalization: finalization });
+    next.instructions += (protocolCorrection ? CORRECTION_SUFFIX : '') + (finalization ? FINAL_SUFFIX : '');
+    return next;
+  };
   for (let round = 0; ; round++) {
     request.signal?.throwIfAborted();
-    let { input, instructions: baseInstructions } = retrievalRequest(request, scope, retrieved);
-    const instructions = baseInstructions + (protocolCorrection ? CORRECTION_SUFFIX : '');
+    await checkExhausted(round);
+    let { input, instructions } = nextRequest(retrieved);
     if (correctProtocol && retrieved.length && Buffer.byteLength(input) + Buffer.byteLength(instructions) > maxInputBytes) input = compactFollowup(input);
     if (Buffer.byteLength(input) + Buffer.byteLength(instructions) > maxInputBytes) throw new Error('Retrieval input budget exceeded');
+    request.signal?.throwIfAborted();
     beforeCall();
+    request.signal?.throwIfAborted();
     const response = await model({ ...request, instructions, input });
     request.signal?.throwIfAborted();
     const serialized = typeof response === 'string' ? response : JSON.stringify(response);
     if (typeof serialized !== 'string' || Buffer.byteLength(serialized) > 128 * 1024) throw new Error('Retrieval response too large');
     const parsed = JSON.parse(serialized);
     if (!parsed || !Object.hasOwn(parsed, 'requests')) return parsed;
-    if (round >= maxRounds) throw new Error('Retrieval round budget exceeded');
+    // Schema and authorization remain hard failures, including on the final turn.
+    // Preflight all dynamic ranges and aggregate budgets before any capability.
     let batch;
     try {
-      batch = executeRetrievalBatch(parsed, scope, request.signal, ({ request: operation, result }) => recordRetrieval(operation, result, onTruncated, onRetrieved));
+      const operations = parseRetrievalResponse(parsed);
+      const allowed = new Set(scope.catalog().map(item => item.id));
+      if (operations.some(r => r.kind === 'read' ? !allowed.has(r.id) : r.sourceIds?.some(id => !allowed.has(id)))) throw new Error('Source not authorized');
+      if (finalization) {
+        const error = new Error(finalization.reason + '; final response required, no further retrieval permitted');
+        error.code = 'RETRIEVAL_FINAL_RESPONSE_REQUIRED';
+        throw error;
+      }
+      scope.preflight?.(operations);
+      const execute = () => executeRetrievalBatch(parsed, scope, request.signal);
+      batch = scope.transaction ? scope.transaction(execute) : execute();
     } catch (error) {
       request.signal?.throwIfAborted();
-      if (!correctProtocol || protocolCorrection || !(/Invalid retrieval batch|Invalid read request|Invalid search request|Invalid find request/.test(error.message))) throw error;
+      if (!finalization && budgetFailure(error)) { 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 });
       continue;
     }
+    for (const item of batch) recordRetrieval(item.request, item.result, onTruncated, onRetrieved);
+    await checkExhausted(round + 1);
     for (const item of batch) {
       let candidate = [...retrieved, item];
-      let next = retrievalRequest(request, scope, candidate);
+      let next = nextRequest(candidate);
       if (correctProtocol) {
         while (retrieved.length && Buffer.byteLength(compactFollowup(next.input)) + Buffer.byteLength(next.instructions) > maxInputBytes) {
           retrieved.shift();
           await request.onProtocolEvent?.({ action: 'prior-retrieval-deferred', notice: 'Prior returned fragment no longer in current prompt; reread approved source for evidence.' });
           candidate = [...retrieved, item];
-          next = retrievalRequest(request, scope, candidate);
+          next = nextRequest(candidate);
         }
       }
       let fits = Buffer.byteLength(next.input) + Buffer.byteLength(next.instructions) <= maxInputBytes;
       if (correctProtocol && !fits) fits = Buffer.byteLength(compactFollowup(next.input)) + Buffer.byteLength(next.instructions) <= maxInputBytes;
       if (correctProtocol && !fits) {
         const omitted = { request: item.request, result: { omitted: true, reason: 'Result omitted: request fewer lines/matches; no body or receipt provided.' } };
-        const minimal = retrievalRequest(request, scope, [...retrieved, omitted]);
+        const minimal = nextRequest([...retrieved, omitted]);
         if (Buffer.byteLength(compactFollowup(minimal.input)) + Buffer.byteLength(minimal.instructions) > maxInputBytes) throw new Error('Retrieval input metadata exceeds model capacity');
         retrieved.push(omitted);
         await request.onProtocolEvent?.({ action: 'oversized-retrieval-omitted', kind: item.request.kind });

package/src/review.mjs

@@ -1,6 +1,7 @@
 import { REVIEW_INSTRUCTIONS, PROJECT_REVIEW_INSTRUCTIONS } from './prompts.mjs';
 import { reviewRounds } from './review-rounds.mjs';
 import { correctAnchor } from './anchor-correction.mjs';
+import { correctedResponse } from './response-correction.mjs';
 import { validateBusinessRequirement } from './business-requirement.mjs';
 import { riskReadCoverage } from './risk-read-coverage.mjs';
 import { BUSINESS_GROUP_INSTRUCTIONS, localBusinessGroups, prepareBusinessGroups, validateBusinessGroups } from './business-groups.mjs';
@@ -27,6 +28,7 @@ export { REVIEW_INSTRUCTIONS };
 export { PROJECT_REVIEW_INSTRUCTIONS };
 const nonempty = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 8000;
 const lines = text => text.replaceAll('\r\n', '\n').split('\n');
+const protocolError = (code, message) => Object.assign(new Error(message), { code });
 
 export function validateFindings(response, file) {
   return validateResponse(response, file);
@@ -35,20 +37,21 @@ export function validateFindings(response, file) {
 function validateResponse(response, file, knownChanges) {
   if (Buffer.byteLength(typeof response === 'string' ? response : JSON.stringify(response) ?? '') > 128 * 1024) throw new Error('Review response too large');
   if (typeof response === 'string') response = JSON.parse(response);
-  if (!response || !Array.isArray(response.findings) || response.findings.length > 50 || !Array.isArray(response.limitations) || response.limitations.length > 50 || response.limitations.some(s => !nonempty(s))) throw new Error('Invalid review response');
+  if (!response || !Array.isArray(response.findings) || response.findings.length > 50 || !Array.isArray(response.limitations) || response.limitations.length > 50 || response.limitations.some(s => !nonempty(s))) throw protocolError('MODEL_INVALID_REVIEW_RESPONSE', 'Invalid review response');
   const changes = knownChanges ?? changeMap(file.left.text, file.right.text);
   const findings = response.findings.map(raw => {
-    if (!raw || raw.fileId !== file.id || !['critical', 'high', 'medium', 'low'].includes(raw.severity)) throw new Error('Invalid finding identity or severity');
-    for (const key of ['title', 'evidence', 'trigger', 'impact', 'suggestion']) if (!nonempty(raw[key])) throw new Error('Missing finding field: ' + key);
+    if (!raw || raw.fileId !== file.id) throw protocolError('MODEL_INVALID_FINDING_IDENTITY', 'Invalid finding identity or severity');
+    if (!['critical', 'high', 'medium', 'low'].includes(raw.severity)) throw protocolError('MODEL_INVALID_FINDING_SEVERITY', 'Invalid finding identity or severity');
+    for (const key of ['title', 'evidence', 'trigger', 'impact', 'suggestion']) if (!nonempty(raw[key])) throw protocolError('MODEL_MISSING_FINDING_FIELD', 'Missing finding field: ' + key);
     const anchor = raw.anchor;
     if(file.reviewMode==='project'&&(anchor?.side==='old'||anchor?.kind==='property'))throw new Error('Project findings require current source evidence');
-    if (!anchor || !['line', 'property', 'file'].includes(anchor.kind)) throw new Error('Invalid anchor');
+    if (!anchor || !['line', 'property', 'file'].includes(anchor.kind)) throw protocolError('MODEL_INVALID_ANCHOR', 'Invalid anchor');
     let validated;
     if (anchor.kind === 'line') {
       const side = anchor.side === 'old' ? file.left : anchor.side === 'new' ? file.right : null;
-      if (!side || !Number.isSafeInteger(anchor.start) || !Number.isSafeInteger(anchor.end) || anchor.start < 1 || anchor.end < anchor.start || !nonempty(anchor.snippet)) throw new Error('Invalid line anchor');
+      if (!side || !Number.isSafeInteger(anchor.start) || !Number.isSafeInteger(anchor.end) || anchor.start < 1 || anchor.end < anchor.start || !nonempty(anchor.snippet)) throw protocolError('MODEL_INVALID_ANCHOR', 'Invalid line anchor');
       const source = lines(side.text);
-      if (anchor.end > source.length || source.slice(anchor.start - 1, anchor.end).join('\n') !== anchor.snippet.replaceAll('\r\n', '\n')) throw new Error('Finding snippet does not match snapshot');
+      if (anchor.end > source.length || source.slice(anchor.start - 1, anchor.end).join('\n') !== anchor.snippet.replaceAll('\r\n', '\n')) throw protocolError('MODEL_ANCHOR_MISMATCH', 'Finding snippet does not match snapshot');
       validated = { kind: 'line', side: anchor.side, start: anchor.start, end: anchor.end, snippet: anchor.snippet };
     } else if (anchor.kind === 'property') {
       if (!file.properties.some(p => p.name === anchor.name)) throw new Error('Unknown changed property');
@@ -128,7 +131,7 @@ export async function reviewSnapshot(snapshot, model, options = {}) {
     await options.onProgress?.({stage:'file-started',snapshotId:input.id,fileId:file.id,path:file.path,status:state.status});
     if (state.status !== 'pending') continue;
     if (signal?.aborted) { state.status = 'cancelled'; state.reason = '用户取消'; continue; }
-    if (report.modelCalls >= maxCalls) { state.reason = '模型调用预算耗尽'; continue; }
+    if (report.modelCalls >= maxCalls || options.remainingCalls?.() <= 0) { state.reason = '模型调用预算耗尽'; continue; }
     const prepared = preparePrimaryInput(input, file, { instructions, scope, grouping: report.grouping, maxInputBytes });
     const { changes, payload } = prepared;
     Object.assign(state, prepared.metadata);
@@ -141,13 +144,20 @@ export async function reviewSnapshot(snapshot, model, options = {}) {
     if (state.groupFallback) report.limitations.push({ fileId: file.id, text: '关联组上下文超过输入预算，回退单文件审查' });
     if (state.initialInputBytes > maxInputBytes) { state.status = 'blocked'; state.reason = '输入超过预算，未截断或提交模型'; continue; }
     try {
-      const beforeCall = () => {
+      const beforeCall = ({ reserved = false } = {}) => {
+        if (!reserved && options.remainingCalls?.() <= 0) throw Object.assign(new Error('Shared project model call limit exceeded'), { code: 'PROJECT_MODEL_CALL_LIMIT' });
         if (report.modelCalls >= maxCalls) throw new Error('Model call budget exceeded');
         report.modelCalls++;
       };
-      const trackedModel=request=>model({...request,onProtocolEvent:async info=>{await options.onProgress?.({stage:'protocol-correction',fileId:file.id,path:file.path,...info});},onProtocolCorrection:async info=>{beforeCall();await request.onProtocolCorrection?.(info);await options.onProgress?.({stage:'protocol-correction',fileId:file.id,path:file.path,...info});}});
+      const onBudgetLimited = info => {
+        state.retrievalLimited = true;
+        (state.retrievalLimits ??= []).push(info);
+        report.limitations.push({ fileId: file.id, text: '检索预算受限，已保留现有结果但不能视为完整审查：' + info.reason });
+      };
+      const onProtocolEvent = async info => { await options.onProgress?.({ stage: 'protocol-correction', fileId: file.id, path: file.path, ...info }); };
+      const trackedModel=request=>model({...request,onProtocolEvent,onProtocolCorrection:async info=>{beforeCall({ reserved: true });await request.onProtocolCorrection?.(info);await options.onProgress?.({stage:'protocol-correction',fileId:file.id,path:file.path,...info});}});
       const executor = scope
-        ? request => retrievalLoop(trackedModel, request, scope, { correctProtocol:options.correctProtocol===true,maxInputBytes, beforeCall, onRetrieved: records => {
+        ? (request, onLimited = () => {}) => retrievalLoop(trackedModel, { ...request, onProtocolEvent }, scope, { correctProtocol:options.correctProtocol===true,maxInputBytes, beforeCall, onBudgetLimited: info => { onBudgetLimited(info); onLimited(info); }, onRetrieved: records => {
           (state.retrievalAudit ??= []).push(...records);
         }, onTruncated: () => {
           if (!state.retrievalTruncated) report.limitations.push({ fileId: file.id, text: '检索结果达到数量上限，部分匹配未提供给模型' });
@@ -164,7 +174,7 @@ export async function reviewSnapshot(snapshot, model, options = {}) {
             const groupInput = prepareBusinessGroups(input.files);
             if (Buffer.byteLength(groupInput) + Buffer.byteLength(BUSINESS_GROUP_INSTRUCTIONS) > maxInputBytes) throw new Error('Business grouping input budget exceeded');
             beforeCall();
-            const response = await model({ ...enclosingRequest, instructions: BUSINESS_GROUP_INSTRUCTIONS, input: groupInput });
+            const response = await trackedModel({ ...enclosingRequest, instructions: BUSINESS_GROUP_INSTRUCTIONS, input: groupInput });
             enclosingRequest.signal.throwIfAborted();
             grouped = validateBusinessGroups(response, input.files);
             }
@@ -218,30 +228,48 @@ export async function reviewSnapshot(snapshot, model, options = {}) {
         if(report.modelCalls>=maxCalls)throw new Error('Model call budget exceeded before next review pass');
         if(rounds>1) state.reviewPasses[batchIndex].status='running';
         const request = { ...enclosingRequest, input: batchPayload };
-        const auditStart = state.retrievalAudit?.length ?? 0;
-        let response = await executor(request);
-        if (options.enableAnchorCorrection === true) {
-          if (Buffer.byteLength(typeof response === 'string' ? response : JSON.stringify(response)) > 128 * 1024) throw new Error('Review response too large');
-          const decoded = typeof response === 'string' ? JSON.parse(response) : structuredClone(response);
-          if (Array.isArray(decoded?.findings) && decoded.findings.length <= 50) {
-            decoded.findings = decoded.findings.map(raw => {
-              const target = batch.interaction ? input.files.find(f => f.id === raw?.fileId && batch.interaction.fileIds.includes(f.id) && f.eligibility === 'reviewable') : file;
-              if (!target) return raw;
-              const correction = correctAnchor(raw, target, target === file ? changes : changeMap(target.left.text,target.right.text), { signal: request.signal });
-              if (!['unchanged','not-applicable'].includes(correction.status)) (state.anchorCorrections ??= []).push(correction);
-              return correction.status === 'corrected' ? correction.candidate : raw;
-            });
-            response = decoded;
+        let auditStart = state.retrievalAudit?.length ?? 0;
+        let finalResponseOnly = false;
+        const generate = async attempt => {
+          if (!initialInputBudget(attempt, scope, maxInputBytes).fits) throw new Error('Review correction input budget exceeded');
+          return executor(attempt, () => { finalResponseOnly = true; });
+        };
+        const validate = response => {
+          if (options.enableAnchorCorrection === true) {
+            if (Buffer.byteLength(typeof response === 'string' ? response : JSON.stringify(response) ?? '') > 128 * 1024) throw new Error('Review response too large');
+            const decoded = typeof response === 'string' ? JSON.parse(response) : structuredClone(response);
+            if (Array.isArray(decoded?.findings) && decoded.findings.length <= 50) {
+              decoded.findings = decoded.findings.map(raw => {
+                const target = batch.interaction ? input.files.find(f => f.id === raw?.fileId && batch.interaction.fileIds.includes(f.id) && f.eligibility === 'reviewable') : file;
+                if (!target) return raw;
+                const correction = correctAnchor(raw, target, target === file ? changes : changeMap(target.left.text,target.right.text), { signal: request.signal });
+                if (!['unchanged','not-applicable'].includes(correction.status)) (state.anchorCorrections ??= []).push(correction);
+                return correction.status === 'corrected' ? correction.candidate : raw;
+              });
+              response = decoded;
+            }
           }
-        }
+          const generated = batch.interaction ? validateInteractionFindings(response, input, batch.interaction, (state.retrievalAudit ?? []).slice(auditStart), scope.catalog()) : validateResponse(response, file, changes);
+          if (batch.synthesis) validateSynthesisReads(generated.findings, changes, (state.retrievalAudit ?? []).slice(auditStart), scope.catalog(), file.id, input.id);
+          if (!batch.interaction && state.sourceMode === 'change-windows') validateWindowFindings(generated.findings, batch.synthesis ? prepared.synthesis.windows : JSON.parse(batch.payload).windows, batch.synthesis === true);
+          return generated;
+        };
+        const generated = await correctedResponse(generate, validate, request, {
+          enabled: options.correctProtocol === true,
+          canCorrect: () => !finalResponseOnly,
+          onCorrection: async info => {
+            // A fresh generation must establish its own synthesis/interaction read evidence.
+            auditStart = state.retrievalAudit?.length ?? 0;
+            (state.responseCorrections ??= []).push({ code: info.code, round: batch.round, phase });
+            report.limitations.push({ fileId: file.id, text: '主审响应校验失败，已请求一次显式纠正；原响应未接受，纠正不证明缺陷成立。' });
+            await options.onProgress?.({ stage: 'protocol-correction', fileId: file.id, path: file.path, ...info });
+          },
+        });
         if (options.enableRiskPlanning === true && !batch.synthesis && batch.round === 1) {
           const entry=state.riskPlans.at(-1);
           entry.sourceReadCoverage=riskReadCoverage(entry.risks,(state.retrievalAudit??[]).slice(auditStart),scope?.catalog()??[],input.id);
           if(entry.sourceReadCoverage.some(c=>c.unreadSourceIds.length)) report.limitations.push({fileId:file.id,text:'风险计划请求的部分来源未在本次生成阶段读取；不能视为已核查风险条件或排除问题'});
         }
-        const generated = batch.interaction ? validateInteractionFindings(response, input, batch.interaction, (state.retrievalAudit ?? []).slice(auditStart), scope.catalog()) : validateResponse(response, file, changes);
-        if (batch.synthesis) validateSynthesisReads(generated.findings, changes, (state.retrievalAudit ?? []).slice(auditStart), scope.catalog(), file.id, input.id);
-        if (!batch.interaction && state.sourceMode === 'change-windows') validateWindowFindings(generated.findings, batch.synthesis ? prepared.synthesis.windows : JSON.parse(batch.payload).windows, batch.synthesis === true);
         request.signal.throwIfAborted();
         if(rounds>1)generated.findings.forEach(f=>{f.reviewRound=batch.round;});
         report.findings.push(...generated.findings);
@@ -250,8 +278,8 @@ export async function reviewSnapshot(snapshot, model, options = {}) {
         if (options.enableVerification === true && generated.findings.length) {
           for (const finding of generated.findings) finding.verification = { status: 'pending', causality: 'unverified' };
           try {
-            const verdicts = await verificationLoop(trackedModel, request, generated.findings, scope, {
-              correctProtocol:options.correctProtocol===true,maxInputBytes, beforeCall,
+            const verdicts = await verificationLoop(trackedModel, { ...request, onProtocolEvent }, generated.findings, scope, {
+              correctProtocol:options.correctProtocol===true,maxInputBytes, beforeCall, onBudgetLimited,
               onRetrieved: records => { (state.retrievalAudit ??= []).push(...records); },
               onTruncated: () => { report.limitations.push({ fileId: file.id, text: '复核检索结果达到数量上限' }); },
             });
@@ -292,15 +320,17 @@ export async function reviewSnapshot(snapshot, model, options = {}) {
       }, { instructions, input: payload }, timeoutMs, signal);
       if (signal?.aborted) throw signal.reason;
 
-      state.status = 'completed';
+      state.status = state.retrievalLimited ? 'pending' : 'completed';
+      if (state.retrievalLimited) state.reason = '检索预算受限，未完成完整审查；已有发现保留，不表示通过';
 
     } catch (error) {
-      state.status = signal?.aborted ? 'cancelled' : 'failed';
+      state.status = signal?.aborted ? 'cancelled' : error?.code === 'PROJECT_MODEL_CALL_LIMIT' ? 'pending' : 'failed';
       state.reason = error?.message ?? String(error);
       if(error.attempts)state.protocolAttempts=error.attempts;
+      if(error.responseAttempts)state.responseAttempts=error.responseAttempts;
       if(error.diagnostic)state.protocolDiagnostic=error.diagnostic;
       for(const pass of state.reviewPasses??[])if(pass.status==='running')pass.status=signal?.aborted?'cancelled':'failed';
-      state.failureCode = signal?.aborted ? 'CANCELLED' : ['MODEL_INVALID_JSON','MODEL_INCOMPLETE_OUTPUT','MODEL_TIMEOUT','MODEL_INVALID_READ_REQUEST'].includes(error?.code) ? error.code : 'REVIEW_EXECUTION_FAILED';
+      state.failureCode = signal?.aborted ? 'CANCELLED' : ['MODEL_INVALID_JSON','MODEL_INCOMPLETE_OUTPUT','MODEL_TIMEOUT','MODEL_INVALID_READ_REQUEST','MODEL_OUTPUT_LIMIT','MODEL_PROTOCOL_ERROR','MODEL_INVALID_REVIEW_RESPONSE','MODEL_INVALID_FINDING_IDENTITY','MODEL_INVALID_FINDING_SEVERITY','MODEL_MISSING_FINDING_FIELD','MODEL_INVALID_ANCHOR','MODEL_ANCHOR_MISMATCH','READER_CALL_BUDGET_EXCEEDED','READER_OUTPUT_BUDGET_EXCEEDED','RETRIEVAL_ROUND_BUDGET_EXCEEDED','RETRIEVAL_FINAL_RESPONSE_REQUIRED','PROJECT_MODEL_CALL_LIMIT'].includes(error?.code) ? error.code : 'REVIEW_EXECUTION_FAILED';
     }
   }
   await options.onProgress?.({stage:'batch-complete',snapshotId:input.id,files:report.files,findings:report.findings,limitations:report.limitations});

package/src/snapshot-reader.mjs

@@ -14,6 +14,12 @@ function validQuery(query, limit) {
   return typeof query === 'string' && query.length > 0 && query.length <= 256 && !/[\r\n]/.test(query) && Number.isSafeInteger(limit) && limit >= 1 && limit <= 100;
 }
 
+function budgetError(kind) {
+  const error = new Error('Reader ' + kind + ' budget exceeded');
+  error.code = kind === 'call' ? 'READER_CALL_BUDGET_EXCEEDED' : 'READER_OUTPUT_BUDGET_EXCEEDED';
+  return error;
+}
+
 // 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 } = {}) {
   if (typeof snapshotId !== 'string' || !snapshotId || snapshotId.length > 200) throw new Error('Invalid snapshot identity');
@@ -24,16 +30,21 @@ export function createSnapshotReader(snapshotId, entries, { maxBytes = 4 * 1024
   }
   signal?.throwIfAborted();
 
-  let calls = 0, outputBytes = 0;
+  let calls = 0, outputBytes = 0, inTransaction = false;
   const begin = () => {
     signal?.throwIfAborted();
-    if (calls >= maxCalls) throw new Error('Reader call budget exceeded');
+    if (calls >= maxCalls) throw budgetError('call');
     calls++;
   };
+  const resultSize = result => {
+    const size = Buffer.byteLength(JSON.stringify(result));
+    if (size > 64 * 1024) throw budgetError('output');
+    return size;
+  };
   const finish = result => {
     signal?.throwIfAborted();
-    const size = Buffer.byteLength(JSON.stringify(result));
-    if (size > 64 * 1024 || outputBytes + size > maxOutputBytes) throw new Error('Reader output budget exceeded');
+    const size = resultSize(result);
+    if (outputBytes + size > maxOutputBytes) throw budgetError('output');
     outputBytes += size;
     return result;
   };
@@ -47,55 +58,91 @@ export function createSnapshotReader(snapshotId, entries, { maxBytes = 4 * 1024
     sources.set(entry.id, { path: entry.path, side: entry.side, text: entry.text, hash: createHash('sha256').update(entry.text).digest('hex') });
   }
 
+  const find = ({ query, limit = 20 }) => {
+    if (!validQuery(query, limit)) throw new Error('Invalid find request');
+    const matches = [];
+    for (const [id, source] of sources) {
+      signal?.throwIfAborted();
+      if (typeof source.path !== 'string' || !source.path.includes(query)) continue;
+      if (matches.length === limit) return { snapshotId, matches, truncated: true };
+      matches.push({ sourceId: id, path: source.path, side: source.side, hash: source.hash });
+    }
+    return { snapshotId, matches, truncated: false };
+  };
+  const search = ({ query, limit = 20, sourceIds }) => {
+    if (!validQuery(query, limit)) throw new Error('Invalid search request');
+    if (sourceIds !== undefined && (!Array.isArray(sourceIds) || !sourceIds.length || sourceIds.length > 20 || new Set(sourceIds).size !== sourceIds.length || sourceIds.some(id => !sources.has(id)))) throw new Error('Invalid search source filter');
+    const selected = sourceIds === undefined ? null : new Set(sourceIds);
+    const matches = [];
+    for (const [id, source] of sources) {
+      if (selected && !selected.has(id)) continue;
+      signal?.throwIfAborted();
+      for (const range of lineRanges(source.text)) {
+        if (!source.text.slice(range.start, range.end).includes(query)) continue;
+        if (matches.length === limit) return { snapshotId, matches, truncated: true };
+        matches.push({ sourceId: id, hash: source.hash, line: range.line });
+      }
+    }
+    return { snapshotId, matches, truncated: false };
+  };
+  const read = ({ id, start, count }) => {
+    if (!sources.has(id)) throw new Error('Source not authorized');
+    if (!Number.isSafeInteger(start) || start < 1 || !Number.isSafeInteger(count) || count < 1 || count > 200) throw new Error('Invalid line range');
+    const source = sources.get(id);
+    let beginOffset = -1, endOffset = 0, selectedCount = 0;
+    for (const range of lineRanges(source.text)) {
+      if (range.line < start) continue;
+      if (beginOffset < 0) beginOffset = range.start;
+      endOffset = range.end;
+      selectedCount++;
+      if (selectedCount === count) break;
+    }
+    if (beginOffset < 0) throw new Error('Line range outside source');
+    const text = source.text.slice(beginOffset, endOffset);
+    if (Buffer.byteLength(text) > 64 * 1024) throw budgetError('output');
+    return { snapshotId, sourceId: id, hash: source.hash, start, count: selectedCount, text, endOfSource: endOffset === source.text.length };
+  };
+
   return Object.freeze({
     usage: () => ({ calls, outputBytes }),
-    find({ query, limit = 20 }) {
-      begin();
-      if (!validQuery(query, limit)) throw new Error('Invalid find request');
-      const matches = [];
-      for (const [id, source] of sources) {
+    budget: () => ({ maxCalls, maxOutputBytes, remainingCalls: maxCalls - calls, remainingOutputBytes: maxOutputBytes - outputBytes, maxResultBytes: 64 * 1024 }),
+    // 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;
+      inTransaction = true;
+      try {
+        const result = execute();
+        if (result && typeof result.then === 'function') throw new Error('Invalid asynchronous reader transaction');
         signal?.throwIfAborted();
-        if (typeof source.path !== 'string' || !source.path.includes(query)) continue;
-        if (matches.length === limit) return finish({ snapshotId, matches, truncated: true });
-        matches.push({ sourceId: id, path: source.path, side: source.side, hash: source.hash });
-      }
-      return finish({ snapshotId, matches, truncated: false });
+        return result;
+      } catch (error) {
+        calls = previousCalls; outputBytes = previousBytes;
+        throw error;
+      } finally { inTransaction = false; }
     },
-    search({ query, limit = 20, sourceIds }) {
-      begin();
-      if (!validQuery(query, limit)) throw new Error('Invalid search request');
-      if (sourceIds !== undefined && (!Array.isArray(sourceIds) || !sourceIds.length || sourceIds.length > 20 || new Set(sourceIds).size !== sourceIds.length || sourceIds.some(id => !sources.has(id)))) throw new Error('Invalid search source filter');
-      const selected = sourceIds === undefined ? null : new Set(sourceIds);
-      const matches = [];
-      for (const [id, source] of sources) {
-        if (selected && !selected.has(id)) continue;
-        signal?.throwIfAborted();
-        for (const range of lineRanges(source.text)) {
-          if (!source.text.slice(range.start, range.end).includes(query)) continue;
-          if (matches.length === limit) return finish({ snapshotId, matches, truncated: true });
-          matches.push({ sourceId: id, hash: source.hash, line: range.line });
-        }
-      }
-      return finish({ snapshotId, matches, truncated: 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({ id, start, count }, decorate = value => value) {
-      begin();
-      if (!sources.has(id)) throw new Error('Source not authorized');
-      if (!Number.isSafeInteger(start) || start < 1 || !Number.isSafeInteger(count) || count < 1 || count > 200) throw new Error('Invalid line range');
-      const source = sources.get(id);
-      let beginOffset = -1, endOffset = 0, selectedCount = 0;
-      for (const range of lineRanges(source.text)) {
-        if (range.line < start) continue;
-        if (beginOffset < 0) beginOffset = range.start;
-        endOffset = range.end;
-        selectedCount++;
-        if (selectedCount === count) break;
-      }
-      if (beginOffset < 0) throw new Error('Line range outside source');
-      const text = source.text.slice(beginOffset, endOffset);
-      if (Buffer.byteLength(text) > 64 * 1024) throw new Error('Reader output budget exceeded');
-      return finish(decorate({ snapshotId, sourceId: id, hash: source.hash, start, count: selectedCount, text, endOfSource: endOffset === source.text.length }));
-    },
+    read(request, decorate = value => value) { begin(); return finish(decorate(read(request))); },
   });
 }