@thincoder/core 0.9.4 → 0.10.1

package/index-discover.mjs

@@ -8,14 +8,14 @@
  * PORTABILITY VSC mirror · VP-9 (P9): the extension tables were 14 code + 5 doc
  * entries with no declaration surface — a project in any other mainstream language
  * was invisible AND undeclarable, silently. Now: the tables carry the CLI-aligned
- * additions, `.thincoder/conventions.json` (index.codeExtensions / index.docExtensions)
- * unions in project-specific extensions, and files whose extension is in NO list are
+ * additions, the manifest's `index.codeExtensions` / `index.docExtensions` union in
+ * project-specific extensions, and files whose extension is in NO list are
  * TALLIED (`collectUnlisted`) so "my .xyz files are not searchable" stops being
  * invisible (buildIndex → panel hint + a log event).
  */
 import { readdirSync } from "node:fs"
 import { join, relative } from "node:path"
-import { DEFAULT_CONVENTIONS, loadConventions } from "./conventions.mjs"
+import { DEFAULT_DECLARATION, loadProjectDeclaration } from "./conventions.mjs"
 
 const CODE_EXTS = new Set([
   ".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".py", ".rs", ".go", ".java", ".c", ".cpp", ".h", ".hpp",
@@ -36,11 +36,11 @@ function extensionOf(p) {
 }
 
 /** Effective extension sets for one conventions object: defaults ∪ declared
- *  (declaration is a UNION — §4.1: index.*Extensions APPEND). Cached per frozen
+ *  (declaration is a UNION — §3.1: index.*Extensions APPEND). Cached per frozen
  *  conventions object (the loader hands out stable per-root instances). */
 const _knownCache = new WeakMap()
 function knownExtensions(conv) {
-  const key = conv ?? DEFAULT_CONVENTIONS
+  const key = conv ?? DEFAULT_DECLARATION
   let hit = _knownCache.get(key)
   if (!hit) {
     const code = new Set(CODE_EXTS)
@@ -126,7 +126,7 @@ function isIndexableName(name, allExts) {
  *   files array (backward-compatible with needsRebuild / the memory self-check).
  */
 export function discoverFiles(cwd, signal, { collectUnlisted = false } = {}) {
-  const res = collectFiles(cwd, cwd, false, signal, loadConventions(cwd), collectUnlisted)
+  const res = collectFiles(cwd, cwd, false, signal, loadProjectDeclaration(cwd), collectUnlisted)
   return collectUnlisted ? res : res.files
 }
 
@@ -135,7 +135,7 @@ export function discoverFiles(cwd, signal, { collectUnlisted = false } = {}) {
 export function discoverFilesUnder(cwd, subdir, { collectUnlisted = false } = {}) {
   const base = String(subdir ?? "").replaceAll("\\", "/").replace(/\/+$/, "")
   if (!base) return collectUnlisted ? { files: [], unlisted: { count: 0, exts: [] } } : []
-  const res = collectFiles(join(cwd, base), cwd, false, undefined, loadConventions(cwd), collectUnlisted)
+  const res = collectFiles(join(cwd, base), cwd, false, undefined, loadProjectDeclaration(cwd), collectUnlisted)
   return collectUnlisted ? res : res.files
 }
 

package/ledger-cmd.mjs

@@ -1,15 +1,20 @@
 /**
- * ledger-cmd.mjs — 台账命令族（查询 = 只读全角色 / 写 = 仅主 agent 装配）+ 工具定义
- * （M2 模块拆分件——设计档 docs/core/design/modules/ENGINEERING-MODE-V2-MODULE-LEDGER.md §2.3 拆分计划）。
+ * ledger-cmd.mjs — 台账核心函数档（查询 = 只读全角色 / 写 = 仅主 agent 装配）。
+ * 工具定义 + 工具层参数守卫 = 拆分件 `thincoder-core/ledger-tools.mjs`（2026-09-28 守卫族微修批 ·
+ * 台账 #473——纯搬移、语义零变；拆分触发 = 本档 298 行贴 300 顾问线，本批读面守卫增量必越线）；
+ * 核函数（`ledgerQuery` / `ledgerCount` / `ledgerAdd` / `ledgerUpdate` / `ledgerClose`）留本档，
+ * 工具档消费之。
  *
- * 接线（设计档 §2.2 命令面接线）：查询命令 ← tools/index.mjs（assembleBuiltinTools 全角色面）；
- * 写命令 ← agent/family-tools.mjs（assembleFamilyTools 的 depthOnly 分支）——一律**动态 import** 本模块链
- * （ledger-db.mjs 静态 import node:sqlite ⇒ 消费侧静态 import 会破 W8 契约②）。
+ * 接线（设计档 §2.2 命令面接线）：族出口 = `ledger.mjs`（re-export 两源——KD-M2-3）；查询命令 ←
+ * tools/index.mjs（assembleBuiltinTools 全角色面）；写命令 ← agent/family-tools.mjs（assembleFamilyTools
+ * 的 depthOnly 分支）——一律**动态 import** 本模块链（ledger-db.mjs 静态 import node:sqlite ⇒
+ * 消费侧静态 import 会破 W8 契约②）。
  */
 import { statSync } from "node:fs"
-import { resolve } from "node:path"
+import { basename, resolve } from "node:path"
 import { ALLOWED_MIGRATIONS, nowIso, openLedger, PENDING_STATUSES } from "./ledger-db.mjs"
 import { resolveProjectRoot } from "./manifest.mjs"
+import { declaredPublicRoots } from "./declaration.mjs"
 
 /** 查询（只读，全角色）：SELECT 行集（status/kind/board 过滤，缺省 = 全部行；id 升序）。库不在 = 空账。 */
 export function ledgerQuery({ cwd, status = null, kind = null, board = null } = {}) {
@@ -37,21 +42,31 @@ export function ledgerCount({ cwd } = {}) {
 /** 路径 = 存在的**档**？（目录 / 缺失 → false——写门存在性判据用）。 */
 const isFile = (p) => { try { return statSync(p).isFile() } catch { return false } }
 
-/** 写门·指针存在性（设计档 §6.1 · 台账 #38 · AC-M2-9）：写命令落盘前判**结果行**——`status ∈
- *  {在途, 待核销}` 且 `task_book` 非空 ⇒ 文件部分（首个 `§` 前子串，trim）须经基准 `resolve(base, …)`
- *  指向存在的档；缺文件部分（`§2` / 全空白）⇒ 拒；不在册 / 非文件 ⇒ 拒（throw，行不变）。
+/** 写门·指针存在性（设计档 §6.1 · 台账 #38 · AC-M2-10）：写命令落盘前判**结果行**——`status ∈
+ *  {在途, 待核销}` ⇒ 判 `task_book`：`null`（缺指针）⇒ 拒（「必填」文案）；非 `null` ⇒ 文件部分
+ *  （首个 `§` 前子串，trim）须经基准 `resolve(base, …)` 指向存在的档；缺文件部分（`§2` / 空串 /
+ *  全空白）⇒ 拒；不在册 / 非文件 ⇒ 拒（throw，行不变）。
  *  判位与迁移表判同层（落盘前）；文案前缀 = 调用函数名（与同函数既有两条文案同款）。
  *  基准 `base` = **与台账库关联键同源**（2026-09-18 fix 轮 · O1 收正）：`resolveProjectRoot(cwd) ??
  *  resolve(cwd ?? ".")`——同表达式见 `ledger-db.mjs` `ledgerDbPath`；容器根会话（锚 cwd 下唯一注册
- *  子仓 P）与子仓会话 ⇒ 库键与指针基准同取 P（同库同基准；原实现 `resolve(cwd, …)` = 原始 cwd 会误拒）。 */
+ *  子仓 P）与子仓会话 ⇒ 库键与指针基准同取 P（同库同基准；原实现 `resolve(cwd, …)` = 原始 cwd 会误拒）。
+ *  #832：声明源前缀形同判（§6.15——首段 = 声明公共仓目录名 ⇒ 于该声明根解析；可核 ⇒ 通过；缺位拒）。 */
 function assertTaskBookGate(cwd, fnName, status, taskBook) {
   if (status !== "在途" && status !== "待核销") return
-  if (taskBook == null || taskBook === "") return
+  if (taskBook == null) throw new Error(`${fnName}：task_book 必填（在途 / 待核销 须携任务书指针）`)
   const part = String(taskBook).split("§")[0].trim()
   if (!part) throw new Error(`${fnName}：task_book 不可解析（缺文件部分）：${taskBook}`)
   const base = resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")
   const abs = resolve(base, part)
-  if (!isFile(abs)) throw new Error(`${fnName}：task_book 指向的档不存在：${taskBook}（解析 = ${abs}）`)
+  // §6.15 声明源候选（#832 · LEDGER.md §6.1-4）：首段 = 声明公共仓目录名 ⇒ 该声明根解析余段（同名多仓 ⇒ 声明序首者）；未声明 ∥ 缺位 ⇒ 照旧拒。
+  if (isFile(abs)) return
+  const segs = part.replace(/\\/g, "/").split("/").filter(Boolean)
+  for (const root of declaredPublicRoots(base)) {
+    if (segs[0] !== basename(root)) continue
+    if (segs.length > 1 && isFile(resolve(root, segs.slice(1).join("/")))) return
+    break
+  }
+  throw new Error(`${fnName}：task_book 指向的档不存在：${taskBook}（解析 = ${abs}）`)
 }
 
 /** 新增（写命令，仅主 agent）：INSERT——入待讨论（六态状态机入口）。 */
@@ -101,7 +116,9 @@ export function ledgerUpdate({ cwd, id, patch, executorSessionId }) {
   } finally { db.close() }
 }
 
-/** 收口（写命令，仅主 agent）：勾销（待核销 → 已核销）/ 撤回（任意态 → 已废弃），事务包裹；归档 = 软删除。 */
+/** 收口（写命令，仅主 agent）：核销两源（勾销：待核销 → 已核销；追认核销：待讨论 / 待设计 → 已核销，
+ *  行 `evidence` 非空，缺 / 全空白 ⇒ 拒）/ 撤回（任意态 → 已废弃），事务包裹；归档 = 软删除。
+ *  判序（同函数体同层）：目标集判 → 行取 → 源态判 → `evidence` 门 → UPDATE（LEDGER.md §3 收口两源）。 */
 export function ledgerClose({ cwd, id, status }) {
   if (status !== "已核销" && status !== "已废弃") throw new Error(`ledgerClose：目标态 ${status} ∉ {已核销, 已废弃}`)
   const db = openLedger(cwd, { create: true })
@@ -110,123 +127,14 @@ export function ledgerClose({ cwd, id, status }) {
     try {
       const row = db.prepare("SELECT * FROM items WHERE id = ?").get(id)
       if (!row) throw new Error(`ledgerClose：行 ${id} 不存在`)
-      if (status === "已核销" && row.status !== "待核销") throw new Error(`ledgerClose：勾销仅限待核销（现态 ${row.status}）`)
+      // 判序：源态判（核销仅三源——在途不可跳）→ 追认口 `evidence` 门（行字段非空，缺 / 全空白 ⇒ 拒）
+      if (status === "已核销" && !["待讨论", "待设计", "待核销"].includes(row.status)) throw new Error(`ledgerClose：核销仅限 待讨论 / 待设计 / 待核销（现态 ${row.status}）`)
+      if (status === "已核销" && ["待讨论", "待设计"].includes(row.status) && (row.evidence == null || String(row.evidence).trim() === "")) throw new Error(`ledgerClose：追认核销须带 evidence（现态 ${row.status}）`)
       const now = nowIso()
-      // 撤回（任意态 → 已废弃——含在途直撤）同步 executor = NULL（LEDGER.md §3.1 ④）；勾销路径 executor 已在离场迁移清空，零触碰
+      // 撤回（任意态 → 已废弃——含在途直撤）同步 executor = NULL（LEDGER.md §3.1 ④）；核销两源（勾销 / 追认）executor 零触碰（非在途出边）
       db.prepare("UPDATE items SET status = ?, closed_at = ?, updated_at = ?, executor = ? WHERE id = ?").run(status, now, now, status === "已废弃" ? null : row.executor, id)
       db.exec("COMMIT")
       return { id, status }
     } catch (e) { db.exec("ROLLBACK"); throw e }
   } finally { db.close() }
 }
-
-// ── 工具定义（接线：查询 → tools/index.mjs 全角色面；写 → family-tools.mjs depthOnly 分支） ──
-
-/** 工具 cwd 供值面（缺省 → 当前项目根）。 */
-const cwdOf = (ctx) => ctx?.agent?.cwd ?? ctx?.cwd ?? process.cwd()
-
-export const ledgerQueryTool = {
-  name: "ledger_query",
-  description: "台账查询（需求池 / 技术待办）——SQLite 行集，只读、全角色可用。未决四态 = 待讨论 / 待设计 / 在途 / 待核销；已核销 / 已废弃 = 归档态（软删除，行保留）。过滤参数缺省 = 全部行。",
-  parameters: {
-    type: "object",
-    properties: {
-      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
-      status: { type: "string", enum: ["待讨论", "待设计", "在途", "待核销", "已核销", "已废弃"], description: "按状态过滤（六态之一，缺省 = 不过滤）" },
-      kind: { type: "string", enum: ["requirement", "tech_todo"], description: "按类别过滤" },
-      board: { type: "string", description: "按归属板块过滤（需求档文档名）" },
-    },
-  },
-  readonly: true,
-  async execute(args, ctx) {
-    return JSON.stringify(ledgerQuery({ cwd: args.cwd ?? cwdOf(ctx), status: args.status, kind: args.kind, board: args.board }), null, 2)
-  },
-}
-
-export const ledgerCountTool = {
-  name: "ledger_count",
-  description: "台账计数单源：未决四态（待讨论 / 待设计 / 在途 / 待核销）COUNT(*)，只读、全角色可用。",
-  parameters: {
-    type: "object",
-    properties: { cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" } },
-  },
-  readonly: true,
-  async execute(args, ctx) {
-    return JSON.stringify({ count: ledgerCount({ cwd: args.cwd ?? cwdOf(ctx) }) })
-  },
-}
-
-export const ledgerAddTool = {
-  name: "ledger_add",
-  description: "台账新增条目（写命令，仅主 agent）——入待讨论（六态状态机入口）。kind = requirement（需求池）/ tech_todo（技术待办）；trigger = 归批 / 条件 / 认账不排期（可空）。",
-  parameters: {
-    type: "object",
-    required: ["kind", "title"],
-    properties: {
-      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
-      kind: { type: "string", enum: ["requirement", "tech_todo"], description: "类别" },
-      title: { type: "string", description: "条目标题" },
-      board: { type: "string", description: "归属板块（需求档文档名，可空）" },
-      req_doc: { type: "string", description: "需求档指针（可空）" },
-      task_book: { type: "string", description: "任务书指针（可空；在途 / 待核销必填——咬合 CHECK）" },
-      evidence: { type: "string", description: "最小证据行（可空）" },
-      trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "技术待办触发（可空）" },
-    },
-  },
-  readonly: false,
-  async execute(args, ctx) {
-    const { cwd, ...row } = args
-    const id = ledgerAdd({ cwd: cwd ?? cwdOf(ctx), row })
-    return JSON.stringify({ id, status: "待讨论" })
-  },
-}
-
-export const ledgerUpdateTool = {
-  name: "ledger_update",
-  description: "台账更新条目（写命令，仅主 agent）——状态迁移按六态允许迁移表：待讨论→待设计 / 待设计→在途 / 在途→待核销 / 待核销→已核销 / 任意态→已废弃；表外迁移被拒。status 缺省 = 仅更新字段。",
-  parameters: {
-    type: "object",
-    required: ["id"],
-    properties: {
-      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
-      id: { type: "number", description: "条目 id" },
-      status: { type: "string", description: "目标状态（六态之一，缺省 = 不变）" },
-      title: { type: "string", description: "标题（缺省 = 不变）" },
-      board: { type: "string", description: "归属板块（缺省 = 不变）" },
-      req_doc: { type: "string", description: "需求档指针（缺省 = 不变）" },
-      task_book: { type: "string", description: "任务书指针（缺省 = 不变）" },
-      evidence: { type: "string", description: "证据（缺省 = 不变）" },
-      trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "触发（缺省 = 不变）" },
-      executor: { type: "string", description: "执行者 sessionId（可选——接手改写归属用；缺省 = 按状态迁移语义：进在途自动写本会话 / 出在途自动清空 / 其余不变）" },
-    },
-  },
-  readonly: false,
-  async execute(args, ctx) {
-    const { cwd, id, ...patch } = args
-    let executorSessionId
-    if (patch.executor === undefined) {
-      // 动态 import——零新静态边（K-LX1）；工具层供值，核心函数保持参数注入纯函数
-      const { getSessionId } = await import("./session-slots.mjs")
-      executorSessionId = getSessionId()
-    }
-    return JSON.stringify(ledgerUpdate({ cwd: cwd ?? cwdOf(ctx), id, patch, executorSessionId }))
-  },
-}
-
-export const ledgerCloseTool = {
-  name: "ledger_close",
-  description: "台账收口（写命令，仅主 agent）——勾销：待核销 → 已核销；撤回：任意态 → 已废弃。归档 = 软删除（写 closed_at，行保留）。",
-  parameters: {
-    type: "object",
-    required: ["id", "status"],
-    properties: {
-      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
-      id: { type: "number", description: "条目 id" },
-      status: { type: "string", enum: ["已核销", "已废弃"], description: "目标态（勾销 / 撤回）" },
-    },
-  },
-  readonly: false,
-  async execute(args, ctx) {
-    return JSON.stringify(ledgerClose({ cwd: args.cwd ?? cwdOf(ctx), id: args.id, status: args.status }))
-  },
-}

package/ledger-db.mjs

@@ -7,8 +7,10 @@
  * 本档静态 import node:sqlite ⇒ 消费侧一律动态 import 本模块链（W8 契约②——KD-M2-3）。
  *
  * 落点（2026-09-17 用户裁定收正）：台账库**不在项目目录**——住用户数据目录
- * `~/.thincoder/ledger/<sha1(项目根绝对路径)[:16]>.db`（工作树外、天然不进 git；
+ * `~/.thincoder/ledger/<sha1(normalizeCwd(项目根绝对路径))[:16]>.db`（工作树外、天然不进 git；
  * 同区先例 = configDir 的 memory.db / tool-results）。项目根仅作**关联键**，不在项目内留任何文件。
+ * 键归一（2026-09-25 批 ledger-key-normalize · 台账 #286）：盘符大写契约直引 `session-slots.mjs`
+ * `normalizeCwd`——与 session / checkpoint / traces / peers 同契约，跨端同 cwd 同键同库。
  */
 import { createHash } from "node:crypto"
 import { existsSync, mkdirSync } from "node:fs"
@@ -16,7 +18,9 @@ import { join, resolve } from "node:path"
 import { DatabaseSync } from "node:sqlite"
 
 import { configDir } from "./config-io.mjs"
-import { resolveProjectRoot } from "./manifest.mjs"
+import { projectRootView, resolveProjectRoot } from "./manifest.mjs"
+// 归一步单源（KD-LN1——直引，不抽新 util：先例 = peer-domains.mjs / traces/trace-store.mjs）。
+import { normalizeCwd } from "./session-slots.mjs"
 
 /** 台账库目录（默认 = 用户数据目录；测试注入面 `_setLedgerDirForTest` 覆盖）。 */
 let ledgerDir = join(configDir, "ledger")
@@ -25,11 +29,27 @@ let ledgerDir = join(configDir, "ledger")
 export function _setLedgerDirForTest(dir) { ledgerDir = dir }
 export function _resetLedgerDirForTest() { ledgerDir = join(configDir, "ledger") }
 
-/** 项目根 → 库路径（稳定键 = sha1(规范化项目根绝对路径) 前 16 位——路径唯一标识，不含分隔符。
- *  项目根与 manifest 同一判据（git 仓根 / 显式声明容器根）——两端会话键一致）。 */
+/** 台账库目录读数（设计档 §7.1 导出面）：键控库住它；迁移 / 审计面默认根 = 本值——备份 /
+ *  回收目录取它的**兄弟位**（同派生于可覆盖基⇒ `_setLedgerDirForTest` 覆盖后三者同随）。 */
+export function ledgerDirPath() { return ledgerDir }
+
+/** 项目根 → 库键（**键式单源**——设计档 `LEDGER.md` §2.1：键只在**本函数**一处生成）：
+ *  `sha1(normalizeCwd(root))[:16]`——`normalizeCwd`（盘符统一大写）是唯一补丁面：`resolve()`
+ *  已覆盖分隔符 / 点段 / 尾斜杠；非盘符段大小写**不折叠**（§2.1 不做段）。
+ *  @param {string} root 项目根绝对路径
+ *  @returns {string} 16 位十六进制键 */
+export function ledgerKey(root) {
+  return createHash("sha1").update(normalizeCwd(root)).digest("hex").slice(0, 16)
+}
+
+/** 项目根 → 库路径（稳定键 = `ledgerKey` 前 16 位——路径唯一标识，不含分隔符）。
+ *  项目根与 manifest 同一判据（归属 ∨ 发现——`resolveProjectRoot`；无 manifest ⇒ `resolve(cwd ?? ".")`
+ *  兜底且**单值**）——与写门指针基准同一子表达式（键另加 `normalizeCwd` 一步，§2.1）。
+ *  v2 键归一（2026-09-25 批）：盘符本大写（CLI）⇒ 键恒等零变；小写盘符（VSC `uri.fsPath`）
+ *  并入同键 ⇒ 同项目两端同库（收正前 = 同项目两键两库）。 */
 export function ledgerDbPath(cwd) {
-  const key = createHash("sha1").update(resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")).digest("hex").slice(0, 16)
-  return join(ledgerDir, `${key}.db`)
+  const root = resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")
+  return join(ledgerDir, `${ledgerKey(root)}.db`)
 }
 
 /** 未决四态（「活条目」口径 = 计数单源 WHERE 集；已核销 / 已废弃 = 归档态）。 */
@@ -82,9 +102,17 @@ export function ensureExecutorColumn(db, { exists } = {}) {
 
 /** 开库（cwd = 项目根——仅作关联键）→ DatabaseSync 句柄 + 幂等建表 + 老库幂等迁移（executor 列）。
  *  读面（create=false）：库文件不存在 → 返回 null（空账——读面不建库、无副作用）。
- *  写面（create=true）：库文件不存在自动建（台账目录随之创建）；项目根目录不存在 → 抛友好错误。 */
+ *  写面（create=true）：库文件不存在自动建（台账目录随之创建）；项目根目录不存在 → 抛友好错误。
+ *  **歧义锚**（≥2 候选——`projectRootView` `ambiguous` 态）⇒ **显式拒**（列候选 + 显式项目根指引；
+ *  零写——不静默回退锚；族锚「项目不可解析」，AC-M2-17）；兜底 `resolve(cwd ?? ".")` 只属 none 态。 */
 export function openLedger(cwd, { create = false } = {}) {
   const dir = resolve(cwd ?? ".")
+  // 歧义锚 ⇒ 显式拒（零写——消「缺省空读 / 错写落锚」双面症；读 / 写五工具同经本门）。
+  const view = projectRootView(dir)
+  if (view.state === "ambiguous") {
+    const list = view.candidates.map((c) => `- ${c}`).join("\n")
+    throw new Error(`项目不可解析：cwd ${dir} 下候选项目不是恰好一个（下列 ${view.candidates.length} 个）——台账按项目根键控，请显式给出项目根 cwd：\n${list}`)
+  }
   const file = ledgerDbPath(dir)
   if (!existsSync(dir)) {
     throw new Error(`项目目录不存在：${dir}——cwd 请给存在的项目根（相对路径按当前工作目录解析；缺省 = 会话项目根）`)

package/ledger-migrate.mjs

@@ -0,0 +1,299 @@
+/**
+ * ledger-migrate.mjs — 台账存量收正命令面（M2 · 设计档 docs/core/design/LEDGER.md §2.2 · 台账 #286）。
+ * ② `ledger migrate --dry-run | --confirm`：变体键库一次性合并——三件套 = dry-run 零写 / 先备份（拷贝 + 读回同计数）/ 幂等（全字段等值）；
+ *   六步 = 备份 → 源就绪与列集判 → 单事务迁入（事务内读回核验）→ 回收源（rename 进 `ledger-trash`，不 unlink）→ 报告 → 汇总。执行主体 = 父侧 ops（KD-LN6）。
+ * ③ `ledger audit`：逐 `*.db` 定性（目标库 / 变体源 / 空库 / 不可归因（有行）/ 不可读（坏档）；stat 失败 ⇒ 读取失败态）+ 候选根集合归因；只报告零动作。
+ * 铁律：**12 数据列逐字复制（不含 id）+ id 重发**（两库 id 空间重叠）；备份 / 回收目录 = `ledgerDirPath()` 的**兄弟位**（§2.11#6 ⇒ 夹具根外零写）；
+ * 迁移走直接 SQL（§6.1 写门不拦迁移本身 ⇒ 风险行出旗不拦截）；本档静态 import node:sqlite ⇒ 消费侧一律动态 import（W8 契约②——同 ledger-db.mjs）。
+ */
+import { createHash } from "node:crypto"
+import { copyFileSync, mkdirSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+import { DatabaseSync } from "node:sqlite"
+
+import { ledgerDirPath, ledgerKey, openLedger } from "./ledger-db.mjs"
+import { resolveProjectRoot } from "./manifest.mjs"
+
+/** 12 数据列（**等值比对列集**——不含 id：id 重发，§2.2 语义保全 / AC-M2-12）。 */
+export const DATA_COLUMNS = [
+  "kind", "status", "title", "board", "req_doc", "task_book",
+  "evidence", "trigger", "executor", "created_at", "updated_at", "closed_at",
+]
+/** 备份面根 / 回收面根（`ledgerDirPath()` 的**兄弟位**——同派生于可覆盖基，§2.11#6）。 */
+export function ledgerBackupRoot() { return join(dirname(ledgerDirPath()), "ledger-backup") }
+export function ledgerTrashRoot() { return join(dirname(ledgerDirPath()), "ledger-trash") }
+
+const sha16 = (s) => createHash("sha1").update(s).digest("hex").slice(0, 16)
+const isFile = (p) => { try { return statSync(p).isFile() } catch { return false } }
+const sig = (values) => JSON.stringify(values)
+const byStatus = (rows) => rows.reduce((m, r) => { const s = r.values[1]; m[s] = (m[s] ?? 0) + 1; return m }, {})
+const openRead = (file) => new DatabaseSync(file, { readOnly: true }) // 源库 / 备份读回 / 审计一律只读
+const itemColumns = (db) => db.prepare("SELECT name FROM pragma_table_info('items')").all().map((r) => r.name)
+
+/** 盘符大小写翻转拼写（仅盘符换形；非盘符打头 ⇒ null——非盘符段不生成变体，§2.1 不做段）。 */
+export function flipDriveLetter(root) {
+  const m = /^([A-Za-z]):/.exec(root)
+  if (!m) return null
+  const d = m[1]
+  return (d === d.toLowerCase() ? d.toUpperCase() : d.toLowerCase()) + root.slice(1)
+}
+/** 变体键枚举（单源）：盘符翻转拼写的**原样 `sha1[:16]`**——收正前键式 = 无归一哈希（CLI 大写 / VSC `uri.fsPath` 小写 ⇒ 两键两库；先例 = `session-migrate.mjs`）。 */
+export function legacyKeyVariants(root) {
+  const flip = flipDriveLetter(root)
+  return flip ? [sha16(flip)] : []
+}
+/** 批次名（`YYYYMMDD-HHmmss` 本地——备份与回收共用同一批名）。 */
+function batchStamp(date) {
+  const p = (n) => String(n).padStart(2, "0")
+  return `${date.getFullYear()}${p(date.getMonth() + 1)}${p(date.getDate())}-${p(date.getHours())}${p(date.getMinutes())}${p(date.getSeconds())}`
+}
+/** 行集读取（id + 12 数据列；缺失列按 NULL 映射——旧 DDL 源的 `executor` 正常态，KD-LN10）。 */
+function readRows(db, missing = []) {
+  const cols = DATA_COLUMNS.filter((c) => !missing.includes(c))
+  return db.prepare(`SELECT id, ${cols.join(", ")} FROM items ORDER BY id`).all()
+    .map((r) => ({ id: Number(r.id), values: DATA_COLUMNS.map((c) => (missing.includes(c) ? null : r[c] ?? null)) }))
+}
+/** 源描述（dry-run / 步 2 / 备份读回 / 审计共用的只读面；失败收为 `error` 而非抛）。`refusal` = 就绪判：不可读 / 无 items 表 / 缺 `executor` 以外数据列 ⇒ 拒；仅缺 `executor`（旧 DDL 正常态）⇒ NULL 映射照迁（§2.2 步 2 / KD-LN10）。 */
+function describeSource(file) {
+  let db
+  try { db = openRead(file) } catch (e) { return { error: e.message, refusal: `不可读（${e.message}）` } }
+  try {
+    const cols = itemColumns(db)
+    if (!cols.length) return { rows: 0, missing: [], refusal: "不可开为台账库（无 items 表）" }
+    const missing = DATA_COLUMNS.filter((c) => !cols.includes(c))
+    const bad = missing.filter((c) => c !== "executor")
+    const rows = readRows(db, missing)
+    return { rows: rows.length, missing, dist: byStatus(rows), refusal: bad.length ? `缺数据列（列集不可归因）：${bad.join(" / ")}` : null }
+  } catch (e) { return { error: e.message, refusal: `不可读（${e.message}）` } } finally { db.close() }
+}
+/** 单次读行（计划 / 迁入面共用）。 */
+function readRowsOf(file, missing = []) {
+  const db = openRead(file)
+  try { return readRows(db, missing) } finally { db.close() }
+}
+/** 写门风险旗（§2.2 表）：迁入行属 `在途 / 待核销` 且 `task_book` 不可解析 / 指向档不存在 ⇒ 该行后续更新将拒于 §6.1 写门；只出旗，不拦截。 */
+function writeGateFlag(values, projectRoot) {
+  const tb = values[5]
+  if ((values[1] !== "在途" && values[1] !== "待核销") || tb == null || tb === "") return null
+  const part = String(tb).split("§")[0].trim()
+  if (!part) return `task_book 不可解析（缺文件部分）：${tb}`
+  const abs = resolve(projectRoot, part)
+  return isFile(abs) ? null : `task_book 指向的档不存在：${tb}（解析 = ${abs}）`
+}
+/** `--from` 指名键 = **补充源**：键形非 16 位小写十六进制 / 无对应库 / 不可开 ⇒ 拒跑（fail-closed，零写——显式指名不静默跳过；键形判防路径形 / 越目录形取值 join 出台账目录外）。 */
+function fromKeyRefusal(fromKeys, dir) {
+  for (const k of fromKeys) {
+    if (!/^[0-9a-f]{16}$/.test(k)) return `--from ${JSON.stringify(k)} 取值非键形（应 = 16 位小写十六进制 /^[0-9a-f]{16}$/；路径形 / 越目录形一律拒）。Nothing was written.`
+    const p = join(dir, `${k}.db`)
+    if (!isFile(p)) return `--from ${k} 指名的源键无对应库：${p}（显式指名不静默跳过——fail-closed）。Nothing was written.`
+    try { openRead(p).close() } catch (e) { return `--from ${k} 指名的源库不可开：${e.message}。Nothing was written.` }
+  }
+  return null
+}
+
+/** 迁移计划（dry-run / confirm 共用）。cwd 口径 = 写门口径 2 同一子表达式（`resolveProjectRoot` ∨ 兜底）。 */
+export function planLedgerMigration(cwd, { fromKeys = [] } = {}) {
+  const projectRoot = resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")
+  const dir = ledgerDirPath()
+  const targetKey = ledgerKey(projectRoot)
+  const targetPath = join(dir, `${targetKey}.db`)
+  const refusal = fromKeyRefusal(fromKeys, dir)
+  if (refusal) return { refusal }
+  const keys = [...new Set([...legacyKeyVariants(projectRoot), ...fromKeys])].filter((k) => k && k !== targetKey)
+  const sources = keys.map((k) => ({ key: k, path: join(dir, `${k}.db`) })).filter((s) => isFile(s.path))
+    .map((s) => { const desc = describeSource(s.path); return { ...s, mtime: statSync(s.path).mtime.toISOString(), desc, refusal: desc.refusal } })
+  const targetDesc = isFile(targetPath) ? describeSource(targetPath) : { rows: 0, missing: [], absent: true }
+  const flags = []
+  for (const s of sources) {
+    if (s.refusal) continue
+    for (const r of readRowsOf(s.path, s.desc.missing)) {
+      const f = writeGateFlag(r.values, projectRoot)
+      if (f) flags.push({ source: s.key, id: r.id, flag: f })
+    }
+  }
+  const migrate = sources.reduce((n, s) => n + (s.refusal ? 0 : s.desc.rows ?? 0), 0)
+  return { projectRoot, targetKey, targetPath, targetDesc, sources, flags, migrate }
+}
+
+/** dry-run 计划行（零写报告：目标 / 变体源候选 / 计划动作 / 写门风险旗）。 */
+function printPlan(plan, out) {
+  const t = plan.targetDesc
+  const dist = (d) => (d.dist ? Object.entries(d.dist).map(([k, v]) => `${k} ${v}`).join(" · ") : `unreadable: ${d.error}`)
+  out([
+    "Ledger migrate dry-run — no file will be created, moved or modified.",
+    `Target: ${plan.targetKey}  ${plan.targetPath}`,
+    t.absent ? "  ⚠ 拟建（0 行）——目标键库不存在，迁入步建库建表" : t.error ? `  ⚠ 目标不可读（${t.error}）——confirm 面将拒跑（fail-closed）` : `  rows ${t.rows}`,
+    `Variant sources (${plan.sources.length}):${plan.sources.length ? "" : " none（无待迁源）"}`,
+    ...plan.sources.map((s) => `  ${s.key}  ${s.path}  rows ${s.desc.rows ?? "?"}  mtime ${s.mtime}\n    ${dist(s.desc)}${s.refusal ? `  ⚠ ${s.refusal}（confirm 面将拒跑）` : ""}`),
+    `Plan: backup → ${join(ledgerBackupRoot(), "<批次>")}/ ; migrate ${plan.migrate} rows → target (post-migration count = ${t.error ? "?" : (t.rows ?? 0) + plan.migrate})`,
+    `Write-gate risk flags: ${plan.flags.length}${plan.flags.length ? "（不拦截——迁入后在途 / 待核销行的后续更新仍受写入时门约束）" : ""}`,
+    ...plan.flags.map((f) => `  ⚠ ${f.source} #${f.id}: ${f.flag}`),
+    'Run "thincoder ledger migrate --confirm" to execute (backup first, then single-transaction import, then sources are recycled into ledger-trash).',
+  ].join("\n"))
+}
+
+/** 事务内读回核验（§2.2 步 3）：逐插入行按新 id 回读 12 数据列与源等值 ∧ 目标既有行零动；不等 ⇒ throw（ROLLBACK ⇒ 目标零行变、源零动——新建档可能残留）。 */
+function verifyImported(db, inserted, existingById) {
+  const get = db.prepare(`SELECT ${DATA_COLUMNS.join(", ")} FROM items WHERE id = ?`)
+  for (const { key, id, values } of inserted) {
+    const got = get.get(id)
+    if (!got) throw new Error(`读回核验失败：目标缺行 id=${id}（源键 ${key}）`)
+    for (let i = 0; i < DATA_COLUMNS.length; i++) {
+      const a = values[i] ?? null
+      const b = got[DATA_COLUMNS[i]] ?? null
+      if (a !== b) throw new Error(`读回核验失败：id=${id} 列 ${DATA_COLUMNS[i]} 不等（源 ${JSON.stringify(a)} / 目标 ${JSON.stringify(b)}）`)
+    }
+  }
+  const now = new Map(readRows(db).map((r) => [r.id, sig(r.values)]))
+  for (const [id, before] of existingById) {
+    if (now.get(id) !== before) throw new Error(`读回核验失败：目标既有行 id=${id} 被动过`)
+  }
+}
+
+/** 步 1 备份（不可省）：目标 + 全部源文件拷贝进 `ledger-backup/<批次>/`；读回 = 逐档可开 ∧ COUNT 同源。 */
+function backupStep(files, backupDir) {
+  mkdirSync(backupDir, { recursive: true })
+  for (const f of files) copyFileSync(f, join(backupDir, basename(f)))
+  for (const f of files) {
+    const a = describeSource(f)
+    const b = describeSource(join(backupDir, basename(f)))
+    if (a.error || b.error || a.rows !== b.rows) throw new Error(`备份读回核验失败：${basename(f)}（原 ${a.rows ?? a.error} / 副本 ${b.rows ?? b.error}）`)
+  }
+}
+
+/** ② 迁移执行（§2.2 六步）。返回进程退出码（0 成功 / 1 拒跑或失败）。 */
+export function runLedgerMigrate(args, { cwd = process.cwd(), out = console.log, err = console.error, now = new Date(), busyMs = 3000 } = {}) {
+  const dryRun = args.includes("--dry-run")
+  const confirm = args.includes("--confirm")
+  if (dryRun === confirm) { err("Usage: thincoder ledger migrate --dry-run | --confirm [--from <key>]"); return 1 }
+  const fromKeys = []
+  for (let i = 0; i < args.length; i++) if (args[i] === "--from") fromKeys.push(String(args[i + 1] ?? ""))
+  const plan = planLedgerMigration(cwd, { fromKeys })
+  if (plan.refusal) { err(`Refused: ${plan.refusal}`); return 1 }
+  if (dryRun) { printPlan(plan, out); return 0 }
+  if (!plan.sources.length) { out("Ledger migrate: no sources to migrate（无待迁源——源已回收 / 无变体键库）。Nothing to do."); return 0 }
+  const batch = batchStamp(now)
+  const backupDir = join(ledgerBackupRoot(), batch)
+  const targetExists = !plan.targetDesc.absent
+  try { backupStep([...(targetExists ? [plan.targetPath] : []), ...plan.sources.map((s) => s.path)], backupDir) } catch (e) { err(`Refused: 备份失败（${e.message}）——迁入零启动，目标与源零变。`); return 1 }
+  // 步 2 源就绪与列集判（`-wal` / `-shm` 伴生档 ⇒ 拒：单档回收会丢未 checkpoint 数据）。
+  for (const s of plan.sources) {
+    if (isFile(`${s.path}-wal`) || isFile(`${s.path}-shm`)) {
+      err(`Refused: 源库带 -wal / -shm 伴生档：${basename(s.path)}——单档回收会丢未 checkpoint 数据（fail-closed）。先打开并关闭该库令其 checkpoint 后重试。`)
+      return 1
+    }
+    if (s.refusal) { err(`Refused: 源库不就绪 —— ${basename(s.path)}：${s.refusal}。`); return 1 }
+  }
+  // 步 3 单事务迁入：BEGIN → 逐行 INSERT（重发新 id）→ 事务内读回核验 → COMMIT；失败 ⇒ ROLLBACK。
+  const report = { version: 1, batch, at: now.toISOString(), projectRoot: plan.projectRoot, targetKey: plan.targetKey, targetPath: plan.targetPath, targetCreated: !targetExists, sources: [], skippedRows: [], flags: plan.flags, recycled: [], kept: [] }
+  let db
+  try { db = openLedger(plan.projectRoot, { create: true }) } catch (e) { err(`Refused: 目标库不可开（${e.message}）。`); return 1 }
+  try {
+    db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(busyMs))}`)
+    const existing = readRows(db)
+    const seen = new Set(existing.map((r) => sig(r.values)))
+    const existingById = new Map(existing.map((r) => [r.id, sig(r.values)]))
+    const inserted = []
+    db.exec("BEGIN")
+    try {
+      const insert = db.prepare(`INSERT INTO items (${DATA_COLUMNS.join(", ")}) VALUES (${DATA_COLUMNS.map(() => "?").join(", ")})`)
+      for (const s of plan.sources) {
+        const entry = { key: s.key, path: s.path, rows: s.desc.rows, migrated: 0, skipped: 0, idMap: {}, missingColumns: s.desc.missing }
+        for (const row of readRowsOf(s.path, s.desc.missing)) {
+          const s0 = sig(row.values)
+          if (seen.has(s0)) { entry.skipped++; report.skippedRows.push({ source: s.key, id: row.id }); continue }
+          const newId = Number(insert.run(...row.values).lastInsertRowid)
+          entry.idMap[String(row.id)] = newId
+          entry.migrated++
+          seen.add(s0)
+          inserted.push({ key: s.key, id: newId, values: row.values })
+        }
+        report.sources.push(entry)
+      }
+      verifyImported(db, inserted, existingById)
+      db.exec("COMMIT")
+    } catch (e) { db.exec("ROLLBACK"); throw e }
+    report.rowsBefore = existing.length
+    report.rowsAfter = existing.length + inserted.length
+  } catch (e) {
+    db.close()
+    // 措辞收正：目标档为本次新建时 ROLLBACK 后残留 0 行空库档——「目标零变」不足以覆盖，如实写明
+    const note = targetExists ? "目标零变、源零动。" : "目标零行变、源零动（目标档为本次新建——ROLLBACK 后 0 行空库档残留在原路径）。"
+    err(/busy|locked/i.test(e?.message ?? "")
+      ? `Refused: 目标台账库被另一实例占用（持写锁；busy_timeout ${busyMs}ms 用尽）——${note}待对方空闲后重试。`
+      : `Refused: 迁移失败（${e.message}）——已 ROLLBACK，${note}`)
+    return 1
+  }
+  db.close()
+  // 步 4 回收源：rename 进 `ledger-trash/<批次>/`（不 unlink——先例 = session-gc `sessions-trash`）。
+  const trashDir = join(ledgerTrashRoot(), batch)
+  for (const s of plan.sources) {
+    try { mkdirSync(trashDir, { recursive: true }); renameSync(s.path, join(trashDir, basename(s.path))); report.recycled.push(s.key) }
+    catch (e) { report.kept.push({ key: s.key, reason: e.message }) }
+  }
+  // 步 5 报告（`ledger-backup/<批次>/migrate-report.json`）：计数 / 逐源逐行 id 映射 / 跳过行 / 旗标。
+  const reportPath = join(backupDir, "migrate-report.json")
+  try { writeFileSync(reportPath, JSON.stringify(report, null, 2) + "\n") } catch (e) { err(`⚠ 报告写入失败（迁入已 COMMIT——数据无损）：${e.message}`) }
+  // 步 6 汇总（迁入行数 / 跳过数 / 迁移后计数 / 备份与回收路径）。
+  const migrated = report.sources.reduce((n, s) => n + s.migrated, 0)
+  out(`Ledger migrate done — migrated ${migrated} row(s) into ${plan.targetKey} (rows now ${report.rowsAfter}${report.targetCreated ? ", 库为本次新建" : ""}).`)
+  if (report.skippedRows.length) out(`  skipped ${report.skippedRows.length} row(s) — 全字段等值护栏（幂等：重跑不重复）。`)
+  out(`  backup: ${backupDir}  (report: ${basename(reportPath)})`)
+  out(`  recycled sources → ${trashDir}${report.recycled.length ? ` (${report.recycled.join(", ")})` : ""}`)
+  if (report.kept.length) {
+    err(`⚠ 回收失败（数据已迁入，源库留在原位）：${report.kept.map((k) => `${k.key}（${k.reason}）`).join(" · ")}`)
+    return 1
+  }
+  return 0
+}
+
+/** ③ 审计（只读——零删改）：逐 `*.db` 出 `{键, 文件, 大小, mtime, 行数, 状态分布, 定性}`；归因 = **候选根集合**（锚项目 + `--root`）的变体键匹配（sha1 不可逆——只做候选生成）。 */
+export function auditLedgerDir({ cwd = process.cwd(), roots = [], dir = ledgerDirPath() } = {}) {
+  let names = []
+  try { names = readdirSync(dir).filter((n) => n.endsWith(".db")).sort() } catch { /* 不可读 ⇒ 空报告 */ }
+  const anchorKeys = new Set()
+  const variantKeys = new Set()
+  for (const a of [cwd, ...roots]) {
+    const root = resolveProjectRoot(a) ?? resolve(a ?? ".")
+    anchorKeys.add(ledgerKey(root))
+    for (const v of legacyKeyVariants(root)) variantKeys.add(v)
+  }
+  const entries = names.map((name) => {
+    const file = join(dir, name)
+    const key = name.replace(/\.db$/, "")
+    let st = null; try { st = statSync(file) } catch { /* 并发删除 / 不可 stat ⇒ 读取失败态（按档报，不抛） */ }
+    if (!st) return { key, file, size: null, mtime: null, rows: null, dist: {}, kind: "不可归因（读取失败）" }
+    const desc = describeSource(file)
+    const rows = desc.error ? null : desc.rows ?? 0
+    const kind = desc.error ? "不可读（坏档）"
+      : anchorKeys.has(key) ? "目标库" : variantKeys.has(key) ? "变体源" : rows === 0 ? "空库" : "不可归因（有行）"
+    return { key, file, size: st.size, mtime: st.mtime.toISOString(), rows, dist: desc.dist ?? {}, kind }
+  })
+  const counts = {}
+  for (const e of entries) counts[e.kind] = (counts[e.kind] ?? 0) + 1
+  return { dir, entries, counts }
+}
+
+/** 处置建议（本批**只报告零动作**——删除不可逆 ⇒ 回收而非删；非目标 / 非源者保持原位）。 */
+const AUDIT_SUGGESTION = {
+  "目标库": "保留（迁移目标）", "变体源": "迁移（`thincoder ledger migrate --confirm`）",
+  "空库": "建议回收（`ledger-trash`，可回退）——本批零动作",
+  "不可归因（有行）": "保持原位（非目标 / 非源）——本批零动作", "不可读（坏档）": "保持原位（人工处置；本批零动作）",
+}
+const READ_FAIL_SUGGESTION = "保持原位（读取失败态——并发删除 / 不可 stat；本批零动作）"
+/** ③ 显式命令面（壳侧接线 = `case "ledger"`）：只读分类报告。 */
+export function runLedgerAudit(args, { cwd = process.cwd(), out = console.log } = {}) {
+  const roots = []
+  for (let i = 0; i < args.length; i++) if (args[i] === "--root" && args[i + 1]) roots.push(String(args[i + 1]))
+  const { dir, entries, counts } = auditLedgerDir({ cwd, roots })
+  const kinds = [...new Set([...Object.keys(AUDIT_SUGGESTION), ...entries.map((e) => e.kind)])] // 读取失败态随现随列（计数与枚举同列）
+  out([
+    "Ledger audit — read-only: no ledger file is created, moved or deleted.",
+    `Dir: ${dir}  (candidate roots: ${1 + roots.length})`,
+    ...entries.map((e) => `  ${e.key}.db  ${e.size != null ? `${e.size}B` : "—"}  mtime ${e.mtime ?? "—"}  rows ${e.rows ?? "?"}  ${e.kind}${Object.keys(e.dist).length ? `  (${Object.entries(e.dist).map(([k, v]) => `${k} ${v}`).join(" · ")})` : ""}`),
+    `Summary: ${kinds.map((k) => `${k} ${counts[k] ?? 0}`).join(" · ")}`,
+    ...kinds.map((k) => `  ${k} ⇒ ${AUDIT_SUGGESTION[k] ?? READ_FAIL_SUGGESTION}`),
+    `Total ${entries.length} ledger file(s) under ${dir}（只报告零动作——删除不可逆）。`,
+  ].join("\n"))
+  return 0
+}