aura-basetools 0.7.0 → 0.13.1

package/locator-lab/read-core.mjs

@@ -28,28 +28,28 @@ import { indexStructure, langOf, listSymbols, rankSymbols, resolveTarget } from
  * `handle-core.mjs` 是叶子（导入表为空），因此这条 import **不构成环**——
  * 否则 `write-path → read-core → handle-core → read-core` 会让模块求值顺序依赖入口。
  */
-import { HANDLE_MAX_PER_RECEIPT, fnv1a32, handleCharsFor, mintHandle } from './handle-core.mjs'
-/**
- * 参数收敛层（叶子模块，导入表为空 ⇒ 这条 import 也不构成环）。
- *
- * 多目标读（{@link readManyWith}）**必须**用与 `readEnvelope` 同一对判定器
- * （`gaveLineAddress` + `lineRangeOf` + `inferReadMode`）把"今天那套单目标参数"解出来，
- * 而不是在引擎里另写一份。两份判定一旦分叉，症状是"同一个目标，单独调用读得出来、
- * 放进 targets 里就报参数错"——而两边各自的测试都会绿（契约 §2.1 那句"同一个校验器"）。
- */
-import { LINE_ADDRESS_HINT, MT_MAX_TARGETS, MT_POOL, asLinePair, gaveLineAddress, inferReadMode, lineRangeOf } from './args.mjs'
-
-/**
- * 多目标形状的**契约上限**（fs-contract-v2 §2.1）不是本地判据，而是从参数面 `args.mjs` **转出**：
- * 那个数在参数面只有一份（`assertEditTargets` / `assertReadTargets` 与两个壳共用一个上限），
- * 读侧再写一遍就等于把同一份不变式抄成两份独立真值——将来改一处必分叉，而分叉的方向是
- * “参数面放行了、读引擎却拒收”这类没人愿意调的对不上。
- *
- * 接法：上面的 `import` 建一个本地绑定供本文件自己判上限，再把这个**同一绑定**导出
- * （不是 `export … from`：那种写法不建本地绑定，本文件自己的 `if (list.length > MT_MAX_TARGETS)`
- * 会当场 `ReferenceError`——这一点是实跑出来的，不是推的）。取值只有一个来源：`args.mjs` 那个字面量；
- * `const MT_MAX_TARGETS = 32` 这种第二份字面量在这里已无必要。对外导出名与取值逐字未变，`multi-read-test.mjs` 照旧。
- */
+import { HANDLE_MAX_PER_RECEIPT, fnv1a32, handleCharsFor, mintHandle } from './handle-core.mjs'
+/**
+ * 参数收敛层（叶子模块，导入表为空 ⇒ 这条 import 也不构成环）。
+ *
+ * 多目标读（{@link readManyWith}）**必须**用与 `readEnvelope` 同一对判定器
+ * （`gaveLineAddress` + `lineRangeOf` + `inferReadMode`）把"今天那套单目标参数"解出来，
+ * 而不是在引擎里另写一份。两份判定一旦分叉，症状是"同一个目标，单独调用读得出来、
+ * 放进 targets 里就报参数错"——而两边各自的测试都会绿（契约 §2.1 那句"同一个校验器"）。
+ */
+import { MT_MAX_TARGETS, MT_POOL, asLinePair, normalizeReadRequest } from './args.mjs'
+
+/**
+ * 多目标形状的**契约上限**（fs-contract-v2 §2.1）不是本地判据，而是从参数面 `args.mjs` **转出**：
+ * 那个数在参数面只有一份（`assertEditTargets` / `assertReadTargets` 与两个壳共用一个上限），
+ * 读侧再写一遍就等于把同一份不变式抄成两份独立真值——将来改一处必分叉，而分叉的方向是
+ * “参数面放行了、读引擎却拒收”这类没人愿意调的对不上。
+ *
+ * 接法：上面的 `import` 建一个本地绑定供本文件自己判上限，再把这个**同一绑定**导出
+ * （不是 `export … from`：那种写法不建本地绑定，本文件自己的 `if (list.length > MT_MAX_TARGETS)`
+ * 会当场 `ReferenceError`——这一点是实跑出来的，不是推的）。取值只有一个来源：`args.mjs` 那个字面量；
+ * `const MT_MAX_TARGETS = 32` 这种第二份字面量在这里已无必要。对外导出名与取值逐字未变，`multi-read-test.mjs` 照旧。
+ */
 export { MT_MAX_TARGETS }
 
 /**
@@ -119,31 +119,31 @@ function handleFor(ledgerKey, lines, byteOrderMark, startLine, endLine) {
   return mintHandle({ ledgerKey, regionText, byteOrderMark, startLine, endLine: to })
 }
 
-/**
- * 句柄落在 text 里时的分隔串（也是它唯一的**机器可识别标记**）。
- *
- * 为什么必须有个标记而不是直接 "行内容 + 句柄"：`text` 是行的拼接，句柄得能**被抓出来**
- * （`HANDLE_RE` 还需要一个左边界），而且人读时能一眼看出这不是文件里的字节。
- * 选 `  <` … `>` 是因为：它不会出现在正常行尾，长度只有 3 字符，
- * 而且与既有 ` ⋯ [truncated …]` 的"行尾附加说明"风格一致。
- */
-const HANDLE_MARK_OPEN = '  <'
-const HANDLE_MARK_CLOSE = '>'
-
-/** 行尾附加说明的**全部字符数**（含两侧标记）：21 字符句柄 ⇒ 24。 */
-export function handleInlineChars(startLine, endLine) {
-  return HANDLE_MARK_OPEN.length + handleCharsFor(startLine, endLine) + HANDLE_MARK_CLOSE.length
-}
-
-/**
- * 把句柄接到一行文本末尾；`handle` 为 null 时原样返回。
- *
- * `lines` 与 `search` 共用这一处，免得两个模式的"行尾长什么样"漂成两种。
- */
-function withHandleOnLine(line, handle) {
-  return handle === null ? line : `${line}${HANDLE_MARK_OPEN}${handle}${HANDLE_MARK_CLOSE}`
-}
-
+/**
+ * 句柄落在 text 里时的分隔串（也是它唯一的**机器可识别标记**）。
+ *
+ * 为什么必须有个标记而不是直接 "行内容 + 句柄"：`text` 是行的拼接，句柄得能**被抓出来**
+ * （`HANDLE_RE` 还需要一个左边界），而且人读时能一眼看出这不是文件里的字节。
+ * 选 `  <` … `>` 是因为：它不会出现在正常行尾，长度只有 3 字符，
+ * 而且与既有 ` ⋯ [truncated …]` 的"行尾附加说明"风格一致。
+ */
+const HANDLE_MARK_OPEN = '  <'
+const HANDLE_MARK_CLOSE = '>'
+
+/** 行尾附加说明的**全部字符数**（含两侧标记）：21 字符句柄 ⇒ 24。 */
+export function handleInlineChars(startLine, endLine) {
+  return HANDLE_MARK_OPEN.length + handleCharsFor(startLine, endLine) + HANDLE_MARK_CLOSE.length
+}
+
+/**
+ * 把句柄接到一行文本末尾；`handle` 为 null 时原样返回。
+ *
+ * `lines` 与 `search` 共用这一处，免得两个模式的"行尾长什么样"漂成两种。
+ */
+function withHandleOnLine(line, handle) {
+  return handle === null ? line : `${line}${HANDLE_MARK_OPEN}${handle}${HANDLE_MARK_CLOSE}`
+}
+
 /** 句柄的字符长度（契约 §3）——测试与体积核算共用这一个来源，不各写一个 21。 */
 // 句柄长度常量与上面那个上限同源，都在 `handle-core.mjs`（见文件顶部那条 re-export）。
 
@@ -939,7 +939,7 @@ function renderChanged(base, source, lines, request, symbolsIndex = null, ledger
    * 先前这里把非字符串的 `since` 当成"首读哨兵"并返回 `version: null`。那个 null 传不下去：
    * 工具声明的 schema 里 version 是 string，框架对字符串字段做类型校验
    * （dsh-tools/lib/index.js:495 `typeof value === "string"`），于是 null 会被判违规：
-   *   tool "aura_read" returned invalid output: "value.version" must be a string
+   *   tool "aura_basetools_read" returned invalid output: "value.version" must be a string
    * 更糟的是它**没意义**：回执的 next 让模型"把 version 传回来"，而 null 传回来又落回同一分支——
    * 一个永远解不开的环。现在首读也给真令牌，环就断了。
    */
@@ -981,14 +981,22 @@ function renderChanged(base, source, lines, request, symbolsIndex = null, ledger
     }
   }
   if (prev === null) {
-    // 缓存未命中：换进程、或读完太多轮被淘汰。诚实说明，不假装能比对。
+    /**
+     * 缓存未命中：换进程、被淘汰，或**大文件只记了令牌、没保留全文**（`source_omitted`）。
+     * 最后一种不是“过期”，说成“no longer cached”会让调用方以为重读一次就能修好——
+     * 它即使重读，>256 KiB 的全文仍然不会进缓存。把两种事实分开说。
+     */
+    const omitted = prevEntry?.source_omitted === true
+    const note = omitted
+      ? 'that revision is in the ledger, but the file exceeds 256 KiB so its full text was not retained — cannot diff; read the regions you need'
+      : 'that version is no longer cached — cannot diff; read the regions you need'
     return {
       ...base,
       mode: 'changed',
       version,
-      note: 'that version is no longer cached — cannot diff; read the regions you need',
+      note,
       next: 'mode=map then mode=lines',
-      text: 'that version is no longer cached — cannot diff; read the regions you need (next: mode=map then mode=lines)',
+      text: `${note} (next: mode=map then mode=lines)`,
     }
   }
 
@@ -1098,28 +1106,28 @@ export function leadingByteOrderMarks(text) {
 /**
  * 内容指纹：用于 changed 模式的比对。变化敏感、且不依赖 mtime。
  *
- * 带 BOM 的文件按**含 U+FEFF 的内容**算——否则只差一个 BOM 的两个文件会拿到同一个令牌，
- * `changed` 会说"没变"。令牌因此与落盘字节、与写路径带回的内容给出一致答案。
- *
- * **哈希本体不在这里**：它是 `handle-core.mjs` 的 {@link fnv1a32}（全仓唯一一份 FNV-1a）。
- * 句柄的区间摘要（`regionFingerprint`）取的是同一个哈希的前 8 位，所以"整文件令牌"与
- * "区间摘要"在 BOM 口径上永远一致——两边各自实现一份就可能漂开，而漂开是静默的。
- * 搬家的边界很窄：**只有哈希那几行**搬了，下面这个返回串的形状（`指纹:长度`）
- * 与 `effective` 的口径都逐字未改（否则 `changed` 与既有判据全要重算）。
- *
- * @param source - 解码后的全文
- * @param byteOrderMark - 这份文件是否带 UTF-8 BOM（判据只能是字节，见 {@link startsWithByteOrderMark}）
- */
-export function contentToken(source, byteOrderMark = false) {
-  const effective = byteOrderMark ? BYTE_ORDER_MARK + source : source
-  return `${fnv1a32(source, byteOrderMark)}:${effective.length}`
+ * 带 BOM 的文件按**含 U+FEFF 的内容**算——否则只差一个 BOM 的两个文件会拿到同一个令牌，
+ * `changed` 会说"没变"。令牌因此与落盘字节、与写路径带回的内容给出一致答案。
+ *
+ * **哈希本体不在这里**：它是 `handle-core.mjs` 的 {@link fnv1a32}（全仓唯一一份 FNV-1a）。
+ * 句柄的区间摘要（`regionFingerprint`）取的是同一个哈希的前 8 位，所以"整文件令牌"与
+ * "区间摘要"在 BOM 口径上永远一致——两边各自实现一份就可能漂开，而漂开是静默的。
+ * 搬家的边界很窄：**只有哈希那几行**搬了，下面这个返回串的形状（`指纹:长度`）
+ * 与 `effective` 的口径都逐字未改（否则 `changed` 与既有判据全要重算）。
+ *
+ * @param source - 解码后的全文
+ * @param byteOrderMark - 这份文件是否带 UTF-8 BOM（判据只能是字节，见 {@link startsWithByteOrderMark}）
+ */
+export function contentToken(source, byteOrderMark = false) {
+  const effective = byteOrderMark ? BYTE_ORDER_MARK + source : source
+  return `${fnv1a32(source, byteOrderMark)}:${effective.length}`
 }
 
 /* ── 同会话增量读 ──────────────────────────────────────────────────────────
  *
  * ## 它治的是什么
  *
- * 实测：15,935 次 aura_read 里 **63.8%** 是同一会话内对**已读文件**的重复读，
+ * 实测：15,935 次 aura_basetools_read 里 **63.8%** 是同一会话内对**已读文件**的重复读，
  * 那些回执合计 53.8M 字符。重复读里绝大多数行根本没变——再发一遍全文，
  * 是把已经给过的东西再收一次钱。
  *
@@ -1524,8 +1532,17 @@ function planIncremental(request, lines, version) {
       : { kind: 'skip' }
   }
   // 身份键在手就递下去（宿主事实优先）：观测账本本来就按身份键记，这里少一次"写法 vs 盘上"的对不上。
-  const before = recallRead(filePath, entry.version, request.identityKey)
+  const beforeEntry = seenEntry(filePath, entry.version, request.identityKey)
+  const before = beforeEntry === null ? null : beforeEntry.source
   if (before === null) {
+    /**
+     * 账本说“你读过”，但没有可 diff 的全文。两种原因要分开：
+     *   · `source_omitted`：文件超过 256 KiB，**按设计**不保留全文（重读也不会改变）；
+     *   · 否则：有界缓存淘汰 / 换进程（重读可以恢复）。
+     */
+    if (beforeEntry?.source_omitted === true) {
+      return { kind: 'degrade', asked, reason: `the baseline you read earlier (${entry.version}) is in the ledger, but this file exceeds 256 KiB so its full text was not retained; cannot diff — the full text follows` }
+    }
     // 账本说"你读过"，缓存却说"我没有那份内容"——有界缓存淘汰或换进程都会走到这里
     return { kind: 'degrade', asked, reason: `the baseline you read earlier (${entry.version}) is no longer in the bounded observation cache, so it cannot be diffed; the full text follows` }
   }
@@ -1575,8 +1592,8 @@ function noChangeEnvelope(base, plan, total) {
  * 那时调用方要的明确是增量，"为什么还是全文"必须有答案；自动路径下省字节优先，
  * 沉默就是答案（全文本身已经回答了那个问题）。
  */
-function renderIncremental(base, lines, symbolsIndex, plan, budget, total, handleContext = null) {
-  // `handleContext` 在这里**不被消费**：`full` 不发句柄（见 `readWith` 里的长注释）。
+function renderIncremental(base, lines, symbolsIndex, plan, budget, total, handleContext = null) {
+  // `handleContext` 在这里**不被消费**：`full` 不发句柄（见 `readWith` 里的长注释）。
   // 参数留着是为了让调用点不必按模式分叉——去掉它就得在调用处再判一次模式。
   const full = () => renderFull(base, lines, symbolsIndex)
   if (plan.kind === 'skip') return { env: full(), record: null }
@@ -1643,9 +1660,9 @@ function recordDelivery(filePath, result, version, total, bom, record) {
  * （1 个函数时全文 156 字符、map 123、digest 180；再小一点全文就反超）。
  * 把这种情况硬塞给 lines 模式是错的——lines 需要调用方给区间，而这里调用方什么都没给。
  */
-function renderFull(base, lines, symbolsIndex = null) {
-  // 不发句柄（理由见 `readWith` 里 `handleContext` 那段）：全文读不是编辑地址。
-  return windowEnvelope(base, lines, 1, lines.length, 'full file', 1, null, symbolsIndex)
+function renderFull(base, lines, symbolsIndex = null) {
+  // 不发句柄（理由见 `readWith` 里 `handleContext` 那段）：全文读不是编辑地址。
+  return windowEnvelope(base, lines, 1, lines.length, 'full file', 1, null, symbolsIndex)
 }
 
 /**
@@ -1659,15 +1676,29 @@ function renderFull(base, lines, symbolsIndex = null) {
  *
  * @returns {{mode: string, reason: string, sizes: object}}
  */
-export function suggestMode(source, filePath) {
-  const sizes = { full: source.length }
+export function suggestMode(source, filePath, budget = null) {
+  /**
+   * 宿主预算（`request.budget`）优先：它是调用方**实际会执行**的剪枝阈值，缺省才是 8192。
+   * 内容上限必须减去两层信封开销（{@link DEFAULT_ENVELOPE_ALLOWANCE}），与 `readWith` 的
+   * `contentCeiling` 同一口径——否则 auto 会以为“装得下”，实际渲染时又被信封挤出去。
+   */
+  const hostBudget = Number.isInteger(budget) && budget > 0 ? budget : DEFAULT_PRUNE_BUDGET
+  const contentBudget = Math.max(0, hostBudget - DEFAULT_ENVELOPE_ALLOWANCE)
+  /**
+   * `full` 的渲染长度**不是** `source.length`：每行有 `N: ` 行号前缀，736 行的文件会多出
+   * 约 1.6KB。旧判据拿原始字符数比预算，于是 5902 字符 / 736 行被判成“全文装得下”，
+   * 实际渲染时剪掉 193 行，`auto` 理由还写着 “complete answer”。这里直接用 full 的真实
+   * 渲染结果（`omitted === undefined` 才算完整）作判据。
+   */
+  const fullProbe = readWith(source, { filePath, mode: 'full', budget: hostBudget, probe: true })
+  const sizes = { full: fullProbe.text?.length ?? source.length }
   const lang = filePath === null || filePath === undefined ? null : langOf(filePath)
   let symbols = null
   if (lang !== null) {
     symbols = listSymbols(indexStructure(source, lang)).length
-    sizes.map = readWith(source, { filePath, mode: 'map' }).text?.length ?? 0
+    sizes.map = readWith(source, { filePath, mode: 'map', budget: hostBudget, probe: true }).text?.length ?? 0
     if (sizes.map <= sizes.full) {
-      sizes.digest = readWith(source, { filePath, mode: 'digest' }).text?.length ?? 0
+      sizes.digest = readWith(source, { filePath, mode: 'digest', budget: hostBudget, probe: true }).text?.length ?? 0
     }
   }
 
@@ -1698,11 +1729,11 @@ export function suggestMode(source, filePath) {
    * 为什么用预算而不是固定字符数：预算是算出来的（内容预算随信封收紧），
    * 而固定字符数会随着预算变化而变成另一个隐含的错值。
    */
-  const FULL_TEXT_FITS = source.length <= CONTENT_BUDGET
+  const FULL_TEXT_FITS = fullProbe.ok === true && fullProbe.omitted === undefined
   if (FULL_TEXT_FITS) {
     return {
       mode: 'full',
-      reason: `the whole text fits the content budget (${source.length} ≤ ${CONTENT_BUDGET} chars), so it is the complete answer`,
+      reason: `the whole text fits the content budget (${sizes.full} ≤ ${contentBudget} chars rendered; host budget ${hostBudget}, envelope allowance ${DEFAULT_ENVELOPE_ALLOWANCE}), so it is the complete answer`,
       sizes,
     }
   }
@@ -1730,381 +1761,391 @@ export function suggestMode(source, filePath) {
     return n > 0 && n >= source.length * 0.01
   }
   const top = Object.entries(sizes).sort((a, b) => a[1] - b[1])
-  const ranked = top.filter(([name]) => name === 'full' || delivered(name))
+  // `full` 通常不受“1% 交付”门槛限制（它的少是预算裁剪，有解释）；
+  // 但渲染长度是 0 的 full 是**空壳**，不能因为“叫 full”就被选中。
+  const ranked = top.filter(([name]) => (name === 'full' ? sizes.full > 0 : delivered(name)))
   const candidates = ranked.length > 0 ? ranked : [['full', sizes.full]]
   const best = candidates[0]
   const reason =
-    best[0] === 'full'
-      ? `full text is the smallest option (${source.length} chars)`
-      : `${best[0]} is ${(sizes.full / best[1]).toFixed(1)}x smaller than the full text`
+    best[1] === 0
+      ? `no mode can render text at host budget ${hostBudget} (below the minimum envelope); raise the budget or pass maxChars`
+      : best[0] === 'full'
+        ? `full text is the smallest option (${sizes.full} chars rendered)`
+        : `${best[0]} is ${(sizes.full / best[1]).toFixed(1)}x smaller than the full text`
   return { mode: best[0], reason, sizes, ...(symbols === null ? {} : { symbols }) }
 }
 
-/**
- * 多目标读（契约 §2.1 / §4）——**与单目标并列的新增形状**，既有形状一字不改。
- *
- * 这不是 `readWith` 的变体：`readWith` 吃**已经读进来的全文**，本入口吃**目标描述**，
- * 读盘那一步由 provider 完成。两者共用的只有"一个目标怎么读"这一处逻辑
- * （{@link readManyTarget}），因此不存在"单目标一套、多目标另一套"两份判定。
- *
- * ## 为什么新入口要读盘、而单目标那条路不读（这一条是可复核的历史，不是取舍）
- *
- * 读侧的真编排入口是 `ops.mjs` 的 `readEnvelope`，它在文件分支用 `readFileBytes`（直接 fs 读）
- * ——**不经 `provider.readText`**。上一单把这条现状钉成了红线（`provider-calls` 那三类逐条比对
- * 调用序列）。所以本入口**绝不**改 `readEnvelope`：多目标走 provider 是**新路径**，单目标
- * 继续走它原来那条。谁要动单目标那条路，先绿的是红线套件，不是这份代码。
- *
- * 本文件**零 `node:` 依赖**（契约 §1.5）：这里只做纯计算与 provider 调用，
- * 计时用 `Date.now()`（全局，不是内置模块）。
- */
-
-/**
- * 并发池大小（契约 §4：`MT_POOL = 8`）—— **不是本地真值**，而是参数面 `args.mjs` 那一份的转发。
- *
- * 这里原来写着 `export const MT_POOL = 8`，与写侧 `write-path.mjs` 里同一句构成**两份活真值**；
- * 两边恰好都是 8，于是两个套件同时绿，把缝盖住了。现在取值只有一个来源，与上面 `MT_MAX_TARGETS`
- * 同一条纪律、同一种接法：上面的 `import` 建本地绑定供本文件自己用（`options.pool ?? MT_POOL`），
- * 再用 `export { MT_POOL }` 把这个**同一绑定**转出去。**不是** `export … from`：那种写法不建本地绑定，
- * 本文件自己那两处会当场 `ReferenceError`——`node --check` 抓不到，只有实跑套件才炸。
- *
- * 导出名与取值逐字未变（`multi-read-test.mjs` 从这里取 `MT_POOL` 并断言在飞峰值）。
- */
-export { MT_POOL }
-/** 多目标的"参数形状没成形"错误码（与 `ARGS_UNKNOWN_KEY` 同族：**抛错**，不是结果通道）。 */
-export const MT_BAD_TARGETS = 'MT_BAD_TARGETS'
-export const MT_TOO_MANY_TARGETS = 'MT_TOO_MANY_TARGETS'
-
-/** 一个目标读完之后账面上算哪一类（汇总行只按这一列计数）。 */
-const MT_OK = 'ok'
-
-/**
- * 汇总行：形如 `targets: 7 ｜ ok 6 ｜ not_found 1`。
- *
- * 计数**按结果现算**，不另维护一套账：两套账迟早会分叉，而分叉的方向必然是
- * "汇总说 6 条成了、逐项里只有 5 条 ok"这种谁都不信的中间态。
- * 没成的按 `code` 逐个列出（`not_found` 用短名，其余用原码），因此
- * "哪几条没成"在一行里就能读出来。
- */
-function mtSummaryLine(entries) {
-  const counts = new Map()
-  for (const entry of entries) {
-    const label = entry.outcome === MT_OK ? MT_OK : mtShortCode(entry.code)
-    counts.set(label, (counts.get(label) ?? 0) + 1)
-  }
-  // `ok` 永远排第一（它是这条行的主语），其余按名字排序 ⇒ 同一份输入恒定给同一行。
-  const names = [...counts.keys()].sort((a, b) => (a === MT_OK ? -1 : b === MT_OK ? 1 : a < b ? -1 : a > b ? 1 : 0))
-  return [`targets: ${entries.length}`, ...names.map((name) => `${name} ${counts.get(name)}`)].join(' ｜ ')
-}
-
-/** 汇总行里的短码：只给 `not_found` 起短名，其余原样——短名多了就成了第二种语言。 */
-const mtShortCode = (code) => (code === 'FS_NOT_FOUND' ? 'not_found' : String(code ?? 'error'))
-
-/**
- * 读一个 target：**唯一的**"一个目标 = 一次读"实现。
- *
- * N===1 直调它、N>1 池里调它——同一条代码路径，所以"多目标那条路会不会比单目标多跑一次"
- * 这个问题在结构上就只有一种答案。
- *
- * 顺序（也就是 provider 调用序列）是刻意钉死的：`resolve` → `stat` → `readText` →（可选）`readByteRange`。
- * 它刻意与 `readEnvelope` 文件分支的 `resolve` → `stat` → 读 同形：
- * 这样 N===1 的调用**序列**与直接读一个目标逐字相同，红线那条断言才有东西可比。
- *
- * @param provider - 四方法契约：`resolve` / `stat` / `readText` / `readByteRange`
- * @param rawTarget - 调用方给的单个目标（**就是今天那套单目标参数**）
- * @param index - 在输入数组里的序号（进回执，用于"哪一条没成"）
- * @param probeBom - 是否用 `readByteRange` 探一次 BOM。理由见 {@link readManyWith}
- * @returns 逐项回执行（与单目标回执同一套渲染：成功时就是 `readWith` 的原样输出）
- */
-async function readManyTarget(provider, rawTarget, index, probeBom) {
-  const request = rawTarget === null || typeof rawTarget !== 'object' ? null : rawTarget
-  if (request === null) throw Object.assign(new Error(`targets[${index}] must be an object`), { code: MT_BAD_TARGETS })
-  /**
-   * 目标里的 `file_path` 留**原样**（回执原样回抄调用方给的路径，与单目标同一条纪律）；
-   * `readWith` 要的是 `filePath`，转换只在这一处发生。
-   */
-  const filePath = request.file_path ?? request.filePath ?? request.path
-  if (typeof filePath !== 'string' || filePath === '') {
-    throw Object.assign(new Error(`targets[${index}] needs a file_path string`), { code: MT_BAD_TARGETS })
-  }
-  /**
-   * 行区间：`gaveLineAddress` + `lineRangeOf` 与单目标**同一对判定器**，这里不另写一份。
-   * 给了但解不出来 ⇒ 逐项拒绝（结果通道），理由与 `readEnvelope` 那处一字不差：
-   * 静默退回 auto 会让人以为是别的问题。
-   */
-  const range = lineRangeOf(request)
-  if (range === undefined && gaveLineAddress(request)) {
-    return mtFailure(index, [filePath, filePath], 'READ_BAD_ARGS', LINE_ADDRESS_HINT)
-  }
-  const mode = inferReadMode(request, range)
-  const lines = asLinePair(range)
-  /**
-   * `provider.resolve` 的两种返回形状**都认**（`await` 对同步值等价，所以旧提供方一行不用改）：
-   *   · **字符串** —— 旧形状（CLI/MCP 的 `createNodeFsProvider`、绝大多数测试）：它就是显示路径，
-   *     账本键也由它算（`identityKey` 缺席）⇒ 与本参数存在之前**逐字节相同**；
-   *   · **宿主解析结果** `{displayPath, targetKey}` —— DSH 壳的 `ctx.fs.resolve()` 就是这个形状：
-   *     显示路径用 `displayPath`，**身份键**用 `targetKey`。
-   *
-   * 为什么必须认第二种（实测：同一文件同一区间，单目标读发 `h4745015d4840:…`、多目标读发
-   * `he6dd015d4840:…` —— 指纹段相同、**身份标签段不同**）：句柄的身份标签按
-   * `ledgerIdentityKey(filePath, identityKey)` 算，而单目标那条路（`readEnvelope` 前的壳）递的正是
-   * `ctx.fs.resolve()` 的 `targetKey`。多目标若只把路径串当身份，就会对**同一份盘上文件**发出两个
-   * 不同的句柄，后果具体：拿批量读来的句柄去 `aura_edit` ⇒ `PATCH_HANDLE_IDENTITY_MISMATCH`。
-   *
-   * 身份口径**不新造第三份**：宿主给的 `targetKey` 就是既有那一份（@see ledgerIdentityKey / IDENTITY_KEYS）；
-   * 元素自带的 `identityKey`（与写侧 `editTargetRequests` 同名的那个键）只作为提供方给不出事实时的回落。
-   */
-  const hostTarget = await provider.resolve(filePath)
-  const target =
-    hostTarget !== null && typeof hostTarget === 'object' ? (hostTarget.displayPath ?? filePath) : hostTarget
-  const identityKey =
-    hostTarget !== null && typeof hostTarget === 'object' && typeof hostTarget.targetKey === 'string' && hostTarget.targetKey.length > 0
-      ? hostTarget.targetKey
-      : request.identityKey
-  let info
-  try {
-    info = await provider.stat(target)
-  } catch (error) {
-    return mtFailure(index, [target, filePath], error?.code ?? 'IO_ERROR', String(error?.message ?? error))
-  }
-  /**
-   * `stat` 的两套约定都要认：
-   *   · `createNodeFsProvider` 与 DSH 的 `probe()` 给 `{type: 'file'|'directory'|'other', …}`；
-   *   · 有些提供方给 `undefined` 表示不存在。
-   * 存在但拿不到类型时**按文件试读**（读不动自有 provider 抛错兜底），
-   * 不在这里替提供方发明第三种类型判定。
-   */
-  if (info === undefined || info === null) {
-    return mtFailure(index, [target, filePath], 'FS_NOT_FOUND', `cannot read "${filePath}": not found`)
-  }
-  if (info.type === 'directory') {
-    // 目录级地图（T26）是**单目标**的既有能力，多目标这一波不扩它：只给可执行的拒绝。
-    return mtFailure(index, [target, filePath], 'MT_TARGET_IS_DIRECTORY', `"${filePath}" is a directory: read it on its own (a repo map is not a window)`, `read "${filePath}" by itself for a repo map`)
-  }
-  /**
-   * `readText` 可能同步抛（非 UTF-8 / 二进制 / 竞争删除）——`await` 包在 try 里，
-   * 于是同步抛与 reject 走同一条路。逐项拒绝，整批不受影响（契约 §1.3）。
-   */
-  let source
-  try {
-    source = await provider.readText(target)
-  } catch (error) {
-    return mtFailure(index, [target, filePath], error?.code ?? 'IO_ERROR', String(error?.message ?? error))
-  }
-  /**
-   * BOM：`provider.readText` 把第一个 BOM 吃掉了（默认 `ignoreBOM: false`），
-   * 而 BOM **进内容指纹**、也进句柄（契约 §4 的令牌语义），因此它必须由**字节**得出。
-   *
-   * 这一笔是"多目标路径上多出来的一次读"，代价与理由都摆在这里：只读 BOM 那几个字节，
-   * 且只在提供方有 `readByteRange` 时；`probeBom: false` 可整体关掉（那时按"无 BOM"读）。
-   * **单目标那条路一点没碰**：它仍旧走 `readEnvelope` 的 `readFileBytes`（一次 fs 读，BOM 一次拿到）。
-   */
-  let byteOrderMark = false
-  if (probeBom && typeof provider.readByteRange === 'function') {
-    try {
-      const head = await provider.readByteRange(target, { offset: 0, length: BYTE_ORDER_MARK_BYTES.length })
-      byteOrderMark = startsWithByteOrderMark(head)
-    } catch {
-      // 读头失败不回滚整条读：BOM 是**元数据**，缺它就按没有处理（下面那次 readText 已经成功了）。
-      byteOrderMark = false
-    }
-  }
-  const env = readWith(source, {
-    mode,
-    around: request.around,
-    lines,
-    search: request.search,
-    since: request.since,
-    // 读侧两层叫法不同：宿主面 `max_chars`，引擎面 `maxChars`（与 `readEnvelope` 同源）。
-    maxChars: request.max_chars ?? request.maxChars,
-    byteOrderMark,
-    /**
-     * `filePath` 给的是 **provider.resolve 之后的那个串**，不是调用方原样给的路径。
-     *
-     * 为什么必须是它（这条是实测出来的，不是风格）：`readWith` 用它算**账本键**，
-     * 而账本键进句柄的身份标签。单目标那条路（`readEnvelope`）给的正是 `provider.resolve(file)`，
-     * 于是这里若给原样的 `file_path`，同一个文件在两条路上会得到**两个不同的句柄**
-     * ——`multi-read-test` 段A 的"逐项回执与单独跑一次逐字节相同"当场变红，
-     * 而且更坏的是：拿批内句柄去 `aura_edit` 会查不到那一条观测。
-     *
-     * 回执里显示哪一份由 `file_path` 字段负责（下面那条）——两件事分开，各归各的字段。
-     */
-    filePath: target,
-    /**
-     * 身份键与 `filePath` **分开递**，与单目标那条路（`readEnvelope` 的 `identityKey: target.targetKey`）
-     * 同源。缺席时（提供方只给字符串、元素也没带）走旧行为：账本键 = `filePath`。
-     */
-    ...(typeof identityKey === 'string' && identityKey.length > 0 ? { identityKey } : {}),
-  })
-  /**
-   * 成了 ⇒ **这一条就是单目标回执本身**（同一个对象引用，不是另渲染一遍）。
-   * 另渲染一遍是这一单最容易犯的错：两份渲染一开始一样，改一处就只改一份。
-   */
-  return {
-    index,
-    file_path: filePath,
-    ok: true,
-    outcome: MT_OK,
-    mode: env.mode,
-    envelope: env,
-  }
-}
-
-/**
- * 一条没成的逐项回执。
- *
- * 形状刻意与成了的那条**逐字段对齐**（`index` / `file_path` / `ok` / `outcome` 都在），
- * 只有 `envelope` 换成 `code` + `message`：调用方按同一个字段集读两种结果，不用分叉。
- * `next` 只在能给**可执行**的下一步时才出现（与单目标的 `next` 同一条纪律：不给空话）。
- */
-function mtFailure(index, [target, displayPath], code, message, next) {
-  return {
-    index,
-    file_path: displayPath,
-    ok: false,
-    outcome: 'failed',
-    ...(code === 'FS_NOT_FOUND' ? { target } : {}),
-    code,
-    message,
-    ...(next === undefined ? {} : { next }),
-  }
-}
-
-/**
- * **一次调用读多个目标**（契约 §2.1 的读侧形状）。
- *
- * ## 形状
- *
- * 两种调用方式，**互斥**：
- *   · `readManyWith(provider, [{file_path, mode, …}, …], opts)` —— 多目标（推荐，显式）；
- *   · `readManyWith(provider, {file_path, mode, …}, opts)` —— 单个目标，与上面**同一条代码路径**。
- * 单个对象被归一成"长度 1 的数组"，所以不存在第二条实现。
- *
- * ## N===1 ⇒ 直调（结构性保证，不是"我们测了没变慢"）
- *
- * 长度 1 时**不建池、不建队列、不包一层**：直接 `await` 那个唯一的目标，
- * 一行 `if` 就出函数。因此"N=1 时多跑一次 / 多包一层 / 多一个字段"这件事
- * 在本入口里没有可发生的语法位置——它是控制流性质，不是性能观测。
- * 测试（`multi-read-test.mjs` 段C）用计数 provider 把这条钉成"调用序列逐项相同"。
- *
- * ## N>1 ⇒ 有界并发池，只并发 I/O 与纯计算（契约 §4）
- *
- * 池子就是 `min(MT_POOL, N)` 个**常驻 worker** 各拉一条队列：`maxInFlight` 因此由结构决定，
- * 不用"数一数同时在飞几个"去经验地保证。
- * **结果按输入顺序装配**：`results[i] = …` 按下标写，完成顺序只影响"谁先写"、不影响任何一项的位置。
- * 这一条是硬要求（契约 §1.4）——并发完成顺序一旦泄漏到输出，同一份输入两次调用可能给两种排列。
- *
- * ## 失败语义（契约 §1.3）
- *
- * 逐项失败（不存在 / 找不到 / 需选择 / 不是文本 / 目录）一律**走结果通道**：那一条带
- * `ok:false` + `code` + `message`（能给下一步时还有 `next`），**其余目标照常**。
- * 只有"参数形状没成形"才抛错：
- *   · `targets` 不是数组/不是对象 ⇒ `MT_BAD_TARGETS`；
- *   · 目标数超过 {@link MT_MAX_TARGETS} ⇒ `MT_TOO_MANY_TARGETS`，**message 里报出实得数**；
- *   · `targets` 为空 ⇒ `MT_BAD_TARGETS`（空批不是"成功读了 0 个"，那是静默换语义）。
- * 抛错**不会**吞掉已经读成的那些：抛发生在**读之前**（形状校验是第一件事），所以没有"半批已读"这种状态。
- *
- * ## 回执
- *
- * 逐项（同一套渲染）+ **一行汇总**（`targets: N ｜ ok K ｜ not_found M`）。
- * 汇总只在 `summary` 字段里、不进任何 `envelope.text`：正文是宿主剪枝器量的东西（契约 §5），
- * 往里塞一行就是让每一份多目标回执的正文回涨。
- *
- * @param provider - 四方法契约：`resolve` / `stat` / `readText` / `readByteRange`
- * @param targets - 目标数组（每个元素就是今天那套单目标参数），或**单个**这样的对象
- * @param {number} [options.pool] - 覆盖池大小（默认 {@link MT_POOL}）。测试要它把"有界"钉成结构观测
- * @param {boolean} [options.probeBom] - 是否探 BOM，默认 `true`
- * @param {(event: {index: number, maxInFlight: number}) => void} [options.trace] - 纯观测钩子（测试用）
- * @returns 逐项 + 汇总的整批回执（**不是** Promise 之外的任何包装）
- * @throws {Error} `code` ∈ {`MT_BAD_TARGETS`, `MT_TOO_MANY_TARGETS`}
- */
-export async function readManyWith(provider, targets, options = {}) {
-  if (provider === null || typeof provider !== 'object' || typeof provider.readText !== 'function') {
-    throw Object.assign(new Error('readManyWith needs a provider with resolve/stat/readText'), { code: MT_BAD_TARGETS })
-  }
-  /** 单个对象 = 长度 1 的数组：**归一只有这一处**，下面再没有"单个/多个"的分叉。 */
-  const list = Array.isArray(targets) ? targets : targets !== null && typeof targets === 'object' ? [targets] : null
-  if (list === null) {
-    throw Object.assign(new Error(`targets must be an array or a single target object, got ${targets === null ? 'null' : typeof targets}`), { code: MT_BAD_TARGETS })
-  }
-  if (list.length === 0) {
-    throw Object.assign(new Error('targets must not be empty (an empty batch is not "read 0 files")'), { code: MT_BAD_TARGETS })
-  }
-  if (list.length > MT_MAX_TARGETS) {
-    throw Object.assign(new Error(`targets has ${list.length} entries, but the limit is ${MT_MAX_TARGETS} — split the call`), {
-      code: MT_TOO_MANY_TARGETS,
-      got: list.length,
-      max: MT_MAX_TARGETS,
-    })
-  }
-  const probeBom = options.probeBom !== false
-  const started = Date.now()
-  const entries = new Array(list.length)
-  if (list.length === 1) {
-    // ── N===1：直调。没有池、没有队列、没有 trace、没有包装 —— 这里少写一行代码就是保证。 ──
-    entries[0] = await readManyTarget(provider, list[0], 0, probeBom)
-  } else {
-    await mtPool(list, options.pool ?? MT_POOL, options.trace, async (item, index) => {
-      entries[index] = await readManyTarget(provider, item, index, probeBom)
-    })
-  }
-  const counts = { ok: 0, failed: 0 }
-  for (const entry of entries) {
-    if (entry.ok === true) counts.ok += 1
-    else counts.failed += 1
-  }
-  return {
-    ok: counts.failed === 0,
-    targets: entries.length,
-    counts,
-    summary: mtSummaryLine(entries),
-    entries,
-    elapsedMs: Date.now() - started,
-  }
-}
-
-/**
- * 有界并发池：`min(pool, N)` 个常驻 worker 各拉一条队列。
- *
- * 为什么是"常驻 worker + 共享游标"而不是"分批 `Promise.all`"：分批发的话，
- * 一格慢就整批等（尾部空转），而"同时在飞几个"这件事会随每批的完成快慢漂移。
- * 常驻 worker 下**在飞数恒 ≤ pool**——这是结构，不靠经验观测。
- *
- * 为什么 worker 自己 `await`：`maxInFlight` 只在 worker 真正进入/离开时增减，
- * 而它进出之间**只**做一件事：跑 `run`（I/O 与纯计算）。`trace` 因此能给出
- * "同时在飞的最大值"这个**确定性**读数（慢 provider 下它必然等于 pool），
- * 而不是一次墙钟计时（机器上有并行单元，计时不作判据）。
- */
-async function mtPool(items, pool, trace, run) {
-  const width = Math.max(1, Math.min(Math.trunc(pool) || MT_POOL, items.length))
-  let next = 0
-  let inFlight = 0
-  let maxInFlight = 0
-  const worker = async () => {
-    while (true) {
-      const index = next
-      next += 1
-      if (index >= items.length) return
-      inFlight += 1
-      if (inFlight > maxInFlight) maxInFlight = inFlight
-      if (typeof trace === 'function') trace({ index, maxInFlight })
-      try {
-        await run(items[index], index)
-      } finally {
-        inFlight -= 1
-      }
-    }
-  }
-  const workers = []
-  for (let w = 0; w < width; w += 1) workers.push(worker())
-  await Promise.all(workers)
-}
-
-/**
- * 读一个文件，按模式返回**带预算与省略说明**的结构化结果。
- *
- * 多目标（多文件 / 多区间一次调用）走 {@link readManyWith}：它**逐个**调用本函数，
- * 因此"一个目标怎么读"只有一处实现。本函数自身一行未改——单目标零回归由红线套件钉住。
- *
+/**
+ * 多目标读（契约 §2.1 / §4）——**与单目标并列的新增形状**，既有形状一字不改。
+ *
+ * 这不是 `readWith` 的变体：`readWith` 吃**已经读进来的全文**，本入口吃**目标描述**，
+ * 读盘那一步由 provider 完成。两者共用的只有"一个目标怎么读"这一处逻辑
+ * （{@link readManyTarget}），因此不存在"单目标一套、多目标另一套"两份判定。
+ *
+ * ## 为什么新入口要读盘、而单目标那条路不读（这一条是可复核的历史，不是取舍）
+ *
+ * 读侧的真编排入口是 `ops.mjs` 的 `readEnvelope`，它在文件分支用 `readFileBytes`（直接 fs 读）
+ * ——**不经 `provider.readText`**。上一单把这条现状钉成了红线（`provider-calls` 那三类逐条比对
+ * 调用序列）。所以本入口**绝不**改 `readEnvelope`：多目标走 provider 是**新路径**，单目标
+ * 继续走它原来那条。谁要动单目标那条路，先绿的是红线套件，不是这份代码。
+ *
+ * 本文件**零 `node:` 依赖**（契约 §1.5）：这里只做纯计算与 provider 调用，
+ * 计时用 `Date.now()`（全局，不是内置模块）。
+ */
+
+/**
+ * 并发池大小（契约 §4：`MT_POOL = 8`）—— **不是本地真值**，而是参数面 `args.mjs` 那一份的转发。
+ *
+ * 这里原来写着 `export const MT_POOL = 8`，与写侧 `write-path.mjs` 里同一句构成**两份活真值**；
+ * 两边恰好都是 8，于是两个套件同时绿，把缝盖住了。现在取值只有一个来源，与上面 `MT_MAX_TARGETS`
+ * 同一条纪律、同一种接法：上面的 `import` 建本地绑定供本文件自己用（`options.pool ?? MT_POOL`），
+ * 再用 `export { MT_POOL }` 把这个**同一绑定**转出去。**不是** `export … from`：那种写法不建本地绑定，
+ * 本文件自己那两处会当场 `ReferenceError`——`node --check` 抓不到，只有实跑套件才炸。
+ *
+ * 导出名与取值逐字未变（`multi-read-test.mjs` 从这里取 `MT_POOL` 并断言在飞峰值）。
+ */
+export { MT_POOL }
+/** 多目标的"参数形状没成形"错误码（与 `ARGS_UNKNOWN_KEY` 同族：**抛错**，不是结果通道）。 */
+export const MT_BAD_TARGETS = 'MT_BAD_TARGETS'
+export const MT_TOO_MANY_TARGETS = 'MT_TOO_MANY_TARGETS'
+
+/** 一个目标读完之后账面上算哪一类（汇总行只按这一列计数）。 */
+const MT_OK = 'ok'
+
+/**
+ * 汇总行：形如 `targets: 7 ｜ ok 6 ｜ not_found 1`。
+ *
+ * 计数**按结果现算**，不另维护一套账：两套账迟早会分叉，而分叉的方向必然是
+ * "汇总说 6 条成了、逐项里只有 5 条 ok"这种谁都不信的中间态。
+ * 没成的按 `code` 逐个列出（`not_found` 用短名，其余用原码），因此
+ * "哪几条没成"在一行里就能读出来。
+ */
+function mtSummaryLine(entries) {
+  const counts = new Map()
+  for (const entry of entries) {
+    const label = entry.outcome === MT_OK ? MT_OK : mtShortCode(entry.code)
+    counts.set(label, (counts.get(label) ?? 0) + 1)
+  }
+  // `ok` 永远排第一（它是这条行的主语），其余按名字排序 ⇒ 同一份输入恒定给同一行。
+  const names = [...counts.keys()].sort((a, b) => (a === MT_OK ? -1 : b === MT_OK ? 1 : a < b ? -1 : a > b ? 1 : 0))
+  return [`targets: ${entries.length}`, ...names.map((name) => `${name} ${counts.get(name)}`)].join(' ｜ ')
+}
+
+/** 汇总行里的短码：只给 `not_found` 起短名，其余原样——短名多了就成了第二种语言。 */
+const mtShortCode = (code) => (code === 'FS_NOT_FOUND' ? 'not_found' : String(code ?? 'error'))
+
+/**
+ * 读一个 target：**唯一的**"一个目标 = 一次读"实现。
+ *
+ * N===1 直调它、N>1 池里调它——同一条代码路径，所以"多目标那条路会不会比单目标多跑一次"
+ * 这个问题在结构上就只有一种答案。
+ *
+ * 顺序（也就是 provider 调用序列）是刻意钉死的：`resolve` → `stat` → `readText` →（可选）`readByteRange`。
+ * 它刻意与 `readEnvelope` 文件分支的 `resolve` → `stat` → 读 同形：
+ * 这样 N===1 的调用**序列**与直接读一个目标逐字相同，红线那条断言才有东西可比。
+ *
+ * @param provider - 四方法契约：`resolve` / `stat` / `readText` / `readByteRange`
+ * @param rawTarget - 调用方给的单个目标（**就是今天那套单目标参数**）
+ * @param index - 在输入数组里的序号（进回执，用于"哪一条没成"）
+ * @param probeBom - 是否用 `readByteRange` 探一次 BOM。理由见 {@link readManyWith}
+ * @returns 逐项回执行（与单目标回执同一套渲染：成功时就是 `readWith` 的原样输出）
+ */
+async function readManyTarget(provider, rawTarget, index, probeBom) {
+  const request = rawTarget === null || typeof rawTarget !== 'object' ? null : rawTarget
+  if (request === null) throw Object.assign(new Error(`targets[${index}] must be an object`), { code: MT_BAD_TARGETS })
+  /**
+   * 目标里的 `file_path` 留**原样**（回执原样回抄调用方给的路径，与单目标同一条纪律）；
+   * `readWith` 要的是 `filePath`，转换只在这一处发生。
+   */
+  const filePath = request.file_path ?? request.filePath ?? request.path
+  if (typeof filePath !== 'string' || filePath === '') {
+    throw Object.assign(new Error(`targets[${index}] needs a file_path string`), { code: MT_BAD_TARGETS })
+  }
+  /**
+   * 行区间 / 分页 / 模式推断：与单目标**同一个** `normalizeReadRequest`。
+   * 旧版只转发 `around/lines/search/since/maxChars`，于是 `offset/limit/context/kind/budget`
+   * 在多目标里被静默丢掉（同一个元素单独读与放进 targets 读会得到两种结果）。
+   * 这里先只判形状；读到内容后再用它做 offset 越界与尾行截断。
+   */
+  const shape = normalizeReadRequest(request)
+  if (shape.ok !== true) {
+    return mtFailure(index, [filePath, filePath], 'READ_BAD_ARGS', shape.error)
+  }
+  /**
+   * `provider.resolve` 的两种返回形状**都认**（`await` 对同步值等价，所以旧提供方一行不用改）：
+   *   · **字符串** —— 旧形状（CLI/MCP 的 `createNodeFsProvider`、绝大多数测试）：它就是显示路径，
+   *     账本键也由它算（`identityKey` 缺席）⇒ 与本参数存在之前**逐字节相同**；
+   *   · **宿主解析结果** `{displayPath, targetKey}` —— DSH 壳的 `ctx.fs.resolve()` 就是这个形状：
+   *     显示路径用 `displayPath`，**身份键**用 `targetKey`。
+   *
+   * 为什么必须认第二种（实测：同一文件同一区间，单目标读发 `h4745015d4840:…`、多目标读发
+   * `he6dd015d4840:…` —— 指纹段相同、**身份标签段不同**）：句柄的身份标签按
+   * `ledgerIdentityKey(filePath, identityKey)` 算，而单目标那条路（`readEnvelope` 前的壳）递的正是
+   * `ctx.fs.resolve()` 的 `targetKey`。多目标若只把路径串当身份，就会对**同一份盘上文件**发出两个
+   * 不同的句柄，后果具体：拿批量读来的句柄去 `aura_basetools_edit` ⇒ `PATCH_HANDLE_IDENTITY_MISMATCH`。
+   *
+   * 身份口径**不新造第三份**：宿主给的 `targetKey` 就是既有那一份（@see ledgerIdentityKey / IDENTITY_KEYS）；
+   * 元素自带的 `identityKey`（与写侧 `editTargetRequests` 同名的那个键）只作为提供方给不出事实时的回落。
+   */
+  const hostTarget = await provider.resolve(filePath)
+  const target =
+    hostTarget !== null && typeof hostTarget === 'object' ? (hostTarget.displayPath ?? filePath) : hostTarget
+  const identityKey =
+    hostTarget !== null && typeof hostTarget === 'object' && typeof hostTarget.targetKey === 'string' && hostTarget.targetKey.length > 0
+      ? hostTarget.targetKey
+      : request.identityKey
+  let info
+  try {
+    info = await provider.stat(target)
+  } catch (error) {
+    return mtFailure(index, [target, filePath], error?.code ?? 'IO_ERROR', String(error?.message ?? error))
+  }
+  /**
+   * `stat` 的两套约定都要认：
+   *   · `createNodeFsProvider` 与 DSH 的 `probe()` 给 `{type: 'file'|'directory'|'other', …}`；
+   *   · 有些提供方给 `undefined` 表示不存在。
+   * 存在但拿不到类型时**按文件试读**（读不动自有 provider 抛错兜底），
+   * 不在这里替提供方发明第三种类型判定。
+   */
+  if (info === undefined || info === null) {
+    return mtFailure(index, [target, filePath], 'FS_NOT_FOUND', `cannot read "${filePath}": not found`)
+  }
+  if (info.type === 'directory') {
+    // 目录级地图（T26）是**单目标**的既有能力，多目标这一波不扩它：只给可执行的拒绝。
+    return mtFailure(index, [target, filePath], 'MT_TARGET_IS_DIRECTORY', `"${filePath}" is a directory: read it on its own (a repo map is not a window)`, `read "${filePath}" by itself for a repo map`)
+  }
+  /**
+   * `readText` 可能同步抛（非 UTF-8 / 二进制 / 竞争删除）——`await` 包在 try 里，
+   * 于是同步抛与 reject 走同一条路。逐项拒绝，整批不受影响（契约 §1.3）。
+   */
+  let source
+  try {
+    source = await provider.readText(target)
+  } catch (error) {
+    return mtFailure(index, [target, filePath], error?.code ?? 'IO_ERROR', String(error?.message ?? error))
+  }
+  /**
+   * BOM：`provider.readText` 把第一个 BOM 吃掉了（默认 `ignoreBOM: false`），
+   * 而 BOM **进内容指纹**、也进句柄（契约 §4 的令牌语义），因此它必须由**字节**得出。
+   *
+   * 这一笔是"多目标路径上多出来的一次读"，代价与理由都摆在这里：只读 BOM 那几个字节，
+   * 且只在提供方有 `readByteRange` 时；`probeBom: false` 可整体关掉（那时按"无 BOM"读）。
+   * **单目标那条路一点没碰**：它仍旧走 `readEnvelope` 的 `readFileBytes`（一次 fs 读，BOM 一次拿到）。
+   */
+  let byteOrderMark = false
+  if (probeBom && typeof provider.readByteRange === 'function') {
+    try {
+      const head = await provider.readByteRange(target, { offset: 0, length: BYTE_ORDER_MARK_BYTES.length })
+      byteOrderMark = startsWithByteOrderMark(head)
+    } catch {
+      // 读头失败不回滚整条读：BOM 是**元数据**，缺它就按没有处理（下面那次 readText 已经成功了）。
+      byteOrderMark = false
+    }
+  }
+  const requestShape = normalizeReadRequest(request, source.split(/\r?\n/).length)
+  if (requestShape.ok !== true) {
+    return mtFailure(index, [target, filePath], 'READ_BAD_ARGS', requestShape.error)
+  }
+  const env = readWith(source, {
+    mode: requestShape.mode,
+    around: request.around,
+    lines: asLinePair(requestShape.lines),
+    search: request.search,
+    since: request.since,
+    // 读侧两层叫法不同：宿主面 `max_chars`，引擎面 `maxChars`（与 `readEnvelope` 同源）。
+    maxChars: request.max_chars ?? request.maxChars,
+    ...(request.context === undefined ? {} : { context: request.context }),
+    ...(request.kind === undefined ? {} : { kind: request.kind }),
+    ...(request.budget === undefined ? {} : { budget: request.budget }),
+    byteOrderMark,
+    /**
+     * `filePath` 给的是 **provider.resolve 之后的那个串**，不是调用方原样给的路径。
+     *
+     * 为什么必须是它（这条是实测出来的，不是风格）：`readWith` 用它算**账本键**，
+     * 而账本键进句柄的身份标签。单目标那条路（`readEnvelope`）给的正是 `provider.resolve(file)`，
+     * 于是这里若给原样的 `file_path`，同一个文件在两条路上会得到**两个不同的句柄**
+     * ——`multi-read-test` 段A 的"逐项回执与单独跑一次逐字节相同"当场变红，
+     * 而且更坏的是：拿批内句柄去 `aura_basetools_edit` 会查不到那一条观测。
+     *
+     * 回执里显示哪一份由 `file_path` 字段负责（下面那条）——两件事分开，各归各的字段。
+     */
+    filePath: target,
+    /**
+     * 身份键与 `filePath` **分开递**，与单目标那条路（`readEnvelope` 的 `identityKey: target.targetKey`）
+     * 同源。缺席时（提供方只给字符串、元素也没带）走旧行为：账本键 = `filePath`。
+     */
+    ...(typeof identityKey === 'string' && identityKey.length > 0 ? { identityKey } : {}),
+  })
+  /**
+   * 成了 ⇒ **这一条就是单目标回执本身**（同一个对象引用，不是另渲染一遍）。
+   * 另渲染一遍是这一单最容易犯的错：两份渲染一开始一样，改一处就只改一份。
+   */
+  return {
+    index,
+    file_path: filePath,
+    ok: true,
+    outcome: MT_OK,
+    mode: env.mode,
+    envelope: env,
+  }
+}
+
+/**
+ * 一条没成的逐项回执。
+ *
+ * 形状刻意与成了的那条**逐字段对齐**（`index` / `file_path` / `ok` / `outcome` 都在），
+ * 只有 `envelope` 换成 `code` + `message`：调用方按同一个字段集读两种结果，不用分叉。
+ * `next` 只在能给**可执行**的下一步时才出现（与单目标的 `next` 同一条纪律：不给空话）。
+ */
+function mtFailure(index, [target, displayPath], code, message, next) {
+  return {
+    index,
+    file_path: displayPath,
+    ok: false,
+    outcome: 'failed',
+    ...(code === 'FS_NOT_FOUND' ? { target } : {}),
+    code,
+    message,
+    ...(next === undefined ? {} : { next }),
+  }
+}
+
+/**
+ * **一次调用读多个目标**（契约 §2.1 的读侧形状）。
+ *
+ * ## 形状
+ *
+ * 两种调用方式，**互斥**：
+ *   · `readManyWith(provider, [{file_path, mode, …}, …], opts)` —— 多目标（推荐，显式）；
+ *   · `readManyWith(provider, {file_path, mode, …}, opts)` —— 单个目标，与上面**同一条代码路径**。
+ * 单个对象被归一成"长度 1 的数组"，所以不存在第二条实现。
+ *
+ * ## N===1 ⇒ 直调（结构性保证，不是"我们测了没变慢"）
+ *
+ * 长度 1 时**不建池、不建队列、不包一层**：直接 `await` 那个唯一的目标，
+ * 一行 `if` 就出函数。因此"N=1 时多跑一次 / 多包一层 / 多一个字段"这件事
+ * 在本入口里没有可发生的语法位置——它是控制流性质，不是性能观测。
+ * 测试（`multi-read-test.mjs` 段C）用计数 provider 把这条钉成"调用序列逐项相同"。
+ *
+ * ## N>1 ⇒ 有界并发池，只并发 I/O 与纯计算（契约 §4）
+ *
+ * 池子就是 `min(MT_POOL, N)` 个**常驻 worker** 各拉一条队列：`maxInFlight` 因此由结构决定，
+ * 不用"数一数同时在飞几个"去经验地保证。
+ * **结果按输入顺序装配**：`results[i] = …` 按下标写，完成顺序只影响"谁先写"、不影响任何一项的位置。
+ * 这一条是硬要求（契约 §1.4）——并发完成顺序一旦泄漏到输出，同一份输入两次调用可能给两种排列。
+ *
+ * ## 失败语义（契约 §1.3）
+ *
+ * 逐项失败（不存在 / 找不到 / 需选择 / 不是文本 / 目录）一律**走结果通道**：那一条带
+ * `ok:false` + `code` + `message`（能给下一步时还有 `next`），**其余目标照常**。
+ * 只有"参数形状没成形"才抛错：
+ *   · `targets` 不是数组/不是对象 ⇒ `MT_BAD_TARGETS`；
+ *   · 目标数超过 {@link MT_MAX_TARGETS} ⇒ `MT_TOO_MANY_TARGETS`，**message 里报出实得数**；
+ *   · `targets` 为空 ⇒ `MT_BAD_TARGETS`（空批不是"成功读了 0 个"，那是静默换语义）。
+ * 抛错**不会**吞掉已经读成的那些：抛发生在**读之前**（形状校验是第一件事），所以没有"半批已读"这种状态。
+ *
+ * ## 回执
+ *
+ * 逐项（同一套渲染）+ **一行汇总**（`targets: N ｜ ok K ｜ not_found M`）。
+ * 汇总只在 `summary` 字段里、不进任何 `envelope.text`：正文是宿主剪枝器量的东西（契约 §5），
+ * 往里塞一行就是让每一份多目标回执的正文回涨。
+ *
+ * @param provider - 四方法契约：`resolve` / `stat` / `readText` / `readByteRange`
+ * @param targets - 目标数组（每个元素就是今天那套单目标参数），或**单个**这样的对象
+ * @param {number} [options.pool] - 覆盖池大小（默认 {@link MT_POOL}）。测试要它把"有界"钉成结构观测
+ * @param {boolean} [options.probeBom] - 是否探 BOM，默认 `true`
+ * @param {(event: {index: number, maxInFlight: number}) => void} [options.trace] - 纯观测钩子（测试用）
+ * @returns 逐项 + 汇总的整批回执（**不是** Promise 之外的任何包装）
+ * @throws {Error} `code` ∈ {`MT_BAD_TARGETS`, `MT_TOO_MANY_TARGETS`}
+ */
+export async function readManyWith(provider, targets, options = {}) {
+  if (provider === null || typeof provider !== 'object' || typeof provider.readText !== 'function') {
+    throw Object.assign(new Error('readManyWith needs a provider with resolve/stat/readText'), { code: MT_BAD_TARGETS })
+  }
+  /** 单个对象 = 长度 1 的数组：**归一只有这一处**，下面再没有"单个/多个"的分叉。 */
+  const list = Array.isArray(targets) ? targets : targets !== null && typeof targets === 'object' ? [targets] : null
+  if (list === null) {
+    throw Object.assign(new Error(`targets must be an array or a single target object, got ${targets === null ? 'null' : typeof targets}`), { code: MT_BAD_TARGETS })
+  }
+  if (list.length === 0) {
+    throw Object.assign(new Error('targets must not be empty (an empty batch is not "read 0 files")'), { code: MT_BAD_TARGETS })
+  }
+  if (list.length > MT_MAX_TARGETS) {
+    throw Object.assign(new Error(`targets has ${list.length} entries, but the limit is ${MT_MAX_TARGETS} — split the call`), {
+      code: MT_TOO_MANY_TARGETS,
+      got: list.length,
+      max: MT_MAX_TARGETS,
+    })
+  }
+  const probeBom = options.probeBom !== false
+  const started = Date.now()
+  const entries = new Array(list.length)
+  if (list.length === 1) {
+    // ── N===1：直调。没有池、没有队列、没有 trace、没有包装 —— 这里少写一行代码就是保证。 ──
+    entries[0] = await readManyTarget(provider, list[0], 0, probeBom)
+  } else {
+    await mtPool(list, options.pool ?? MT_POOL, options.trace, async (item, index) => {
+      entries[index] = await readManyTarget(provider, item, index, probeBom)
+    })
+  }
+  const counts = { ok: 0, failed: 0 }
+  for (const entry of entries) {
+    if (entry.ok === true) counts.ok += 1
+    else counts.failed += 1
+  }
+  return {
+    ok: counts.failed === 0,
+    targets: entries.length,
+    counts,
+    summary: mtSummaryLine(entries),
+    entries,
+    elapsedMs: Date.now() - started,
+  }
+}
+
+/**
+ * 有界并发池：`min(pool, N)` 个常驻 worker 各拉一条队列。
+ *
+ * 为什么是"常驻 worker + 共享游标"而不是"分批 `Promise.all`"：分批发的话，
+ * 一格慢就整批等（尾部空转），而"同时在飞几个"这件事会随每批的完成快慢漂移。
+ * 常驻 worker 下**在飞数恒 ≤ pool**——这是结构，不靠经验观测。
+ *
+ * 为什么 worker 自己 `await`：`maxInFlight` 只在 worker 真正进入/离开时增减，
+ * 而它进出之间**只**做一件事：跑 `run`（I/O 与纯计算）。`trace` 因此能给出
+ * "同时在飞的最大值"这个**确定性**读数（慢 provider 下它必然等于 pool），
+ * 而不是一次墙钟计时（机器上有并行单元，计时不作判据）。
+ */
+async function mtPool(items, pool, trace, run) {
+  const width = Math.max(1, Math.min(Math.trunc(pool) || MT_POOL, items.length))
+  let next = 0
+  let inFlight = 0
+  let maxInFlight = 0
+  const worker = async () => {
+    while (true) {
+      const index = next
+      next += 1
+      if (index >= items.length) return
+      inFlight += 1
+      if (inFlight > maxInFlight) maxInFlight = inFlight
+      if (typeof trace === 'function') trace({ index, maxInFlight })
+      try {
+        await run(items[index], index)
+      } finally {
+        inFlight -= 1
+      }
+    }
+  }
+  const workers = []
+  for (let w = 0; w < width; w += 1) workers.push(worker())
+  await Promise.all(workers)
+}
+
+/**
+ * 读一个文件，按模式返回**带预算与省略说明**的结构化结果。
+ *
+ * 多目标（多文件 / 多区间一次调用）走 {@link readManyWith}：它**逐个**调用本函数，
+ * 因此"一个目标怎么读"只有一处实现。本函数自身一行未改——单目标零回归由红线套件钉住。
+ *
  * @param {string} source - 文件全文
  * @param {object} request
  * @param {'map'|'digest'|'around'|'lines'|'search'|'changed'|'auto'} [request.mode] - 默认 auto
@@ -2143,7 +2184,7 @@ export function readWith(source, request = {}) {
     // 实测后果：changed 在真实会话里只被用过 1 次、且那一次没带 since——工具递出了钥匙，引擎不接。
     else if (request.since !== undefined || request.token !== undefined || request.previous !== undefined) mode = 'changed'
     else {
-      auto = suggestMode(source, request.filePath ?? null)
+      auto = suggestMode(source, request.filePath ?? null, request.budget)
       mode = auto.mode
     }
   }
@@ -2152,14 +2193,14 @@ export function readWith(source, request = {}) {
   }
   const lines = source.split(/\r?\n/)
   const total = lines.length
-  const filePath = request.filePath ?? null
-  const lang = filePath === null ? null : langOf(filePath)
-  /**
-   * 账本的**身份键**：算一次，下面每一处账本操作都用它（{@link ledgerIdentityKey} 是
-   * 全引擎唯一那道归一）。`filePath` 从这一行往下只管显示与语言判定。
-   */
-  const ledgerKey = ledgerIdentityKey(filePath, request.identityKey)
-  /**
+  const filePath = request.filePath ?? null
+  const lang = filePath === null ? null : langOf(filePath)
+  /**
+   * 账本的**身份键**：算一次，下面每一处账本操作都用它（{@link ledgerIdentityKey} 是
+   * 全引擎唯一那道归一）。`filePath` 从这一行往下只管显示与语言判定。
+   */
+  const ledgerKey = ledgerIdentityKey(filePath, request.identityKey)
+  /**
    * 版本令牌与"这份内容带不带 BOM"
    * （它们原先在 `render` 里算——每轮重算一遍纯属白做工，而下面还要用它们做一次增量判定。）
    */
@@ -2170,7 +2211,7 @@ export function readWith(source, request = {}) {
    * 增量层的判定也放在循环外：它只看账本、缓存与内容，不看预算。
    * 放进 `render` 会让收敛的每一轮把差分重做一遍（大文件上那就是百毫秒级 × 8 轮）。
    */
-  const incremental = mode === 'full' ? planIncremental(request, lines, version) : { kind: 'skip' }
+  const incremental = mode === 'full' && request.probe !== true ? planIncremental(request, lines, version) : { kind: 'skip' }
   /**
    * 顺扫判定同样放在循环外：它只看请求与会话账本（不看预算），而且
    * 「这一次是不是同一段顺扫的下一段」不应该随收敛轮次变。
@@ -2189,7 +2230,7 @@ export function readWith(source, request = {}) {
      *
      * 这个字段曾经被 `mode === 'changed' || lang === null` 这个条件剥掉，后果是一整类
      * 调用被框架直接拒绝（schema 声明它必填）：
-     *   tool "aura_read" returned invalid output: missing required property "value.version"
+     *   tool "aura_basetools_read" returned invalid output: missing required property "value.version"
      * 实测命中的组合：`around`／`lines`／`search` 三种模式（它们经 windowEnvelope 再铺 base，
      * 而 base 里已经被剥掉了），以及**所有未索引扩展名**上的内容读取——
      * `.json`／`.yml`／`.md` 一个都读不了。
@@ -2204,12 +2245,12 @@ export function readWith(source, request = {}) {
      * 版本令牌与**观测记录**：每一模式都要。
      *
      * `changed` 自己也会记一次（同一键重复记无害），而其余模式此前不记——
-     * 实测后果：普通 `aura_read` 之后拿那个令牌去问 `changed`，得到的是
+     * 实测后果：普通 `aura_basetools_read` 之后拿那个令牌去问 `changed`，得到的是
      * “that version is no longer cached — cannot diff”，把“上次观测”当判据的路直接断掉。
      */
     delivery = null
     // 账本键换成**身份键**（有的话）：`filePath` 只用于显示与语言判定
-    if (filePath !== null) rememberRead(ledgerKey, version, source, bom, request.identityKey)
+    if (filePath !== null && request.probe !== true) rememberRead(ledgerKey, version, source, bom, request.identityKey)
     const base = {
       ok: true,
       mode,
@@ -2226,25 +2267,25 @@ export function readWith(source, request = {}) {
     /**
      * 句柄上下文：`lines` / `search` / `full` 用它铸柄，其余模式为 null。
      *
-     * 为什么按模式逐个点名、而不是"凡有窗口就发"：契约 §4 的表把发法逐模式钉死了。
-     * `around` / `changed` 不在表里，给它们附加柄就是**超出契约的发法**——
-     * 而回执体积那条不变式（§2.5）只管得住被量过的模式。
-     *
-     * `search` 必须在这一行里点名：这个函数**按模式逐个分支**，少一个名字就是静默不发
-     * （而"没发句柄"与"发了空句柄"在回执上长得一样，只有掐住字段才看得出来）。
-     *
-     * **`full` 不在名单里（本单的裁决，理由是可复核的）**：
-     * 契约 §4 给 `full` 写的是"发一条，仅在调用方显式要时"——**条件句、非强制**（同表的
-     * `map`/`digest` 写的是硬"不发"）。而代价是实测的：`full` 的句柄带**身份标签**，
-     * 于是**两条不同路径上的同一份内容**不再给出逐字节相同的回执。
-     * 既有套件 `incremental-read-test` 的 K1（"首次读的回执不受本层影响（两条新路径逐字节相同）"）
-     * 正是拿这件事当判据的，实测**只因这一个字段变红**（把 `full` 从这行名单里去掉 ⇒ 45/45 绿）。
-     * 而 §7 对 HD1 的硬验收要求那三个既有套件判据**逐字不变**，
-     * 因此这里选择**不发 `full` 句柄**：一个"把整个文件给我"的读本来就不是编辑地址
-     * （它没有相对定位可依附），而"同一份内容两份回执逐字节相同"是既有契约。
-     * `lines`（区间读）与 `search`（命中行）不受影响——那才是编辑要用的两种读法。
-     */
-    const handleContext =
+     * 为什么按模式逐个点名、而不是"凡有窗口就发"：契约 §4 的表把发法逐模式钉死了。
+     * `around` / `changed` 不在表里，给它们附加柄就是**超出契约的发法**——
+     * 而回执体积那条不变式（§2.5）只管得住被量过的模式。
+     *
+     * `search` 必须在这一行里点名：这个函数**按模式逐个分支**，少一个名字就是静默不发
+     * （而"没发句柄"与"发了空句柄"在回执上长得一样，只有掐住字段才看得出来）。
+     *
+     * **`full` 不在名单里（本单的裁决，理由是可复核的）**：
+     * 契约 §4 给 `full` 写的是"发一条，仅在调用方显式要时"——**条件句、非强制**（同表的
+     * `map`/`digest` 写的是硬"不发"）。而代价是实测的：`full` 的句柄带**身份标签**，
+     * 于是**两条不同路径上的同一份内容**不再给出逐字节相同的回执。
+     * 既有套件 `incremental-read-test` 的 K1（"首次读的回执不受本层影响（两条新路径逐字节相同）"）
+     * 正是拿这件事当判据的，实测**只因这一个字段变红**（把 `full` 从这行名单里去掉 ⇒ 45/45 绿）。
+     * 而 §7 对 HD1 的硬验收要求那三个既有套件判据**逐字不变**，
+     * 因此这里选择**不发 `full` 句柄**：一个"把整个文件给我"的读本来就不是编辑地址
+     * （它没有相对定位可依附），而"同一份内容两份回执逐字节相同"是既有契约。
+     * `lines`（区间读）与 `search`（命中行）不受影响——那才是编辑要用的两种读法。
+     */
+    const handleContext =
       mode === 'lines' || mode === 'search' ? { ledgerKey, byteOrderMark: bom } : null
     if (mode === 'full') {
       // 整文件内容请求：先让增量层说话（差量 / no change / 全量＋为什么），
@@ -2312,7 +2353,28 @@ export function readWith(source, request = {}) {
     Number.isInteger(request.maxChars) && request.maxChars > 0
       ? Math.min(request.maxChars, contentCeiling)
       : contentCeiling
-  let result = render(budget)
+  /**
+   * 0.9.8：确定性的回执 metrics。`mode` / `totalLines` / `text` / `symbols` 本来就在信封里，
+   * 但调用方要自己数字符、自己判断有没有裁剪；这里统一附一份，三面同形。
+   * 不加 `elapsedMs`（墙钟有噪声），只放**可由内容复算**的事实。
+   *
+   * **必须进收敛循环**：metrics 本身也占字节；事后贴上去会让 `sizeBy(result)` 少算几十字节，
+   * 实测把 8192 档顶到 8250。所以每次 render 后立刻附 metrics，再量尺寸。
+   */
+  const withMetrics = (env) => env.ok === false ? env : ({
+    ...env,
+    metrics: {
+      mode: env.mode,
+      lines: env.totalLines,
+      chars: (env.text ?? '').length,
+      ...(env.symbols === undefined ? {} : { symbols: env.symbols }),
+      // `truncated` = **被预算裁过**，不是“有任何 omitted”。map 的 “nested locals omitted”
+      // 是刻意不列（不是内容被裁），旧判据会把它误报成 truncated。
+      truncated: typeof env.omitted === 'string' && /content budget|minimum envelope|host result limit|withheld|truncated/i.test(env.omitted),
+    },
+  })
+  const renderMeasured = (chars) => withMetrics(render(chars))
+  let result = renderMeasured(budget)
   /** 每轮额外多收的余量：只按"超出多少"收窄会恰好贴着上限，信封随内容缩短而重算时容易再涨回去。 */
   const SHRINK_MARGIN = 64
   /** 轮数上限：收敛是单调的，几轮就够；给足是为了让下面那道硬断言根本不触发。 */
@@ -2323,7 +2385,7 @@ export function readWith(source, request = {}) {
     const next = Math.max(0, budget - (size - ceiling) - SHRINK_MARGIN)
     if (next >= budget) break // 收不动了，交给下面那道硬断言
     budget = next
-    result = render(budget)
+    result = renderMeasured(budget)
   }
   /**
    * 收不到上限时，缩到最小再试一次。
@@ -2340,19 +2402,28 @@ export function readWith(source, request = {}) {
    */
   const finalSize = sizeBy(result)
   if (finalSize > ceiling) {
-    const minimal = render(0)
+    const minimal = renderMeasured(0)
     const minimalSize = sizeBy(minimal)
     // 记账必须发生在**确定要发哪一份之后**：账本决定下一次还能不能做差量。
-    recordDelivery(ledgerKey, minimal, version, total, bom, delivery)
-    recordScan(mode, ledgerKey, version, minimal, total)
+    // probe（`suggestMode` 的选型探针）只量渲染长度，不改账本、也不触发增量。
+    if (request.probe !== true) {
+      recordDelivery(ledgerKey, minimal, version, total, bom, delivery)
+      recordScan(mode, ledgerKey, version, minimal, total)
+    }
     if (minimalSize <= ceiling) return minimal
     return {
       ...minimal,
+      metrics: {
+        ...minimal.metrics,
+        truncated: true,
+      },
       omitted: `${minimal.omitted === undefined ? '' : `${minimal.omitted}; `}output is already at its minimum envelope (${minimalSize} chars) and still exceeds the host result limit (${ceiling}); the limit is below what a read result can physically be`,
     }
   }
-  recordDelivery(ledgerKey, result, version, total, bom, delivery)
-  recordScan(mode, ledgerKey, version, result, total)
+  if (request.probe !== true) {
+    recordDelivery(ledgerKey, result, version, total, bom, delivery)
+    recordScan(mode, ledgerKey, version, result, total)
+  }
   return result
 }
 
@@ -2682,20 +2753,20 @@ function renderSearch(base, lines, request, symbolsIndex = null, handleContext =
   const limit = Math.min(request.limit ?? 40, HANDLE_MAX_PER_RECEIPT)
   const shown = hits.slice(0, limit)
   /**
-   * 每条命中一个句柄（契约 §4）。两个落点**都要**：
-   *   · `handles: [{line, handle}]`（结构化，与 `relocatable` 同形）——宿主 / UI / schema 面用；
-   *   · **每个命中行的行尾**（`  <句柄>`）——模型面用。
-   *
-   * 为什么非要有第二个落点（HD3 集成时实测出来的）：壳层只把 `value.text` 交给模型
-   * （`aura-read/index.js` 的 `render: (_args, value) => [{type:'text', text: value.text}]`），
-   * 框架再把 `result.content` 装进 tool 消息——**结构化字段一个都到不了模型**。
-   * 只发结构化字段 = 句柄存在但没人看得见，而本波的全部价值就是让模型手里有一个
-   * 工具发的、逐字节正确的区间地址。
-   *
-   * 行首的 `N: ` 前缀一个字不许动：既有解析器（`^\d+: `）靠它取行号，动了就会把
-   * "格式演进"变成"行为退化"。所以句柄一律接在**行尾**。
-   *
-   * 区间取**单行**（`n-n`）：`search` 的命中就是一行，句柄指多行反而让"改哪里"变模糊。
+   * 每条命中一个句柄（契约 §4）。两个落点**都要**：
+   *   · `handles: [{line, handle}]`（结构化，与 `relocatable` 同形）——宿主 / UI / schema 面用；
+   *   · **每个命中行的行尾**（`  <句柄>`）——模型面用。
+   *
+   * 为什么非要有第二个落点（HD3 集成时实测出来的）：壳层只把 `value.text` 交给模型
+   * （`aura-read/index.js` 的 `render: (_args, value) => [{type:'text', text: value.text}]`），
+   * 框架再把 `result.content` 装进 tool 消息——**结构化字段一个都到不了模型**。
+   * 只发结构化字段 = 句柄存在但没人看得见，而本波的全部价值就是让模型手里有一个
+   * 工具发的、逐字节正确的区间地址。
+   *
+   * 行首的 `N: ` 前缀一个字不许动：既有解析器（`^\d+: `）靠它取行号，动了就会把
+   * "格式演进"变成"行为退化"。所以句柄一律接在**行尾**。
+   *
+   * 区间取**单行**（`n-n`）：`search` 的命中就是一行，句柄指多行反而让"改哪里"变模糊。
    */
   const handles = (handleContext === null ? [] : shown)
     .map((n) => ({ line: n, handle: handleFor(handleContext.ledgerKey, lines, handleContext.byteOrderMark, n, n) }))
@@ -2709,14 +2780,14 @@ function renderSearch(base, lines, request, symbolsIndex = null, handleContext =
    * 不披露就等于告诉模型“这一行就到那里”。
    * `windowEnvelope` 早就有这套机制（`truncated` + `omitted`），这里只是把同一件事补上。
    */
-  /** 行号 → 句柄。末尾没柄的行拿不到（不会指到没渲染的文本）。 */
-  const handleByLine = new Map(handles.map((h) => [h.line, h.handle]))
-  const clipped = []
-  const rows = shown.map((n) => {
-    const raw = lines[n - 1].trim()
-    // 句柄接在**行尾**：行首的 `N: ` 前缀是既有解析器（`^\d+: `）的锚点，一个字符都不能动。
-    const handle = handleByLine.get(n) ?? null
-    if (raw.length <= MATCH_LINE_CHARS) return withHandleOnLine(`${n}: ${raw}`, handle)
+  /** 行号 → 句柄。末尾没柄的行拿不到（不会指到没渲染的文本）。 */
+  const handleByLine = new Map(handles.map((h) => [h.line, h.handle]))
+  const clipped = []
+  const rows = shown.map((n) => {
+    const raw = lines[n - 1].trim()
+    // 句柄接在**行尾**：行首的 `N: ` 前缀是既有解析器（`^\d+: `）的锚点，一个字符都不能动。
+    const handle = handleByLine.get(n) ?? null
+    if (raw.length <= MATCH_LINE_CHARS) return withHandleOnLine(`${n}: ${raw}`, handle)
     const cut = raw.length - MATCH_LINE_CHARS
     // 形状与 `windowEnvelope` 的 `truncated` **完全一致**（{line, shown, omittedChars}）：
     // 第一版这里给的是 `{line, omittedChars}` 的数组，而 `windowEnvelope` 给的是对象——
@@ -2852,59 +2923,59 @@ function windowEnvelope(
    * （见 {@link SCAN} / {@link planScan}）。它只往下、不越过文件末尾、永远包含请求区间，
    * 因此 `lines` 的既有语义（请求的那几行一定在里面）没有被改。
    */
-  const limit = scan !== null && scan.extend === true ? Math.max(to, total) : to
-  const rows = []
-  let chars = 0
-  let lostFrom = null
-  let truncated = null
-  /**
-   * 句柄要落在**窗口的头行**上（契约 §4），而头行是哪一行由预算决定——
-   * 所以预留不能拍死：先按 `from` 算一份，等 `deliveredTo` 定下来再换真的那一份。
-   *
-   * 预留必须**在循环里**算：句柄是行的一部分，把它排除在预算外，
-   * 就会出现"行放下了、句柄被拆掉"的静默半答案。
-   */
-  const reserve = handleContext === null ? 0 : handleInlineChars(from, from)
-  for (let n = from; n <= limit; n += 1) {
-    const raw = lines[n - 1] ?? ''
-    const rendered = `${n}: ${raw}`
-    const cost = rendered.length + 1 + (rows.length === 0 ? reserve : 0)
-    if (chars + cost <= base.contentBudget) {
-      chars += cost
-      rows.push(rendered)
-      continue
-    }
-    // 放不下。若这是窗口的第一行，就不能空手而归——给一段并标注截断。
-    if (rows.length === 0) {
-      // `suffix` 是行号之外还要留的说明空间：截断标记本身也要算进预算，
-      // 否则"标注"会把内容顶出预算，重演同一个问题。
-      const suffix = ' ⋯ [truncated]'
-      const budget = base.contentBudget - reserve
-      const take = Math.max(0, budget - suffix.length - `${n}: `.length)
-      if (take > 0) {
-        rows.push(`${n}: ${raw.slice(0, take)}${suffix}`)
-        truncated = { line: n, shown: take, omittedChars: raw.length - take }
-      }
-    }
-    lostFrom = n
-    break
+  const limit = scan !== null && scan.extend === true ? Math.max(to, total) : to
+  const rows = []
+  let chars = 0
+  let lostFrom = null
+  let truncated = null
+  /**
+   * 句柄要落在**窗口的头行**上（契约 §4），而头行是哪一行由预算决定——
+   * 所以预留不能拍死：先按 `from` 算一份，等 `deliveredTo` 定下来再换真的那一份。
+   *
+   * 预留必须**在循环里**算：句柄是行的一部分，把它排除在预算外，
+   * 就会出现"行放下了、句柄被拆掉"的静默半答案。
+   */
+  const reserve = handleContext === null ? 0 : handleInlineChars(from, from)
+  for (let n = from; n <= limit; n += 1) {
+    const raw = lines[n - 1] ?? ''
+    const rendered = `${n}: ${raw}`
+    const cost = rendered.length + 1 + (rows.length === 0 ? reserve : 0)
+    if (chars + cost <= base.contentBudget) {
+      chars += cost
+      rows.push(rendered)
+      continue
+    }
+    // 放不下。若这是窗口的第一行，就不能空手而归——给一段并标注截断。
+    if (rows.length === 0) {
+      // `suffix` 是行号之外还要留的说明空间：截断标记本身也要算进预算，
+      // 否则"标注"会把内容顶出预算，重演同一个问题。
+      const suffix = ' ⋯ [truncated]'
+      const budget = base.contentBudget - reserve
+      const take = Math.max(0, budget - suffix.length - `${n}: `.length)
+      if (take > 0) {
+        rows.push(`${n}: ${raw.slice(0, take)}${suffix}`)
+        truncated = { line: n, shown: take, omittedChars: raw.length - take }
+      }
+    }
+    lostFrom = n
+    break
   }
   const kept = rows.length
   /** 实际交付到的最后一行；“已经读到哪”这句话的唯一来源。 */
   const deliveredTo = kept === 0 ? from - 1 : from + kept - 1
-  const budgetCut = lostFrom !== null && lostFrom <= limit
-  /**
-   * 头行现在是确定的，句柄就在这里真的接上去（第二轮）。
-   *
-   * 为什么不在循环里直接接：头行上那个句柄的**结束行**就是 `deliveredTo`，而它要到
-   * 循环跑完才知道（预算可能砍在中间、顺扫可能把窗口拉长）。用 `from` 硬编出来的是
-   * 一个**指错区间**的地址——那比不发还坏。
-   */
-  const headHandle =
-    handleContext === null || kept === 0
-      ? null
-      : handleFor(handleContext.ledgerKey, lines, handleContext.byteOrderMark, from, deliveredTo)
-  const rowsWithHandle = headHandle === null ? rows : [withHandleOnLine(rows[0], headHandle), ...rows.slice(1)]
+  const budgetCut = lostFrom !== null && lostFrom <= limit
+  /**
+   * 头行现在是确定的，句柄就在这里真的接上去（第二轮）。
+   *
+   * 为什么不在循环里直接接：头行上那个句柄的**结束行**就是 `deliveredTo`，而它要到
+   * 循环跑完才知道（预算可能砍在中间、顺扫可能把窗口拉长）。用 `from` 硬编出来的是
+   * 一个**指错区间**的地址——那比不发还坏。
+   */
+  const headHandle =
+    handleContext === null || kept === 0
+      ? null
+      : handleFor(handleContext.ledgerKey, lines, handleContext.byteOrderMark, from, deliveredTo)
+  const rowsWithHandle = headHandle === null ? rows : [withHandleOnLine(rows[0], headHandle), ...rows.slice(1)]
   const out = {
     ...base,
     mode: base.mode,
@@ -2920,11 +2991,11 @@ function windowEnvelope(
     //
     // 覆盖的区间是**实际交付的**那一段（预算截断与顺扫延伸都算进去），而不是请求里那个 N：
     // 调用方拿到柄之后要编辑的是"它手里那段字节"，不是"它当初点名要的那几行"。
-    // 两者在预算截断时会分叉，而分叉后一个指得到、一个指不到——指不到的那个是错的。
-    // 与接在头行上的那一个**是同一个值**（`headHandle` 只算一次）：两处各算一次的话，
-    // 以后任何一处改了口径，结构化字段与模型看到的文本就会静默地对不上。
-    ...(headHandle === null ? {} : { handle: headHandle }),
-    text: rowsWithHandle.join('\n'),
+    // 两者在预算截断时会分叉，而分叉后一个指得到、一个指不到——指不到的那个是错的。
+    // 与接在头行上的那一个**是同一个值**（`headHandle` 只算一次）：两处各算一次的话，
+    // 以后任何一处改了口径，结构化字段与模型看到的文本就会静默地对不上。
+    ...(headHandle === null ? {} : { handle: headHandle }),
+    text: rowsWithHandle.join('\n'),
   }
   const omissions = []
   if (truncated !== null) {