@thincoder/core 0.10.2 → 0.10.4

package/ledger-tools.mjs

@@ -1,14 +1,16 @@
 /**
- * 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`
+ * 零改）；判于核函数之前 ⇒ 非法入参零写、零库动作、零 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()
@@ -68,51 +70,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,23 +96,11 @@ 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: "标题（缺省 = 不变）" },
@@ -152,37 +113,139 @@ export const ledgerUpdateTool = {
     },
     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: "目标态（勾销 / 追认核销 / 撤回）" },
     },
     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: "按归属板块过滤（需求档文档名）" },
+    },
+    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 缺省 = 不变；追认核销须非空）" },
+    trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "技术待办触发（add / update 可空）" },
+    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 }))
+        case "query":
+          return JSON.stringify(ledgerQuery({ cwd: rest.cwd ?? cwdOf(ctx), status: rest.status, kind: rest.kind, board: rest.board }), 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 }
+}

package/ledger.mjs

@@ -6,23 +6,21 @@
  * 锁死、COUNT 单源计数、事务保证收口原子、归档 = 软删除。行龄源 = SQLite 时间戳（无 git blame）。
  *
  * 面：① 命令族（查询 = 只读全角色 / 写 = 仅主 agent——核函数 `ledger-cmd.mjs` + 工具定义 `ledger-tools.mjs`
- * 两源，接线见 tools/index.mjs 与 agent/family-tools.mjs）
+ * 两源，接线见 `agent/family-tools.mjs`——统一入口 `ledger` 两变体，2026-10-05 统一入口批）
  * ② 族发现（findProject / discoverFamily——标记 = ledger.db）③ scan 组装（buildScan——行集 + ledgerCount
  * → scan 对象，形状契约 = pool/tech/aged/thresholdReached/actionable/root/name/ledger）
- * ④ 通知去重（送达门 + 一次性去重——去重档跨会话、跨端共享）⑤ 格式 helper（行文本逐字契约）。
+ * ④ 格式 helper（L1 标记 ∥ L2 明细行逐字契约——含标记范围归约 `scopeMarkerOf`，§7.2）。
  * 判活展示 = 拆分件 `ledger-executors.mjs`（在途 executor 解析 + 三态尾段——本档 re-export，
  * 消费面仍只认本档）。
  *
  * W8 契约②：ledger-db.mjs 静态 import node:sqlite ⇒ 消费侧一律**动态 import** 本档（禁止静态 import）。
  */
-import { mkdirSync, opendirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs"
+import { opendirSync, statSync } from "node:fs"
 import { basename, dirname, join, resolve } from "node:path"
-import { configDir } from "./config.mjs"
+import { projectRootView } from "./manifest.mjs"
 import { ledgerDbPath, PENDING_STATUSES } from "./ledger-db.mjs"
 import { ledgerQuery } from "./ledger-cmd.mjs"
 import { executorTail } from "./ledger-executors.mjs"
-// 归一步单源（#585——盘符大写契约直引 `session-slots.mjs`；先例 = `ledger-db.mjs:23`）。
-import { normalizeCwd } from "./session-slots.mjs"
 
 /** 老化阈值（天——口径 = 需求档；`days` 参数可覆盖）。 */
 export const AGING_DAYS = 30
@@ -32,18 +30,16 @@ export const THRESHOLD_BOARD = 2
 export const THRESHOLD_POOL = 3
 /** 刷新周期（N2 实现常量；VSC 端另有换项目事件触发）。 */
 export const REFRESH_MS = 120000
-/** 变化行去重档（跨会话、跨端共享——需求档 §1.18 F5；configDir 先例 = crash-reports 同区）。 */
-export const NOTIFY_FILE = join(configDir, "ledger-notify.json")
-/** 空族提示（仅命令面——运行时面静默，N1 / 设计档 §2.30.3.3）。 */
+/** 空族提示（仅命令面——运行时面静默，N1 / 归档档 ENGINEERING-MODE.md §2.30.3.3——现行承接 = `docs/core/design/LEDGER.md`）。 */
 export const EMPTY_FAMILY_LINE = "台账：未发现台账。"
 
 /** 条目归一化文本 = 条目键（去 `- [ ] ` 前缀 + 去首尾空白 + 连续空白折叠单空格）。
- *  位置无关（位移 / 他条编辑稳定）；自身文本变更 = 键变（最坏一次重报）。§2.30.3.2。 */
+ *  位置无关（位移 / 他条编辑稳定）；自身文本变更 = 键变（最坏一次重报）。归档档 ENGINEERING-MODE.md §2.30.3.2。 */
 export function normalizeEntry(text) {
   return text.replace(/^- \[[ x]\]\s+/, "").trim().replace(/\s+/g, " ")
 }
 
-/** 条目标题：首个 `**…**` 段；无粗体段 → 归一化文本前 20 字（超出加 `…`）。§2.30.3.3 L3。 */
+/** 条目标题：首个 `**…**` 段；无粗体段 → 归一化文本前 20 字（超出加 `…`）。归档档 ENGINEERING-MODE.md §2.30.3.3 L3。 */
 export function entryTitle(text) {
   const m = /\*\*(.+?)\*\*/.exec(text)
   if (m) return m[1]
@@ -91,9 +87,14 @@ function ledgerChildren(dir) {
 }
 
 /** 项目族发现：{current, projects}——projects = current + 其同级含台账库目录（**发现序：current 在前**，
- *  其余按目录名升序）；current 缺（容器目录，K6）→ 上下文目录向上最近「含台账子目录」者取其子目录。 */
+ *  其余按目录名升序）；current 缺（容器目录，K6）→ 上下文目录向上最近「含台账子目录」者取其子目录。
+ *  **歧义根不充当项目**（轻通道轮 · 2026-10-04）：命中锚若项目解析 `ambiguous`（≥2 候选——`projectRootView`）
+ *  ⇒ 该锚不可扫描（`openLedger` 歧义拒）——其键控库（先于 #828 写门的存量空壳 / 幽灵）不得遮蔽族发现；
+ *  按容器形落子目录族（需求：打开容器根 ⇒ 族内合计——标记范围批 §1 原话）。 */
 export function discoverFamily(anchor) {
-  const current = findProject(anchor)
+  const hit = findProject(anchor)
+  // 歧义根跳过（键控库存在 ≠ 可作项目——扫描面 `buildScan` 对歧义锚必拒；遮蔽则标记静默缺席）。
+  const current = hit && projectRootView(hit.root).state === "ambiguous" ? null : hit
   if (current) {
     const siblings = ledgerChildren(dirname(current.root)).filter((p) => p.root !== current.root)
     return { current, projects: [current, ...siblings] }
@@ -143,27 +144,39 @@ export function buildScan({ cwd, days = AGING_DAYS, now = Date.now() } = {}) {
   }
 }
 
-/** L1 状态标记（逐字——§2.30.3.3）。 */
+/** L1 状态标记（逐字——归档档 ENGINEERING-MODE.md §2.30.3.3）。 */
 export function formatMarker(scan) {
   return scan ? `台账 ${scan.pool}·${scan.tech}` : null
 }
 
+/** 标记范围归约（L1 取值单源——LEDGER.md §7.2「标记范围」）：`current` 在场 ⇒ 范围 = `scans` 中
+ *  `root` = `family.current.root` 的 scan（命中但不在 `scans`——不可读 ⇒ 空范围，不掺兄弟）；
+ *  `current` 缺席（容器根锚）⇒ 范围 = `scans` 全体（族内已读项目——构建期不可读已跳过）。
+ *  空范围 ⇒ `{ marker: null, warn: false }`（不落 `0·0`）；范围非空 ⇒ `marker` = `formatMarker`
+ *  逐字（两池分列求和——F1）；`warn` = 范围内任一项 `aged>0 ∨ deadExecutors>0`（端零重算）。
+ *  消费面 = 核拍面（`ledger-surface.mjs`）∥ VSC item——端零自算单源。 */
+export function scopeMarkerOf(scans, family) {
+  const list = Array.isArray(scans) ? scans : []
+  const currentRoot = family?.current?.root ?? null
+  const range = currentRoot === null ? list : list.filter((s) => s?.root === currentRoot)
+  if (range.length === 0) return { marker: null, warn: false }
+  let pool = 0
+  let tech = 0
+  let warn = false
+  for (const s of range) {
+    pool += s.pool
+    tech += s.tech
+    if (s.aged > 0 || s.deadExecutors > 0) warn = true
+  }
+  return { marker: formatMarker({ pool, tech }), warn }
+}
+
 /** L2 明细行（逐字——`（老化 <n>）` 恒显；阈值达成加 ` — 可开批`；判活尾段 = executorTail 三态——
  *  在途 executor 缺席时尾段空串，既有逐字断言零破）。 */
 export function formatDetailLine(scan) {
   return `台账 ${scan.name}：需求池 ${scan.pool} · 技术待办 ${scan.tech}（老化 ${scan.aged}）${scan.thresholdReached ? " — 可开批" : ""}${executorTail(scan)}`
 }
 
-/** L3 变化行·老化（titles = 新增老化条目标题；> 3 条时第三项后接 `；…`）。 */
-export function formatAgingLine(scan, titles) {
-  return `台账变化：${scan.name} 老化首次越线 ${titles.length} 条（超 30 天未处置）：${titles.slice(0, 3).join("；")}${titles.length > 3 ? "；…" : ""}`
-}
-
-/** L4 变化行·阈值。 */
-export function formatThresholdLine(scan) {
-  return `台账变化：${scan.name} 需求池达阈值（${scan.pool} 条）— 可开批`
-}
-
 /** 明细行集 = {current} ∪ {可动作项目}（发现序——current 在前，其余按目录名升序；同项去重）。 */
 export function detailScans(scans, current) {
   const out = []
@@ -172,48 +185,9 @@ export function detailScans(scans, current) {
   return out
 }
 
-/** 变化行规划（纯函数）：{lines:[{text,warn}], next:{aged,threshold}}（去重口径 §2.30.3.2）。 */
-export function planChangeLines(prev, scan) {
-  const p = prev && typeof prev === "object" ? prev : {}
-  const before = new Set(Array.isArray(p.aged) ? p.aged : [])
-  const freshTitles = scan.agedKeys.map((k, i) => (before.has(k) ? null : scan.agedTitles[i])).filter((t) => t != null)
-  const lines = []
-  if (freshTitles.length) lines.push({ text: formatAgingLine(scan, freshTitles), warn: true })
-  if (scan.thresholdReached && !p.threshold) lines.push({ text: formatThresholdLine(scan), warn: true })
-  return { lines, next: { aged: scan.agedKeys, threshold: scan.thresholdReached } }
-}
-
-/** 去重档键 = 台账库绝对路径·正斜杠 + **盘符大写**（跨端同规则——CLI 的 `process.cwd()` 盘符大写、
- *  VSC 的 `uri.fsPath` 小写（`session-slots.mjs` `normalizeCwd` 同一契约——session / checkpoint /
- *  trace 跨端共享即赖此）；盘符步 = `normalizeCwd` 直调（单源——#585；先例 = `ledger-db.mjs:23`）、
- *  分隔符折叠自持；CLI 写的键 VSC 须逐字认得）。 */
-export function notifyKey(ledger) {
-  return normalizeCwd(resolve(ledger).replace(/\\/g, "/"))
-}
-
-/** 去重档读（缺失 / 坏 JSON → 空态——N1 降级不崩）。 */
-export function loadNotifyState(file = NOTIFY_FILE) {
-  try {
-    const j = JSON.parse(readFileSync(file, "utf8"))
-    if (j && typeof j === "object" && j.ledgers && typeof j.ledgers === "object") return { version: 1, ledgers: j.ledgers }
-  } catch { /* 缺失 / 坏档 → 空态 */ }
-  return { version: 1, ledgers: {} }
-}
-
-/** 去重档写（temp + rename 防撕裂；写失败静默返回 false——唯一写面，仅送达后调）。 */
-export function saveNotifyState(file, state) {
-  try {
-    mkdirSync(dirname(file), { recursive: true })
-    const tmp = `${file}.tmp-${process.pid}`
-    writeFileSync(tmp, JSON.stringify(state), "utf8")
-    renameSync(tmp, file)
-    return true
-  } catch { return false }
-}
-
 // ── re-export（拆分件接口——命令面接线 = 动态 import 本档，KD-M2-3） ──
 export { ALLOWED_MIGRATIONS, ledgerDbPath, ledgerKey, ledgerDirPath, openLedger, PENDING_STATUSES, _setLedgerDirForTest, _resetLedgerDirForTest, ensureExecutorColumn } from "./ledger-db.mjs"
 export { ledgerAdd, ledgerClose, ledgerCount, ledgerQuery, ledgerUpdate } from "./ledger-cmd.mjs"
-export { ledgerAddTool, ledgerCloseTool, ledgerCountTool, ledgerQueryTool, ledgerUpdateTool } from "./ledger-tools.mjs"
+export { ledgerTool, ledgerReadTool, ledgerAddTool, ledgerCloseTool, ledgerCountTool, ledgerQueryTool, ledgerUpdateTool } from "./ledger-tools.mjs"
 export { runLedgerAudit, runLedgerMigrate } from "./ledger-migrate.mjs"
 export { resolveExecutorStates, executorTail, _setExecutorProbeTtlForTest } from "./ledger-executors.mjs"

package/manifest-schema.mjs

@@ -12,12 +12,14 @@
 
 /**
  * `docRoot` 子键**值形态判据**（F7 / KD-M1-6 / KD-M1-8——判据单源）：非空字符串（`trim` 后
- * 非空），或非空数组且元素皆非空字符串（**同款口径**：元素 `trim` 后非空）；其余（空串 /
- * 空白串 / 空数组 / 数组含非串 / 空串 / 空白串元素 / 非串非数组）为非法。
+ * 非空），或非空数组且元素皆非空字符串（**同款口径**：元素 `trim` 后非空），或 `null`
+ * （**「本面无」合法哨兵**——KD-M1-37）；其余（空串 / 空白串 / 空数组 / 数组含非串 / 空串 /
+ * 空白串元素 / 非串非数组）为非法。
  * @param {unknown} value docRoot 某子键的值
  * @returns {boolean}
  */
 export function isValidDocRootValue(value) {
+  if (value === null) return true
   if (typeof value === "string") return value.trim() !== ""
   if (!Array.isArray(value) || value.length === 0) return false
   return value.every((p) => typeof p === "string" && p.trim() !== "")
@@ -80,14 +82,24 @@ function isLineCountsValue(v) {
  * 形状校验（模块设计 §2.2）——枚举 / version 数值恒做；**纯函数、零 fs**（原 `{ cwd }`
  * 指针腿已随字段整链裁撤——KD-M1-5 墓志）；不落盘。键存在性入 missingKeys（非拒）：
  * 缺键 = 便利 fallback（补默认值），不是错（与整档缺失两分——KD-M1-2）。
+ * 未知键（#802 / KD-M1-36）：顶层 + 四嵌套层产 `unknownKeys`（非拒——ok 定性零变；产线恰 =
+ * fillDefaults 丢弃面；嵌套键用点形路径——同 missingKeys 口径）。
  * @param {object} obj 待校验 manifest 对象
- * @returns {{ok:boolean, errors:string[], missingKeys:string[]}}
+ * @returns {{ok:boolean, errors:string[], missingKeys:string[], unknownKeys:string[]}}
  */
 export function validateManifest(obj) {
   const errors = []
   const missingKeys = []
   if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
-    return { ok: false, errors: ["manifest 顶层必须是 JSON 对象"], missingKeys }
+    return { ok: false, errors: ["manifest 顶层必须是 JSON 对象"], missingKeys, unknownKeys: [] }
+  }
+  // #802（KD-M1-36——未知键可见化）：顶层 + 四嵌套层逐键对照（非拒——ok 定性零变；嵌套键点形）。
+  const unknownKeys = []
+  for (const key of Object.keys(obj)) if (!MANIFEST_SCHEMA.keys.includes(key)) unknownKeys.push(key)
+  for (const [nested, subkeys] of Object.entries(MANIFEST_SCHEMA.nestedKeys)) {
+    const value = obj[nested]
+    if (value === null || typeof value !== "object" || Array.isArray(value)) continue
+    for (const sub of Object.keys(value)) if (!subkeys.includes(sub)) unknownKeys.push(`${nested}.${sub}`)
   }
   for (const key of MANIFEST_SCHEMA.keys) {
     if (!(key in obj)) missingKeys.push(key)
@@ -100,9 +112,9 @@ export function validateManifest(obj) {
     }
     for (const sub of subkeys) {
       if (!(sub in value)) { missingKeys.push(`${nested}.${sub}`); continue } // 子键路径（AC-3 / T3b）
-      // docRoot 子键值形态（F7 / KD-M1-7）：串 | 非空串数组；非法 → 拒（不静默跳过）。
+      // docRoot 子键值形态（F7 / KD-M1-7 / KD-M1-37）：串 | 非空串数组 | null（本面无）；非法 → 拒（不静默跳过）。
       if (nested === "docRoot" && !isValidDocRootValue(value[sub])) {
-        errors.push(`docRoot.${sub} 值形态非法：${JSON.stringify(value[sub])}（须为非空字符串或非空字符串数组——KD-M1-6 / KD-M1-7）`)
+        errors.push(`docRoot.${sub} 值形态非法：${JSON.stringify(value[sub])}（须为非空字符串 / 非空字符串数组 / null（本面无）——KD-M1-6 / KD-M1-7 / KD-M1-37）`)
       }
       // checkConfig.lineCounts 元素层形态（#546）：数组，元素 = { doc, section } 非空串；非法 → 拒（不静默跳过）。
       if (nested === "checkConfig" && sub === "lineCounts" && !isLineCountsValue(value[sub])) {
@@ -138,7 +150,7 @@ export function validateManifest(obj) {
   if (obj.version !== undefined && (typeof obj.version !== "number" || !Number.isFinite(obj.version))) {
     errors.push(`version 非法：${JSON.stringify(obj.version)}（须为数值）`)
   }
-  return { ok: errors.length === 0, errors, missingKeys }
+  return { ok: errors.length === 0, errors, missingKeys, unknownKeys }
 }
 
 /** 缺键补默认值（module 设计 §2.2 管线）：顶层缺键补默认、嵌套键（docRoot/checkConfig/index/advisor）