@thincoder/core 0.10.6 → 0.10.8

package/ledger-cmd.mjs

@@ -11,8 +11,7 @@
  * 消费侧静态 import 会破 W8 契约②）。
  */
 import { resolve } from "node:path"
-import { ALLOWED_MIGRATIONS, nowIso, openLedger, PENDING_STATUSES, AGING_DAYS } from "./ledger-db.mjs"
-import { resolveProjectRoot } from "./manifest.mjs"
+import { AGING_DAYS, ALLOWED_MIGRATIONS, nowIso, openLedger, PENDING_STATUSES, resolveLedgerRoot } from "./ledger-db.mjs"
 import { resolveDeclaredRef } from "./declaration.mjs"
 
 /** 逐行老化判真（LEDGER.md §13.4 · 2026-10-07 批 ledger-tool）：未决四态（`PENDING_STATUSES`）∧
@@ -60,8 +59,8 @@ export function ledgerCount({ cwd } = {}) {
  *  （首个 `§` 前子串，trim）须经基准 `resolve(base, …)` 指向存在的档；缺文件部分（`§2` / 空串 /
  *  全空白）⇒ 拒；不在册 / 非文件 ⇒ 拒（throw，行不变）。
  *  判位与迁移表判同层（落盘前）；文案前缀 = 调用函数名（与同函数既有两条文案同款）。
- *  基准 `base` = **与台账库关联键同源**（2026-09-18 fix 轮 · O1 收正）：`resolveProjectRoot(cwd) ??
- *  resolve(cwd ?? ".")`——同表达式见 `ledger-db.mjs` `ledgerDbPath`；容器根会话（锚 cwd 下唯一注册
+ *  基准 `base` = **与台账库关联键同源**（设计档 §6.1 口径 2——根推导单源）：`resolveLedgerRoot(cwd)?.root
+ *  ?? resolve(cwd ?? ".")`——同一子表达式见 `ledger-db.mjs` `ledgerDbPath`；容器根会话（锚 cwd 下唯一注册
  *  子仓 P）与子仓会话 ⇒ 库键与指针基准同取 P（同库同基准；原实现 `resolve(cwd, …)` = 原始 cwd 会误拒）。
  *  #832 ∥ #834：声明源前缀形同判——判定单源 = `declaration.mjs` `resolveDeclaredRef`（① 仓根解析 →
  *  ② 声明源前缀解析序；同名多仓 ⇒ 声明序首者）——**与迁移旗（`ledger-migrate.mjs` `writeGateFlag`）
@@ -71,7 +70,7 @@ function assertTaskBookGate(cwd, fnName, status, taskBook) {
   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 base = resolveLedgerRoot(cwd)?.root ?? resolve(cwd ?? ".")
   const { ok, abs } = resolveDeclaredRef(base, part)
   if (!ok) throw new Error(`${fnName}：task_book 指向的档不存在：${taskBook}（解析 = ${abs}）`)
 }

package/ledger-db.mjs

@@ -6,6 +6,9 @@
  * 靠 DDL（AC-M2-2），不靠应用层 if。归档 = 软删除（状态值，无物理 DELETE——KD-M2-4）。
  * 本档静态 import node:sqlite ⇒ 消费侧一律动态 import 本模块链（W8 契约②——KD-M2-3）。
  *
+ * 项目根推导单源（`resolveLedgerRoot`）+ 同级枚举（`ledgerChildren`）居本档——键 / 库位 / 根同源
+ * （设计档 `LEDGER.md` §2.1「根解析面」/ §3.8）：读写同一判据（档在盘 ∨ 以目录自身路径为键的库在盘）。
+ *
  * 落点（2026-09-17 用户裁定收正）：台账库**不在项目目录**——住用户数据目录
  * `~/.thincoder/ledger/<sha1(normalizeCwd(项目根绝对路径))[:16]>.db`（工作树外、天然不进 git；
  * 同区先例 = configDir 的 memory.db / tool-results）。项目根仅作**关联键**，不在项目内留任何文件。
@@ -13,12 +16,12 @@
  * `normalizeCwd`——与 session / checkpoint / traces / peers 同契约，跨端同 cwd 同键同库。
  */
 import { createHash } from "node:crypto"
-import { existsSync, mkdirSync } from "node:fs"
-import { join, resolve } from "node:path"
+import { existsSync, mkdirSync, opendirSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
 import { DatabaseSync } from "node:sqlite"
 
 import { configDir } from "./config-io.mjs"
-import { projectRootView, resolveProjectRoot } from "./manifest.mjs"
+import { MANIFEST_REL, projectRootView } from "./manifest.mjs"
 // 归一步单源（KD-LN1——直引，不抽新 util：先例 = peer-domains.mjs / traces/trace-store.mjs）。
 import { normalizeCwd } from "./session-slots.mjs"
 
@@ -42,14 +45,89 @@ export function ledgerKey(root) {
   return createHash("sha1").update(normalizeCwd(root)).digest("hex").slice(0, 16)
 }
 
+/** 键控库文件路径（根 → 库位）——**内部形**：根推导内部判「库在盘」时用它，**不得经 `ledgerDbPath`**
+ *  （互指即环，设计档 §3.8「无自指」）。库目录 = `ledgerDir`（`_setLedgerDirForTest` 覆盖 ⇒ 夹具根外零写）。 */
+const keyedDbFile = (root) => join(ledgerDir, `${ledgerKey(root)}.db`)
+
+/** 「已注册」判据（设计档 §2.1——**唯一**事实，两臂取一即成立）：
+ *  档臂 = 该目录带项目声明档 `PROJECT-MANIFEST.json`（档在盘）；
+ *  库臂 = 以该目录自身路径为键的键控库在盘 ∧ 该目录**非工作区态**（键控库存在 ≠ 可作项目）；
+ *  工作区判据只在库在盘时才查（`projectRootView` 含 fs 扫描——档臂已中即短路）。 */
+function isRegistered(dir) {
+  if (existsSync(join(dir, MANIFEST_REL))) return true
+  if (!existsSync(keyedDbFile(dir))) return false
+  return projectRootView(dir).state !== "workspace"
+}
+
+/** 同级枚举上限（成本有界：父目录超此规模 = 缓存 / 临时等非仓族形态 → 退化空集）。
+ *  2026-10-16 批 ledger-root-derivation 自 `ledger.mjs` 随迁（根推导收敛序 ∥ 族发现同级枚举同源）。 */
+export const MAX_SIBLING_SCAN = 100
+
+/** 目录下**已注册**（档 ∨ 库——§2.1 单谓词）的直接子目录（目录名升序；不可读 ∥ 超限 ⇒ 空集；
+ *  **惰性枚举 + 上限**——大目录零全量扫描）。消费面 = 根推导收敛序 ∥ 族发现 ∥ 轻通道闸候选枚举。
+ *  `ledger` = 该子目录根的键控库路径（谓词含档臂 ⇒ 可能尚未在盘）。2026-10-16 批自 `ledger.mjs` 随迁。 */
+export function ledgerChildren(dir) {
+  const out = []
+  let handle
+  try { handle = opendirSync(dir) } catch { return out }
+  try {
+    let n = 0
+    for (;;) {
+      const ent = handle.readSync()
+      if (!ent) break
+      if (++n > MAX_SIBLING_SCAN) return []
+      if (!ent.isDirectory()) continue
+      const root = join(dir, ent.name)
+      if (!isRegistered(root)) continue
+      out.push({ root, ledger: keyedDbFile(root) })
+    }
+  } catch { /* 读中断 → 已得子集（尽力而为） */ }
+  finally { try { handle.closeSync() } catch { /* 已关 */ } }
+  return out.sort((a, b) => (a.root < b.root ? -1 : a.root > b.root ? 1 : 0))
+}
+
+/** 项目根推导**单源**（设计档 §2.1「根解析面」/ §3.8——读写同一判据、同一实现）：
+ *  自 `target`（「动作目标路径」；缺省 = `.`）起沿**祖先链**向上（含自身）取**最近一个「已注册」目录**
+ *  ⇒ `{ root, basis: 'ancestor' }`（自明——回执逐字零改）。
+ *  祖先链无命中 ∧ `descend: true` ⇒ **向下收敛**锚的直接子目录（`ledgerChildren` 同款惰性枚举 +
+ *  上限、名序升序）：恰一 ⇒ 取之；≥2 ⇒ ① 先取**有键控库**者（账已在盘 = 事实）② 该集名序首者 ⇒
+ *  `{ root, basis: 'descendant' }`（向下发现——**须报明**）；零已注册子目录 ⇒ `null`（无根）。
+ *  `descend: false` ⇒ 只问祖先支（族发现 ∥ 标记面——容器 ∥ 工作区锚 ⇒ `null` ⇒ 族求和）。
+ *  **无自指**：内部「库在盘」判据只用 `ledgerKey` + `keyedDbFile`（不经 `ledgerDbPath`）。
+ *  @param {string} [target] 动作目标路径（目录）
+ *  @param {{descend?: boolean}} [opts] `descend` 缺省 `true`（动作面——`openLedger` / `ledgerDbPath` / 单范围读）
+ *  @returns {{root: string, basis: 'ancestor'|'descendant'}|null} 项目根 + 判据来源 / 无根（`null`） */
+export function resolveLedgerRoot(target, { descend = true } = {}) {
+  const start = resolve(target ?? ".")
+  let dir = start
+  for (;;) {
+    if (isRegistered(dir)) return { root: dir, basis: "ancestor" }
+    const parent = dirname(dir)
+    if (parent === dir) break // 盘根 → 祖先链无已注册者
+    dir = parent
+  }
+  if (!descend) return null
+  const children = ledgerChildren(start)
+  if (children.length === 0) return null
+  if (children.length === 1) return { root: children[0].root, basis: "descendant" }
+  const withDb = children.filter((c) => existsSync(c.ledger))
+  return { root: (withDb.length > 0 ? withDb : children)[0].root, basis: "descendant" }
+}
+
+/** 无根文案（单源——设计档 §3.8「无根契约」逐字；`openLedger` 写面 ∥ `ledgerDbPath` 共用同一句）。 */
+const noRootMessage = (start) =>
+  `台账：自 ${start} 未能推导项目根——祖先链与本级子目录均无已注册项目（带 PROJECT-MANIFEST.json 或已有键控台账库）`
+
 /** 项目根 → 库路径（稳定键 = `ledgerKey` 前 16 位——路径唯一标识，不含分隔符）。
- *  项目根与 manifest 同一判据（归属 ∨ 发现——`resolveProjectRoot`；无 manifest ⇒ `resolve(cwd ?? ".")`
- *  兜底且**单值**）——与写门指针基准同一子表达式（键另加 `normalizeCwd` 一步，§2.1）。
+ *  **归单源**（2026-10-16 批 ledger-root-derivation）：根 = `resolveLedgerRoot(cwd)`——与读面 / 写面
+ *  同一推导；无根 ⇒ 抛**同一**无根文案（键需根，不产第二答案）。
  *  v2 键归一（2026-09-25 批）：盘符本大写（CLI）⇒ 键恒等零变；小写盘符（VSC `uri.fsPath`）
  *  并入同键 ⇒ 同项目两端同库（收正前 = 同项目两键两库）。 */
 export function ledgerDbPath(cwd) {
-  const root = resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")
-  return join(ledgerDir, `${ledgerKey(root)}.db`)
+  const start = resolve(cwd ?? ".")
+  const derived = resolveLedgerRoot(start)
+  if (!derived) throw new Error(noRootMessage(start))
+  return keyedDbFile(derived.root)
 }
 
 /** 未决四态（「活条目」口径 = 计数单源 WHERE 集；已核销 / 已废弃 = 归档态）。 */
@@ -135,25 +213,26 @@ function markSchemaVersion(db) {
   if (v < LEDGER_SCHEMA_VERSION) db.exec(`PRAGMA user_version = ${LEDGER_SCHEMA_VERSION}`)
 }
 
-/** 开库（cwd = 项目根——仅作关联键）→ DatabaseSync 句柄 + 幂等建表 + 老库幂等迁移（executor 列）。
- *  读面（create=false）：库文件不存在 → 返回 null（空账——读面不建库、无副作用）。
- *  写面（create=true）：库文件不存在自动建（台账目录随之创建）；项目根目录不存在 → 抛友好错误。
+/** 开库（cwd = 「动作目标路径」）→ DatabaseSync 句柄 + 幂等建表 + 老库幂等迁移（executor 列）。
+ *  **根推导**（设计档 §2.1 / §3.8）：项目根 = `resolveLedgerRoot(cwd)`——读写同一判据；嵌套取近者、
+ *  容器锚向下收敛。**无根（`null`）**：写面（`create:true`）抛（fail-loud、零落盘零建库）；读面空账
+ *  （`null`——与「库不在 = 空账」同形）。
+ *  读面（create=false）：库文件不存在 → 返回 null（读面不建库、无副作用）。
+ *  写面（create=true）：库文件不存在自动建（台账目录随之创建）。
  *  **只读态**（readOnly=true——读面专用）：只读句柄 + 零 DDL / ALTER + items 探针（见 openReadOnly）；
  *  如实副作用：旧库（缺 executor 列）**读**不再自动补列——补列归写面开库；读出行缺列按 null 归一。
- *  **歧义锚**（≥2 候选——`projectRootView` `ambiguous` 态）⇒ **显式拒**（列候选 + 显式项目根指引；
- *  零写——不静默回退锚；族锚「项目不可解析」，AC-M2-17）；兜底 `resolve(cwd ?? ".")` 只属 none 态。 */
+ *  「目录不存在」的真错照抛（fail-loud——先于推导，文案逐字零改）。 */
 export function openLedger(cwd, { create = false, readOnly = 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 start = resolve(cwd ?? ".")
+  if (!existsSync(start)) {
+    throw new Error(`项目目录不存在：${start}——cwd 请给存在的项目根（相对路径按当前工作目录解析；缺省 = 会话项目根）`)
   }
-  const file = ledgerDbPath(dir)
-  if (!existsSync(dir)) {
-    throw new Error(`项目目录不存在：${dir}——cwd 请给存在的项目根（相对路径按当前工作目录解析；缺省 = 会话项目根）`)
+  const derived = resolveLedgerRoot(start)
+  if (!derived) {
+    if (create) throw new Error(noRootMessage(start)) // 写面抛——零落盘零建库
+    return null // 读面空账（未注册目录下旧行为亦为空 ⇒ 零回归）
   }
+  const file = keyedDbFile(derived.root)
   if (!existsSync(file) && !create) return null
   if (readOnly) return openReadOnly(file)
   try { mkdirSync(ledgerDir, { recursive: true }) } catch { /* 已存在 / 并发建目录竞争——忽略 */ }

package/ledger-migrate.mjs

@@ -12,7 +12,7 @@ import { basename, dirname, join, resolve } from "node:path"
 import { DatabaseSync } from "node:sqlite"
 
 import { resolveDeclaredRef } from "./declaration.mjs"
-import { ledgerDirPath, ledgerKey, openLedger } from "./ledger-db.mjs"
+import { ledgerDirPath, ledgerKey, openLedger, resolveLedgerRoot } from "./ledger-db.mjs"
 import { resolveProjectRoot } from "./manifest.mjs"
 
 /** 12 数据列（**等值比对列集**——不含 id：id 重发，§2.2 语义保全 / AC-M2-12）。 */
@@ -92,9 +92,9 @@ function fromKeyRefusal(fromKeys, dir) {
   return null
 }
 
-/** 迁移计划（dry-run / confirm 共用）。cwd 口径 = 写门口径 2 同一子表达式（`resolveProjectRoot` ∨ 兜底）。 */
+/** 迁移计划（dry-run / confirm 共用）。cwd 口径 = 写门口径 2 同一子表达式（根推导单源 `resolveLedgerRoot(cwd)?.root` ∨ 兜底）——与实开库（`openLedger`）同源。 */
 export function planLedgerMigration(cwd, { fromKeys = [] } = {}) {
-  const projectRoot = resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")
+  const projectRoot = resolveLedgerRoot(cwd)?.root ?? resolve(cwd ?? ".")
   const dir = ledgerDirPath()
   const targetKey = ledgerKey(projectRoot)
   const targetPath = join(dir, `${targetKey}.db`)

package/ledger-read.mjs

@@ -10,19 +10,18 @@
  * （列集单源 = `DATA_COLUMNS`——D-10 直引，不另立副本；`evidence` 仅 full 入行）；缺列（旧库）按
  * null 归一；`schemaVersion` = 库 `PRAGMA user_version` 如实回读（旧库未标 = 0）；库不在 / 非台账库
  * ⇒ 项目不出项（空集）。
- * 范围（§2.4）：单范围 = 解析后项目根一项（`resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")`——与库键
- * 同源）；`--family` = `discoverFamily` 发现序逐项（不可读跳过——既有语义）。
+ * 范围（§2.4）：单范围 = 推导所得项目根一项（`resolveLedgerRoot(cwd)`——与库键同源；无根 ⇒ 空集）；
+ * `--family` = `discoverFamily` 发现序逐项（不可读跳过——既有语义）。
  *
  * W8 契约②：本档静态入 `ledger-db.mjs`（node:sqlite）⇒ 消费侧一律**动态 import** 本档。
  * D-11：`ledger.mjs` 零编辑——族发现只 import `discoverFamily`。
  */
-import { basename, resolve } from "node:path"
+import { basename } from "node:path"
 
 import { ledgerQuery } from "./ledger-cmd.mjs"
 import { discoverFamily } from "./ledger.mjs"
 import { DATA_COLUMNS } from "./ledger-migrate.mjs"
-import { resolveProjectRoot } from "./manifest.mjs"
-import { openLedger } from "./ledger-db.mjs"
+import { openLedger, resolveLedgerRoot } from "./ledger-db.mjs"
 
 /** 行出形（§3.2）：`id` + 数据列序（`evidence` 仅 full）；缺列按 null 归一。 */
 function exportRow(r, full) {
@@ -50,8 +49,8 @@ function readProject(root, full) {
 export function ledgerExport({ cwd, family = false, full = false } = {}) {
   const anchor = cwd ?? process.cwd()
   if (!family) {
-    const root = resolveProjectRoot(anchor) ?? resolve(anchor)
-    const item = readProject(root, full)
+    const derived = resolveLedgerRoot(anchor)
+    const item = derived ? readProject(derived.root, full) : null
     return { projects: item ? [item] : [] }
   }
   const projects = []

package/ledger-tools.mjs

@@ -11,11 +11,20 @@
  * 消费侧一律动态 import（`ledger-db.mjs` 静态 import node:sqlite ⇒ W8 契约②）。
  */
 import { ledgerAdd, ledgerClose, ledgerCount, ledgerQuery, ledgerUpdate } from "./ledger-cmd.mjs"
+import { resolveLedgerRoot } from "./ledger-db.mjs"
 import { DESC } from "./tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/ledger.md（DESC 单解析面）
 
-/** 工具 cwd 供值面（缺省 → 当前项目根）。 */
+/** 工具 cwd 供值面（缺省 → 当前会话锚——「动作目标路径」；项目根由核 `resolveLedgerRoot` 推导）。 */
 const cwdOf = (ctx) => ctx?.agent?.cwd ?? ctx?.cwd ?? process.cwd()
 
+/** 根推导**报明面**（设计档 §3.8「报明形态」）：向下发现（`basis === 'descendant'`——容器锚收敛序）⇒
+ *  对象形回执增 `root` 键；祖先支（自明路径）⇒ `null`（展开零键——回执逐字零改）。供值面 = 核同一
+ *  单源 `resolveLedgerRoot`（工具层零自算根；单实现、多调用点）。 */
+const reportedRoot = (cwd) => {
+  const derived = resolveLedgerRoot(cwd)
+  return derived && derived.basis === "descendant" ? { root: derived.root } : null
+}
+
 // ── 工具层参数守卫（设计档 §3.2 · 2026-09-27 快车道修复 · Gitee #IKIQGK / 台账 #472） ──
 
 /** 值预览（P1–P5 文案的 `<预览>`——设计档 §3.2）：`JSON.stringify`，超 80 字符截断加 `…`
@@ -80,7 +89,7 @@ const FULL_ACTIONS = ["add", "update", "close", "query", "count"]
 const READ_ACTIONS = ["query", "count"]
 
 /** cwd 参数描述（五前身声明同文——文本单点）。 */
-const CWD_DESC = "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根"
+const CWD_DESC = "本次动作的目标路径——项目根由它推导：沿祖先链最近的项目目录（带 PROJECT-MANIFEST.json 或已有台账库）；容器目录下收敛到子项目。台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话锚"
 
 /** 各 action 声明条目（= 前身旧工具 `parameters` 逐字；伪工具对象守卫 + 弃用壳共用单源）。 */
 const ACTION_SPECS = {
@@ -207,25 +216,31 @@ function makeLedgerTool(actions, { readonly = false, writeFace = false } = {}) {
       switch (action) {
         case "add": {
           const { cwd, ...row } = rest
-          const id = ledgerAdd({ cwd: cwd ?? cwdOf(ctx), row })
-          return JSON.stringify({ id, status: "待讨论" })
+          const target = cwd ?? cwdOf(ctx)
+          const id = ledgerAdd({ cwd: target, row })
+          return JSON.stringify({ id, status: "待讨论", ...reportedRoot(target) })
         }
         case "update": {
           const { cwd, id, ...patch } = rest
+          const target = cwd ?? cwdOf(ctx)
           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 }))
+          return JSON.stringify({ ...ledgerUpdate({ cwd: target, id, patch, executorSessionId }), ...reportedRoot(target) })
+        }
+        case "close": {
+          const target = rest.cwd ?? cwdOf(ctx)
+          return JSON.stringify({ ...ledgerClose({ cwd: target, id: rest.id, status: rest.status, evidence: rest.evidence, evidenceReplace: rest.evidenceReplace }), ...reportedRoot(target) })
         }
-        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) }) })
+        case "count": {
+          const target = rest.cwd ?? cwdOf(ctx)
+          return JSON.stringify({ count: ledgerCount({ cwd: target }), ...reportedRoot(target) })
+        }
         default:
           // 不可达（② 枚举守门已先拒）——fail-loud 兜底（防未来变体增量 drift）
           throw new Error(`ledger：action 非法：${argPreview(action)}（取值 ∈ ${enumText(actions)}）`)

package/ledger.mjs

@@ -15,10 +15,8 @@
  *
  * W8 契约②：ledger-db.mjs 静态 import node:sqlite ⇒ 消费侧一律**动态 import** 本档（禁止静态 import）。
  */
-import { opendirSync, statSync } from "node:fs"
-import { basename, dirname, join, resolve } from "node:path"
-import { projectRootView } from "./manifest.mjs"
-import { ledgerDbPath, PENDING_STATUSES, AGING_DAYS } from "./ledger-db.mjs"
+import { basename, dirname, resolve } from "node:path"
+import { AGING_DAYS, PENDING_STATUSES, ledgerChildren, ledgerDbPath, resolveLedgerRoot } from "./ledger-db.mjs"
 import { ledgerQuery } from "./ledger-cmd.mjs"
 import { executorTail } from "./ledger-executors.mjs"
 
@@ -45,55 +43,20 @@ export function entryTitle(text) {
   return norm.length > 20 ? norm.slice(0, 20) + "…" : norm
 }
 
-const isFile = (p) => { try { return statSync(p).isFile() } catch { return false } }
-
-/** 向上（含自身）最近的已注册台账项目根 → {root, ledger} / null（F4——CLI 锚 = cwd；
- *  标记 = 用户数据目录里以该项目路径为键的台账库——项目目录内不落任何标记文件）。 */
+/** 向上（含自身）最近的**已注册**项目根 → {root, ledger} / null（F4——CLI 锚 = cwd）。
+ *  薄委托 `resolveLedgerRoot(anchor, { descend: false })`（设计档 §3.8——**取祖先支**）：`root` = 推导所
+ *  得项目根（非锚）；容器 ∥ 工作区锚 ⇒ `null` ⇒ 族发现按容器形（族求和——§7.2 / AC-M2-18 / AC-M2-19）。 */
 export function findProject(anchor) {
-  let dir = resolve(anchor)
-  for (;;) {
-    const ledger = ledgerDbPath(dir)
-    if (isFile(ledger)) return { root: dir, ledger }
-    const parent = dirname(dir)
-    if (parent === dir) return null
-    dir = parent
-  }
-}
-
-/** 同级枚举上限（N2 成本有界：父目录超此规模 = 缓存 / 临时等非仓族形态 → 退化空集，只显当前项目）。 */
-export const MAX_SIBLING_SCAN = 100
-
-/** 目录下已注册台账的直接子目录（目录名升序；不可读 → []；**惰性枚举 + 上限**——大目录零全量扫描）。
- *  导出面 = 族发现（本档）∥ 轻通道闸候选枚举（`agent/light-round.mjs`——同级判据单源）。 */
-export function ledgerChildren(dir) {
-  const out = []
-  let handle
-  try { handle = opendirSync(dir) } catch { return out }
-  try {
-    let n = 0
-    for (;;) {
-      const ent = handle.readSync()
-      if (!ent) break
-      if (++n > MAX_SIBLING_SCAN) return []
-      if (!ent.isDirectory()) continue
-      const root = join(dir, ent.name)
-      const ledger = ledgerDbPath(root)
-      if (isFile(ledger)) out.push({ root, ledger })
-    }
-  } catch { /* 读中断 → 已得子集（尽力而为） */ }
-  finally { try { handle.closeSync() } catch { /* 已关 */ } }
-  return out.sort((a, b) => (a.root < b.root ? -1 : a.root > b.root ? 1 : 0))
+  const derived = resolveLedgerRoot(anchor, { descend: false })
+  return derived ? { root: derived.root, ledger: ledgerDbPath(derived.root) } : null
 }
 
-/** 项目族发现：{current, projects}——projects = current + 其同级含台账库目录（**发现序：current 在前**，
- *  其余按目录名升序）；current 缺（容器目录，K6）→ 锚本地：取锚自身含台账库的直接子目录（不沿祖先链上找）。
- *  **歧义根不充当项目**（轻通道轮 · 2026-10-04）：命中锚若项目解析 `ambiguous`（≥2 候选——`projectRootView`）
- *  ⇒ 该锚不可扫描（`openLedger` 歧义拒）——其键控库（先于 #828 写门的存量空壳 / 幽灵）不得遮蔽族发现；
- *  按容器形落子目录族（需求：打开容器根 ⇒ 族内合计——标记范围批 §1 原话）。 */
+/** 项目族发现：{current, projects}——current = `findProject`（**祖先支**：容器 ∥ 工作区锚 ⇒ `null` ⇒ 按
+ *  容器形落子目录族）；projects = current + 其**同级已注册**目录（**发现序：current 在前**，其余按目录
+ *  名升序）；current 缺（容器目录，K6）→ **锚本地**：取锚自身**已注册**的直接子目录（不沿祖先链上找）。
+ *  「工作区根不充当项目」的判据单源 = `resolveLedgerRoot` 的库臂排除（§2.1）——本函数零自持判据。 */
 export function discoverFamily(anchor) {
-  const hit = findProject(anchor)
-  // 歧义根跳过（键控库存在 ≠ 可作项目——扫描面 `buildScan` 对歧义锚必拒；遮蔽则标记静默缺席）。
-  const current = hit && projectRootView(hit.root).state === "ambiguous" ? null : hit
+  const current = findProject(anchor)
   if (current) {
     const siblings = ledgerChildren(dirname(current.root)).filter((p) => p.root !== current.root)
     return { current, projects: [current, ...siblings] }
@@ -105,10 +68,16 @@ export function discoverFamily(anchor) {
  *  agedKeys/agedTitles/thresholdReached/boards/actionable/root/name/ledger。行龄 = 时间戳
  *  （updated_at ?? created_at 距今 > days；未知不计——零假阳降级，同 v1 行龄未知口径）。
  *  `now`/`days` = 注入面（确定性用例——替代 v1 ageOf git 注入面）。
+ *  **根推导**（设计档 §3.8）：`root` / `name` / `ledger` = `resolveLedgerRoot(anchor)` 推导所得项目根（非锚
+ *  ——容器 ∥ 工作区锚取收敛序之根）——与行集读取同一单源；无根 ⇒ `ledger` = `null`（不落兜底根——
+ *  该态下 `root` / `name` 回落锚、行集为空，且该 scan 不进族枚举（`discoverFamily` 容器支只列已注册子目录））。
  *  `inflightExecutors`（F-LX1 · sync 零变——K-LX2）：在途且 executor 非空行集原样携带
  *  {executor, updated_at, created_at}——判活解析由 `resolveExecutorStates` async 单源负责，本函数零探测。 */
 export function buildScan({ cwd, days = AGING_DAYS, now = Date.now() } = {}) {
-  const rows = ledgerQuery({ cwd })
+  const anchor = resolve(cwd)
+  const derived = resolveLedgerRoot(anchor)
+  const root = derived ? derived.root : anchor
+  const rows = ledgerQuery({ cwd: anchor })
   const pending = rows.filter((r) => PENDING_STATUSES.includes(r.status))
   const poolEntries = pending.filter((r) => r.kind === "requirement")
   const techEntries = pending.filter((r) => r.kind === "tech_todo")
@@ -123,12 +92,11 @@ export function buildScan({ cwd, days = AGING_DAYS, now = Date.now() } = {}) {
     if (key) boards.set(key, (boards.get(key) ?? 0) + 1)
   }
   const thresholdReached = poolEntries.length >= THRESHOLD_POOL || [...boards.values()].some((n) => n >= THRESHOLD_BOARD)
-  const root = resolve(cwd)
   const inflightExecutors = pending
     .filter((r) => r.status === "在途" && r.executor)
     .map((r) => ({ executor: r.executor, updated_at: r.updated_at ?? null, created_at: r.created_at ?? null }))
   return {
-    name: basename(root), root, ledger: ledgerDbPath(root),
+    name: basename(root), root, ledger: derived ? ledgerDbPath(root) : null,
     pool: poolEntries.length, tech: techEntries.length, aged: aged.length,
     agedKeys: aged.map((r) => normalizeEntry(r.title)), agedTitles: aged.map((r) => entryTitle(r.title)),
     thresholdReached, boards, actionable: aged.length > 0 || thresholdReached,
@@ -178,8 +146,9 @@ export function detailScans(scans, current) {
 }
 
 // ── re-export（拆分件接口——命令面接线 = 动态 import 本档，KD-M2-3；`AGING_DAYS` 常量单源 = `ledger-db.mjs`
-//    ——2026-10-07 批 ledger-tool 自本档迁入，公共面零变） ──
-export { AGING_DAYS, ALLOWED_MIGRATIONS, ledgerDbPath, ledgerKey, ledgerDirPath, openLedger, PENDING_STATUSES, _setLedgerDirForTest, _resetLedgerDirForTest, ensureExecutorColumn } from "./ledger-db.mjs"
+//    ——2026-10-07 批 ledger-tool 自本档迁入，公共面零变；`ledgerChildren` / `MAX_SIBLING_SCAN` / `resolveLedgerRoot`
+//    ——2026-10-16 批 ledger-root-derivation 随迁 / 新增，公共面形零改） ──
+export { AGING_DAYS, ALLOWED_MIGRATIONS, MAX_SIBLING_SCAN, ledgerChildren, ledgerDbPath, ledgerKey, ledgerDirPath, openLedger, PENDING_STATUSES, resolveLedgerRoot, _setLedgerDirForTest, _resetLedgerDirForTest, ensureExecutorColumn } from "./ledger-db.mjs"
 export { ledgerAdd, ledgerClose, ledgerCount, ledgerQuery, ledgerUpdate } from "./ledger-cmd.mjs"
 export { ledgerTool, ledgerReadTool, ledgerAddTool, ledgerCloseTool, ledgerCountTool, ledgerQueryTool, ledgerUpdateTool } from "./ledger-tools.mjs"
 export { runLedgerAudit, runLedgerMigrate } from "./ledger-migrate.mjs"

package/log.mjs

@@ -16,8 +16,10 @@
  *   ① 字段名精确匹配黑名单（apiKey/designToken/password/secret/token，大小写不敏感；
  *      另加防御性名称 authorization/proxy/proxyUri——防凭据型 URL/头字段泄漏——§2.5）
  *      → 整个字段丢弃；
- *   ② 内容只扫密钥形态（sk-xxx / Bearer xxx / key=… 等）→ 截断到形态之前
+ *   ② 内容只扫密钥形态（sk-xxx / Bearer xxx / key=… / token 值形等）→ 截断到形态之前
  *      ——宁可丢信息不漏密钥。
+ *      token 值形（`uuid:epoch`——2026-10-14 design-token-recovery 批并入）：design-slots
+ *      reveal 结果经 `tool:done` head 落盘时不落值（与 batch.mjs 凭据第三形同判据）。
  *   工具事件不记 args；URL 不入事件（llm/tool 事件从不携带 URL；err 文本经形态扫描）。
  * - 摘要截断（B 方案，2026-09-03 用户裁定）：截断处带 "…" 标记（截后仍 ≤上限）。
  * - 测试隔离：node --test 进程（NODE_TEST_CONTEXT）默认不写盘——防测试事件污染真实
@@ -37,8 +39,8 @@ import { join } from "node:path"
 export const MAX_LINE = 512
 /** 字段名精确黑名单（NF-L3/§2.4——2026-09-03 评审 refinement #7：与 §2.4 词表一致含 token） */
 const BLACKLIST_FIELDS = new Set(["apikey", "designtoken", "password", "secret", "token", "authorization", "proxyuri", "proxy"])
-/** 内容密钥形态扫描（大小写不敏感）——命中即截断到形态前 */
-const SECRET_FORM = /(\bsk-[A-Za-z0-9_-]{6,}|\bBearer\s+[A-Za-z0-9._~+/=-]{6,}|\b(?:api[_-]?key|key|token|secret|password|pwd|passwd)\s*[=:]\s*['"]?[A-Za-z0-9._~+/=-]{6,})/i
+/** 内容密钥形态扫描（大小写不敏感）——命中即截断到形态前（含 token 值形 `uuid:epoch`——同 batch.mjs 凭据第三形判据） */
+const SECRET_FORM = /(\bsk-[A-Za-z0-9_-]{6,}|\bBearer\s+[A-Za-z0-9._~+/=-]{6,}|\b(?:api[_-]?key|key|token|secret|password|pwd|passwd)\s*[=:]\s*['"]?[A-Za-z0-9._~+/=-]{6,}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}:\d{10,16})/i
 /** 字符串字段长度兜底：head ≤300 / err ≤200 / 其余 ≤120 */
 const FIELD_CAPS = { head: 300, err: 200 }
 
@@ -154,6 +156,18 @@ export function redactSecret(fieldKey, value) {
   return hit ? s.slice(0, hit.index) + "[redacted]" : s
 }
 
+/** 结构面遮蔽（#1432——tool-errors args 落痕前过同一链）：键级 ∥ 内容级复用 `redactSecret`；嵌套对象 ∥ 数组递归；
+ *  非串值仅在键名命中黑名单时整键遮蔽（否则原样 ∥ 递归）——「宁可丢信息不漏密钥」同判据。 */
+export function redactArgs(value) {
+  if (Array.isArray(value)) return value.map(redactArgs)
+  if (value && typeof value === "object") {
+    const out = {}
+    for (const [k, v] of Object.entries(value)) out[k] = typeof v === "string" || BLACKLIST_FIELDS.has(String(k).toLowerCase()) ? redactSecret(k, v) : redactArgs(v)
+    return out
+  }
+  return typeof value === "string" ? redactSecret("", value) : value
+}
+
 /** 内容级净化：密钥形态截断到形态前（②）；超长截断 + "…" 标记。 */
 export function sanitizeString(key, value) {
   let s = String(value)

package/manifest-discovery.mjs

@@ -1,6 +1,6 @@
 /**
  * manifest-discovery.mjs — **发现 ∕ 归属族**出档（2026-09-29 structure-split-2 · 台账 #620）：自 `manifest.mjs`
- * 全量迁出〔原 `:39-143`〕——`MANIFEST_REL` · 测试注入位（`_setProjectRootForTest` / `_resetProjectRootForTest`）·
+ * 全量迁出——`MANIFEST_REL` · 测试注入位（`_setProjectRootForTest` / `_resetProjectRootForTest`）·
  * `scanChildren`（两条梯表共用 walk 内核）· `discoverProjects`（项目梯）· `discoverRepos`（仓梯）·
  * `owningProject`（归属形）· `resolveProjectRoot`（归属 ∨ 发现）；**结构拆分零语义**（面不变 ∕ 判据不变，
  * 只换宿主档；切点 ∕ 缝单源 = 批档 `docs/batches/2026-09-29-structure-split-2.md` §2.2-C）。
@@ -41,13 +41,14 @@ function scanChildren(anchor, isHit) {
 /**
  * **项目发现**（项目梯五级——KD-M1-23 / 设计 `docs/core/design/MANIFEST.md` §2.2；**git 非前提**，
  * 2026-09-21 用户裁定）：① 锚自身带 `MANIFEST_REL` ⇒ 锚；② 锚含 `.git` ⇒ 锚（缺档 = 建档机会）；
- * ③ 直接子目录中**带档**者优先（非空即只看此级：恰一 ⇒ `unique` / ≥2 ⇒ `ambiguous`）；
- * ④ 零带档才看含 `.git` 的**裸仓**（同判）；⑤ 均无 ⇒ `none`（⇒ 建档流，落点 = 会话锚）。
+ * ③ 直接子目录中**带档**者优先（非空即只看此级：恰一 ⇒ `unique` / ≥2 ⇒ `workspace`——下辖多项目
+ * = 工作区常态，非错误态）；④ 零带档才看含 `.git` 的**裸仓**（同判）；⑤ 均无 ⇒ `none`（⇒ 建档流，
+ * 落点 = 会话锚）。
  * `candidates` 一律**按名排序**（`self` / `none` ⇒ `[]`）；`matched` ∈ `manifest` / `git` / `null`
- * 记命中（或歧义）出自哪一级。**纯 fs**（只判存在性——不解析档内容）· **不抛** · **不向上** · **不递归**。
+ * 记命中（或工作区）出自哪一级。**纯 fs**（只判存在性——不解析档内容）· **不抛** · **不向上** · **不递归**。
  * **覆盖位**（`_setProjectRootForTest` 在场）⇒ **头部短路**（测试注入面——先于真判据，同 `discoverRepos`）。
  * @param {string} [cwd] 会话锚（缺省 → 进程 cwd）
- * @returns {{kind:'self'|'unique'|'none'|'ambiguous', root:string|null, candidates:string[], matched:'manifest'|'git'|null}}
+ * @returns {{kind:'self'|'unique'|'none'|'workspace', root:string|null, candidates:string[], matched:'manifest'|'git'|null}}
  */
 export function discoverProjects(cwd) {
   if (_projectRootOverride) return { kind: "self", root: resolve(_projectRootOverride), candidates: [], matched: null }
@@ -55,10 +56,10 @@ export function discoverProjects(cwd) {
   if (existsSync(join(anchor, MANIFEST_REL))) return { kind: "self", root: anchor, candidates: [], matched: "manifest" }
   if (existsSync(join(anchor, ".git"))) return { kind: "self", root: anchor, candidates: [], matched: "git" }
   const withManifest = scanChildren(anchor, (d) => existsSync(join(d, MANIFEST_REL)))
-  if (withManifest.length > 1) return { kind: "ambiguous", root: null, candidates: withManifest, matched: "manifest" }
+  if (withManifest.length > 1) return { kind: "workspace", root: null, candidates: withManifest, matched: "manifest" }
   if (withManifest.length === 1) return { kind: "unique", root: withManifest[0], candidates: [...withManifest], matched: "manifest" }
   const bareRepos = scanChildren(anchor, (d) => existsSync(join(d, ".git")))
-  if (bareRepos.length > 1) return { kind: "ambiguous", root: null, candidates: bareRepos, matched: "git" }
+  if (bareRepos.length > 1) return { kind: "workspace", root: null, candidates: bareRepos, matched: "git" }
   if (bareRepos.length === 1) return { kind: "unique", root: bareRepos[0], candidates: [...bareRepos], matched: "git" }
   return { kind: "none", root: null, candidates: [], matched: null }
 }
@@ -66,21 +67,22 @@ export function discoverProjects(cwd) {
 /**
  * **仓发现**（仓梯——KD-M1-23 / `docs/core/design/TOOLS.md` §6.13；**单源** KD-M1-22——`git` 工具
  * 经此符号接线，禁第二份实现）：① 锚含 `.git` ⇒ 锚；② 直接子目录中 `.git` **∧** 带档者恰一 ⇒ 命中
- * （≥2 ⇒ 歧义）；③ **零个此类时才看**含 `.git` 的裸仓（恰一 ⇒ 命中 / ≥2 ⇒ 歧义）；④ 均无 ⇒ `none`。
+ * （≥2 ⇒ `workspace`——下辖多仓 = 常态）；③ **零个此类时才看**含 `.git` 的裸仓（恰一 ⇒ 命中 /
+ * ≥2 ⇒ `workspace`）；④ 均无 ⇒ `none`。
  * 与 `discoverProjects` = **同一 walk 内核**（`scanChildren`）的两种梯表——差异只在谓词与级序。
  * `candidates` 按名排序；`matched` 记档位；纯 fs / 不抛 / 不递归 / 不向上；覆盖位 ⇒ 头部短路。
  * @param {string} [cwd] 会话锚（缺省 → 进程 cwd）
- * @returns {{kind:'self'|'unique'|'none'|'ambiguous', root:string|null, candidates:string[], matched:'manifest'|'git'|null}}
+ * @returns {{kind:'self'|'unique'|'none'|'workspace', root:string|null, candidates:string[], matched:'manifest'|'git'|null}}
  */
 export function discoverRepos(cwd) {
   if (_projectRootOverride) return { kind: "self", root: resolve(_projectRootOverride), candidates: [], matched: null }
   const anchor = resolve(cwd ?? ".")
   if (existsSync(join(anchor, ".git"))) return { kind: "self", root: anchor, candidates: [], matched: "git" }
   const scoped = scanChildren(anchor, (d) => existsSync(join(d, ".git")) && existsSync(join(d, MANIFEST_REL)))
-  if (scoped.length > 1) return { kind: "ambiguous", root: null, candidates: scoped, matched: "manifest" }
+  if (scoped.length > 1) return { kind: "workspace", root: null, candidates: scoped, matched: "manifest" }
   if (scoped.length === 1) return { kind: "unique", root: scoped[0], candidates: [...scoped], matched: "manifest" }
   const bare = scanChildren(anchor, (d) => existsSync(join(d, ".git")))
-  if (bare.length > 1) return { kind: "ambiguous", root: null, candidates: bare, matched: "git" }
+  if (bare.length > 1) return { kind: "workspace", root: null, candidates: bare, matched: "git" }
   if (bare.length === 1) return { kind: "unique", root: bare[0], candidates: [...bare], matched: "git" }
   return { kind: "none", root: null, candidates: [], matched: null }
 }
@@ -107,23 +109,24 @@ export function owningProject(target) {
   }
 }
 
-/** **项目根解析的歧义直读形**（判定单点——设计 `MANIFEST.md` §2.2 `projectRootView` 契约行 / §2.5
- *  「多档解析消费面收口」条）：`ok`（唯一解析：归属命中 ∥ 发现 `self` / `unique`）/ `ambiguous`
- *  （≥2 候选 ⇒ `root` null + 候选全列**按名排序**）/ `none`（无项目 ⇒ 双空）；覆盖位在场 ⇒
- *  头部短路（`ok` + 覆盖值）。**非抛错 / 零写**；`resolveProjectRoot` 薄委托本函数（行为逐字零变）。
- *  @returns {{state:'ok'|'ambiguous'|'none', root:string|null, candidates:string[]}} */
+/** **项目根解析的直读形**（判定单点——设计 `MANIFEST.md` §2.2 `projectRootView` 契约行 / §2.5
+ *  「单项目解析律与四处会话级缺省收口」条）：`ok`（唯一解析：归属命中 ∥ 发现 `self` / `unique`）/
+ *  `workspace`（锚自身无档 ∧ 下辖 **≥2** 项目 ⇒ `root` null + 下辖项目全列**按名排序**——工作区
+ *  常态，非错误态）/ `none`（无项目 ⇒ 双空）；覆盖位在场 ⇒ 头部短路（`ok` + 覆盖值）。
+ *  **非抛错 / 零写**；`resolveProjectRoot` 薄委托本函数（行为逐字零变）。
+ *  @returns {{state:'ok'|'workspace'|'none', root:string|null, candidates:string[]}} */
 export function projectRootView(cwd) {
   const owning = owningProject(cwd)
   if (owning) return { state: "ok", root: owning, candidates: [] }
   const d = discoverProjects(cwd)
   if (d.root) return { state: "ok", root: d.root, candidates: [] }
-  if (d.kind === "ambiguous") return { state: "ambiguous", root: null, candidates: d.candidates }
+  if (d.kind === "workspace") return { state: "workspace", root: null, candidates: d.candidates }
   return { state: "none", root: null, candidates: [] }
 }
 
 /** 项目根解析（**归属 ∨ 发现**——KD-M1-30 / M1-24）：**薄委托** `projectRootView(cwd).root`（判定
  *  单点见上——#828）。带档路径与批前**逐字同**；变更面两条（设计 §2.2 同条）：① 项目树内路径
- *  （祖先带档）⇒ 该项目根；② 裸仓恰一 ⇒ 该仓根（零档降级 = 建档机会）。`none` / `ambiguous` ⇒
+ *  （祖先带档）⇒ 该项目根；② 裸仓恰一 ⇒ 该仓根（零档降级 = 建档机会）。`none` / `workspace` ⇒
  *  `null`。调用方零改（行为随语义变更——设计 §2.5 键面条 / 错层条）。
  *  @returns {string|null} 项目根绝对路径 / null */
 export function resolveProjectRoot(cwd) {