@thincoder/core 0.10.7 → 0.10.9

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 集；已核销 / 已废弃 = 归档态）。 */
@@ -61,9 +139,15 @@ export const PENDING_STATUSES = ["待讨论", "待设计", "在途", "待核销"
  *  保公共面零变——LEDGER.md §13.4）。 */
 export const AGING_DAYS = 30
 
+/** `evidence` 软上限（字——设计档 `LEDGER.md` §5 P4 读数面单源）：超限**只出读数，不拒写**
+ *  （软上限非闸门——用户裁定「无限机检反感」；读数面 = `query` 逐行 `evidenceOversize` ∥
+ *  `count` 回报）。 */
+export const EVIDENCE_SOFT_LIMIT = 300
+
 /** 台账库结构版本（N2 标记**单源**——`PRAGMA user_version` 落标：写面开库 `v < 本值 ⇒ 置`；
- *  读面如实回读（旧库未标 = 0）；结构变更（新列 / 新表）同步升号——2026-10-03 read-data-interface 批）。 */
-export const LEDGER_SCHEMA_VERSION = 1
+ *  读面如实回读（旧库未标 = 0）；结构变更（新列 / 新表）同步升号——2026-10-03 read-data-interface 批。
+ *  2 = `resume_when` 可空列（设计档 §3.4 P5）。 */
+export const LEDGER_SCHEMA_VERSION = 2
 
 /** 六态允许迁移表（ledgerUpdate 迁移前判，不在表内 → 拒——规格 ②.2；设计档 §2.1）。 */
 export const ALLOWED_MIGRATIONS = {
@@ -91,25 +175,30 @@ CREATE TABLE IF NOT EXISTS items (
   created_at TEXT,
   updated_at TEXT,
   closed_at  TEXT,
+  resume_when TEXT,
   CHECK (status NOT IN ('在途','待核销') OR (task_book IS NOT NULL AND task_book <> ''))
 )`
 
-/** 老库幂等迁移：items 表缺 executor 列（旧 DDL 建的库）→ ALTER 补列。
- *  判据 = PRAGMA table_info 实查（不猜版本号）；ALTER duplicate column 竞争 → 复核列在吞 / 不在抛真错。
- *  列存在性谓词抽成单元（param exists），便于并发竞争拍直测。K-LX5：老库零删改、零重建。 */
-export function ensureExecutorColumn(db, { exists } = {}) {
+/** 老库幂等迁移共件：items 表缺该可空列 ⇒ ALTER 补列（`executor` ∥ `resume_when` 两列共用一份
+ *  「复判列在否」逻辑——设计档 §3.4）。判据 = PRAGMA table_info 实查（不猜版本号）；ALTER
+ *  duplicate column 竞争 → 复核列在吞 / 不在抛真错。列存在性谓词抽成单元（param exists），
+ *  便于并发竞争拍直测。K-LX5：老库零删改、零重建。 */
+export function ensureColumn(db, name, { exists } = {}) {
   const columnExists = exists
-    ?? (() => db.prepare("SELECT 1 FROM pragma_table_info('items') WHERE name = 'executor'").get() !== undefined)
+    ?? (() => db.prepare("SELECT 1 FROM pragma_table_info('items') WHERE name = ?").get(name) !== undefined)
   if (columnExists()) return false
   try {
-    db.exec("ALTER TABLE items ADD COLUMN executor TEXT")
+    db.exec(`ALTER TABLE items ADD COLUMN ${name} TEXT`)
     return true
   } catch (e) {
     if (columnExists()) return false // 并发竞争——另一连接已加列：吞
-    throw new Error(`台账库 executor 列迁移失败：${e.message}`)
+    throw new Error(`台账库 ${name} 列迁移失败：${e.message}`)
   }
 }
 
+/** `executor` 列补列（F-LX1——共件别名，公共面形零改）。 */
+export const ensureExecutorColumn = (db, opts) => ensureColumn(db, "executor", opts)
+
 /** 只读态开库（read-data-interface 批 FR2③——readOnly 句柄 + **零 DDL / 零 ALTER**；先例 = 本包
  *  `ledger-migrate.mjs` 的 `openRead`）：文件必已在盘；items 表缺失探针 ⇒ 视同空账返回 null
  *  （非台账库的 SQLite 档 / 空档——观测面保持「空集」，文件零触）。不可开（坏档 / 非 SQLite）⇒
@@ -135,32 +224,34 @@ 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 { /* 已存在 / 并发建目录竞争——忽略 */ }
   const db = new DatabaseSync(file)
   try {
     db.exec(DDL)
-    ensureExecutorColumn(db)
+    ensureColumn(db, "executor")
+    ensureColumn(db, "resume_when")
     markSchemaVersion(db)
   } catch (e) {
     db.close()

package/ledger-migrate.mjs

@@ -3,7 +3,8 @@
  * ② `ledger migrate --dry-run | --confirm`：变体键库一次性合并——三件套 = dry-run 零写 / 先备份（拷贝 + 读回同计数）/ 幂等（全字段等值）；
  *   六步 = 备份 → 源就绪与列集判 → 单事务迁入（事务内读回核验）→ 回收源（rename 进 `ledger-trash`，不 unlink）→ 报告 → 汇总。执行主体 = 父侧 ops（KD-LN6）。
  * ③ `ledger audit`：逐 `*.db` 定性（目标库 / 变体源 / 空库 / 不可归因（有行）/ 不可读（坏档）；stat 失败 ⇒ 读取失败态）+ 候选根集合归因；只报告零动作。
- * 铁律：**12 数据列逐字复制（不含 id）+ id 重发**（两库 id 空间重叠）；备份 / 回收目录 = `ledgerDirPath()` 的**兄弟位**（§2.11#6 ⇒ 夹具根外零写）；
+ * 铁律：**13 数据列逐字复制（不含 id）+ id 重发**（两库 id 空间重叠；列集单源 = `DATA_COLUMNS`——`resume_when`
+ * 落地后 12 ⇒ 13，设计档 §3.4）；备份 / 回收目录 = `ledgerDirPath()` 的**兄弟位**（§2.11#6 ⇒ 夹具根外零写）；
  * 迁移走直接 SQL（§6.1 写门不拦迁移本身 ⇒ 风险行出旗不拦截）；本档静态 import node:sqlite ⇒ 消费侧一律动态 import（W8 契约②——同 ledger-db.mjs）。
  */
 import { createHash } from "node:crypto"
@@ -12,14 +13,17 @@ 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）。 */
+/** 13 数据列（**等值比对列集**——不含 id：id 重发，§2.2 语义保全 / AC-M2-12；`resume_when` 落地后\n *  12 ⇒ 13——设计档 §3.4）。 */
 export const DATA_COLUMNS = [
   "kind", "status", "title", "board", "req_doc", "task_book",
-  "evidence", "trigger", "executor", "created_at", "updated_at", "closed_at",
+  "evidence", "trigger", "executor", "created_at", "updated_at", "closed_at", "resume_when",
 ]
+/** 旧库可缺列容忍集（缺则按 NULL 映射照迁）：`executor`（F-LX1 前的旧 DDL）∥ `resume_when`
+ *  （P5 落地前的旧 DDL——设计档 §3.4）。其余任一数据列缺 ⇒ 列集不可归因，拒（fail-closed）。 */
+const TOLERATED_MISSING = ["executor", "resume_when"]
 /** 备份面根 / 回收面根（`ledgerDirPath()` 的**兄弟位**——同派生于可覆盖基，§2.11#6）。 */
 export function ledgerBackupRoot() { return join(dirname(ledgerDirPath()), "ledger-backup") }
 export function ledgerTrashRoot() { return join(dirname(ledgerDirPath()), "ledger-trash") }
@@ -48,7 +52,7 @@ function batchStamp(date) {
   const p = (n) => String(n).padStart(2, "0")
   return `${date.getFullYear()}${p(date.getMonth() + 1)}${p(date.getDate())}-${p(date.getHours())}${p(date.getMinutes())}${p(date.getSeconds())}`
 }
-/** 行集读取（id + 12 数据列；缺失列按 NULL 映射——旧 DDL 源的 `executor` 正常态，KD-LN10）。 */
+/** 行集读取（id + `DATA_COLUMNS` 全列；缺失列按 NULL 映射——旧 DDL 源的 `executor` / `resume_when` 正常态，KD-LN10）。 */
 function readRows(db, missing = []) {
   const cols = DATA_COLUMNS.filter((c) => !missing.includes(c))
   return db.prepare(`SELECT id, ${cols.join(", ")} FROM items ORDER BY id`).all()
@@ -62,7 +66,7 @@ function describeSource(file) {
     const cols = itemColumns(db)
     if (!cols.length) return { rows: 0, missing: [], refusal: "不可开为台账库（无 items 表）" }
     const missing = DATA_COLUMNS.filter((c) => !cols.includes(c))
-    const bad = missing.filter((c) => c !== "executor")
+    const bad = missing.filter((c) => !TOLERATED_MISSING.includes(c))
     const rows = readRows(db, missing)
     return { rows: rows.length, missing, dist: byStatus(rows), refusal: bad.length ? `缺数据列（列集不可归因）：${bad.join(" / ")}` : null }
   } catch (e) { return { error: e.message, refusal: `不可读（${e.message}）` } } finally { db.close() }
@@ -72,7 +76,9 @@ function readRowsOf(file, missing = []) {
   const db = openRead(file)
   try { return readRows(db, missing) } finally { db.close() }
 }
-/** 写门风险旗（§2.2 表）：迁入行属 `在途 / 待核销` 且 `task_book` 不可解析 / 指向档不存在 ⇒ 该行后续更新将拒于 §6.1 写门；只出旗，不拦截（判面与写门同源·#834——共享解析单点 `resolveDeclaredRef`：① 仓根解析 → ② 声明源前缀解析序）。 */
+/** 指针读数旗（§2.2 表 · §6.1 口径 5）：迁入行属 `在途 / 待核销` 且 `task_book` 不可解析 / 指向档不存在 ⇒ 出旗；
+ *  **读数非门**——不拦任何写入（该行迁入照旧、后续更新按 §6.1 本笔写入面判）。判面与写门同源·#834
+ *  （共享解析单点 `resolveDeclaredRef`：① 仓根解析 → ② 声明源前缀解析序）。 */
 function writeGateFlag(values, projectRoot) {
   const tb = values[5]
   if ((values[1] !== "在途" && values[1] !== "待核销") || tb == null || tb === "") return null
@@ -92,9 +98,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`)
@@ -116,7 +122,7 @@ export function planLedgerMigration(cwd, { fromKeys = [] } = {}) {
   return { projectRoot, targetKey, targetPath, targetDesc, sources, flags, migrate }
 }
 
-/** dry-run 计划行（零写报告：目标 / 变体源候选 / 计划动作 / 写门风险旗）。 */
+/** dry-run 计划行（零写报告：目标 / 变体源候选 / 计划动作 / 指针读数旗（非门））。 */
 function printPlan(plan, out) {
   const t = plan.targetDesc
   const dist = (d) => (d.dist ? Object.entries(d.dist).map(([k, v]) => `${k} ${v}`).join(" · ") : `unreadable: ${d.error}`)
@@ -127,13 +133,13 @@ function printPlan(plan, out) {
     `Variant sources (${plan.sources.length}):${plan.sources.length ? "" : " none（无待迁源）"}`,
     ...plan.sources.map((s) => `  ${s.key}  ${s.path}  rows ${s.desc.rows ?? "?"}  mtime ${s.mtime}\n    ${dist(s.desc)}${s.refusal ? `  ⚠ ${s.refusal}（confirm 面将拒跑）` : ""}`),
     `Plan: backup → ${join(ledgerBackupRoot(), "<批次>")}/ ; migrate ${plan.migrate} rows → target (post-migration count = ${t.error ? "?" : (t.rows ?? 0) + plan.migrate})`,
-    `Write-gate risk flags: ${plan.flags.length}${plan.flags.length ? "（不拦截——迁入后在途 / 待核销行的后续更新仍受写入时门约束）" : ""}`,
+    `Pointer reading flags: ${plan.flags.length}${plan.flags.length ? "（读数非门——不拦任何写入：行照迁，后续更新按本笔写入面判）" : ""}`,
     ...plan.flags.map((f) => `  ⚠ ${f.source} #${f.id}: ${f.flag}`),
     'Run "thincoder ledger migrate --confirm" to execute (backup first, then single-transaction import, then sources are recycled into ledger-trash).',
   ].join("\n"))
 }
 
-/** 事务内读回核验（§2.2 步 3）：逐插入行按新 id 回读 12 数据列与源等值 ∧ 目标既有行零动；不等 ⇒ throw（ROLLBACK ⇒ 目标零行变、源零动——新建档可能残留）。 */
+/** 事务内读回核验（§2.2 步 3）：逐插入行按新 id 回读 `DATA_COLUMNS` 全列与源等值 ∧ 目标既有行零动；不等 ⇒ throw（ROLLBACK ⇒ 目标零行变、源零动——新建档可能残留）。 */
 function verifyImported(db, inserted, existingById) {
   const get = db.prepare(`SELECT ${DATA_COLUMNS.join(", ")} FROM items WHERE id = ?`)
   for (const { key, id, values } of inserted) {

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 = []