aura-basetools 0.13.3 → 0.15.0

package/lib/ops.mjs

@@ -10,10 +10,11 @@
  * （`flatHunk` 也从这里出去），于是「引擎在哪」这个问题在整棵树里只有一个答案。
  */
 import fs from 'node:fs'
+import { spawnSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { createNodeFsProvider, DEFAULT_MAX_TEXT_BYTES } from './fs-provider.mjs'
 import { withWorkspaceLock } from './workspace-lock.mjs'
-import { createTransaction, listTransactions, undoTransaction } from './transaction-store.mjs'
+import { createTransaction } from './transaction-store.mjs'
 import { createDiskStore } from './observation-store.mjs'
 
 /**
@@ -91,26 +92,26 @@ export function capabilitiesEnvelope() {
       {
         name: 'aura_basetools_edit',
         addressKinds: [...new Set([...engineArgs.FLAT_ADDRESS_KEYS, 'old', 'context', 'position'])],
-        options: ['replace_all', 'require_observation'],
+        options: ['replace_all', 'require_observation', 'verify'],
         writeSafety: {
-          cli: ['transaction', 'undo', 'workspace-lock', 'stale-region-gate', 'byte-verify'],
-          mcp: ['transaction', 'undo', 'workspace-lock', 'stale-region-gate', 'byte-verify'],
+          cli: ['workspace-lock', 'stale-region-gate', 'byte-verify'],
+          mcp: ['workspace-lock', 'stale-region-gate', 'byte-verify'],
           dsh: ['stale-region-gate', 'byte-verify'],
         },
       },
       {
         name: 'aura_basetools_write',
         operations: ['create', 'overwrite'],
-        options: ['eol'],
+        options: ['eol', 'verify'],
         writeSafety: {
-          cli: ['transaction', 'undo', 'workspace-lock', 'stale-region-gate', 'observation-gate', 'byte-verify'],
-          mcp: ['transaction', 'undo', 'workspace-lock', 'stale-region-gate', 'observation-gate', 'byte-verify'],
-          // DSH 壳没有事务/undo/工作区锁；它经过引擎的区域闸、严格新鲜度与回读校验。
+          cli: ['workspace-lock', 'stale-region-gate', 'observation-gate', 'byte-verify'],
+          mcp: ['workspace-lock', 'stale-region-gate', 'observation-gate', 'byte-verify'],
+          // DSH 壳没有工作区锁；它经过引擎的区域闸、严格新鲜度与回读校验。
           dsh: ['stale-region-gate', 'observation-gate', 'byte-verify'],
         },
       },
     ],
-    commands: ['basetools read', 'basetools edit', 'basetools write', 'basetools undo', 'basetools transactions', 'basetools mcp', 'basetools doctor', 'basetools capabilities', '--version', '--help'],
+    commands: ['basetools read', 'basetools edit', 'basetools write', 'basetools mcp', 'basetools doctor', 'basetools capabilities', '--version', '--help'],
     langs,
     langsCount: langs.length,
     limits: {
@@ -479,6 +480,45 @@ function transactionError(error) {
   }
 }
 
+const VERIFY_OUTPUT_LIMIT = 4000
+const tailText = (value) => {
+  const text = String(value ?? '')
+  return text.length <= VERIFY_OUTPUT_LIMIT ? text : `…${text.slice(-VERIFY_OUTPUT_LIMIT)}`
+}
+
+/**
+ * 写后验证：**只在调用方显式给出命令时**执行。
+ *
+ * 不是自动发现仓库脚本，也不绕过沙箱/权限；命令在 workspace 根下跑，有超时与输出上限。
+ * 失败由外层事务回滚，调用方拿到的是可判定的 `PATCH_VERIFY_FAILED`，不是“写完再说”。
+ */
+function runVerification(command, cwd) {
+  const timeout = Math.min(600000, Math.max(1000, Number(process.env.AURA_VERIFY_TIMEOUT_MS) || 120000))
+  const started = Date.now()
+  const res = spawnSync(command, {
+    cwd,
+    shell: true,
+    encoding: 'utf8',
+    timeout,
+    maxBuffer: 8 * 1024 * 1024,
+    env: process.env,
+    windowsHide: true,
+  })
+  const timedOut = res.error?.code === 'ETIMEDOUT'
+  return {
+    command,
+    cwd,
+    ok: res.status === 0 && res.error === undefined,
+    exitCode: res.status,
+    signal: res.signal ?? null,
+    timedOut,
+    durationMs: Date.now() - started,
+    stdout: tailText(res.stdout),
+    stderr: tailText(res.stderr),
+    ...(res.error === undefined ? {} : { error: String(res.error.message ?? res.error) }),
+  }
+}
+
 /**
  * 写事务外壳：workspace 锁 + 事务日志 + 失败回滚。
  *
@@ -489,17 +529,37 @@ export async function editEnvelope(provider, request) {
   // 事务需要工作区根与真实文件系统；测试/嵌入式 provider 没有 root 时保持原来的引擎行为。
   if (provider.root === undefined) return editEnvelopeInner(provider, request)
   /**
-   * 预演不建事务：否则 `--dry-run --transaction` 会提交一条 0 文件的 committed 事务，
-   * 把 `aura undo`（最近一次 committed）顶掉——用户以为撤销了真实编辑，实际 restored:0。
-   * 预演也不写盘，不需要工作区锁。
+   * 预演不建事务、不写盘，也不需要工作区锁；0.14.0 起事务日志只用于失败回滚。
    */
   if (request.dryRun === true) return editEnvelopeInner(provider, request)
-  const includeTransaction = request.includeTransaction === true
+  const verifyCommand = typeof request.verify === 'string' && request.verify.trim().length > 0 ? request.verify.trim() : null
   try {
     return await withWorkspaceLock(provider.root, async () => {
       const tx = createTransaction(provider.root, 'aura_basetools_edit')
       const env = await editEnvelopeInner(tx.proxy(provider), request)
       if (env.ok) {
+        if (verifyCommand !== null) {
+          const verification = runVerification(verifyCommand, provider.root)
+          if (!verification.ok) {
+            const rollback = await tx.rollback(provider)
+            return {
+              ok: false,
+              error: `edit verification failed (exit ${verification.exitCode ?? 'no-status'}${verification.timedOut ? ', timed out' : ''}): ${verifyCommand}`,
+              code: 'PATCH_VERIFY_FAILED',
+              verification,
+              rollback,
+            }
+          }
+          try {
+            tx.commit()
+          } catch (error) {
+            const rollback = await tx.rollback(provider)
+            error.transaction = tx.summary()
+            error.rollback = rollback
+            throw error
+          }
+          return { ...env, verification }
+        }
         try {
           tx.commit()
         } catch (error) {
@@ -508,10 +568,10 @@ export async function editEnvelope(provider, request) {
           error.rollback = rollback
           throw error
         }
-        return includeTransaction ? { ...env, result: { ...env.result, transaction: tx.summary() } } : env
+        return env
       }
-      const rollback = await tx.rollback(provider)
-      return includeTransaction ? { ...env, transaction: tx.summary(), rollback } : env
+      await tx.rollback(provider)
+      return env
     })
   } catch (error) {
     return transactionError(error)
@@ -523,13 +583,37 @@ export async function editManyEnvelope(provider, request) {
   if (provider.root === undefined) return editManyEnvelopeInner(provider, request)
   // 与单目标同一条：预演不建事务、不写盘，不能顶掉真正的最近 committed 事务。
   if (request.dryRun === true) return editManyEnvelopeInner(provider, request)
-  const includeTransaction = request.includeTransaction === true
+  const verifyCommand = typeof request.verify === 'string' && request.verify.trim().length > 0 ? request.verify.trim() : null
   try {
     return await withWorkspaceLock(provider.root, async () => {
       const tx = createTransaction(provider.root, 'aura_basetools_edit')
       try {
         const batch = await editManyEnvelopeInner(tx.proxy(provider), request)
         if (batch.ok) {
+          if (verifyCommand !== null) {
+            const verification = runVerification(verifyCommand, provider.root)
+            if (!verification.ok) {
+              const rollback = await tx.rollback(provider)
+              const finalBatch = writePath.rebuildAfterRollback(batch, rollback)
+              return {
+                ...finalBatch,
+                ok: false,
+                code: 'PATCH_VERIFY_FAILED',
+                error: `edit verification failed (exit ${verification.exitCode ?? 'no-status'}${verification.timedOut ? ', timed out' : ''}): ${verifyCommand}`,
+                verification,
+                rollback,
+              }
+            }
+            try {
+              tx.commit()
+            } catch (error) {
+              const rollback = await tx.rollback(provider)
+              error.transaction = tx.summary()
+              error.rollback = rollback
+              throw error
+            }
+            return { ...batch, verification }
+          }
           try {
             tx.commit()
           } catch (error) {
@@ -538,14 +622,13 @@ export async function editManyEnvelope(provider, request) {
             error.rollback = rollback
             throw error
           }
-          return includeTransaction ? { ...batch, transaction: tx.summary() } : batch
+          return batch
         }
         const rollback = await tx.rollback(provider)
         const finalBatch = writePath.rebuildAfterRollback(batch, rollback)
         return {
           ...finalBatch,
           ok: false,
-          ...(includeTransaction ? { transaction: tx.summary() } : {}),
         }
       } catch (error) {
         const rollback = await tx.rollback(provider)
@@ -572,6 +655,7 @@ function compactWriteReceipt(env, content) {
   const bytes = result.write_verify?.bytes ?? (dryRun && result.operation === 'create' ? Buffer.byteLength(content, 'utf8') : undefined)
   return {
     ok: true,
+    ...(env.verification === undefined ? {} : { verification: env.verification }),
     result: {
       path: result.path,
       operation: result.operation ?? 'write',
@@ -579,7 +663,6 @@ function compactWriteReceipt(env, content) {
       dryRun,
       ...(result.write_verify === undefined ? {} : { write_verify: result.write_verify }),
       ...(result.unverified_region === true ? { unverified_region: true } : {}),
-      ...(result.transaction === undefined ? {} : { transaction: result.transaction }),
     },
   }
 }
@@ -600,7 +683,7 @@ function compactWriteReceipt(env, content) {
  * `preserve` 按 content 原样写（与内置 Write 的“给什么写什么”对齐），`lf` / `crlf` 强制统一。
  * 新建文件永远按 content 原样写；显式传非 `auto` 的 eol 会被拒绝（不做静默忽略）。
  */
-export async function writeEnvelope(provider, { file, content, dryRun = false, noOverwrite = false, includeTransaction = false, allowUnobserved = false, eol = 'auto' } = {}) {
+export async function writeEnvelope(provider, { file, content, dryRun = false, noOverwrite = false, allowUnobserved = false, eol = 'auto', verify } = {}) {
   if (typeof file !== 'string' || file.length === 0) {
     return { ok: false, error: 'write needs a file path', code: 'WRITE_BAD_ARGS' }
   }
@@ -627,7 +710,7 @@ export async function writeEnvelope(provider, { file, content, dryRun = false, n
       if (dryRun) {
         return { ok: true, result: { path: displayPath, operation: 'create', bytes: Buffer.byteLength(content, 'utf8'), dryRun: true } }
       }
-      return compactWriteReceipt(await editEnvelope(provider, { file, create: content, includeTransaction }), content)
+      return compactWriteReceipt(await editEnvelope(provider, { file, create: content, verify }), content)
     }
     return compactWriteReceipt(
       await editEnvelope(provider, {
@@ -635,10 +718,10 @@ export async function writeEnvelope(provider, { file, content, dryRun = false, n
         wholeFile: content,
         eol,
         dryRun,
-        includeTransaction,
         requireObservation: allowUnobserved !== true,
         skipStaleGate: allowUnobserved === true,
         toolName: 'aura_basetools_write',
+        verify,
       }),
       content,
     )
@@ -646,17 +729,3 @@ export async function writeEnvelope(provider, { file, content, dryRun = false, n
     return transactionError(error)
   }
 }
-
-export async function undoEnvelope(provider, { id, force } = {}) {  try {
-    return {
-      ok: true,
-      ...(await withWorkspaceLock(provider.root, () => undoTransaction(provider.root, provider, { id, force: force === true }))),
-    }
-  } catch (error) {
-    return transactionError(error)
-  }
-}
-
-export function transactionsEnvelope(provider) {
-  return { ok: true, transactions: listTransactions(provider.root) }
-}

package/lib/transaction-store.mjs

@@ -1,17 +1,16 @@
 /**
- * transaction-store.mjs —— 写事务日志、回滚与 undo。
+ * transaction-store.mjs —— 写事务日志与**失败回滚**（内部实现，不再暴露 undo/transactions 工具）。
  *
  * 一次写事务在 `~/.aura/transactions/<workspace-key>/<id>/` 下留下：
  *   · `meta.json` —— 事务状态与每个文件的原始 mode/版本/备份名；
  *   · `originals/<n>.bin` —— 写前原始字节（逐字节，含 BOM/行尾）。
  *
  * 事务的生命周期：
- *   pending → committed（写成功，可 undo）
+ *   pending → committed（写成功；日志仅用于内部回滚，不再提供 undo）
  *           → rolled_back（写失败，已恢复原字节）
  *           → recovery_required（写失败且恢复也失败；meta 里留着可手工恢复的路径）
- *   committed → undone（undo 成功）
  *
- * 回滚/undo 前会比一次 `afterVersion`：文件在事务之后又被别人改过就拒绝覆盖（`--force` 才强制）。
+ * 回滚前会比一次 `afterVersion`：文件在事务之后又被别人改过就拒绝覆盖。
  * 这不是安全边界；它只保证遵守本协议的进程不会静默覆盖并发写。
  */
 import fs from 'node:fs'
@@ -262,21 +261,6 @@ function readAllMeta(root) {
   return out.sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)))
 }
 
-/** 取最近一条可 undo 的 committed 事务。 */
-export function latestCommitted(root) {
-  return readAllMeta(root).find((meta) => meta.status === 'committed') ?? null
-}
-
-export function listTransactions(root) {
-  return readAllMeta(root).map((meta) => ({
-    id: meta.id,
-    tool: meta.tool,
-    createdAt: meta.createdAt,
-    status: meta.status,
-    files: Array.isArray(meta.files) ? meta.files.length : 0,
-    dir: meta.dir,
-  }))
-}
 
 function prune(root, keep = KEEP) {
   const metas = readAllMeta(root).filter((meta) => meta.status !== 'pending')
@@ -285,66 +269,3 @@ function prune(root, keep = KEEP) {
   }
 }
 
-/**
- * 撤销一条 committed 事务。
- *
- * 任何文件在当前时间点的版本与事务提交后的版本不一致 ⇒ 默认拒绝，避免覆盖后续编辑；
- * `force: true` 才强制恢复旧字节。
- */
-export async function undoTransaction(root, provider, options = {}) {
-  const metas = readAllMeta(root)
-  const meta = options.id ? metas.find((m) => m.id === options.id) : metas.find((m) => m.status === 'committed')
-  if (meta === undefined) {
-    throw Object.assign(new Error(options.id ? `transaction not found: ${options.id}` : 'no committed transaction to undo'), {
-      code: 'TRANSACTION_NOT_FOUND',
-    })
-  }
-  if (meta.status !== 'committed') {
-    throw Object.assign(new Error(`transaction ${meta.id} is ${meta.status}, not committed`), {
-      code: 'TRANSACTION_NOT_UNDOABLE',
-      status: meta.status,
-    })
-  }
-  const force = options.force === true
-  /**
-   * 先做一次**只读预检**：任何文件在事务后又被改过 ⇒ 整个 undo 拒绝。
-   * 旧顺序会先把还能恢复的文件写回去，再发现某个文件冲突——那就是一次部分 undo；
-   * 对一个以“不会静默改错”为卖点的工具，部分恢复比拒绝更坏。
-   */
-  const plans = []
-  const conflicts = []
-  for (const entry of meta.files) {
-    if (!entry.written) continue
-    let current
-    try { current = provider.stat(entry.path) } catch { current = undefined }
-    if (!force && entry.afterVersion !== null && current?.version !== entry.afterVersion) {
-      conflicts.push({ path: entry.path, reason: 'changed since this transaction', expected: entry.afterVersion, actual: current?.version ?? null })
-    }
-    plans.push(entry)
-  }
-  if (conflicts.length > 0) {
-    throw Object.assign(new Error(`transaction ${meta.id} cannot be undone: ${conflicts.length} file(s) changed after it`), {
-      code: 'TRANSACTION_STALE',
-      transaction: meta.id,
-      conflicts,
-    })
-  }
-  let restored = 0
-  for (const entry of plans) {
-    try {
-      if (entry.existed) {
-        writeBytesAtomic(entry.realPath, fs.readFileSync(path.join(meta.dir, entry.backup)), entry.mode ?? 0o600)
-      } else {
-        fs.rmSync(entry.realPath, { force: true })
-      }
-      restored += 1
-    } catch (error) {
-      conflicts.push({ path: entry.path, reason: String(error?.message ?? error) })
-    }
-  }
-  meta.status = conflicts.length === 0 ? 'undone' : 'recovery_required'
-  meta.undoneAt = new Date().toISOString()
-  meta.undoConflicts = conflicts
-  saveMeta(meta)
-  return { transaction: meta.id, status: meta.status, restored, conflicts, dir: meta.dir }
-}

package/locator-lab/args.mjs

@@ -126,12 +126,12 @@ export function normalizeReadRequest(args, totalLines = undefined) {
  * 导出它是为了不再出现第二份：守卫要拿它算“合法键集合”，而如果有两份名单，
  * 新增一种地址写法时必有一处漏改——那正是本项目反复出现的形状。
  */
-export const FLAT_ADDRESS_KEYS = ['target', 'intent', 'lines', 'start_line', 'end_line', 'line_cue', 'anchor', 'handle', 'old']
+export const FLAT_ADDRESS_KEYS = ['target', 'lines', 'start_line', 'end_line', 'line_cue', 'anchor', 'handle', 'old']
 
 /**
  * `targets` 元素（单目标参数）的合法键。
  *
- * 与顶层工具键**分开**：`targets` 本身、批量级的 `include_transaction` 都不是元素参数；
+ * 与顶层工具键**分开**：`targets` 本身不是元素参数；
  * 放进元素里只会被静默丢掉。三面（CLI / MCP / DSH）共用这一份，未知键一律
  * `ARGS_UNKNOWN_KEY`，不再只校验顶层。
  */
@@ -140,7 +140,7 @@ export const MT_READ_ELEMENT_KEYS = [
 ]
 export const MT_EDIT_ELEMENT_KEYS = [
   'file_path', 'hunks', 'create', 'dry_run', 'require_observation',
-  'target', 'intent', 'lines', 'start_line', 'end_line', 'line_cue', 'anchor', 'old', 'context',
+  'target', 'lines', 'start_line', 'end_line', 'line_cue', 'anchor', 'old', 'context',
   'replace', 'replace_all', 'eol', 'expect', 'near', 'handle', 'line', 'position',
 ]
 

package/locator-lab/locator-api.mjs

@@ -23,28 +23,24 @@ import { indexFile, locateWith, normSpace } from './anchor-core.mjs'
 /**
  * 定位一份源码里的改动点。
  *
- * 五层寻址，按"模型要提供什么"从强到弱排列。每层覆盖上一层够不到的场景，
+ * 四层寻址，按"模型要提供什么"从强到弱排列。每层覆盖上一层够不到的场景，
  * 但**都不要求模型复现字节**——这是它们与 `edit` 的根本差别：
  *
- *   1. `intent`  —— 一段模糊意图（符号名片段 / 短语 / 近似原文）。引擎按固定次序收敛：
- *                    精确符号 → 符号子串 → 文本锚点；收敛不了就报歧义并给候选，绝不猜。
- *   2. `target`  —— 符号名。不读文本，对内容记错免疫。适合改整个函数/类/类型。
- *   3. `lines`   —— 行号区间。模型刚用 `read` 看过文件，输出就是 `<行号>: <文本>`，
+ *   1. `target`  —— 符号名。不读文本，对内容记错免疫。适合改整个函数/类/类型。
+ *   2. `lines`   —— 行号区间。模型刚用 `read` 看过文件，输出就是 `<行号>: <文本>`，
  *                    `grep` 也给行号——**位置是它本来就知道的信息**，我却一直只让它给内容。
  *                    把行号纳入地址空间后，符号体内的任意一行都变得可精确寻址。
- *   4. `lineCue` —— 一个词。当模型记不住行号时，说"就在有 resolvePolicy 的那一行"。
+ *   3. `lineCue` —— 一个词。当模型记不住行号时，说"就在有 resolvePolicy 的那一行"。
  *                    只接受**全文件唯一**的线索；不唯一则报歧义并给出候选行号，绝不猜。
- *   5. `anchor`  —— 记得的原文。五级降级匹配，容错性最好但要求模型复现内容。
+ *   4. `anchor`  —— 记得的原文。五级降级匹配，容错性最好但要求模型复现内容。
  *
- * `intent` 与其余四层**互斥**（由 `planHunks` 判）：同时给两个地址时谁说了算没有正确答案。
- * 前两层偏**精确**（要么命中要么报错），后三层偏**容错**。
- * 调用方可以传 `assert` 做内容校验，五层都适用——那才是防止"指到错的行"的那道闸。
+ * 前两层偏**精确**（要么命中要么报错），后两层偏**容错**。
+ * 调用方可以传 `assert` 做内容校验，四层都适用——那才是防止"指到错的行"的那道闸。
  * 判据是**包含且唯一**：这段文字必须在整个文件里只出现一处，且该处落在受寻址区间内
  * （短引文例外，仍要求与区间整段相等；推导见 {@link ASSERT_RELAX_MIN_CHARS}）。
  *
  * @param {string} source - 源码全文
  * @param {object} request - 定位请求
- * @param {string} [request.intent] - 模糊意图地址（符号名片段 / 短语 / 近似原文）
  * @param {string} [request.target] - 符号名（`name` / `kind:name` / `Outer/Inner` / `name#n`）
  * @param {{start:number,end:number}} [request.lines] - 1-based 闭区间行号
  * @param {string} [request.lineCue] - 一个词的线索，必须全文件唯一
@@ -644,53 +640,14 @@ function assertVerdict(lines, startLine, endLine, tier, actual, assertText) {
   }
 }
 
-/**
- * 意图地址（T16）的符号子串匹配：这个候选符号离 `near` 有多远。
- *
- * 判据只有一条：**`near` 落在符号的跨度里就是 0**，否则取到两端中较近的那一端。
- * 与 `resolveTarget` 的 `|startLine - near|` 刻意不同：`intent` 匹配的是"大概想改哪个符号"，
- * 调用方给的 `near` 常常是**符号体内**的一行（它刚从 read 回执里抄来），拿起点算距离会把
- * 一个明显在说的符号判成第二近。跨度包含 `near` ⇒ 距离 0，是这里唯一能自洽的口径。
- *
- * @param - 符号投影（含 startLine / endLine）
- * @param near - 1-based 行号提示
- * @returns 非负整数距离
- */
-function symbolDistanceFrom(symbol, near) {
-  if (near >= symbol.startLine && near <= symbol.endLine) return 0
-  return Math.min(Math.abs(near - symbol.startLine), Math.abs(near - symbol.endLine))
-}
 
 /**
- * 多个子串命中里，`near` 能否**严格**收敛到一个（唯一最小值）。
+ * 定位一个区间。四层降级：符号身份 → 行号 → 唯一词 → 文本锚点。
  *
- * 不唯一（并列最小）⇒ null：那正是"该报歧义"的形状，猜测在这里比拒绝贵得多。
- * @returns 命中的符号，或 null（near 没给 / 并列）
- */
-function nearestSymbolBySpan(symbols, near) {
-  let best = null
-  let bestDistance = Infinity
-  let ties = 0
-  for (const symbol of symbols) {
-    const distance = symbolDistanceFrom(symbol, near)
-    if (distance < bestDistance) {
-      bestDistance = distance
-      best = symbol
-      ties = 1
-    } else if (distance === bestDistance) ties += 1
-  }
-  return ties === 1 ? best : null
-}
-
-/**
- * 定位一个区间。五层降级：意图 → 符号身份 → 行号 → 唯一词 → 文本锚点。
- *
- * `intent`（T16）是**最弱但最自然**的一层：调用方给一个符号名片段、短语或近似原文，
- * 引擎先当符号名解析（精确/限定写法），再按符号名子串匹配，最后才落到文本匹配。
  * 每一档都**确定性地**收敛到一个区间；收敛不了就报歧义并给候选，不猜。
  *
  * @param source - 文件全文
- * @param request - `intent` / `target` / `lines` / `lineCue` / `anchor` 五选一，外加 `near` 与 `assert`
+ * @param request - `target` / `lines` / `lineCue` / `anchor` 四选一，外加 `near` 与 `assert`
  * @returns 命中时 `{ok: true, startLine, endLine, tier, actual}`；未命中时 `{ok: false, code, message, ...}`。
  *   `actual` 是该区间的原文，供调用方核对或展示。
  */
@@ -761,125 +718,6 @@ export function locate(source, request = {}) {
     return { ok: false, code: 'LOCATOR_LINE_SHARED', message, shared }
   }
 
-  // ── 第 0 层：意图地址（T16）。调用方给一段模糊的意图串，引擎确定性地落成精确区间。
-  //
-  // 解析次序（每一档都不猜，落不下来就报歧义并给候选）：
-  //   ① 已知语言时，先当符号名解析（`resolveTarget` 的精确 / 限定写法）——命中就算 symbol 档；
-  //   ② 符号名没对上（或对上多个）⇒ 按符号名**子串**匹配（先区分大小写，再忽略大小写）；
-  //   ③ 一个符号都没命中（或语言未知）⇒ 落到文本匹配（`locateWith`，与 `anchor` 同一份引擎）。
-  //
-  // 顺序上刻意在 `target` 之前：`intent` 与其余地址字段**互斥**（`PATCH_INTENT_CONFLICT`，
-  // 由 `planHunks` 判），所以两者同时到达这里是不可能的；放在最前只是把"intent 自成一层"写明。
-  if (typeof request.intent === 'string' && request.intent.trim().length > 0) {
-    const intent = request.intent.trim()
-    const near = request.near ?? null
-    const label = clipReceiptLabel(filePath === null ? 'this file' : filePath, RECEIPT_LABEL_CHARS)
-    /** 跨度覆盖不了符号体时的拒绝——与 `target=` 那一支**同一句话、同一个码**（不是第二套说法）。 */
-    const spanIncomplete = (hit) => ({
-      ok: false,
-      code: 'LOCATOR_SPAN_INCOMPLETE',
-      message: `cannot address "${hit.name}" by intent in ${label}: the span does not cover the body — ${hit.spanNote}; address it with lines= or line_cue= instead`,
-      hint: directoryHint(source, lang),
-    })
-    if (lang !== null) {
-      const index = indexStructure(source, lang)
-      /**
-       * 精确/限定符号：先**不带 near** 解析，拿到唯一命中或完整候选。
-       * 带 near 交给 `resolveTarget` 会用“起点距离”，与 intent 档的“跨度包含 near 记 0”冲突，
-       * 实测会把 near 落在第一个长函数体内的情况选到第二个同名函数上。歧义时这里用
-       * `nearestSymbolBySpan` 按跨度收敛；解析不了再落到子串匹配。
-       */
-      let exact = null
-      try {
-        exact = resolveTarget(index, intent, null)
-      } catch (error) {
-        if (error.code === 'STRUCT_AMBIGUOUS') {
-          const candidates = Array.isArray(error.candidates) ? error.candidates : []
-          if (near !== null && near !== undefined) {
-            const chosen = nearestSymbolBySpan(candidates, near)
-            if (chosen !== null) {
-              if (chosen.spanComplete === false) return spanIncomplete(chosen)
-              return done(chosen.startLine, chosen.endLine, 'intent~symbol', true)
-            }
-          }
-          return failure('LOCATOR_INTENT_AMBIGUOUS', `intent ${JSON.stringify(intent)}: ${error.message}`, candidates)
-        }
-        // STRUCT_NOT_FOUND / 其它：符号名没猜中不是终点，落到子串匹配（下面）。
-      }
-      if (exact !== null) {
-        if (exact.spanComplete === false) return spanIncomplete(exact)
-        const shared = sharedLineContent(source, index, exact, lang)
-        if (shared !== null) return sharedLineRefusal(exact, shared, 'intent')
-        return done(exact.startLine, exact.endLine, 'intent~symbol')
-      }
-      // 用原始符号表而不是 `listSymbols` 投影：整行区间是否越界要看 token，投影里没有。
-      const symbols = index.symbols
-      let matches = symbols.filter((s) => s.name.includes(intent))
-      if (matches.length === 0) {
-        const lower = intent.toLowerCase()
-        matches = symbols.filter((s) => s.name.toLowerCase().includes(lower))
-      }
-      if (matches.length === 1) {
-        const only = matches[0]
-        if (only.spanComplete === false) return spanIncomplete(only)
-        const shared = sharedLineContent(source, index, only, lang)
-        if (shared !== null) return sharedLineRefusal(only, shared, 'intent')
-        return done(only.startLine, only.endLine, 'intent~symbol')
-      }
-      if (matches.length > 1) {
-        if (near !== null && near !== undefined) {
-          const chosen = nearestSymbolBySpan(matches, near)
-          if (chosen !== null) {
-            if (chosen.spanComplete === false) return spanIncomplete(chosen)
-            const shared = sharedLineContent(source, index, chosen, lang)
-            if (shared !== null) return sharedLineRefusal(chosen, shared, 'intent')
-            return done(chosen.startLine, chosen.endLine, 'intent~symbol', true)
-          }
-        }
-        const why =
-          near === null || near === undefined
-            ? `intent ${JSON.stringify(intent)} matched ${matches.length} symbols — pick one with target=<name>, or add near=<line>`
-            : `intent ${JSON.stringify(intent)} matched ${matches.length} symbols and near=${near} did not single one out`
-        return failure(
-          'LOCATOR_INTENT_AMBIGUOUS',
-          why,
-          matches.map((s) => ({
-            name: s.name,
-            kind: s.kind,
-            startLine: s.startLine,
-            endLine: s.endLine,
-            enclosing: s.enclosing,
-          })),
-        )
-      }
-    }
-    // ── ③ 文本兜底：与 `anchor` 同一份引擎（`locateWith`）；tier 里带上它命中的那一档
-    try {
-      const loc = locateWith(indexFile(source), intent, near)
-      return done(loc.start + 1, loc.end, `intent~text~${loc.tier}`, loc.byNear === true)
-    } catch (error) {
-      if (error.code === 'PATCH_AMBIGUOUS') {
-        /**
-         * 行候选统一成 `{line, text}`（`failure` 只认这一形状才会印出行号与原文）：
-         * `locateWith` 抛的是 `number[]`，直接递下去会印成 `line undefined`。
-         */
-        const listed = (Array.isArray(error.candidates) ? error.candidates : [])
-          .filter((n) => typeof n === 'number' && n >= 1 && n <= lines.length)
-          .map((n) => ({ line: n, text: lines[n - 1].slice(0, 80) }))
-        return failure('LOCATOR_INTENT_AMBIGUOUS', `intent ${JSON.stringify(intent)}: ${error.message}`, listed)
-      }
-      if (error.code === 'PATCH_NOT_FOUND' || error.code === 'PATCH_EMPTY_ANCHOR') {
-        return {
-          ok: false,
-          code: 'LOCATOR_INTENT_NOT_FOUND',
-          message: `no symbol or text matches intent ${JSON.stringify(intent)} in ${label}; try target=<name>, lines=, or line_cue=`,
-          // 符号目录是实测支撑的恢复路径（与 anchor 失败同一条）：只有认识这门语言时才给得出。
-          ...(lang === null ? {} : { hint: directoryHint(source, lang) }),
-        }
-      }
-      return failure(error.code ?? 'LOCATOR_FAILED', error.message, error.candidates)
-    }
-  }
 
   // ── 第 1 层：符号身份。不读文本，因此对内容记错免疫。
   if (typeof request.target === 'string' && request.target.trim().length > 0) {
@@ -1028,7 +866,7 @@ export function locate(source, request = {}) {
     }
   }
 
-  return { ok: false, code: 'LOCATOR_NO_REQUEST', message: 'provide one of: intent, target, lines, lineCue, anchor' }
+  return { ok: false, code: 'LOCATOR_NO_REQUEST', message: 'provide one of: target, lines, lineCue, anchor' }
 }
 
 /**