aura-basetools 0.13.2 → 0.14.0

package/README.md

@@ -1,8 +1,8 @@
-# aura-basetools 0.13.2
+# aura-basetools 0.14.0
 
-Byte-exact file tools for coding agents: read by intent, edit by intent, and write whole files without corrupting bytes. One engine shared by a standalone CLI and an MCP server.
+Byte-exact file tools for coding agents: read by intent, edit by address, and write whole files without corrupting bytes. One engine shared by a standalone CLI and an MCP server.
 
-面向 coding agent 的逐字节文件工具：按意图读取、按意图编辑、整文件写入；CLI 与 MCP 共用同一套引擎。
+面向 coding agent 的逐字节文件工具：按意图读取、按地址编辑、整文件写入；CLI 与 MCP 共用同一套引擎。
 
 ---
 
@@ -21,7 +21,7 @@ The engine is intentionally not a general file manager: it reads and edits UTF-8
 ### Install
 
 ```bash
-npm i -g aura-basetools@0.13.2
+npm i -g aura-basetools@0.14.0
 aura --version
 ```
 
@@ -31,8 +31,6 @@ aura --version
 aura basetools read  --file src/app.ts --mode map
 aura basetools edit  --file src/app.ts --hunks '[{"target":"main","replace":"..."}]'
 aura basetools write --file generated.ts --content @body.ts
-aura basetools undo
-aura basetools transactions
 aura basetools mcp
 ```
 
@@ -77,36 +75,35 @@ The server exposes:
 | Tool | Purpose |
 |---|---|
 | `aura_basetools_read` | Intent-based views: `map`, `digest`, `full`, `around`, `lines`, `search`, `changed`, `auto` |
-| `aura_basetools_edit` | Anchored multi-hunk edits; `old` + `replace_all`; optional transaction |
+| `aura_basetools_edit` | Anchored multi-hunk edits; `old` + `replace_all` |
 | `aura_basetools_write` | Whole-file create/overwrite with read-before-write and read-back verification |
-| `aura_basetools_undo` | Undo the latest or a named write transaction |
-| `aura_basetools_transactions` | List write transactions for the current workspace |
+
+0.14.0 removed the public `undo` / `transactions` tools (0 uses in 642 sessions); failure rollback remains internal and automatic.
 
 The older tool names (`aura_read`, `aura_edit`, `aura_write`, ...) are no longer exposed by MCP or DSH.
 
-### Guarantees and verification
+### Why aura-basetools
 
-The 0.13.0 release gate was run on Windows and reported:
+Compared with the DSH built-in `dsh-tool-fs` tools, the differences are deliberate:
 
-| Suite | Result |
-|---|---|
-| `standalone` | 228 / 0 |
-| `range-bytes` | 218 / 218 |
-| `write` | 66 / 66 |
-| `argument-surface` | 18 / 18 |
-| `split-package` | 75 / 75 |
-| `upgrade` | 94 / 94 |
+- **Byte fidelity, not text normalization.** Leading BOM and per-line endings are preserved; only the addressed bytes change. The byte-fidelity suite asserts this with 102 checks.
+- **Read by intent, not whole file.** `map` / `digest` / `lines` / `search` return the structural slice you ask for; the customer comparison measured about 1/24 of the context for the same file.
+- **Edits refuse stale bases.** A region-level gate rejects an edit when the addressed region changed after the read that authorized it, and points at the lines to re-read; `expect` makes the intended text explicit.
+- **Writes are verified, not assumed.** Every write goes through a temp file, flush, rename, and a byte-for-byte read-back; multi-target edits plan first and write nothing if any target fails.
+- **Addressing is structural.** `target` / `lines` / `old` / `expect` / handles replace "copy the literal text exactly"; failure receipts include ready-to-use retry addresses.
+- **The core is DSH-free.** `aura-basetools` has no runtime dependencies and no DSH imports; the DSH adapter is a separate optional package.
+
+Scope note: the byte-level comparison is against the DSH built-in tools. Other clients may already preserve BOM/CRLF (for example ZCode's built-in `Edit`); do not generalize this comparison to every editor.
+
+### Verification
 
-The guarantees the tests exercise:
+The release gate is the source of truth:
 
-- UTF-8 decoding is fatal; invalid UTF-8 is rejected rather than silently replaced.
-- Leading BOM and per-line endings are preserved.
-- Writes go through a temporary file, flush, rename, and a byte-for-byte read-back check.
-- A region-level stale gate and an optional strict read-before-write policy reject edits whose basis changed.
-- Write transactions record original bytes, support rollback/undo, and reject undo when a file changed after the transaction.
-- Multi-target writes plan first; if planning fails, no file is written.
+```bash
+node build/release-check.mjs
+```
 
-Linux CI is configured but was not executed on the local Windows machine used for the 0.13.0 gate. Do not read that sentence as a Linux pass.
+It runs the full suite set, range fixtures, packaged tests, split-package install, and consistency checks. Exact counts and pass/fail are recorded in the GitHub release notes; they are not copied here, so they cannot go stale.
 
 ### Boundaries
 
@@ -129,7 +126,7 @@ MIT.
 `aura-basetools` 是一个 Node.js（>=18）包，运行时零依赖，提供：
 
 - **CLI**：`aura basetools <verb>`
-- **MCP 服务**：stdio 上的五个工具
+- **MCP 服务**：stdio 上的三个工具
 - **不依赖 DSH**：DeepSeek Harness 适配器是独立的可选包 `aura-basetools-dsh`
 
 它不是通用文件管理器：只处理 UTF-8 文本，保留字节级格式；如果被寻址区域在“授权读取”之后被改动，编辑会被拒绝。
@@ -137,7 +134,7 @@ MIT.
 ### 安装
 
 ```bash
-npm i -g aura-basetools@0.13.2
+npm i -g aura-basetools@0.14.0
 aura --version
 ```
 
@@ -147,8 +144,6 @@ aura --version
 aura basetools read  --file src/app.ts --mode map
 aura basetools edit  --file src/app.ts --hunks '[{"target":"main","replace":"..."}]'
 aura basetools write --file generated.ts --content @body.ts
-aura basetools undo
-aura basetools transactions
 aura basetools mcp
 ```
 
@@ -193,36 +188,35 @@ npx -y --package aura-basetools aura basetools mcp
 | 工具 | 作用 |
 |---|---|
 | `aura_basetools_read` | `map` / `digest` / `full` / `around` / `lines` / `search` / `changed` / `auto` |
-| `aura_basetools_edit` | 多 hunk 锚点编辑；`old` + `replace_all`；可选事务 |
+| `aura_basetools_edit` | 多 hunk 锚点编辑；`old` + `replace_all` |
 | `aura_basetools_write` | 整文件新建/覆写；覆写默认要求先读，写后回读校验 |
-| `aura_basetools_undo` | 撤销最近一次或指定写事务 |
-| `aura_basetools_transactions` | 列出当前工作区写事务 |
+
+0.14.0 移除了公开 `undo` / `transactions`（642 个会话中 0 次使用）；失败回滚仍是内部自动行为。
 
 旧工具名（`aura_read`、`aura_edit`、`aura_write` 等）不再由 MCP/DSH 暴露。
 
-### 保证与验证
+### 为什么是 aura-basetools
 
-0.13.0 发布闸在 Windows 上实跑，读数：
+与 DSH 内置 `dsh-tool-fs` 相比，差异是刻意设计的：
 
-| 套件 | 结果 |
-|---|---|
-| `standalone` | 228 / 0 |
-| `range-bytes` | 218 / 218 |
-| `write` | 66 / 66 |
-| `argument-surface` | 18 / 18 |
-| `split-package` | 75 / 75 |
-| `upgrade` | 94 / 94 |
-
-这些套件实际检查：
-
-- UTF-8 解码使用 fatal 模式；非法字节被拒绝，不做静默替换。
-- 保留前导 BOM 与逐行行尾。
-- 写入走同目录临时文件、flush、rename，并做逐字节回读校验。
-- 区域级陈旧闸门；可选的严格“先读后写”策略会拒绝依据已变化的编辑。
-- 写事务记录原始字节，支持回滚/undo；事务后文件又被改过时拒绝 undo。
-- 多目标写入先全量规划；规划失败则一个文件都不写。
-
-Linux CI 已配置，但本机 0.13.0 发布闸是 Windows 实跑；不能据此声称 Linux 已通过。
+- **字节保真，不做文本归一化。** 保留前导 BOM 与逐行行尾，只改被寻址的字节；字节保真套件用 102 条断言守着。
+- **按意图读，不读整份。** `map` / `digest` / `lines` / `search` 只返回你要的结构切片；客户版对照实测同一文件上下文约 1/24。
+- **依据过期就拒绝。** 区域级陈旧闸门在“授权读取之后该区域被改过”时拒绝，并指出重读哪几行；`expect` 让目标原文显式化。
+- **写完要验，不靠相信。** 每次写盘走临时文件、flush、rename，再做逐字节回读；多目标先全量规划，任一失败则一个字节都不写。
+- **寻址是结构化的。** `target` / `lines` / `old` / `expect` / 句柄替代“把原文一字不差抄对”；失败回执带可直接用的重试地址。
+- **核心不依赖 DSH。** `aura-basetools` 零运行时依赖、无 DSH import；DSH 适配器是独立可选包。
+
+范围说明：字节级对照的对象是 DSH 内置工具；其他客户端可能本来就保留 BOM/CRLF（例如 ZCode 内置 `Edit`），不要把该对照泛化到所有编辑器。
+
+### 验证
+
+发布闸是唯一事实源：
+
+```bash
+node build/release-check.mjs
+```
+
+它跑完整套件、三套靶场、包内验收、拆包安装与一致性检查。本次发布的精确读数与通过/失败记录在 GitHub Release notes 里，本文不手抄，避免过期。
 
 ### 边界
 

package/bin/aura-mcp.mjs

@@ -5,12 +5,10 @@
  * 为什么是它：Codex / Claude Code / Cursor / Zed 这些 agent 都吃 MCP —— 一次写壳，到处能用，
  * 且**不要求对方装 DSH**（本文件只依赖 node:fs 与本包的引擎）。
  *
- * 暴露五个工具：
+ * 暴露三个工具：
  *   aura_basetools_read          七种取景（map/digest/full/around/lines/search/changed）+ 版本令牌
  *   aura_basetools_edit          四层寻址 + expect + dry_run；逐字节写回 + 陈旧区域闸门 + 落盘后回读校验
- *   aura_basetools_write         整份写入（对应内置 Write）：新建或整文件替换，同走事务与回读校验
- *   aura_basetools_undo          撤销最近一次/指定写事务（默认拒绝覆盖后续编辑）
- *   aura_basetools_transactions  列出当前工作区写事务
+ *   aura_basetools_write         整份写入（对应内置 Write）：新建或整文件替换，同走原子写与回读校验
  *
  * 接法（写进各家的 MCP 配置即可）：
  *   codex:        codex mcp add aura -- npx -y --package aura-basetools aura basetools mcp
@@ -21,9 +19,9 @@
  * `aura-basetools`；npx 在"多个 bin 且没有与包名同名的"时候会拒绝猜，直接报
  * `could not determine executable to run`（实测）。`--package` 明确指定包，`aura` 才是命令。
  */
-import { readFileSync } from 'node:fs'
+import { readFileSync, realpathSync } from 'node:fs'
 import process from 'node:process'
-import { pathToFileURL } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import {
   openProvider,
   readEnvelope,
@@ -32,8 +30,6 @@ import {
   // 多目标（fs-contract-v2）的引擎绑定：与单目标同一处（`lib/ops.mjs`），bin 里不另找引擎。
   readManyWith,
   editManyEnvelope,
-  undoEnvelope,
-  transactionsEnvelope,
   assertReadTargets,
   assertEditTargets,
   assertTargetShape,
@@ -81,11 +77,6 @@ const HUNK_SCHEMA = {
   type: 'object',
   properties: {
     target: { type: 'string', description: '符号名，如 `toTodoList` 或 `function:apply`；跳过全部文本匹配' },
-    intent: {
-      type: 'string',
-      description:
-        '模糊意图地址：符号名片段、短语或近似原文（如 `parseConfig`、`config loader`、`// retry the upload`），由引擎确定性地落成一个精确区间；歧义时报候选并拒绝（不猜）。单独使用（不与 target/lines/line_cue/anchor/old/context/handle 同用）；可用 near 与 expect',
-    },
     lines: {
       oneOf: [
         { type: 'array' },
@@ -137,7 +128,7 @@ const HUNK_SCHEMA = {
     replace_all: {
       type: 'boolean',
       description:
-        '与 old 同用：替换全部非重叠出现（从左到右），不再要求唯一。不能与 target/intent/lines/line_cue/anchor/context/handle/near 同用；读取后出现次数变了会整体拒绝。',
+        '与 old 同用：替换全部非重叠出现（从左到右），不再要求唯一。不能与 target/lines/line_cue/anchor/context/handle/near 同用；读取后出现次数变了会整体拒绝。',
     },
     eol: {
       type: 'string',
@@ -198,14 +189,13 @@ const TOOLS = [
   {
     name: 'aura_basetools_edit',
     description:
-      'Edit or create a UTF-8 text file with hunks in one call. Address each hunk by intent (fuzzy name/phrase), target (symbol), lines, line_cue, anchor, or old (verbatim content + optional context). With `old`, set `replace_all: true` to replace every non-overlapping occurrence. Writes back byte-for-byte (BOM and per-line endings preserved), refuses a hunk whose addressed region changed since your last read, and reads the file back to verify. All hunks must locate or nothing is written.',
+      'Edit or create a UTF-8 text file with hunks in one call. Address each hunk by target (symbol), lines, line_cue, anchor, or old (verbatim content + optional context). With `old`, set `replace_all: true` to replace every non-overlapping occurrence. Writes back byte-for-byte (BOM and per-line endings preserved), refuses a hunk whose addressed region changed since your last read, and reads the file back to verify. All hunks must locate or nothing is written.',
     inputSchema: {
       type: 'object',
       properties: {
         file_path: { type: 'string' },
         hunks: { type: 'array', items: HUNK_SCHEMA },
         dry_run: { type: 'boolean', description: '只定位不落盘' },
-        include_transaction: { type: 'boolean', description: '在回执里返回 transaction id（默认不返回，保持输出稳定）' },
         require_observation: {
           type: 'boolean',
           description: '严格新鲜度：要求这一版文件在本会话里被读过（或由本工具写过）；否则 PATCH_UNOBSERVED。create 不受影响；dry_run 同样执行这条判决。',
@@ -230,7 +220,7 @@ const TOOLS = [
   {
     name: 'aura_basetools_write',
     description:
-      'Write a whole UTF-8 text file at once (create or overwrite), matching a plain Write tool. Preserves an existing file\'s BOM and line endings, goes through the same transaction/undo path as aura_basetools_edit, and reads the file back to verify bytes. Prefer aura_basetools_edit for partial changes.',
+      'Write a whole UTF-8 text file at once (create or overwrite), matching a plain Write tool. Preserves an existing file\'s BOM and line endings, goes through the same atomic write path as aura_basetools_edit, and reads the file back to verify bytes. Prefer aura_basetools_edit for partial changes.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -247,28 +237,10 @@ const TOOLS = [
           enum: ['auto', 'preserve', 'lf', 'crlf'],
           description: '覆写时的换行风格：auto（默认）适配文件已有风格；preserve 按 content 原样写；lf/crlf 强制。新建文件始终按 content 原样写（非 auto 会被拒绝）。',
         },
-        include_transaction: { type: 'boolean', description: '在回执里返回 transaction id（默认不返回）' },
       },
       required: ['file_path', 'content'],
     },
   },
-  {
-    name: 'aura_basetools_undo',
-    description:
-      'Undo the latest committed write transaction, or the transaction with the given id. Refuses if a file changed after the transaction; pass force=true to override. Restores the exact bytes captured before the write.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        id: { type: 'string', description: '事务 id；省略则撤销最近一条 committed 事务' },
-        force: { type: 'boolean', description: '即使文件在事务后又被改过也强制恢复' },
-      },
-    },
-  },
-  {
-    name: 'aura_basetools_transactions',
-    description: 'List write transactions for the current workspace (id, status, file count, time).',
-    inputSchema: { type: 'object', properties: {} },
-  },
 ]
 
 /**
@@ -351,7 +323,6 @@ async function editTargetsCall(provider, args) {
   return await editManyEnvelope(provider, {
     targets,
     dryRun: args.dry_run === true,
-    includeTransaction: args.include_transaction === true,
     ...(args.require_observation === true ? { requireObservation: true } : {}),
   })
 }
@@ -436,7 +407,6 @@ async function callTool(provider, name, args = {}) {
       hunks: Array.isArray(args.hunks) ? args.hunks : [],
       dryRun: args.dry_run === true,
       create: creating ? args.create : undefined,
-      includeTransaction: args.include_transaction === true,
       ...(args.require_observation === true ? { requireObservation: true } : {}),
     })
   }
@@ -446,13 +416,10 @@ async function callTool(provider, name, args = {}) {
       content: args.content,
       dryRun: args.dry_run === true,
       noOverwrite: args.no_overwrite === true,
-      includeTransaction: args.include_transaction === true,
       allowUnobserved: args.allow_unobserved === true,
       ...(typeof args.eol === 'string' ? { eol: args.eol } : {}),
     })
   }
-  if (name === 'aura_basetools_undo') return await undoEnvelope(provider, { id: args.id, force: args.force === true })
-  if (name === 'aura_basetools_transactions') return transactionsEnvelope(provider)
   return { ok: false, error: `unknown tool ${JSON.stringify(name)}`, code: 'UNKNOWN_TOOL' }
 }
 
@@ -561,6 +528,25 @@ export async function serve() {
 
 // 直接运行本文件（`aura-mcp`，package.json 里声明的第二个 bin）也要起服务，与 `aura basetools mcp` 等价。
 // 用 pathToFileURL 比手拼 file:// 靠得住（Windows 盘符就是那种手拼会踩的地方）。
-if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+/**
+ * 直接执行本文件才起 stdio 服务。
+ *
+ * 不能只比 `import.meta.url === pathToFileURL(argv[1])`：macOS 的临时目录
+ * `/var/folders/...` 是 `/private/var/folders/...` 的符号链接，Node 给模块的 URL 与
+ * argv 的写法可能一侧已 realpath、另一侧没有 ⇒ 服务静默退出，客户端看到 0 个工具
+ * （post-publish / split-package 在 macOS 上正是这条）。两边都过 realpath 再比。
+ */
+function isDirectRun() {
+  const invoked = process.argv[1]
+  if (invoked === undefined) return false
+  if (import.meta.url === pathToFileURL(invoked).href) return true
+  try {
+    return realpathSync.native(fileURLToPath(import.meta.url)) === realpathSync.native(invoked)
+  } catch {
+    return false
+  }
+}
+
+if (isDirectRun()) {
   await serve()
 }

package/bin/aura.mjs

@@ -6,8 +6,6 @@
  *   aura basetools edit  --file F (--hunks '<json>' | --hunks-file P) [--dry-run] [--create <文本|@文件>]
  *   aura basetools read  --targets '[...]|@spec.json'                    一次读多个目标（与 --file 互斥）
  *   aura basetools edit  --targets '[...]|@spec.json'                    一次改多个文件（与 --file 互斥；任一规划失败 ⇒ 零写入）
- *   aura basetools undo [--id <事务 id>] [--force]                      撤销最近一次/指定写事务
- *   aura basetools transactions                                         列出当前工作区写事务
  *   aura basetools mcp
  *   aura --help | --version
  *
@@ -27,8 +25,6 @@ import {
   // 多目标（fs-contract-v2）的引擎绑定：与单目标同一处（`lib/ops.mjs`），bin 里不另找引擎。
   readManyWith,
   editManyEnvelope,
-  undoEnvelope,
-  transactionsEnvelope,
   capabilitiesEnvelope,
   writeEnvelope,
   assertReadTargets,
@@ -74,7 +70,7 @@ let command = argv[0]
  * 有了这份名单，“下一个是已知布尔旗标”才当没带值，**其它以 `--` 开头的东西都当值**。
  * 代价是名单要维护；收益是那个静默丢值的路径从根上消失，而不是靠叫用户改写法。
  */
-const BOOLEAN_FLAGS = new Set(['pretty', 'dry-run', 'plan', 'transaction', 'force', 'no-overwrite', 'replace-all', 'require-observation', 'allow-unobserved', 'json'])
+const BOOLEAN_FLAGS = new Set(['pretty', 'dry-run', 'plan', 'no-overwrite', 'replace-all', 'require-observation', 'allow-unobserved', 'json'])
 const isBooleanFlag = (token) => typeof token === 'string' && BOOLEAN_FLAGS.has(token.replace(/^--/, ''))
 
 /**
@@ -90,15 +86,13 @@ const COMMAND_FLAGS = {
     bool: ['pretty'],
   },
   edit: {
-    value: ['cwd', 'file', 'targets', 'hunks', 'hunks-file', 'create', 'target', 'intent', 'lines', 'start-line', 'end-line', 'line-cue', 'anchor', 'old', 'context', 'handle', 'line', 'position', 'replace', 'expect', 'near', 'eol'],
-    bool: ['pretty', 'dry-run', 'plan', 'transaction', 'replace-all', 'require-observation'],
+    value: ['cwd', 'file', 'targets', 'hunks', 'hunks-file', 'create', 'target', 'lines', 'start-line', 'end-line', 'line-cue', 'anchor', 'old', 'context', 'handle', 'line', 'position', 'replace', 'expect', 'near', 'eol'],
+    bool: ['pretty', 'dry-run', 'plan', 'replace-all', 'require-observation'],
   },
   write: {
     value: ['cwd', 'file', 'content', 'eol'],
-    bool: ['pretty', 'dry-run', 'plan', 'transaction', 'no-overwrite', 'allow-unobserved'],
+    bool: ['pretty', 'dry-run', 'plan', 'no-overwrite', 'allow-unobserved'],
   },
-  undo: { value: ['cwd', 'id'], bool: ['pretty', 'force'] },
-  transactions: { value: ['cwd'], bool: ['pretty'] },
   doctor: { value: ['cwd'], bool: ['pretty', 'json'] },
   capabilities: { value: ['cwd'], bool: ['pretty'] },
   mcp: { value: ['cwd'], bool: ['pretty'] },
@@ -177,20 +171,20 @@ const USAGE = [
   "  aura basetools edit  --file <路径> (--hunks '<json>' | --hunks-file <路径>) [--dry-run|--plan] [--eol auto|preserve|lf|crlf] [--require-observation]",
   '   aura basetools edit  --file <路径> --lines <a,b> --replace <文本> [--expect <文本>] [--near <n>]',
   '   aura basetools edit  --file <路径> --old <原文> --replace <文本> --replace-all        # 改全部非重叠出现',
-  "              （只改一处时不必包成 JSON：--target / --intent / --lines / --start-line+--end-line / --line-cue / --anchor 任选其一）",
+          "              （只改一处时不必包成 JSON：--target / --lines / --start-line+--end-line / --line-cue / --anchor 任选其一）",
   // 句柄（fs-contract-v2 §5）：读侧发的柄 + 三种定位写法。下面三行是三种**用法**，不是三种键。
   '   aura basetools edit  --file <路径> --handle <h…> --replace <文本>                          # 整段替换：区间由柄定，不靠转述',
   '   aura basetools edit  --file <路径> --handle <h…> --line <段内行号> --replace <文本>            # 只换区间内第 k 行（1-based，从区间首行数起）',
   '   aura basetools edit  --file <路径> --handle <h…> --position before|after --replace <文本>  # 在区间边界插入，区间本身不动',
   "              （--line / --position 是从属键：只有与 --handle 同时给才成立，单独给不构成一次编辑）",
   '  aura basetools mcp                    启动 MCP stdio 服务',
-  '  aura basetools write --file <路径> --content <文本|@文件> [--no-overwrite] [--dry-run|--plan] [--transaction] [--allow-unobserved] [--eol auto|preserve|lf|crlf]',
+  '  aura basetools write --file <路径> --content <文本|@文件> [--no-overwrite] [--dry-run|--plan] [--allow-unobserved] [--eol auto|preserve|lf|crlf]',
   '             （覆写默认要求先读过这一版；--allow-unobserved 才允许盲写）',
   '  aura basetools doctor [--json]        自检：Node/版本/MCP 握手/缓存与锁目录可写',
   '  aura basetools capabilities [--pretty] 能力清单：读模式/地址档/语言/限制（JSON）',
   '  aura --help | --version',
   '',
-  'hunks 形状：[{"target":"符号名"|"intent":"模糊意图（符号片段/短语/近似原文）"|"lines":[a,b]|"line_cue":"唯一词"|"anchor":"记得的原文",',
+      'hunks 形状：[{"target":"符号名"|"lines":[a,b]|"line_cue":"唯一词"|"anchor":"记得的原文",',
   '              "replace":"替换文本","expect":"该处应是什么","near":行号}]',
   '',
   '例：',
@@ -311,7 +305,7 @@ if (command === '--version' || command === '-v') emit({ ok: true, version: VERSI
  * 旧顶层动词只给**迁移提示**，不再作为别名执行——保留别名等于保留未来的撞名。
  * 只提示、不执行：`aura basetools read` 不会偷偷改文件。
  */
-const MOVED_COMMANDS = new Set(['read', 'outline', 'edit', 'write', 'undo', 'transactions', 'mcp', 'doctor', 'capabilities'])
+const MOVED_COMMANDS = new Set(['read', 'outline', 'edit', 'write', 'mcp', 'doctor', 'capabilities'])
 if (!namespaced && MOVED_COMMANDS.has(command)) {
   emit(
     {
@@ -356,26 +350,12 @@ if (command === 'write') {
     content,
     dryRun: has('dry-run') || has('plan'),
     noOverwrite: has('no-overwrite'),
-    includeTransaction: has('transaction'),
     allowUnobserved: has('allow-unobserved'),
     ...(typeof eol === 'string' ? { eol } : {}),
   })
   emit(env, env.ok ? 0 : 2)
 }
 
-if (command === 'undo') {
-  const env = await undoEnvelope(provider, {
-    id: typeof flag('id') === 'string' ? flag('id') : undefined,
-    force: has('force'),
-  })
-  emit(env, env.ok ? 0 : 2)
-}
-
-if (command === 'transactions') {
-  const env = transactionsEnvelope(provider)
-  emit(env, 0)
-}
-
 if (command === 'doctor') {
   /**
    * `aura basetools doctor`：把“装完能不能用”的机械检查放在 CLI 自己身上。
@@ -492,7 +472,6 @@ if (command === 'edit') {
     const env = await editManyEnvelope(provider, {
       targets: spec.targets,
       dryRun: has('dry-run') || has('plan') || spec.dryRun,
-      includeTransaction: has('transaction'),
       ...(has('require-observation') ? { requireObservation: true } : {}),
     })
     emit(env, env.ok ? 0 : 2)
@@ -509,8 +488,6 @@ if (command === 'edit') {
    */
   const flat = flatHunk({
     target: flag('target'),
-    // 意图地址（T16）：`--intent 'config loader'` 一句话定位一处改动，不要求符号全名或原文。
-    intent: flag('intent'),
     lines: flag('lines'),
     start_line: flag('start-line'),
     end_line: flag('end-line'),
@@ -593,7 +570,7 @@ if (command === 'edit') {
       {
         ok: false,
         error:
-          'edit 需要 --hunks/--hunks-file，或平铺一组地址旗标（--target / --intent / --lines / --start-line+--end-line / --line-cue / --anchor / --handle（配 --line 或 --position），外加 --replace），或 --create <整份内容>',
+      'edit 需要 --hunks/--hunks-file，或平铺一组地址旗标（--target / --lines / --start-line+--end-line / --line-cue / --anchor / --handle（配 --line 或 --position），外加 --replace），或 --create <整份内容>',
         code: 'USAGE',
       },
       1,
@@ -607,7 +584,6 @@ if (command === 'edit') {
     hunks: hunks ?? [],
     dryRun: has('dry-run') || has('plan'),
     create,
-    includeTransaction: has('transaction'),
     ...(has('require-observation') ? { requireObservation: true } : {}),
   })
   emit(env, env.ok ? 0 : 2)

package/lib/ops.mjs

@@ -13,7 +13,7 @@ import fs from 'node:fs'
 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'
 
 /**
@@ -93,8 +93,8 @@ export function capabilitiesEnvelope() {
         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'],
+          cli: ['workspace-lock', 'stale-region-gate', 'byte-verify'],
+          mcp: ['workspace-lock', 'stale-region-gate', 'byte-verify'],
           dsh: ['stale-region-gate', 'byte-verify'],
         },
       },
@@ -103,14 +103,14 @@ export function capabilitiesEnvelope() {
         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/工作区锁；它经过引擎的区域闸、严格新鲜度与回读校验。
+          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: {
@@ -489,12 +489,9 @@ 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
   try {
     return await withWorkspaceLock(provider.root, async () => {
       const tx = createTransaction(provider.root, 'aura_basetools_edit')
@@ -508,10 +505,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,7 +520,6 @@ 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_basetools_edit')
@@ -538,14 +534,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)
@@ -579,7 +574,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 +594,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' } = {}) {
   if (typeof file !== 'string' || file.length === 0) {
     return { ok: false, error: 'write needs a file path', code: 'WRITE_BAD_ARGS' }
   }
@@ -627,7 +621,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 }), content)
     }
     return compactWriteReceipt(
       await editEnvelope(provider, {
@@ -635,7 +629,6 @@ 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',
@@ -646,17 +639,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) }
-}