aura-basetools 0.7.0 → 0.13.1

package/lib/ops.mjs

@@ -76,6 +76,54 @@ const readCore = await import(engineUrl('read-core.mjs'))
 const repoMap = await import(engineUrl('repo-map.mjs'))
 const engineArgs = await import(engineUrl('args.mjs'))
 const writePath = await import(engineUrl('write-path.mjs'))
+const structCore = await import(engineUrl('struct-core.mjs'))
+const handleCore = await import(engineUrl('handle-core.mjs'))
+
+/**
+ * 0.9.9：运行时可查询的能力清单（与 build/capabilities.mjs 同一份源码常量）。
+ * 不发货额外 JSON：包内已有的引擎模块就是唯一来源。
+ */
+export function capabilitiesEnvelope() {
+  const langs = Object.keys(structCore.LANGS).sort()
+  return {
+    tools: [
+      { name: 'aura_basetools_read', modes: ['auto', ...readCore.MODES] },
+      {
+        name: 'aura_basetools_edit',
+        addressKinds: [...new Set([...engineArgs.FLAT_ADDRESS_KEYS, 'old', 'context', 'position'])],
+        options: ['replace_all', 'require_observation'],
+        writeSafety: {
+          cli: ['transaction', 'undo', 'workspace-lock', 'stale-region-gate', 'byte-verify'],
+          mcp: ['transaction', 'undo', 'workspace-lock', 'stale-region-gate', 'byte-verify'],
+          dsh: ['stale-region-gate', 'byte-verify'],
+        },
+      },
+      {
+        name: 'aura_basetools_write',
+        operations: ['create', 'overwrite'],
+        options: ['eol'],
+        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/工作区锁；它经过引擎的区域闸、严格新鲜度与回读校验。
+          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'],
+    langs,
+    langsCount: langs.length,
+    limits: {
+      multiTargetsMax: engineArgs.MT_MAX_TARGETS,
+      multiTargetPool: engineArgs.MT_POOL,
+      defaultPruneBudget: readCore.DEFAULT_PRUNE_BUDGET,
+      envelopeAllowance: readCore.DEFAULT_ENVELOPE_ALLOWANCE,
+      contentBudget: readCore.CONTENT_BUDGET,
+      handlesPerReceipt: handleCore.HANDLE_MAX_PER_RECEIPT,
+    },
+    packaging: { corePackage: 'aura-basetools', adapterPackage: 'aura-basetools-dsh' },
+  }
+}
 
 /**
  * 引擎公开面的转发：绑定转发，不是「把命名空间塞给调用方」——
@@ -94,6 +142,7 @@ export const asLinePair = engineArgs.asLinePair
 export const gaveLineAddress = engineArgs.gaveLineAddress
 export const inferReadMode = engineArgs.inferReadMode
 export const lineRangeOf = engineArgs.lineRangeOf
+export const normalizeReadRequest = engineArgs.normalizeReadRequest
 export const flatHunk = engineArgs.flatHunk
 export const applyEditToProvider = writePath.applyEditToProvider
 
@@ -117,6 +166,8 @@ export const assertReadTargets = engineArgs.assertReadTargets
 export const assertEditTargets = engineArgs.assertEditTargets
 export const assertTargetShape = engineArgs.assertTargetShape
 export const assertKnownArgs = engineArgs.assertKnownArgs
+export const MT_READ_ELEMENT_KEYS = engineArgs.MT_READ_ELEMENT_KEYS
+export const MT_EDIT_ELEMENT_KEYS = engineArgs.MT_EDIT_ELEMENT_KEYS
 
 // ── C55：非 UTF-8 文件 ⇒ 可执行的拒绝 ──────────────────────────────────────
 
@@ -262,7 +313,7 @@ export function readFileBytes(displayPath) {
     return {
       error: {
         ok: false,
-        error: nonUtf8RefusalMessage('read', displayPath, 'aura_read'),
+        error: nonUtf8RefusalMessage('read', displayPath, 'aura_basetools_read'),
         code: typeof error?.code === 'string' && error.code.length > 0 ? error.code : 'FS_NOT_TEXT',
       },
     }
@@ -277,18 +328,22 @@ export function readFileBytes(displayPath) {
  * 两个调用方（CLI `bin/aura.mjs`、MCP `bin/aura-mcp.mjs`）本来就 `await` 它，写法不变。
  */
 export async function readEnvelope(provider, args) {
-  const { file, around, search, since, maxChars } = args
+  const { file, around, search, since, context, kind, budget } = args
+  // 宿主面用 `max_chars`，引擎面用 `maxChars`；单目标与 targets 元素都必须认两种写法。
+  const maxChars = args.maxChars ?? args.max_chars
   try {
-    // 行区间先收敛：`[412,500]`、`"412,500"`、`412`、`start_line/end_line` 都接受；
-    // 给了但解不出来就明说接受哪些形状（静默退回 auto 会让人以为是别的问题）。
-    const lines = lineRangeOf(args)
-    if (lines === undefined && gaveLineAddress(args)) {
-      return { ok: false, error: LINE_ADDRESS_HINT, code: 'READ_BAD_ARGS' }
-    }
-    const mode = inferReadMode(args, lines)
+    /**
+     * 行区间 / 分页 / 模式推断收成一份（`normalizeReadRequest`）：单目标与 `targets` 元素
+     * 走同一个判定器。第一遍只判形状（文件还没读），第二遍拿到总行数后做 offset 越界与截断。
+     */
+    const requestShape = normalizeReadRequest(args)
+    if (requestShape.ok !== true) return requestShape
     const displayPath = provider.resolve(file)
     const info = provider.stat(displayPath)
     if (info === undefined) return { ok: false, error: `cannot read "${file}": not found`, code: 'FS_NOT_FOUND' }
+    if (info.type === 'directory' && requestShape.paginate) {
+      return { ok: false, error: 'offset/limit applies to files; a directory is returned as a repo map — drop pagination', code: 'READ_BAD_ARGS' }
+    }
     /**
      * 目录：给一张仓库地图（T26）。判据只有“它是目录”这一条，不需要调用方多填参数。
      *
@@ -311,15 +366,20 @@ export async function readEnvelope(provider, args) {
     }
     const got = readFileBytes(displayPath)
     if (got.error !== undefined) return got.error
+    const request = normalizeReadRequest(args, got.source.split(/\r?\n/).length)
+    if (request.ok !== true) return request
     const env = readWith(got.source, {
-      mode,
+      mode: request.mode,
       around,
       // 读侧只认数组：这里从收敛层的 {start,end} 转一次（之前 CLI/MCP 直接传 {start,end}，
       // 于是 `aura read --lines 1,2` 会报 READ_NO_RANGE —— 顺手修掉的既有 bug）。
-      lines: asLinePair(lines),
+      lines: asLinePair(request.lines),
       search,
       since,
       maxChars,
+      ...(context === undefined ? {} : { context }),
+      ...(kind === undefined ? {} : { kind }),
+      ...(budget === undefined ? {} : { budget }),
       byteOrderMark: got.byteOrderMark,
       filePath: displayPath,
     })
@@ -332,7 +392,7 @@ export async function readEnvelope(provider, args) {
     if (isNonUtf8TextFailure(error)) {
       return {
         ok: false,
-        error: nonUtf8RefusalMessage('read', resolvedOrRaw(provider, file), 'aura_read'),
+        error: nonUtf8RefusalMessage('read', resolvedOrRaw(provider, file), 'aura_basetools_read'),
         code: typeof error?.code === 'string' && error.code.length > 0 ? error.code : 'FS_NOT_TEXT',
         ...errorEvidence(error),
       }
@@ -347,12 +407,16 @@ export async function readEnvelope(provider, args) {
 }
 
 /** 改一次（规划 → 陈旧闸门 → 逐字节写 + CAS → 回读校验 → 刷新观测）。 */
-async function editEnvelopeInner(provider, { file, hunks, dryRun, create }) {
+async function editEnvelopeInner(provider, { file, hunks, dryRun, create, requireObservation, wholeFile, eol, skipStaleGate, toolName = 'aura_basetools_edit' }) {
   try {
     const result = await applyEditToProvider(provider, {
       displayPath: provider.resolve(file),
-      hunks,
+      hunks: hunks ?? [],
       dryRun: dryRun === true,
+      ...(requireObservation === true ? { requireObservation: true } : {}),
+      ...(typeof wholeFile === 'string' ? { wholeFile } : {}),
+      ...(typeof eol === 'string' ? { eol } : {}),
+      ...(skipStaleGate === true ? { skipStaleGate: true } : {}),
       ...(typeof create === 'string' ? { create } : {}),
     })
     return { ok: true, result }
@@ -365,7 +429,7 @@ async function editEnvelopeInner(provider, { file, hunks, dryRun, create }) {
     if (isNonUtf8TextFailure(error)) {
       return {
         ok: false,
-        error: nonUtf8RefusalMessage('patch', resolvedOrRaw(provider, file), 'aura_edit'),
+        error: nonUtf8RefusalMessage('patch', resolvedOrRaw(provider, file), toolName),
         code: typeof error?.code === 'string' && error.code.length > 0 ? error.code : 'FS_NOT_TEXT',
         ...errorEvidence(error),
       }
@@ -424,10 +488,16 @@ function transactionError(error) {
 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。
+   * 预演也不写盘，不需要工作区锁。
+   */
+  if (request.dryRun === true) return editEnvelopeInner(provider, request)
   const includeTransaction = request.includeTransaction === true
   try {
     return await withWorkspaceLock(provider.root, async () => {
-      const tx = createTransaction(provider.root, 'aura_edit')
+      const tx = createTransaction(provider.root, 'aura_basetools_edit')
       const env = await editEnvelopeInner(tx.proxy(provider), request)
       if (env.ok) {
         try {
@@ -451,10 +521,12 @@ export async function editEnvelope(provider, request) {
 /** 多目标写事务：与单目标共用锁/日志/回滚；批次返回 ok=false 时也回滚。 */
 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
   try {
     return await withWorkspaceLock(provider.root, async () => {
-      const tx = createTransaction(provider.root, 'aura_edit')
+      const tx = createTransaction(provider.root, 'aura_basetools_edit')
       try {
         const batch = await editManyEnvelopeInner(tx.proxy(provider), request)
         if (batch.ok) {
@@ -469,7 +541,12 @@ export async function editManyEnvelope(provider, request) {
           return includeTransaction ? { ...batch, transaction: tx.summary() } : batch
         }
         const rollback = await tx.rollback(provider)
-        return includeTransaction ? { ...batch, transaction: tx.summary(), rollback } : batch
+        const finalBatch = writePath.rebuildAfterRollback(batch, rollback)
+        return {
+          ...finalBatch,
+          ok: false,
+          ...(includeTransaction ? { transaction: tx.summary() } : {}),
+        }
       } catch (error) {
         const rollback = await tx.rollback(provider)
         error.transaction = tx.summary()
@@ -482,8 +559,95 @@ export async function editManyEnvelope(provider, request) {
   }
 }
 
-export async function undoEnvelope(provider, { id, force } = {}) {
+/** 整文件写的紧凑回执：不把整份 old/new 文本塞进 applied（那是 edit 的形状，不是 write 的）。 */
+function compactWriteReceipt(env, content) {
+  if (env === null || typeof env !== 'object' || env.ok !== true) return env
+  const result = env.result ?? {}
+  const dryRun = result.dryRun === true
+  /**
+   * 覆写预演没有落盘，也没有回读字节数；此时 `content` 的长度可能不等于最终字节数
+   * （整份写会把 content 的换行适配成文件已有风格，CRLF 每行多一个字节）。
+   * 宁可**不报** bytes，也不报一个预演后必然对不上的数。新建预演不需要适配，照报。
+   */
+  const bytes = result.write_verify?.bytes ?? (dryRun && result.operation === 'create' ? Buffer.byteLength(content, 'utf8') : undefined)
+  return {
+    ok: true,
+    result: {
+      path: result.path,
+      operation: result.operation ?? 'write',
+      ...(bytes === undefined ? {} : { bytes }),
+      dryRun,
+      ...(result.write_verify === undefined ? {} : { write_verify: result.write_verify }),
+      ...(result.unverified_region === true ? { unverified_region: true } : {}),
+      ...(result.transaction === undefined ? {} : { transaction: result.transaction }),
+    },
+  }
+}
+
+/**
+ * 0.10.1：整文件写（内置 `Write` 的替代）。
+ *
+ * 新建与覆写都走 `editEnvelope`：同一把工作区锁、同一份事务日志、同一套回读校验。
+ * 覆写用“整文件行区间（含末尾那个空行）+ `eol: auto`”表达：行区间覆盖到文件末尾，
+ * 于是 content 自己的**有无尾换行**被精确保留，而 content 内的换行统一成文件已有的风格
+ * （与内置 Edit 对多行替换的处理一致）。已有的 BOM 也照旧保留。
+ *
+ * **覆写默认要求先读过这版内容**（`PATCH_UNOBSERVED`），与内置 `Write` 的 read-before-write
+ * 同一条；`allowUnobserved` 是显式逃生口（回执照实标 `unverified_region`）。
+ * 新建不受这条约束。
+ *
+ * `eol` 只对覆写有意义：`auto`（默认）把 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' } = {}) {
+  if (typeof file !== 'string' || file.length === 0) {
+    return { ok: false, error: 'write needs a file path', code: 'WRITE_BAD_ARGS' }
+  }
+  if (typeof content !== 'string') {
+    return { ok: false, error: 'write needs `content` as a string', code: 'WRITE_BAD_ARGS' }
+  }
+  if (!['auto', 'preserve', 'lf', 'crlf'].includes(eol)) {
+    return { ok: false, error: 'write `eol` must be auto, preserve, lf, or crlf', code: 'WRITE_BAD_ARGS' }
+  }
   try {
+    const displayPath = provider.resolve(file)
+    const info = provider.stat(displayPath)
+    if (info !== undefined && noOverwrite) {
+      return { ok: false, error: `cannot write "${displayPath}": it already exists (no-overwrite)`, code: 'WRITE_EXISTS' }
+    }
+    if (info === undefined) {
+      if (eol !== 'auto') {
+        return {
+          ok: false,
+          error: 'write `eol` applies when overwriting an existing file; a new file is written exactly as given — pass the endings you want in `content`',
+          code: 'WRITE_BAD_ARGS',
+        }
+      }
+      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,
+        wholeFile: content,
+        eol,
+        dryRun,
+        includeTransaction,
+        requireObservation: allowUnobserved !== true,
+        skipStaleGate: allowUnobserved === true,
+        toolName: 'aura_basetools_write',
+      }),
+      content,
+    )
+  } catch (error) {
+    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 }))),

package/lib/transaction-store.mjs

@@ -118,7 +118,7 @@ function fileSummary(entry) {
  * @param root - 工作区根
  * @param tool - 产生它的工具名（仅记录）
  */
-export function createTransaction(root, tool = 'aura_edit') {
+export function createTransaction(root, tool = 'aura_basetools_edit') {
   const id = transactionId()
   const dir = path.join(transactionsRoot(root), id)
   ensureDir(dir)

package/lib/workspace-lock.mjs

@@ -20,6 +20,8 @@ import crypto from 'node:crypto'
 
 const DEFAULT_TIMEOUT_MS = 5000
 const DEFAULT_STALE_MS = 10 * 60 * 1000
+/** 空锁（已创建、PID 还没写进去）的宽限：短于这个年龄不判陈旧，避免抢走刚持有的锁。 */
+const EMPTY_LOCK_GRACE_MS = 2000
 const RETRY_MS = 50
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
@@ -99,16 +101,35 @@ export async function withWorkspaceLock(root, fn, options = {}) {
     } catch (error) {
       if (error?.code !== 'EEXIST') throw error
       const holder = readLock(file)
-      const age = Date.now() - Number(holder?.createdAt ?? 0)
-      const stale = holder === null || age > staleMs || !processAlive(holder.pid)
+      /**
+       * **空锁不是陈旧锁**：`open(..., 'wx')` 与写入 PID 之间有窗口，另一个进程此时读到的
+       * 是空文件（`readLock` 返回 null）。旧判据把 `holder === null` 直接当陈旧 ⇒ 会删掉
+       * 一个刚被持有、还没写完元数据的锁，两个进程同时进入临界区。实测：4 个进程并发改
+       * 同一文件的不同行，偶发 1 个进程的陈旧闸门报错、两行修改丢失。
+       * 现在空锁给 2 秒宽限：只有 mtime 超过宽限（或超过 staleMs）才回收。
+       */
+      let stale
+      if (holder === null) {
+        let mtime = 0
+        try {
+          mtime = fs.statSync(file).mtimeMs
+        } catch {
+          continue // 锁刚被释放，下一轮重试
+        }
+        stale = Date.now() - mtime > Math.min(staleMs, EMPTY_LOCK_GRACE_MS)
+      } else {
+        const age = Date.now() - Number(holder.createdAt ?? 0)
+        stale = age > staleMs || !processAlive(holder.pid)
+      }
       if (stale) {
         try { fs.rmSync(file, { force: true }) } catch { /* 下一轮再试 */ }
         continue
       }
       if (Date.now() - started > timeoutMs) {
-        throw Object.assign(new Error(`workspace is locked by pid ${holder.pid}`), {
+        const holderLabel = holder === null ? 'an empty lock (pid not written yet)' : `pid ${holder.pid}`
+        throw Object.assign(new Error(`workspace is locked by ${holderLabel}`), {
           code: 'WORKSPACE_LOCKED',
-          holder,
+          holder: holder ?? null,
         })
       }
       await sleep(RETRY_MS)

package/locator-lab/anchor-core.mjs

@@ -12,7 +12,7 @@
  * 唯一的内部状态是 `indexFile` 手里那层**内容派生的记忆化缓存**（见该函数上方注释）：
  * 同一份内容不再被重复建索引，返回值不变。
  * 文件读写、沙箱、观察策略、审批都归调用方——那是各框架自己的事，引擎不该知道。
- * DSH 的 `aura_edit` 工具是本引擎的一个适配器，见 `../aura-edit/index.js`。
+ * DSH 的 `aura_basetools_edit` 工具是本引擎的一个适配器，见 `../aura-edit/index.js`。
  *
  * @module anchor-core
  */

package/locator-lab/args.mjs

@@ -63,23 +63,86 @@ export function flatHunk(source) {
   const ADDRESS_KEYS = FLAT_ADDRESS_KEYS
   if (!ADDRESS_KEYS.some((k) => source[k] !== undefined)) return null
   const hunk = {}
-  for (const key of [...ADDRESS_KEYS, ...HANDLE_SHAPE_KEYS, 'replace', 'expect', 'near']) {
+  for (const key of [...ADDRESS_KEYS, ...HANDLE_SHAPE_KEYS, 'context', 'replace', 'expect', 'near', 'eol', 'replace_all']) {
 
     const value = source[key]
     if (value === undefined || value === null) continue
-    if (typeof value === 'string' && value.length === 0) continue
+    // `replace: ''` 是**删除**，是合法动作；其余空串仍然不是地址/断言。
+    if (typeof value === 'string' && value.length === 0 && key !== 'replace') continue
     hunk[key] = value
   }
   return typeof hunk.replace === 'string' ? hunk : null
 }
 
+/**
+ * 单次读请求的**统一收敛**（单目标与 `targets` 元素共用）。
+ *
+ * 旧版 `readManyTarget` 手写字段转发，`offset` / `limit` / `context` / `kind` / `budget`
+ * 在多目标里被静默丢掉——同一个元素单独读与放进 `targets` 读会得到两种结果。
+ * 这里把“行区间 / 分页 / 模式推断 / 非法组合”收成一份，两个入口都调它。
+ *
+ * `totalLines` 只有在内容已读到时才给得出；第一遍（读文件前）传 undefined，用来尽早拒绝
+ * 形状错误；第二遍传真实行数，用来做 offset 越界与尾行截断。
+ *
+ * @returns `{ok:true, mode, lines, paginate, offset, limit}` 或
+ *   `{ok:false, code:'READ_BAD_ARGS', error}`。
+ */
+export function normalizeReadRequest(args, totalLines = undefined) {
+  const lines = lineRangeOf(args)
+  if (lines === undefined && gaveLineAddress(args)) {
+    return { ok: false, code: 'READ_BAD_ARGS', error: LINE_ADDRESS_HINT }
+  }
+  const paginate = args.offset !== undefined || args.limit !== undefined
+  if (paginate && lines !== undefined) {
+    return { ok: false, code: 'READ_BAD_ARGS', error: 'use either lines/start_line+end_line or offset/limit, not both' }
+  }
+  if (paginate && args.mode !== undefined && args.mode !== null && args.mode !== 'auto') {
+    return { ok: false, code: 'READ_BAD_ARGS', error: `mode=${JSON.stringify(args.mode)} cannot be combined with offset/limit; drop the mode or use lines/start_line+end_line` }
+  }
+  const offset = paginate ? Number(args.offset ?? 0) : null
+  const limit = paginate ? Number(args.limit ?? 2000) : null
+  if (paginate && (!Number.isInteger(offset) || offset < 0 || !Number.isInteger(limit) || limit <= 0)) {
+    return { ok: false, code: 'READ_BAD_ARGS', error: 'offset must be an integer >= 0 and limit an integer > 0' }
+  }
+  let resolvedLines = lines
+  if (paginate && totalLines !== undefined) {
+    if (!Number.isInteger(totalLines) || totalLines < 1 || offset >= totalLines) {
+      return { ok: false, code: 'READ_BAD_ARGS', error: `offset ${offset} is outside 0..${Math.max(0, totalLines - 1)}` }
+    }
+    resolvedLines = { start: offset + 1, end: Math.min(offset + limit, totalLines) }
+  }
+  return {
+    ok: true,
+    mode: paginate ? 'lines' : inferReadMode(args, lines),
+    lines: resolvedLines,
+    paginate,
+    offset,
+    limit,
+  }
+}
 /**
  * 平铺形状的**地址键**（{@link flatHunk} 与未知参数守卫共用同一份名单）。
  *
  * 导出它是为了不再出现第二份：守卫要拿它算“合法键集合”，而如果有两份名单，
  * 新增一种地址写法时必有一处漏改——那正是本项目反复出现的形状。
  */
-export const FLAT_ADDRESS_KEYS = ['target', 'lines', 'start_line', 'end_line', 'line_cue', 'anchor', 'handle']
+export const FLAT_ADDRESS_KEYS = ['target', 'intent', 'lines', 'start_line', 'end_line', 'line_cue', 'anchor', 'handle', 'old']
+
+/**
+ * `targets` 元素（单目标参数）的合法键。
+ *
+ * 与顶层工具键**分开**：`targets` 本身、批量级的 `include_transaction` 都不是元素参数；
+ * 放进元素里只会被静默丢掉。三面（CLI / MCP / DSH）共用这一份，未知键一律
+ * `ARGS_UNKNOWN_KEY`，不再只校验顶层。
+ */
+export const MT_READ_ELEMENT_KEYS = [
+  'file_path', 'mode', 'around', 'lines', 'start_line', 'end_line', 'search', 'context', 'since', 'kind', 'budget', 'max_chars', 'offset', 'limit',
+]
+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',
+  'replace', 'replace_all', 'eol', 'expect', 'near', 'handle', 'line', 'position',
+]
 
 /**
  * 句柄形状的**从属键**（fs-contract-v2 / HD2）：它们只在 `handle` 在场时有意义，
@@ -121,7 +184,7 @@ export function handleShapeVerdict(value) {
  *
  * ## 为什么必须有这道守卫（实测出来的）
  *
- * 真框架**不会**剥掉未声明的参数：实测 `aura_read` 收到 `{file_path, mod: 'map'}` 时
+ * 真框架**不会**剥掉未声明的参数：实测 `aura_basetools_read` 收到 `{file_path, mod: 'map'}` 时
  * `args.mod` 原样到达 `execute`，而工具只读 `args.mode` ⇒ 回一个**默认模式的成功回执**，零反馈。
  * 模型把 `mode` 写成 `mod`、`lines` 写成 `line`、`maxChars` 写成 `max_chars` 时，
  * 它看到的是成功——比报错坏得多（本项目原则：宁可大声失败，不可静默换语义）。
@@ -134,7 +197,7 @@ export function handleShapeVerdict(value) {
  * ## 实测代价（16757 次真实调用）
  *
  * 会被这道守卫拒的：`limit×13`、`offset×10`、`line_cue×2`、`start_mode×1`、`sandbox_permissions×1`
- * （全在 `aura_read` 侧；`aura_edit` 侧**一条都没有**）。
+ * （全在 `aura_basetools_read` 侧；`aura_basetools_edit` 侧**一条都没有**）。
  * 其中 `limit`与`offset` 本意是分页——而本工具的分页参数叫 `start_line`/`end_line`，
  * 静默忽略的结果是“模型以为自己翻页了、实际拿到的是同一段”。报错是**修好**，不是收紧。
  *
@@ -394,6 +457,23 @@ export function assertEditTargets(source, options = {}) {
         { code: 'ARGS_TARGETS_SHAPE', index, got: 'an object without a path' },
       )
     }
+    /**
+     * 元素级布尔参数在**参数面**就判类型：否则 `require_observation:"yes"` 会在
+     * `editTargetRequests` 里抛到编排层之外（dry-run 分支没有 try/catch，CLI 直接吐 Node 栈；
+     * 非 dry-run 还会先建一个事务再回滚）。参数没成形属于 `ARGS_*` 面，与 `USAGE/1` 同档。
+     */
+    for (const key of ['require_observation', 'requireObservation']) {
+      if (element[key] !== undefined && typeof element[key] !== 'boolean') {
+        throw Object.assign(
+          new Error(`${toolName}: \`${targetKey}[${index}].${key}\` must be a boolean — got ${typeWordOf(element[key])}`),
+          { code: 'ARGS_BAD_REQUIRE_OBSERVATION', index, key, got: typeWordOf(element[key]) },
+        )
+      }
+    }
+    // 元素级的未知键：与顶层同一个守卫、同一套报错（合法键由调用方按读/写给）。
+    if (Array.isArray(options.elementKeys)) {
+      assertKnownArgs(element, options.elementKeys, `${toolName} ${targetKey}[${index}]`)
+    }
   })
   return raw
 }
@@ -413,7 +493,7 @@ export function assertEditTargets(source, options = {}) {
  *
  * 为什么不是另一份实现：`assertEditTargets` 里那条互斥判据（`targets` 与单目标形状同时给 ⇒
  * 参数面拒绝）是本仓的**唯一一份**。读侧再写一遍就会漂开 —— 而漂开之后，同一个载荷
- * 在 `aura_read` 被放行、在 `aura_edit` 被拒（或反过来），且两边都不会报错。
+ * 在 `aura_basetools_read` 被放行、在 `aura_basetools_edit` 被拒（或反过来），且两边都不会报错。
  *
  * 读侧元素内部（mode / lines / search / since / kind）本函数**一个字都不解读**：
  * 它们由引擎 `readManyWith` 逐项走今天那套单目标判定器（契约 §2.1「同一个校验器」）。
@@ -486,6 +566,23 @@ export function editTargetRequests(targets) {
     for (const key of ['create', 'identityKey', 'dryRun']) {
       if (element[key] !== undefined) request[key] = element[key]
     }
+    /**
+     * 单目标参数里的 `require_observation` 在这里翻成引擎的驼峰键。
+     *
+     * 旧版只转发 `create/identityKey/dryRun`，于是元素上写 `require_observation: true`
+     * 在参数面被收下、到引擎前被静默丢掉——与“顶层默认值”相反的行为，而且回执照样成功。
+     * 元素显式给了就压过顶层默认（与 `dryRun` 同一口径）。
+     */
+    const requireObservation =
+      element.require_observation !== undefined ? element.require_observation : element.requireObservation
+    if (requireObservation !== undefined) {
+      if (typeof requireObservation !== 'boolean') {
+        throw Object.assign(new Error(`targets[${index}].require_observation must be a boolean`), {
+          code: 'ARGS_BAD_REQUIRE_OBSERVATION',
+        })
+      }
+      request.requireObservation = requireObservation
+    }
     return request
   })
 }