@thincoder/core 0.10.1 → 0.10.3

package/embedding.mjs

@@ -7,6 +7,8 @@
 
 import { RETRYABLE_STATUS } from "./provider/index.mjs"
 import { resolveEnvRefs } from "./env-ref.mjs"
+// #859（MEMORY.md §6.3 ∥ §7 D-MEM31）：嵌入路径发送前净化孤立 UTF-16 代理——sanitize 单源复用
+import { sanitizeLoneSurrogates } from "./escape.mjs"
 const MAX_RETRIES = 3
 const BATCH_SIZE = 32 // max texts per request (within SiliconFlow limits)
 
@@ -48,6 +50,33 @@ export async function embed(embedder, texts, { signal } = {}) {
   return vectors
 }
 
+/**
+ * 毒行隔离消费面（MEMORY.md §6.3 ∥ §7 D-MEM31 · 台账 #859）：补嵌批的容错版 `embed`。
+ * 整批失败且错误携 `httpStatus === 400`（发送前清洗后仍 400 的未知毒形）⇒ 逐条独试：
+ * 成功者照常返回、仍败者置 `null`（调用面跳过不写 + 一行可见回执）；其余错误（网络 ∕ 401 等）
+ * 照旧整抛——隔离只兜 400 类。query 面（搜索侧单条嵌入）不走本函数（语义零变）。
+ * @returns {Promise<{vectors: (Float32Array|null)[], skipped: string[]}>}
+ */
+export async function embedTolerant(embedder, texts, { signal } = {}) {
+  try {
+    return { vectors: await embed(embedder, texts, { signal }), skipped: [] }
+  } catch (err) {
+    if (err?.httpStatus !== 400) throw err
+    const vectors = []
+    const skipped = []
+    for (let i = 0; i < texts.length; i++) {
+      try {
+        const [vec] = await embed(embedder, [texts[i]], { signal })
+        vectors.push(vec)
+      } catch (e) {
+        vectors.push(null)
+        skipped.push(`input #${i}: ${e.message}`)
+      }
+    }
+    return { vectors, skipped }
+  }
+}
+
 /** Cosine similarity (inputs are normalized, dot product equals cosine) */
 export function cosine(a, b) {
   if (a.length !== b.length) return 0
@@ -85,7 +114,8 @@ async function requestWithRetry(embedder, input, signal) {
           "Content-Type": "application/json",
           Authorization: `Bearer ${embedder.apiKey}`,
         },
-        body: JSON.stringify({ model: embedder.model, input }),
+        // #859 主修：发送前逐条净化孤立代理（存量毒行 ⇒ 硅基流动 400/20015；清洗后根因消除）
+        body: JSON.stringify({ model: embedder.model, input: input.map((t) => sanitizeLoneSurrogates(t)) }),
         signal: signal
           ? AbortSignal.any([signal, AbortSignal.timeout(60_000)])
           : AbortSignal.timeout(60_000),
@@ -100,11 +130,13 @@ async function requestWithRetry(embedder, input, signal) {
 
     const text = await response.text().catch(() => "")
     const message = `Embedding API error ${response.status}: ${text}`
+    const err = new Error(message)
+    err.httpStatus = response.status // #859：隔离层判据（400 类 ⇒ embedTolerant 逐条独试）
     if (RETRYABLE_STATUS.has(response.status)) {
-      lastError = new Error(message)
+      lastError = err
       continue
     }
-    throw new Error(message)
+    throw err
   }
   throw lastError
 }

package/ledger-cmd.mjs

@@ -10,15 +10,15 @@
  * 的 depthOnly 分支）——一律**动态 import** 本模块链（ledger-db.mjs 静态 import node:sqlite ⇒
  * 消费侧静态 import 会破 W8 契约②）。
  */
-import { statSync } from "node:fs"
-import { basename, resolve } from "node:path"
+import { 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"
+import { resolveDeclaredRef } from "./declaration.mjs"
 
-/** 查询（只读，全角色）：SELECT 行集（status/kind/board 过滤，缺省 = 全部行；id 升序）。库不在 = 空账。 */
+/** 查询（只读，全角色）：SELECT 行集（status/kind/board 过滤，缺省 = 全部行；id 升序）。库不在 = 空账。
+ *  只读开库（readOnly 句柄 + 零 DDL/ALTER——read-data-interface 批 FR2③）；库档非台账库 ⇒ 空账。 */
 export function ledgerQuery({ cwd, status = null, kind = null, board = null } = {}) {
-  const db = openLedger(cwd)
+  const db = openLedger(cwd, { readOnly: true })
   if (!db) return []
   try {
     const where = [], args = []
@@ -29,9 +29,10 @@ export function ledgerQuery({ cwd, status = null, kind = null, board = null } =
   } finally { db.close() }
 }
 
-/** 计数单源（只读，全角色）：COUNT(*) WHERE 未决四态——替代 v1 md 计数面（AC-M2-3）。库不在 = 0。 */
+/** 计数单源（只读，全角色）：COUNT(*) WHERE 未决四态——替代 v1 md 计数面（AC-M2-3）。库不在 = 0。
+ *  只读开库（同 ledgerQuery——零 DDL/ALTER）；库档非台账库 ⇒ 0。 */
 export function ledgerCount({ cwd } = {}) {
-  const db = openLedger(cwd)
+  const db = openLedger(cwd, { readOnly: true })
   if (!db) return 0
   try {
     const row = db.prepare(`SELECT COUNT(*) AS n FROM items WHERE status IN (${PENDING_STATUSES.map(() => "?").join(",")})`).get(...PENDING_STATUSES)
@@ -39,9 +40,6 @@ export function ledgerCount({ cwd } = {}) {
   } finally { db.close() }
 }
 
-/** 路径 = 存在的**档**？（目录 / 缺失 → false——写门存在性判据用）。 */
-const isFile = (p) => { try { return statSync(p).isFile() } catch { return false } }
-
 /** 写门·指针存在性（设计档 §6.1 · 台账 #38 · AC-M2-10）：写命令落盘前判**结果行**——`status ∈
  *  {在途, 待核销}` ⇒ 判 `task_book`：`null`（缺指针）⇒ 拒（「必填」文案）；非 `null` ⇒ 文件部分
  *  （首个 `§` 前子串，trim）须经基准 `resolve(base, …)` 指向存在的档；缺文件部分（`§2` / 空串 /
@@ -50,23 +48,17 @@ const isFile = (p) => { try { return statSync(p).isFile() } catch { return false
  *  基准 `base` = **与台账库关联键同源**（2026-09-18 fix 轮 · O1 收正）：`resolveProjectRoot(cwd) ??
  *  resolve(cwd ?? ".")`——同表达式见 `ledger-db.mjs` `ledgerDbPath`；容器根会话（锚 cwd 下唯一注册
  *  子仓 P）与子仓会话 ⇒ 库键与指针基准同取 P（同库同基准；原实现 `resolve(cwd, …)` = 原始 cwd 会误拒）。
- *  #832：声明源前缀形同判（§6.15——首段 = 声明公共仓目录名 ⇒ 于该声明根解析；可核 ⇒ 通过；缺位拒）。 */
+ *  #832 ∥ #834：声明源前缀形同判——判定单源 = `declaration.mjs` `resolveDeclaredRef`（① 仓根解析 →
+ *  ② 声明源前缀解析序；同名多仓 ⇒ 声明序首者）——**与迁移旗（`ledger-migrate.mjs` `writeGateFlag`）
+ *  同消费**；未声明 ∥ 声明根缺位 ∥ 目标档缺 ⇒ 照旧拒（既有拒绝面零改——判据本体 = §6.1 口径 1–4 逐字）。 */
 function assertTaskBookGate(cwd, fnName, status, taskBook) {
   if (status !== "在途" && status !== "待核销") 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)
-  // §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}）`)
+  const { ok, abs } = resolveDeclaredRef(base, part)
+  if (!ok) throw new Error(`${fnName}：task_book 指向的档不存在：${taskBook}（解析 = ${abs}）`)
 }
 
 /** 新增（写命令，仅主 agent）：INSERT——入待讨论（六态状态机入口）。 */

package/ledger-db.mjs

@@ -55,6 +55,10 @@ export function ledgerDbPath(cwd) {
 /** 未决四态（「活条目」口径 = 计数单源 WHERE 集；已核销 / 已废弃 = 归档态）。 */
 export const PENDING_STATUSES = ["待讨论", "待设计", "在途", "待核销"]
 
+/** 台账库结构版本（N2 标记**单源**——`PRAGMA user_version` 落标：写面开库 `v < 本值 ⇒ 置`；
+ *  读面如实回读（旧库未标 = 0）；结构变更（新列 / 新表）同步升号——2026-10-03 read-data-interface 批）。 */
+export const LEDGER_SCHEMA_VERSION = 1
+
 /** 六态允许迁移表（ledgerUpdate 迁移前判，不在表内 → 拒——规格 ②.2；设计档 §2.1）。 */
 export const ALLOWED_MIGRATIONS = {
   "待讨论": ["待设计", "已废弃"],
@@ -100,12 +104,39 @@ export function ensureExecutorColumn(db, { exists } = {}) {
   }
 }
 
+/** 只读态开库（read-data-interface 批 FR2③——readOnly 句柄 + **零 DDL / 零 ALTER**；先例 = 本包
+ *  `ledger-migrate.mjs` 的 `openRead`）：文件必已在盘；items 表缺失探针 ⇒ 视同空账返回 null
+ *  （非台账库的 SQLite 档 / 空档——观测面保持「空集」，文件零触）。不可开（坏档 / 非 SQLite）⇒
+ *  抛（调用方按面处置：单范围 = 读错；族范围 = 不可读跳过）。 */
+function openReadOnly(file) {
+  let db
+  try {
+    db = new DatabaseSync(file, { readOnly: true })
+    if (db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'items'").get() === undefined) {
+      db.close()
+      return null // 无 items 表 ⇒ 非台账库 ⇒ 空账（探针零写）
+    }
+    return db
+  } catch (e) {
+    try { db?.close() } catch { /* 已关 / 未开 */ }
+    throw new Error(`台账库打开失败：${file}（${e.message}）`)
+  }
+}
+
+/** 写面落标（N2）：`user_version` < 常量 ⇒ 置；≥ 常量不动（未来版本零回退）。只在写面开库调用。 */
+function markSchemaVersion(db) {
+  const v = Number(db.prepare("PRAGMA user_version").get().user_version ?? 0)
+  if (v < LEDGER_SCHEMA_VERSION) db.exec(`PRAGMA user_version = ${LEDGER_SCHEMA_VERSION}`)
+}
+
 /** 开库（cwd = 项目根——仅作关联键）→ DatabaseSync 句柄 + 幂等建表 + 老库幂等迁移（executor 列）。
  *  读面（create=false）：库文件不存在 → 返回 null（空账——读面不建库、无副作用）。
  *  写面（create=true）：库文件不存在自动建（台账目录随之创建）；项目根目录不存在 → 抛友好错误。
+ *  **只读态**（readOnly=true——读面专用）：只读句柄 + 零 DDL / ALTER + items 探针（见 openReadOnly）；
+ *  如实副作用：旧库（缺 executor 列）**读**不再自动补列——补列归写面开库；读出行缺列按 null 归一。
  *  **歧义锚**（≥2 候选——`projectRootView` `ambiguous` 态）⇒ **显式拒**（列候选 + 显式项目根指引；
  *  零写——不静默回退锚；族锚「项目不可解析」，AC-M2-17）；兜底 `resolve(cwd ?? ".")` 只属 none 态。 */
-export function openLedger(cwd, { create = false } = {}) {
+export function openLedger(cwd, { create = false, readOnly = false } = {}) {
   const dir = resolve(cwd ?? ".")
   // 歧义锚 ⇒ 显式拒（零写——消「缺省空读 / 错写落锚」双面症；读 / 写五工具同经本门）。
   const view = projectRootView(dir)
@@ -118,11 +149,13 @@ export function openLedger(cwd, { create = false } = {}) {
     throw new Error(`项目目录不存在：${dir}——cwd 请给存在的项目根（相对路径按当前工作目录解析；缺省 = 会话项目根）`)
   }
   if (!existsSync(file) && !create) return null
+  if (readOnly) return openReadOnly(file)
   try { mkdirSync(ledgerDir, { recursive: true }) } catch { /* 已存在 / 并发建目录竞争——忽略 */ }
   const db = new DatabaseSync(file)
   try {
     db.exec(DDL)
     ensureExecutorColumn(db)
+    markSchemaVersion(db)
   } catch (e) {
     db.close()
     throw new Error(`台账库打开失败：${file}（${e.message}）`)

package/ledger-migrate.mjs

@@ -11,6 +11,7 @@ import { copyFileSync, mkdirSync, readdirSync, renameSync, statSync, writeFileSy
 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 { resolveProjectRoot } from "./manifest.mjs"
 
@@ -71,14 +72,14 @@ function readRowsOf(file, missing = []) {
   const db = openRead(file)
   try { return readRows(db, missing) } finally { db.close() }
 }
-/** 写门风险旗（§2.2 表）：迁入行属 `在途 / 待核销` 且 `task_book` 不可解析 / 指向档不存在 ⇒ 该行后续更新将拒于 §6.1 写门；只出旗，不拦截。 */
+/** 写门风险旗（§2.2 表）：迁入行属 `在途 / 待核销` 且 `task_book` 不可解析 / 指向档不存在 ⇒ 该行后续更新将拒于 §6.1 写门；只出旗，不拦截（判面与写门同源·#834——共享解析单点 `resolveDeclaredRef`：① 仓根解析 → ② 声明源前缀解析序）。 */
 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}）`
+  const { ok, abs } = resolveDeclaredRef(projectRoot, part)
+  return ok ? null : `task_book 指向的档不存在：${tb}（解析 = ${abs}）`
 }
 /** `--from` 指名键 = **补充源**：键形非 16 位小写十六进制 / 无对应库 / 不可开 ⇒ 拒跑（fail-closed，零写——显式指名不静默跳过；键形判防路径形 / 越目录形取值 join 出台账目录外）。 */
 function fromKeyRefusal(fromKeys, dir) {

package/ledger-read.mjs

@@ -0,0 +1,94 @@
+/**
+ * ledger-read.mjs — 只读数据接口（read-data-interface 批 · 设计档
+ * `docs/cli/design/READ-DATA-INTERFACE.md` §2.1 / §2.3 / §2.4 / §2.7 · 台账 #886 ∥ #887）。
+ *
+ * 面：① `ledgerExport({ cwd, family, full })` —— CLI `ledger list --json` ∥ ACP `ledger/list`
+ * 两出口共用的**统一序列化单源**（N1：零 SQL 复刻、零表名泄漏——行集直用核 `ledgerQuery`）；
+ * ② `runLedgerList(args, opts)` —— CLI 命令 runner（严格解析 · fail-closed——§2.7 / §3.1）。
+ *
+ * 载荷（§3.2 冻结形）：`{ projects: [{ root, name, schemaVersion, rows }] }`；行 = `id` + 12 数据列
+ * （列集单源 = `DATA_COLUMNS`——D-10 直引，不另立副本；`evidence` 仅 full 入行）；缺列（旧库）按
+ * null 归一；`schemaVersion` = 库 `PRAGMA user_version` 如实回读（旧库未标 = 0）；库不在 / 非台账库
+ * ⇒ 项目不出项（空集）。
+ * 范围（§2.4）：单范围 = 解析后项目根一项（`resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")`——与库键
+ * 同源）；`--family` = `discoverFamily` 发现序逐项（不可读跳过——既有语义）。
+ *
+ * W8 契约②：本档静态入 `ledger-db.mjs`（node:sqlite）⇒ 消费侧一律**动态 import** 本档。
+ * D-11：`ledger.mjs` 零编辑——族发现只 import `discoverFamily`。
+ */
+import { basename, resolve } 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"
+
+/** 行出形（§3.2）：`id` + 数据列序（`evidence` 仅 full）；缺列按 null 归一。 */
+function exportRow(r, full) {
+  const row = { id: Number(r.id) }
+  for (const c of DATA_COLUMNS) {
+    if (c === "evidence" && !full) continue
+    row[c] = r[c] ?? null
+  }
+  return row
+}
+
+/** 单项目读（**两开均只读态**——版本探针开 + 行集开，§2.3）：库不在 / 非台账库 ⇒ null（项目不出项）。
+ *  不可读（坏档）⇒ 抛（单范围 = 读错转 exit 1；族范围 = 调用侧捕获跳过）。 */
+function readProject(root, full) {
+  const probe = openLedger(root, { readOnly: true })
+  if (!probe) return null
+  let schemaVersion
+  try { schemaVersion = Number(probe.prepare("PRAGMA user_version").get().user_version ?? 0) } finally { probe.close() }
+  const rows = ledgerQuery({ cwd: root })
+  return { root, name: basename(root), schemaVersion, rows: rows.map((r) => exportRow(r, full)) }
+}
+
+/** 统一序列化单源（N1——两出口共用；载荷 = §3.2 冻结形）。
+ *  单范围 = 当前项目一项；`family=true` = 族内发现序逐项（不可读跳过——余者照常）。 */
+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)
+    return { projects: item ? [item] : [] }
+  }
+  const projects = []
+  for (const p of discoverFamily(anchor).projects) {
+    try { const item = readProject(p.root, full); if (item) projects.push(item) } catch { /* 不可读跳过 */ }
+  }
+  return { projects }
+}
+
+/** CLI 命令 usage（冻结形——§3.1；解析错入 stderr）。 */
+const LIST_USAGE = "Usage: thincoder ledger list --json [--full] [--family] [--cwd <dir>]"
+
+/** CLI runner（§2.7）：严格解析——未知参 / 缺 `--json` / `--cwd` 缺值 ⇒ usage + exit 1（fail-closed，
+ *  与同族 migrate / audit 宽松面刻意不同）；`--cwd` 空格形（同族先例）。成功 = stdout 单段 JSON
+ *  （零杂行）+ exit 0（含空集）；解析类 / 读错 ⇒ stderr 一行消息（零栈泄）+ exit 1。 */
+export function runLedgerList(args, { cwd = process.cwd(), out = console.log, err = console.error } = {}) {
+  const argv = Array.isArray(args) ? args : []
+  let json = false, full = false, family = false, dir = null
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === "--json") json = true
+    else if (a === "--full") full = true
+    else if (a === "--family") family = true
+    else if (a === "--cwd") {
+      const v = argv[i + 1]
+      if (v === undefined || v.startsWith("--")) { err(LIST_USAGE); return 1 }
+      dir = String(v)
+      i++
+    } else { err(LIST_USAGE); return 1 }
+  }
+  if (!json) { err(LIST_USAGE); return 1 }
+  try {
+    out(JSON.stringify(ledgerExport({ cwd: dir ?? cwd, family, full })))
+    return 0
+  } catch (e) {
+    // 错误面「一行消息、零栈泄」（§3.1）：多行诊断（如歧义锚候选清单）折叠单行——内容零丢。
+    err(String(e?.message ?? e).replace(/\s*\r?\n\s*/g, " "))
+    return 1
+  }
+}

package/ledger-surface.mjs

@@ -1,76 +1,45 @@
 /**
- * ledger-surface.mjs — 台账可见面（核内结构归位；CORE-UNIFICATION §2.5 #174
- * 「融合：取一侧 + 渲染面按端注入」）。
+ * ledger-surface.mjs — 台账可见面（核内结构归位；CORE-UNIFICATION §2.5 #174「融合：取一侧」）。
  *
- * 来源 = `thincoder-cli/src/tui/ledger-surface.mjs`（CLI 住 `tui/`、VSC 住 `extension/`；
- * VSC 头注自述同构）——逐字随迁，**渲染面收核为注入**：原档 `import { C } from "./ansi.mjs"`
- * 是 TUI 专用件的颜色表 ⇒ ④ 端差，改由调用方传入 `colors`（未注入 ⇒ 空对象，输出纯文本，
- * 核内零端名分支——契约 5 / 10）。
- *
- * 三面：① 启动行（首扫、**任一项目可动作**才出——明细行集每项目一行）② 变化行（老化首次
- * 越线 / 池达阈值——一次性去重 + **送达门**：未送达不记账）③ 状态位（`state.ledger`——L1
- * 常驻标记，渲染端消费；**不受启动行门约束**——F2 按标记态照显）。
- * 只读台账；唯一写面 = 去重档（`~/.thincoder/ledger-notify.json`）。
+ * 面：族扫描 → 判活批量解析 → 状态位（`state.ledger`——L1 常驻标记，范围归约 `scopeMarkerOf`
+ * 单源 §7.2，渲染端消费）；只读台账，本面零写。
  */
-import { buildScan, detailScans, discoverFamily, formatDetailLine, formatMarker, loadNotifyState, NOTIFY_FILE, notifyKey, planChangeLines, REFRESH_MS, resolveExecutorStates, saveNotifyState } from "./ledger.mjs"
+import { buildScan, discoverFamily, REFRESH_MS, resolveExecutorStates, scopeMarkerOf } from "./ledger.mjs"
 
 /** 单次扫描（直驱面——timer 包装见 `startLedgerSurface`）。**async**（F-LX1：await 判活解析——
- *  LEDGER.md §7.3.1 ④ 读面不阻塞事件循环）。
- *  `startup=true` = 会话首扫（补启动行；变化行在前、明细行在后）。
- *  `colors` = 端注入的渲染色表（`{ warn, dim }`）；未注入 ⇒ `{}`（`undefined` 色值 = 纯文本）。 */
-export async function runLedgerScan({ state, agent = null, anchor = null, notifyFile = NOTIFY_FILE, pushLine = () => {}, render = () => {}, startup = false, colors = {} } = {}) {
+ *  LEDGER.md §7.3.1 ④ 读面不阻塞事件循环）。 */
+export async function runLedgerScan({ state, agent = null, anchor = null, render = () => {} } = {}) {
   const base = anchor ?? agent?.cwd ?? process.cwd()
   const family = discoverFamily(base)
   const scans = []
   for (const p of family.projects) {
     try { scans.push(buildScan({ cwd: p.root })) } catch { /* 台账不可读 → 该项目跳过（余者照常——N1/T110①） */ }
   }
-  const current = family.current ? scans.find((s) => s.root === family.current.root) ?? null : null
   await resolveExecutorStates(scans) // 判活批量解析（一次探束 + TTL 缓存；无在途零 exec）
-  const notify = loadNotifyState(notifyFile)
-  const plans = scans.map((s) => ({ s, plan: planChangeLines(notify.ledgers[notifyKey(s.ledger)], s) }))
-  const changeLines = plans.flatMap(({ plan }) => plan.lines)
-  const showStartup = startup && scans.some((s) => s.actionable)
-  const rows = showStartup
-    ? [...changeLines, ...detailScans(scans, current).map((s) => ({ text: formatDetailLine(s), warn: s.actionable }))]
-    : changeLines
-  let delivered = true
-  for (const line of rows) {
-    try { pushLine(line.text, line.warn ? colors.warn : colors.dim) } catch { delivered = false; break }
-  }
-  // 送达门（F5）：有事件行 → 仅在送达后记账；无事件行 → 仅状态确有变化时静默同步（跌回 false 即重置）
-  const changed = plans.some(({ s, plan }) => {
-    const prev = notify.ledgers[notifyKey(s.ledger)]
-    return !prev || JSON.stringify(prev.aged ?? []) !== JSON.stringify(plan.next.aged) || Boolean(prev.threshold) !== plan.next.threshold
-  })
-  if (changeLines.length ? delivered : changed) {
-    const ledgers = { ...notify.ledgers }
-    for (const { s, plan } of plans) ledgers[notifyKey(s.ledger)] = { ...plan.next, updatedAt: Date.now() }
-    saveNotifyState(notifyFile, { version: 1, ledgers })
-  }
-  // warn 判位钉在判活解析之后（裁定 #7）：属主已死也是可动作态
-  state.ledger = { marker: current ? formatMarker(current) : null, warn: Boolean(current && (current.aged > 0 || current.deadExecutors > 0)), scannedAt: Date.now() }
+  // 范围归约 = `scopeMarkerOf` 单源（§7.2——容器根锚求和 ∥ 具体项目锚只显自身）；warn 判位钉在
+  // 判活解析之后（裁定 #7）：属主已死也是可动作态
+  const { marker, warn } = scopeMarkerOf(scans, family)
+  state.ledger = { marker, warn, scannedAt: Date.now() }
   render()
 }
 
 /** 挂载：首扫（`setImmediate`——不抢首帧）+ 周期（`REFRESH_MS`；`state.processing` 期间跳过本轮）。
- *  端注入的渲染面（`ctx.colors`）与推送面（`ctx.pushLine` / `ctx.render`）照传。
  *  `tick` 异步化（F-LX1——runLedgerScan async）：await 且 catch 不崩（N1）。重叠防衛：
  *  判活探测秒级可达，上一轮未落定时跳过本轮（防探束堆积）。 */
 export function startLedgerSurface(ctx = {}) {
   let disposed = false
   let timer = null
   let inflight = false
-  const tick = async (startup) => {
+  const tick = async () => {
     if (disposed || inflight) return
-    if (!startup && ctx.state?.processing) return // 扫描不打断回合帧
+    if (ctx.state?.processing) return // 扫描不打断回合帧
     inflight = true
-    try { await runLedgerScan({ ...ctx, startup }) } catch { /* 可见面尽力——不崩（N1） */ } finally { inflight = false }
+    try { await runLedgerScan(ctx) } catch { /* 可见面尽力——不崩（N1） */ } finally { inflight = false }
   }
   setImmediate(() => {
     if (disposed) return
-    tick(true)
-    timer = setInterval(() => tick(false), REFRESH_MS)
+    tick()
+    timer = setInterval(() => tick(), REFRESH_MS)
     timer.unref?.()
   })
   return {

package/ledger.mjs

@@ -9,20 +9,18 @@
  * 两源，接线见 tools/index.mjs 与 agent/family-tools.mjs）
  * ② 族发现（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,45 +185,6 @@ 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"

package/manifest-schema.mjs

@@ -80,14 +80,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)
@@ -138,7 +148,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）