@thincoder/core 0.10.3 → 0.10.5

package/ledger-cmd.mjs

@@ -11,13 +11,26 @@
  * 消费侧静态 import 会破 W8 契约②）。
  */
 import { resolve } from "node:path"
-import { ALLOWED_MIGRATIONS, nowIso, openLedger, PENDING_STATUSES } from "./ledger-db.mjs"
+import { ALLOWED_MIGRATIONS, nowIso, openLedger, PENDING_STATUSES, AGING_DAYS } from "./ledger-db.mjs"
 import { resolveProjectRoot } from "./manifest.mjs"
 import { resolveDeclaredRef } from "./declaration.mjs"
 
-/** 查询（只读，全角色）：SELECT 行集（status/kind/board 过滤，缺省 = 全部行；id 升序）。库不在 = 空账。
- *  只读开库（readOnly 句柄 + 零 DDL/ALTER——read-data-interface 批 FR2③）；库档非台账库 ⇒ 空账。 */
-export function ledgerQuery({ cwd, status = null, kind = null, board = null } = {}) {
+/** 逐行老化判真（LEDGER.md §13.4 · 2026-10-07 批 ledger-tool）：未决四态（`PENDING_STATUSES`）∧
+ *  行龄 > `AGING_DAYS` 天；行龄源 = `updated_at ?? created_at`（§5 同源）；时间戳缺 / 不可解析
+ *  ⇒ `false`（零假阳降级——与 `buildScan` 行龄口径同源）。 */
+function isRowAged(row, now) {
+  if (!PENDING_STATUSES.includes(row.status)) return false
+  const t = row.updated_at ?? row.created_at
+  if (t == null) return false
+  const ms = Date.parse(String(t))
+  return Number.isFinite(ms) && (now - ms) / 86400000 > AGING_DAYS
+}
+
+/** 查询（只读，全角色）：SELECT 行集（status / kind / board / trigger 等值过滤并取，缺省 = 全部行；id 升序）。
+ *  库不在 = 空账。只读开库（readOnly 句柄 + 零 DDL/ALTER——read-data-interface 批 FR2③）；库档非台账库 ⇒ 空账。
+ *  逐行携计算字段 `aged: boolean`（§13.4——不入库、不入导出白名单 DATA_COLUMNS）；`trigger` 过滤
+ *  仅三枚举等值（`NULL` 不过滤——批面未列，§13.2）；`now` = 注入缝（确定性用例）。 */
+export function ledgerQuery({ cwd, status = null, kind = null, board = null, trigger = null, now = Date.now() } = {}) {
   const db = openLedger(cwd, { readOnly: true })
   if (!db) return []
   try {
@@ -25,7 +38,9 @@ export function ledgerQuery({ cwd, status = null, kind = null, board = null } =
     if (status) { where.push("status = ?"); args.push(status) }
     if (kind) { where.push("kind = ?"); args.push(kind) }
     if (board) { where.push("board = ?"); args.push(board) }
-    return db.prepare(`SELECT * FROM items${where.length ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY id`).all(...args)
+    if (trigger) { where.push("trigger = ?"); args.push(trigger) }
+    const rows = db.prepare(`SELECT * FROM items${where.length ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY id`).all(...args)
+    return rows.map((r) => ({ ...r, aged: isRowAged(r, now) }))
   } finally { db.close() }
 }
 
@@ -75,9 +90,11 @@ export function ledgerAdd({ cwd, row }) {
 }
 
 /** executor 目标值计算（设计档 docs/core/design/LEDGER.md §3.1——判位在 ledgerUpdate 体内：迁移表判 → 本语义 → 写门 → UPDATE）。
- *  优先级 = patch 显式 > 自动语义（进在途 = executorSessionId / 出在途 = NULL）> 行现值兜底 > NULL。 */
+ *  优先级 = patch 显式 > 自动语义（进边 = executorSessionId / 出边 = NULL）> 行现值兜底 > NULL。
+ *  进边集（2026-10-07 批 ledger-tool 扩面——§13.3 / KD-LT1）：`待讨论 → 待设计`（批点火边）∥
+ *  `待设计 → 在途`（实施入边）——两枚同式。 */
 function resolveExecutorTarget(row, to, patch, executorSessionId) {
-  if (row.status === "待设计" && to === "在途") {
+  if ((row.status === "待讨论" && to === "待设计") || (row.status === "待设计" && to === "在途")) {
     return patch.executor ?? executorSessionId ?? row.executor ?? null
   }
   if (row.status === "在途" && (to === "待核销" || to === "已废弃")) {
@@ -86,9 +103,29 @@ function resolveExecutorTarget(row, to, patch, executorSessionId) {
   return patch.executor ?? row.executor ?? null
 }
 
+/** `evidence` 值计算（设计档 LEDGER.md §13.9——update / close 两函数同源一处落）：追加缺省（旧值非空 ⇒
+ *  `旧 + "｜" + 新`——「｜」两侧零空格直接相接；旧空（`null` ∥ 空串 ∥ 全空白）⇒ 直写，零分隔符残留）；
+ *  `evidenceReplace === true` 与值同传 ⇒ 整段替换（旧文零保留）；`evidence` 缺 / `null` ≡ 略去（零变）。
+ *  拒面①（旗独传——无新文可算）判于本阶段（close 侧先于追认门）；核内旗判只认 `=== true`（类型严判在
+ *  工具层）。两值逐字落行（不裁 / 不判内容）。 */
+function evidenceValue(fnName, oldValue, evidence, evidenceReplace) {
+  if (evidenceReplace === true && evidence == null) throw new Error(`${fnName}：evidenceReplace 须与 evidence 同传（缺新文）`)
+  if (evidence == null) return oldValue
+  const old = oldValue == null || String(oldValue).trim() === "" ? "" : String(oldValue)
+  return evidenceReplace === true || old === "" ? evidence : `${old}｜${evidence}`
+}
+
+/** 拒面②（新值全空白——追加 ∥ 覆盖两径同判）判点（§13.9 判序）：update 随值计算同拍 ∥ close 落
+ *  追认门之后；`evidence` 未传（`null` / 略去）⇒ 不判。 */
+function assertEvidenceValue(fnName, evidence) {
+  if (evidence != null && String(evidence).trim() === "") throw new Error(`${fnName}：evidence 为空（非空字符串）`)
+}
+
 /** 更新（写命令，仅主 agent）：UPDATE——状态迁移前判允许迁移表（不在表内 → 拒，行不变）。
  *  executor 目标值随同一 UPDATE 落列（LEDGER.md §3.1）；executorSessionId = 调用会话（函数参数注入——K-LX1
- *  纯函数可测；工具层动态 import getSessionId() 供值，零新静态边）。 */
+ *  纯函数可测；工具层动态 import getSessionId() 供值，零新静态边）。
+ *  `evidence` 传值 = 追加缺省、`patch.evidenceReplace` = 布尔覆盖旗（§13.9——值计算 / 两拒面 = `evidenceValue`
+ *  / `assertEvidenceValue`；判位 = 本语义段，随 executor 目标值同拍）。 */
 export function ledgerUpdate({ cwd, id, patch, executorSessionId }) {
   const db = openLedger(cwd, { create: true })
   try {
@@ -98,20 +135,27 @@ export function ledgerUpdate({ cwd, id, patch, executorSessionId }) {
     if (to !== row.status && !(ALLOWED_MIGRATIONS[row.status] ?? []).includes(to)) {
       throw new Error(`ledgerUpdate：迁移 ${row.status} → ${to} 不在允许迁移表`)
     }
-    const nextTaskBook = patch.task_book ?? row.task_book
-    assertTaskBookGate(cwd, "ledgerUpdate", to, nextTaskBook) // 判序：迁移表判 → 本门 → UPDATE
+    // 判序（§13.9）：迁移表判 → 本语义（executor 目标值 + evidence 值计算——含两拒面）→ 写门 → UPDATE
     const nextExecutor = resolveExecutorTarget(row, to, patch, executorSessionId)
+    const nextEvidence = evidenceValue("ledgerUpdate", row.evidence, patch.evidence, patch.evidenceReplace)
+    assertEvidenceValue("ledgerUpdate", patch.evidence)
+    const nextTaskBook = patch.task_book ?? row.task_book
+    assertTaskBookGate(cwd, "ledgerUpdate", to, nextTaskBook) // → 写门 → UPDATE
     const now = nowIso()
     db.prepare(`UPDATE items SET status = ?, title = ?, board = ?, req_doc = ?, task_book = ?, evidence = ?, trigger = ?, executor = ?, updated_at = ? WHERE id = ?`)
-      .run(to, patch.title ?? row.title, patch.board ?? row.board, patch.req_doc ?? row.req_doc, nextTaskBook, patch.evidence ?? row.evidence, patch.trigger ?? row.trigger, nextExecutor, now, id)
+      .run(to, patch.title ?? row.title, patch.board ?? row.board, patch.req_doc ?? row.req_doc, nextTaskBook, nextEvidence, patch.trigger ?? row.trigger, nextExecutor, now, id)
     return { id }
   } finally { db.close() }
 }
 
 /** 收口（写命令，仅主 agent）：核销两源（勾销：待核销 → 已核销；追认核销：待讨论 / 待设计 → 已核销，
  *  行 `evidence` 非空，缺 / 全空白 ⇒ 拒）/ 撤回（任意态 → 已废弃），事务包裹；归档 = 软删除。
- *  判序（同函数体同层）：目标集判 → 行取 → 源态判 → `evidence` 门 → UPDATE（LEDGER.md §3 收口两源）。 */
-export function ledgerClose({ cwd, id, status }) {
+ *  可选 `evidence` 参：传值 = 追加缺省（§13.9——旧空直写 / 旧非空拼 `旧｜新`）、`evidenceReplace: true`
+ *  同传 = 整段替换；勾销 / 追认 / 撤回三径同携（写值落行，内容不判）；两拒面（旗独传 @值计算 ∥
+ *  新值空白 @追认门后）见 `evidenceValue` / `assertEvidenceValue`。
+ *  判序（同函数体同层，§13.9）：目标集判 → 行取 → 源态判 → 值计算 → 追认门（原样——判**结果值**缺 /
+ *  全空白 ⇒ 拒，文案逐字不变）→ 拒面②（新值空白）→ UPDATE（LEDGER.md §3 收口两源）。 */
+export function ledgerClose({ cwd, id, status, evidence, evidenceReplace }) {
   if (status !== "已核销" && status !== "已废弃") throw new Error(`ledgerClose：目标态 ${status} ∉ {已核销, 已废弃}`)
   const db = openLedger(cwd, { create: true })
   try {
@@ -119,12 +163,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} 不存在`)
-      // 判序：源态判（核销仅三源——在途不可跳）→ 追认口 `evidence` 门（行字段非空，缺 / 全空白 ⇒ 拒）
+      // 判序（§13.9）：源态判（核销仅三源——在途不可跳）→ 值计算（拒面① 旗独传判于此）→ 追认口 `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 nextEvidence = evidenceValue("ledgerClose", row.evidence, evidence, evidenceReplace)
+      if (status === "已核销" && ["待讨论", "待设计"].includes(row.status) && (nextEvidence == null || String(nextEvidence).trim() === "")) throw new Error(`ledgerClose：追认核销须带 evidence（现态 ${row.status}）`)
+      assertEvidenceValue("ledgerClose", evidence) // 判序：拒面②（新值空白）落追认门之后 → UPDATE
       const now = nowIso()
       // 撤回（任意态 → 已废弃——含在途直撤）同步 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.prepare("UPDATE items SET status = ?, closed_at = ?, updated_at = ?, executor = ?, evidence = ? WHERE id = ?").run(status, now, now, status === "已废弃" ? null : row.executor, nextEvidence, id)
       db.exec("COMMIT")
       return { id, status }
     } catch (e) { db.exec("ROLLBACK"); throw e }

package/ledger-db.mjs

@@ -55,6 +55,12 @@ export function ledgerDbPath(cwd) {
 /** 未决四态（「活条目」口径 = 计数单源 WHERE 集；已核销 / 已废弃 = 归档态）。 */
 export const PENDING_STATUSES = ["待讨论", "待设计", "在途", "待核销"]
 
+/** 老化阈值（天——口径 = 需求档；消费面 = `buildScan`（展示，`days` 可覆盖）+ `ledgerQuery` 逐行
+ *  `aged`（查询面，`now` 可注入））。2026-10-07 批 ledger-tool：自 `ledger.mjs` 迁入（枚举常量档单源
+ *  ——`ledgerQuery` 计算面直引本档，消 `ledger-cmd ↔ ledger.mjs` 新环；`ledger.mjs` 同名 re-export
+ *  保公共面零变——LEDGER.md §13.4）。 */
+export const AGING_DAYS = 30
+
 /** 台账库结构版本（N2 标记**单源**——`PRAGMA user_version` 落标：写面开库 `v < 本值 ⇒ 置`；
  *  读面如实回读（旧库未标 = 0）；结构变更（新列 / 新表）同步升号——2026-10-03 read-data-interface 批）。 */
 export const LEDGER_SCHEMA_VERSION = 1

package/ledger-surface.mjs

@@ -3,8 +3,13 @@
  *
  * 面：族扫描 → 判活批量解析 → 状态位（`state.ledger`——L1 常驻标记，范围归约 `scopeMarkerOf`
  * 单源 §7.2，渲染端消费）；只读台账，本面零写。
+ *
+ * **写后即时**（2026-10-13 缺陷修复——用户原话「写了以后就要立即更新」）：台账库目录
+ * `fs.watch` ⇒ 去抖立即重扫（同进程 ∥ 跨进程写皆覆盖）；`REFRESH_MS` 周期降为兜底。
  */
+import { watch } from "node:fs"
 import { buildScan, discoverFamily, REFRESH_MS, resolveExecutorStates, scopeMarkerOf } from "./ledger.mjs"
+import { ledgerDirPath } from "./ledger-db.mjs"
 
 /** 单次扫描（直驱面——timer 包装见 `startLedgerSurface`）。**async**（F-LX1：await 判活解析——
  *  LEDGER.md §7.3.1 ④ 读面不阻塞事件循环）。 */
@@ -23,18 +28,50 @@ export async function runLedgerScan({ state, agent = null, anchor = null, render
   render()
 }
 
-/** 挂载：首扫（`setImmediate`——不抢首帧）+ 周期（`REFRESH_MS`；`state.processing` 期间跳过本轮）。
+/** 挂载：首扫（`setImmediate`——不抢首帧）+ 周期兜底（`REFRESH_MS`）
+ *  + **写后即时**（台账库目录变更 ⇒ 去抖 400ms 重扫——同进程 ∥ 跨进程写皆覆盖）。
  *  `tick` 异步化（F-LX1——runLedgerScan async）：await 且 catch 不崩（N1）。重叠防衛：
- *  判活探测秒级可达，上一轮未落定时跳过本轮（防探束堆积）。 */
+ *  判活探测秒级可达，上一轮未落定时跳过本轮（防探束堆积）。
+ *  `state.processing` 跳过仅限**定时轮**（不打断回合帧）；库变更轮放行（写后立即可见 ——
+ *  用户 2026-10-13「写了以后就要立即更新」）。
+ *  评审 #5 修复（2026-10-13）：① 变更轮遇在途扫描 ⇒ 记待办、落定补跑（不丢）；② watcher 缺席
+ *  （目录未建）⇒ 2s 短重试补挂（闭「首写才建」窗口）。 */
 export function startLedgerSurface(ctx = {}) {
   let disposed = false
   let timer = null
   let inflight = false
-  const tick = async () => {
-    if (disposed || inflight) return
-    if (ctx.state?.processing) return // 扫描不打断回合帧
+  let watcher = null
+  let schedTimer = null
+  let armTimer = null
+  let pendingForce = false
+  const tick = async (force = false) => {
+    if (disposed) return
+    if (inflight) { if (force) pendingForce = true; return } // 在途扫描：变更轮记待办（落定补跑——不丢）
+    if (!force && ctx.state?.processing) return // 定时轮不打断回合帧
     inflight = true
     try { await runLedgerScan(ctx) } catch { /* 可见面尽力——不崩（N1） */ } finally { inflight = false }
+    armWatcher() // 目录可能首写才建——每轮后补挂一次（零成本：已挂则直接返）
+    if (pendingForce && !disposed) { pendingForce = false; void tick(true) } // 补跑被在途挤掉的变更轮
+  }
+  const onFsEvent = (_evt, name) => {
+    if (name && !/\.db($|-(wal|shm|journal)$)/.test(String(name))) return
+    if (schedTimer) clearTimeout(schedTimer)
+    schedTimer = setTimeout(() => { schedTimer = null; tick(true) }, 400)
+    schedTimer.unref?.()
+  }
+  function armWatcher() {
+    if (disposed || watcher) return
+    try {
+      watcher = watch(ledgerDirPath(), { persistent: false }, onFsEvent)
+      watcher.unref?.()
+      if (armTimer) { clearTimeout(armTimer); armTimer = null }
+    } catch {
+      // 目录未建（首写才建）——2s 短重试补挂（评审 #5 发现②：闭「首写不被观测」窗口）
+      if (!armTimer) {
+        armTimer = setTimeout(() => { armTimer = null; armWatcher() }, 2000)
+        armTimer.unref?.()
+      }
+    }
   }
   setImmediate(() => {
     if (disposed) return
@@ -42,11 +79,18 @@ export function startLedgerSurface(ctx = {}) {
     timer = setInterval(() => tick(), REFRESH_MS)
     timer.unref?.()
   })
+  armWatcher()
   return {
     dispose() {
       disposed = true
       if (timer) clearInterval(timer)
+      if (schedTimer) clearTimeout(schedTimer)
+      if (armTimer) clearTimeout(armTimer)
+      if (watcher) watcher.close()
       timer = null
+      schedTimer = null
+      armTimer = null
+      watcher = null
     },
   }
 }

package/ledger-tools.mjs

@@ -1,14 +1,17 @@
 /**
- * ledger-tools.mjs — 台账五工具定义（查询二 = 只读全角色 / 写三 = 仅主 agent 装配）+ 工具层参数守卫。
- * 自 `ledger-cmd.mjs` 拆出（2026-09-28 守卫族微修批 · 台账 #473——纯搬移、语义零变；核函数留原档）。
- * 守卫 = **声明派生**（设计档 §3.2：枚举 / 必填 / 类型取自工具自身 `parameters`，不在守卫内复写——
- * D2「声明即校验」）；判于核函数之前 ⇒ 非法入参零写、零库动作、零 SQLite 原文外泄。读面二具同拍
- * （#473：非法过滤参数 ⇒ 拒——不再「静默空集 / 绑原文」）。
- * 接线：族出口 = `ledger.mjs`（re-export——消费面 tools/index.mjs · agent/family-tools.mjs 零改）；
- * 消费侧一律动态 import `ledger.mjs`（ledger-db.mjs 静态 import node:sqlite ⇒ W8 契约②）。
+ * ledger-tools.mjs — 台账**统一入口** `ledger`（action 分派）+ 五旧名弃用壳 + 工具层参数守卫。
+ * 自 `ledger-cmd.mjs` 拆出（2026-09-28 守卫族微修批 · 台账 #473）；2026-10-05 统一入口批
+ * （台账 #923）合五工具为一：模型面恰一名 `ledger`（两变体同名单对象、schema 窄化——
+ * 全量 = depth-0 五 action ∥ 只读 = depth>0 二 action）；旧五名 = code 面弃用壳（不入任何装配面）。
+ * 守卫 = **声明派生**（设计档 §3.2 / §11.3：判序① 入参归一 → ② 入口级 action 判（消费 action）→
+ * ③ 余键喂该 action 伪工具对象走 P2–P6——声明源 = 前身旧工具 `parameters` 逐字；helper `assertToolArgs`
+ * 机制沿用，「零改」面破例 = #1006 批增布尔分支（§13.9））；判于核函数之前 ⇒ 非法入参零写、零库动作、
+ * 零 SQLite 原文外泄。
+ * 接线：族出口 = `ledger.mjs`（re-export——消费面 agent/family-tools.mjs；旧读二装配面已清零）；
+ * 消费侧一律动态 import（`ledger-db.mjs` 静态 import node:sqlite ⇒ W8 契约②）。
  */
 import { ledgerAdd, ledgerClose, ledgerCount, ledgerQuery, ledgerUpdate } from "./ledger-cmd.mjs"
-import { DESC } from "./tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/ledger_*.md（DESC 单解析面）
+import { DESC } from "./tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/ledger.md（DESC 单解析面）
 
 /** 工具 cwd 供值面（缺省 → 当前项目根）。 */
 const cwdOf = (ctx) => ctx?.agent?.cwd ?? ctx?.cwd ?? process.cwd()
@@ -60,6 +63,8 @@ function assertToolArgs(tool, args) {
       throw new Error(`${name}：${field} 非法：${argPreview(value)}（应为字符串）`)
     } else if (spec.type === "number" && typeof value !== "number") {
       throw new Error(`${name}：${field} 非法：${argPreview(value)}（应为数字）`)
+    } else if (spec.type === "boolean" && typeof value !== "boolean") {
+      throw new Error(`${name}：${field} 非法：${argPreview(value)}（应为布尔）`)
     }
     if (field === "title" && typeof value === "string" && value.trim() === "") {
       throw new Error(`${name}：${field} 为空（${required ? "必填；" : ""}非空字符串）`)
@@ -68,51 +73,22 @@ function assertToolArgs(tool, args) {
   return args
 }
 
-// ── 工具定义（接线：查询 → tools/index.mjs 全角色面；写 → family-tools.mjs depthOnly 分支） ──
+// ── 统一入口（设计档 §11.2 / §11.3） ─────────────────────────────────────────
 
-export const ledgerQueryTool = {
-  name: "ledger_query",
-  description: DESC("ledger_query"), // #15 外置：文本单点 = tool-docs/ledger_query.md（两池词表逐字保留）
-  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: "按归属板块过滤（需求档文档名）" },
-    },
-    additionalProperties: false,
-  },
-  readonly: true,
-  async execute(args, ctx) {
-    args = assertToolArgs(ledgerQueryTool, args)
-    return JSON.stringify(ledgerQuery({ cwd: args.cwd ?? cwdOf(ctx), status: args.status, kind: args.kind, board: args.board }), null, 2)
-  },
-}
+/** action 枚举（全量 / 只读两变体；顺序 = 文档与按钮序）。 */
+const FULL_ACTIONS = ["add", "update", "close", "query", "count"]
+const READ_ACTIONS = ["query", "count"]
 
-export const ledgerCountTool = {
-  name: "ledger_count",
-  description: DESC("ledger_count"), // #15 外置：文本单点 = tool-docs/ledger_count.md
-  parameters: {
-    type: "object",
-    properties: { cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" } },
-    additionalProperties: false,
-  },
-  readonly: true,
-  async execute(args, ctx) {
-    args = assertToolArgs(ledgerCountTool, args)
-    return JSON.stringify({ count: ledgerCount({ cwd: args.cwd ?? cwdOf(ctx) }) })
-  },
-}
+/** cwd 参数描述（五前身声明同文——文本单点）。 */
+const CWD_DESC = "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根"
 
-export const ledgerAddTool = {
-  name: "ledger_add",
-  description: DESC("ledger_add"), // #15 外置：文本单点 = tool-docs/ledger_add.md（两池词表逐字保留）
-  parameters: {
+/** 各 action 声明条目（= 前身旧工具 `parameters` 逐字；伪工具对象守卫 + 弃用壳共用单源）。 */
+const ACTION_SPECS = {
+  add: {
     type: "object",
     required: ["kind", "title"],
     properties: {
-      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
+      cwd: { type: "string", description: CWD_DESC },
       kind: { type: "string", enum: ["requirement", "tech_todo"], description: "类别" },
       title: { type: "string", description: "条目标题" },
       board: { type: "string", description: "归属板块（需求档文档名，可空）" },
@@ -123,66 +99,161 @@ export const ledgerAddTool = {
     },
     additionalProperties: false,
   },
-  readonly: false,
-  async execute(args, ctx) {
-    args = assertToolArgs(ledgerAddTool, args)
-    const { cwd, ...row } = args
-    const id = ledgerAdd({ cwd: cwd ?? cwdOf(ctx), row })
-    return JSON.stringify({ id, status: "待讨论" })
-  },
-}
-
-export const ledgerUpdateTool = {
-  name: "ledger_update",
-  description: DESC("ledger_update"), // #15 外置：文本单点 = tool-docs/ledger_update.md
-  parameters: {
+  update: {
     type: "object",
     required: ["id"],
     properties: {
-      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
+      cwd: { type: "string", description: CWD_DESC },
       id: { type: "number", description: "条目 id" },
       status: { type: "string", enum: ["待讨论", "待设计", "在途", "待核销", "已核销", "已废弃"], description: "目标状态（六态之一，缺省 = 不变）" },
       title: { type: "string", description: "标题（缺省 = 不变）" },
       board: { type: "string", description: "归属板块（缺省 = 不变）" },
       req_doc: { type: "string", description: "需求档指针（缺省 = 不变）" },
       task_book: { type: "string", description: "任务书指针（缺省 = 不变）" },
-      evidence: { type: "string", description: "证据（缺省 = 不变）" },
+      evidence: { type: "string", description: "证据（缺省 = 不变；传入 = 追加——旧值非空 ⇒ 拼 `旧｜新`（「｜」零空格）、旧空直写；新值全空白 ⇒ 拒；覆盖 = 与 `evidenceReplace: true` 同传）" },
+      evidenceReplace: { type: "boolean", description: "覆盖旗（布尔）：与 evidence 同传 = 整段替换（旧文零保留）；缺省 / false = 追加；旗独传（无新文）⇒ 拒" },
       trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "触发（缺省 = 不变）" },
-      executor: { type: "string", description: "执行者 sessionId（可选——接手改写归属用；缺省 = 按状态迁移语义：进在途自动写本会话 / 出在途自动清空 / 其余不变）" },
+      executor: { type: "string", description: "执行者 sessionId（可选——接手改写归属用；缺省 = 按状态迁移语义：进入待设计 / 在途自动写本会话；出在途 / 撤回清空）" },
     },
     additionalProperties: false,
   },
-  readonly: false,
-  async execute(args, ctx) {
-    args = assertToolArgs(ledgerUpdateTool, args)
-    const { cwd, id, ...patch } = args
-    let executorSessionId
-    if (patch.executor == null) {
-      // 显式 `null` ≡ 略去（§3.1 `null` 口径 · #474——与缺省同分支）；动态 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: DESC("ledger_close"), // #15 外置：文本单点 = tool-docs/ledger_close.md
-  parameters: {
+  close: {
     type: "object",
     required: ["id", "status"],
     properties: {
-      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
+      cwd: { type: "string", description: CWD_DESC },
       id: { type: "number", description: "条目 id" },
       status: { type: "string", enum: ["已核销", "已废弃"], description: "目标态（勾销 / 追认核销 / 撤回）" },
+      evidence: { type: "string", description: "最小证据行（可选；传入 = 追加缺省——旧值非空 ⇒ 拼 `旧｜新`（「｜」零空格）、旧空直写；新值全空白 ⇒ 拒；覆盖 = 与 `evidenceReplace: true` 同传。追认核销面判结果值须非空：缺 / 全空白 ⇒ 拒）" },
+      evidenceReplace: { type: "boolean", description: "覆盖旗（布尔）：与 evidence 同传 = 整段替换（旧文零保留）；缺省 / false = 追加；旗独传（无新文）⇒ 拒" },
     },
     additionalProperties: false,
   },
-  readonly: false,
-  async execute(args, ctx) {
-    args = assertToolArgs(ledgerCloseTool, args)
-    return JSON.stringify(ledgerClose({ cwd: args.cwd ?? cwdOf(ctx), id: args.id, status: args.status }))
+  query: {
+    type: "object",
+    properties: {
+      cwd: { type: "string", description: CWD_DESC },
+      status: { type: "string", enum: ["待讨论", "待设计", "在途", "待核销", "已核销", "已废弃"], description: "按状态过滤（六态之一，缺省 = 不过滤）" },
+      kind: { type: "string", enum: ["requirement", "tech_todo"], description: "按类别过滤" },
+      board: { type: "string", description: "按归属板块过滤（需求档文档名）" },
+      trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "按技术待办触发过滤（三枚举，缺省 = 不过滤——无触发（NULL）不过滤）" },
+    },
+    additionalProperties: false,
+  },
+  count: {
+    type: "object",
+    properties: { cwd: { type: "string", description: CWD_DESC } },
+    additionalProperties: false,
+  },
+}
+
+/** 并集 schema（§11.2——`action` 枚举 + 五 action 参数并集；per-action 必填由运行时守卫裁）。 */
+const UNION_PARAMETERS = {
+  type: "object",
+  required: ["action"],
+  properties: {
+    action: { type: "string", enum: FULL_ACTIONS, description: "" }, // 变体构造时填描述
+    cwd: { type: "string", description: CWD_DESC },
+    kind: { type: "string", enum: ["requirement", "tech_todo"], description: "类别（add 必填 / query 过滤；缺省 = 不过滤）" },
+    title: { type: "string", description: "条目标题（add 必填；update 可改——空串 / 全空白 ⇒ 拒）" },
+    board: { type: "string", description: "归属板块（需求档文档名；add 可空 / update 缺省 = 不变 / query 过滤）" },
+    req_doc: { type: "string", description: "需求档指针（add 可空 / update 缺省 = 不变）" },
+    task_book: { type: "string", description: "任务书指针（add 可空 / update 缺省 = 不变；在途 / 待核销必填——咬合 CHECK）" },
+    evidence: { type: "string", description: "最小证据行（add 可空；update / close 传入 = 追加缺省——旧空直写、旧非空拼 `旧｜新`（「｜」零空格）、新值全空白 ⇒ 拒；覆盖 = 与 `evidenceReplace: true` 同传；update 缺省 = 不变 / close 缺省 = 判行值；追认核销须非空）" },
+    evidenceReplace: { type: "boolean", description: "覆盖旗（布尔）：与 evidence 同传 = 整段替换；缺省 / false = 追加；旗独传（无新文）⇒ 拒（update / close）" },
+    trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "技术待办触发（add / update 可空 / query 过滤）" },
+    id: { type: "number", description: "条目 id（update / close 必填）" },
+    status: { type: "string", enum: ["待讨论", "待设计", "在途", "待核销", "已核销", "已废弃"], description: "状态（close 必填 ∈ {已核销, 已废弃}；update 迁移 / query 过滤——六态之一）" },
+    executor: { type: "string", description: "执行者 sessionId（update 可选——接手改写归属；缺省 = 按状态迁移语义：进入待设计 / 在途自动写本会话；出在途 / 撤回清空）" },
   },
+  additionalProperties: false,
+}
+
+/** 变体构造（同名单对象、schema 窄化、两形永不同装配——先例 = `subagent` 工具 depth 面变体）：
+ *  全量（depth-0 五 action；`writeFace:true` —— `readonly:false` + 动作级分类钩子，写面保持侧效门，
+ *  query / count 归只读类 = 旧读二 `readonly:true` 同行为：planMode 放行 / 免审批）∥ 只读（depth>0
+ *  二 action；`readonly:true`，写三 schema 级不可达）。形态显式声明（不按 actions 长度推导——增量
+ *  变体不改错标文案）。 */
+function makeLedgerTool(actions, { readonly = false, writeFace = false } = {}) {
+  const entryTool = { name: "ledger", parameters: { type: "object", required: ["action"], properties: { action: { type: "string", enum: actions } } } }
+  return {
+    name: "ledger",
+    description: DESC("ledger"), // 文本单点 = tool-docs/ledger.md（五档要点合一）
+    parameters: {
+      ...UNION_PARAMETERS,
+      properties: {
+        ...UNION_PARAMETERS.properties,
+        action: {
+          ...UNION_PARAMETERS.properties.action,
+          enum: actions,
+          description: writeFace
+            ? "操作（五值）：add 新增 / update 更新 / close 收口 / query 查询 / count 计数——写三仅主 agent 装配面"
+            : "操作（只读二值）：query 查询 / count 计数",
+        },
+      },
+    },
+    readonly,
+    isReadonlyAction(args) { return READ_ACTIONS.includes(args?.action) },
+    async execute(args, ctx) {
+      // ① 入参归一（判序①——P1 同式；缺省 / null ⇒ {}）
+      if (args == null) args = {}
+      else if (typeof args !== "object" || Array.isArray(args)) throw new Error(`ledger：参数须为对象（收到 ${argPreview(args)}）`)
+      // ② 入口级 action 判（P3 缺失 / P5 非法——消费 action；取值域 = 本装配面枚举）
+      const { action, ...rest0 } = args
+      assertToolArgs(entryTool, { action })
+      // ③ 余键喂该 action 伪工具对象（声明源 = 前身工具 parameters 逐字——`action` 键不入 P2 域）
+      const rest = assertToolArgs({ name: `ledger(${action})`, parameters: ACTION_SPECS[action] }, rest0)
+      // ④ 路由既有核函数（包装细节携自原工具 execute 逐字保留：cwd 缺省 / JSON 缩进 / getSessionId 动态 import）
+      switch (action) {
+        case "add": {
+          const { cwd, ...row } = rest
+          const id = ledgerAdd({ cwd: cwd ?? cwdOf(ctx), row })
+          return JSON.stringify({ id, status: "待讨论" })
+        }
+        case "update": {
+          const { cwd, id, ...patch } = rest
+          let executorSessionId
+          if (patch.executor == null) {
+            // 显式 `null` ≡ 略去（§3.1 `null` 口径 · #474——与缺省同分支）；动态 import——零新静态边（K-LX1）
+            const { getSessionId } = await import("./session-slots.mjs")
+            executorSessionId = getSessionId()
+          }
+          return JSON.stringify(ledgerUpdate({ cwd: cwd ?? cwdOf(ctx), id, patch, executorSessionId }))
+        }
+        case "close":
+          return JSON.stringify(ledgerClose({ cwd: rest.cwd ?? cwdOf(ctx), id: rest.id, status: rest.status, evidence: rest.evidence, evidenceReplace: rest.evidenceReplace }))
+        case "query":
+          return JSON.stringify(ledgerQuery({ cwd: rest.cwd ?? cwdOf(ctx), status: rest.status, kind: rest.kind, board: rest.board, trigger: rest.trigger }), null, 2)
+        case "count":
+          return JSON.stringify({ count: ledgerCount({ cwd: rest.cwd ?? cwdOf(ctx) }) })
+        default:
+          // 不可达（② 枚举守门已先拒）——fail-loud 兜底（防未来变体增量 drift）
+          throw new Error(`ledger：action 非法：${argPreview(action)}（取值 ∈ ${enumText(actions)}）`)
+      }
+    },
+  }
 }
+
+/** 统一入口两变体（同名 `ledger`——depth-0 装配全量 ∥ depth>0 各角色段装配只读）。 */
+export const ledgerTool = makeLedgerTool(FULL_ACTIONS, { writeFace: true })
+export const ledgerReadTool = makeLedgerTool(READ_ACTIONS, { readonly: true })
+
+// ── 旧五名弃用壳（设计档 §11.4——code 面保留、不入任何装配面） ────────────────
+
+/** 弃用文案（含旧名 + 统一入口 + 对应 action 指引；execute 抛它 ⇒ 零库动作）。
+ *  description 同文静态化——不经 `DESC`（旧五档退场后 DESC 加载必炸；壳面规避）。 */
+const deprecatedLine = (old, action) => `${old} 已退役（本名不再装配）——请改用统一入口 ledger：action="${action}"（参数面与原工具相同）。`
+
+const deprecatedShell = (old, action, readonly) => ({
+  name: old,
+  description: deprecatedLine(old, action),
+  parameters: ACTION_SPECS[action],
+  readonly,
+  async execute() { throw new Error(deprecatedLine(old, action)) },
+})
+
+export const ledgerQueryTool = deprecatedShell("ledger_query", "query", true)
+export const ledgerCountTool = deprecatedShell("ledger_count", "count", true)
+export const ledgerAddTool = deprecatedShell("ledger_add", "add", false)
+export const ledgerUpdateTool = deprecatedShell("ledger_update", "update", false)
+export const ledgerCloseTool = deprecatedShell("ledger_close", "close", false)

package/ledger-variant-notice.mjs

@@ -0,0 +1,47 @@
+/**
+ * ledger-variant-notice.mjs — 变体键库首跑检测提示（F-LX3 · 设计档 `docs/core/design/LEDGER.md` §12 ·
+ * 批 `docs/batches/2026-10-05-ledger-variant-db-notice.md` · 台账 #935）。
+ *
+ * 升级到含键归一的版本后，存量变体键库（旧产物写入的盘符翻转拼写键——`legacyKeyVariants`）不再无声搁浅：
+ * CLI 主入口启动时对**当前项目根**检测，命中 ⇒ 单行 i18n 提示（`thincoder ledger audit` 查看 ∥
+ * `thincoder ledger migrate` 收正）；**只提示，零自动动作**（不迁移 / 不删档 / 不建库 / 零写）。
+ * 判据 = 变体键档**文件存在**（KD-VN1——零开库：不触 SQLite / 不建 WAL；坏档 / 空库不漏报）。
+ * 每进程至多一次 = 模块级闩（首唤检测 / 后唤零动作——重置缝 `_resetLedgerVariantNoticeForTest`，
+ * 先例 = `_resetLedgerDirForTest`）。降级 = 全径 try ⇒ 返回 `null`（零抛零阻塞——启动链不受累）。
+ * 本档静态链入 `ledger-migrate.mjs`（node:sqlite）⇒ 消费侧一律动态 import（W8 契约②）。
+ * 检测面零新建哈希式：键式直引 `ledgerKey` ∥ 变体枚举直引 `legacyKeyVariants`（单源不二写）。
+ */
+import { statSync } from "node:fs"
+import { join, resolve } from "node:path"
+
+import { t } from "./i18n.mjs"
+import { ledgerDirPath, ledgerKey } from "./ledger-db.mjs"
+import { legacyKeyVariants } from "./ledger-migrate.mjs"
+import { resolveProjectRoot } from "./manifest.mjs"
+
+/** 默认探针（吞错形——与 `migrate` 源枚举过滤同判据）：`statSync(p).isFile()`，任何 stat 失败 ⇒ false。 */
+const defaultExists = (p) => { try { return statSync(p).isFile() } catch { return false } }
+
+/** 一次为限闩（「每进程」= ESM 模块实例的天然粒度——首唤检测 / 后唤零动作）。 */
+let noticeChecked = false
+
+/** 测试重置缝（同 `_resetLedgerDirForTest` 先例——闩为进程级事实，直测需复位）。 */
+export function _resetLedgerVariantNoticeForTest() { noticeChecked = false }
+
+/**
+ * 检测当前项目根的变体键库：命中 ⇒ 单行提示文案（i18n 键 `ledger.variantDbNotice`——zh ∥ en 单源），
+ * 无 ∥ 已查过 ∥ 任何异常（根解析 / 探针 / 文案解析）⇒ `null`（静默降级——零抛）。
+ * 命中判据 = 变体键（`k !== 主键`）中有档在盘（文件存在——零开库）；主库在否不影响判定。
+ * @param {{cwd?: string, dir?: string, locale?: string, exists?: (p: string) => boolean}} [opts]
+ * @returns {string|null} 单行文案 / null
+ */
+export function ledgerVariantNotice({ cwd = process.cwd(), dir = ledgerDirPath(), locale = "en", exists = defaultExists } = {}) {
+  if (noticeChecked) return null
+  noticeChecked = true
+  try {
+    const root = resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")
+    const targetKey = ledgerKey(root)
+    const hit = legacyKeyVariants(root).filter((k) => k !== targetKey).some((k) => exists(join(dir, `${k}.db`)))
+    return hit ? t("ledger.variantDbNotice", {}, locale) : null
+  } catch { return null }
+}