@thincoder/core 0.9.5 → 0.10.1

package/file-links.mjs

@@ -0,0 +1,53 @@
+/**
+ * file-links.mjs — 工具结果文本的**验存**文件链接抽取（上提核件 —— 处理流批 R2 · 2026-09-28）。
+ * 上提源 = VSC `thincoder-vscode/src/extension/file-links.mjs`（token 抽取 ∕ 去重 ∕ 封顶）× 桌面同档
+ * （相对径需项目根——无根 ⇒ 相对 token 零判据，不落 `process.cwd()` 第二解析基）；本档 = 单源
+ * （消费面 = 桌面 `thincoder-desktop/src/main/file-links.mjs` · VSC `thincoder-vscode/src/extension/file-links.mjs`——已随
+ * parity-b4 迁移轮改指本档（2026-09-29，双写窗口收口））。
+ * 判据 = **盘上存在闸**（存在 ∧ 是文件）：路径 token 只在真实存在时才成链接 —— URL ∕ 日志噪音 ∕
+ * 版本号恒不成链接（存在检查 = 最后一道闸）。**验存（`existsSync` ∕ `statSync`）转注入缝**：本档零
+ * `node:fs`——盘面探针由调用方注入（`probe = { existsSync, statSync }`）；缺 ∕ 形违 ⇒ 抛（fail-loud——
+ * 存在闸未接线不得静默扮成「零链接」）。返回 `[{ raw, path, line }]`：`raw` = 含行后缀原文 · `path` =
+ * 盘上绝对路径 · `line` = 数 ∕ 缺 ⇒ `null`；零抛面 = fs 判据（探针逐条 try/catch：不可达 = 不成链接）。
+ */
+
+import { isAbsolute, resolve } from "node:path"
+
+/** 路径 token：可选 Windows 盘符 + 路径字符 + 点扩展名 + 可选 `:line` / `:line:col` 后缀；m[1] = 路径本体（供探针）、m[2] = 行号、m[0] = 渲染面包裹面 `raw`。 */
+const PATH_TOKEN_RE = /((?:[A-Za-z]:)?[~./\\\w][\w./\\~-]*\.\w{1,10})(?::(\d+)(?::\d+)?)?/g
+
+/** 逐结果封顶（值同源 = VSC 同档 `MAX_LINKS`）。 */
+export const MAX_LINKS = 50
+
+/**
+ * 工具结果文本 ⇒ 验存文件链接（去重 + 封顶）。`cwd` = 项目根（相对 token 的解析基）；缺 ∕ 空 ⇒ 相对 token
+ * 一律不检（禁假链接）；绝对 token 与 cwd 无关，照检。`probe` = 盘面探针注入缝（`{ existsSync(p), statSync(p) }`——
+ * `node:fs` 同名面；桌面端侧注入）。零文本（`""` ∕ 非串）先于探针校验早退（零判据面 —— 探针不检）。
+ */
+export function extractFileLinks(cwd, text, probe) {
+  if (typeof text !== "string" || text === "") return []
+  if (typeof probe?.existsSync !== "function" || typeof probe?.statSync !== "function") {
+    throw new TypeError("extractFileLinks: probe seam missing — inject { existsSync, statSync } (the existence guard must not silently degrade)")
+  }
+  const base = typeof cwd === "string" && cwd !== "" ? cwd : null
+  const links = []
+  const seen = new Set()
+  for (const m of text.matchAll(PATH_TOKEN_RE)) {
+    const pathPart = m[1]
+    // 协议相对 URL 残体（`//example.com/a.png`）—— 恒非工作区路径。
+    if (pathPart.startsWith("//") || pathPart.startsWith("\\\\")) continue
+    const absolute = isAbsolute(pathPart)
+    if (!absolute && base === null) continue // 无项目根 ⇒ 相对 token 零判据（禁假链接）
+    const line = m[2] ? Number(m[2]) : null
+    const abs = absolute ? pathPart : resolve(base, pathPart)
+    const key = `${abs}:${line ?? ""}`
+    if (seen.has(key)) continue
+    try {
+      if (!probe.existsSync(abs) || !probe.statSync(abs).isFile()) continue
+    } catch { continue }
+    seen.add(key)
+    links.push({ raw: m[0], path: abs, line })
+    if (links.length >= MAX_LINKS) break
+  }
+  return links
+}

package/file-refs.mjs

@@ -0,0 +1,103 @@
+/**
+ * file-refs.mjs — @ 文件引用**注入 ∕ 剥离核件**（缺面族批补 #632 · 2026-09-29 上提）。
+ * 上提源 = VSC `thincoder-vscode/src/extension/file-refs.mjs` 自持档（逐字搬——regex ∕ 4000 截断 ∕
+ * `[File: …]` 围栏 ∕ 摘要块格式零语义改良）；本档 = **单源**；两端各持薄壳（端侧 `node:fs` 探针注入）：
+ * VSC `thincoder-vscode/src/extension/file-refs.mjs` ∥ 桌面 `thincoder-desktop/src/main/file-refs.mjs`。
+ * 消费面：VSC 注入 `panel-chat.mjs:187` ∕ 恢复剥离 `panel-session.mjs:185` ∕ 标题剥离
+ * `panel-session-write.mjs:139`；桌面注入缝 = `turn-driver.mjs`（起跑前单点，`turn-face.mjs`）∥
+ * 恢复剥离 = `session-slots.mjs` `pageHistory` ∥ 标题剥离 = 核 `generate-title.mjs:132`（读源处）。
+ * 文本形逐字冻结（`docs/vsc/design/WEBVIEW.md:154`「落线文本逐字不变」契约）：上提不携任何行为面改动。
+ * 判据 = **盘面探针注入缝**（`probe = { readFileSync, existsSync, statSync }` —— `node:fs` 同名面；
+ * 缺 ∕ 形违 ⇒ 抛 —— fail-loud：盘面闸未接线不得静默扮成「零引用」，沿 `file-links.mjs:29-31` 先例）。
+ * `stripAtRefs` = 注入语法的逆变换：fail-closed 判据逐字依赖注入输出格式 —— 语法与其逆变换同住一处，
+ * 零第二实现（本档为唯一产者）。
+ */
+import { join } from "node:path"
+
+/** 探针三件（`node:fs` 同名面）——缺一即缝违。 */
+const PROBE_KEYS = ["readFileSync", "existsSync", "statSync"]
+
+/** 探针校验（fail-loud）：三件皆须为函数 —— 缺 ∕ 形违 ⇒ 抛。 */
+function probeOf(probe) {
+  if (PROBE_KEYS.some((key) => typeof probe?.[key] !== "function")) {
+    throw new TypeError("injectAtRefs: probe seam missing — inject { readFileSync, existsSync, statSync } (the disk probe must not silently degrade)")
+  }
+  return probe
+}
+
+/** Scan text for @path references and replace with inline file content.
+ *  零文本（非串 ∥ 空串）先于探针校验早退（零判据面——探针不检，同序沿核 `file-links.mjs:28`）。 */
+export function injectAtRefs(text, cwd, probe) {
+  if (typeof text !== "string" || text === "") return text
+  const io = probeOf(probe)
+  const re = /@([^\s,;:()[\]{}"'`]+)/g
+  const refs = []
+  let m
+  while ((m = re.exec(text)) !== null) {
+    const raw = m[1]
+    // Skip things that aren't paths (emails, mentions like @user)
+    if (!/^[a-zA-Z0-9_./\\-]+$/.test(raw)) continue
+    if (raw.includes("@")) continue
+    // Resolve relative to cwd
+    const abs = join(cwd, raw)
+    if (!io.existsSync(abs)) continue
+    try {
+      const stat = io.statSync(abs)
+      if (!stat.isFile()) continue
+      let content = io.readFileSync(abs, "utf8")
+      if (content.length > 4000) content = content.slice(0, 4000) + "\n... (truncated)"
+      refs.push({ raw, abs, content })
+    } catch (e) {
+      console.error(`[file-refs] failed to read @${raw}:`, e.message)
+    }
+  }
+  if (refs.length === 0) return text
+
+  // Replace @refs in the text with inline content blocks
+  for (const ref of refs) {
+    const placeholder = `@${ref.raw}`
+    const injection = `[File: ${ref.raw}]\n\`\`\`\n${ref.content}\n\`\`\``
+    text = text.split(placeholder).join(injection)
+  }
+
+  // Append a summary of referenced files
+  const list = refs.map(r => `  - ${r.raw} (${r.content.length} chars)`).join("\n")
+  text += `\n\n[Referenced files:\n${list}\n]`
+
+  return text
+}
+
+/**
+ * 复原注入前的用户原文（F-W15 端侧显示边界剥离 · D-W17）。
+ *
+ * 契约：同一会话中用户消息的**恢复面**文本 ≡ 活面气泡文本（= 用户所打原文，`@路径` 保持简洁形）。
+ * 与产者同档（本档 = 注入语法的唯一产者——语法与其逆变换同住一处，零第二实现）。
+ *
+ * 剥离判据（fail-closed）：仅当文本尾部为注入**摘要块**（`[Referenced files:` 头 +
+ * 逐行 `  - <raw> (<N> chars)` + 尾 `]`）时，按「`[File: <raw>]` 头 + 围栏 + 恰 N 字符正文 +
+ * 收尾围栏 ⇒ `@<raw>`」逐条还原并删摘要块；**任一条不吻合 ⇒ 整条原样返回**（用户手打的
+ * `[File: x]` / 形近文本零误伤）。落线 / 机读线（模型输入）零触碰——本函数只服务显示边界。
+ */
+export function stripAtRefs(text) {
+  const s = typeof text === "string" ? text : ""
+  const tail = /(?:^|\n\n)\[Referenced files:\n([\s\S]*)\n\]$/.exec(s)
+  if (!tail) return s
+  const entries = []
+  for (const line of tail[1].split("\n")) {
+    const m = /^ {2}- (.*) \((\d+) chars\)$/.exec(line)
+    if (!m) return s // 摘要块形近（行不吻合）⇒ 原样返回
+    entries.push({ raw: m[1], len: Number(m[2]) })
+  }
+  if (entries.length === 0) return s
+  let head = s.slice(0, tail.index) // 删摘要块（含其前空行）
+  for (const { raw, len } of entries) {
+    const open = `[File: ${raw}]\n\`\`\`\n`
+    const at = head.indexOf(open)
+    if (at < 0) return s // 头部缺 / 不对应 ⇒ 原样返回
+    const bodyStart = at + open.length
+    const bodyEnd = bodyStart + len
+    if (head.slice(bodyEnd, bodyEnd + 4) !== "\n\`\`\`") return s // 字符数不符 ⇒ 原样返回
+    head = head.slice(0, at) + `@${raw}` + head.slice(bodyEnd + 4)
+  }
+  return head
+}

package/generate-title.mjs

@@ -9,9 +9,17 @@
  */
 
 import { proxyFetch } from "./proxy.mjs"
+import { resolveProviderSecrets } from "./env-ref.mjs"
 // D7（2026-09-21 块标题行对齐批——标题链单源）：首条真实 user 消息谓词收核单源
 // （`isRealUserMsg`——纯函数零依赖，无环）。
 import { isRealUserMsg } from "./history-window.mjs"
+// #632（缺面族批补 · @ 文件引用对齐 · 2026-09-29）：标题源剥离单源——注入形不得进标题请求（核件
+// `file-refs.mjs`；CLI 无注入 ⇒ 零动作；VSC 同位转口 = `panel-session-write.mjs:139`）。
+import { stripAtRefs } from "./file-refs.mjs"
+// #363③（off 形族单源——MODEL-SPECS.md §16.2 / §16.4）：禁思考形与「是否可禁」一律引核
+// （`thinkOffShape` / `thinkOffPath`——本档零副本）；spec 查表同单源（`specForModel`）。
+import { specForModel } from "./model-specs.mjs"
+import { thinkOffShape, thinkOffPath } from "./think-off.mjs"
 
 // Test seam (_-prefix, mirrors run.mjs seams): lets the proxy-branch regression
 // test swap the proxy fetch. The branch it exercises used to carry a dynamic
@@ -31,7 +39,16 @@ export async function generateTitle(userContent, provider) {
   if (typeof userText !== "string" || userText.length < 10) return null
   if (!provider?.apiKey || !provider?.baseURL || !provider?.model) return null
 
+  // #363③：禁思考形（三格式支共用）——off 取形与可宣称性引核单源：`thinkOffPath` 假
+  // （thinkAlwaysOn 族）或 `thinkOffShape` 为 `null`（effort 族——`null` 形是核载荷门的
+  // 约定，本档无门）⇒ 不发禁形（假标记：被服务端拒 / 静默失效）。
+  const spec = specForModel(provider.model)
+  const offShape = thinkOffPath(spec) ? thinkOffShape(spec) : null
+
   try {
+    // #57（provider-config-family 批）：凭据值位 `${env:VAR}` 消费侧解析（CONFIG.md §6.3）——解析抛错
+    // 落本函数既有非致命兜底（下方 catch ⇒ 标题回落 null——不破坏回合，与「无 key 不生成标题」同形）。
+    provider = resolveProviderSecrets(provider)
     const system = "Generate a concise title (max 40 chars, no quotes) for this conversation. Reply ONLY with the title."
     const text = userText.slice(0, 200)
     let url, body, extract
@@ -43,7 +60,7 @@ export async function generateTitle(userContent, provider) {
         messages: [{ role: "user", content: text }],
         max_tokens: MAX_TITLE_TOKENS,
         stream: false,
-        thinking: { type: "disabled" }, // IK9UZ8：不让 reasoning 吃掉输出预算
+        ...(offShape !== null ? { thinking: offShape } : {}), // IK9UZ8：不让 reasoning 吃掉输出预算
       })
       extract = (data) => data.content?.map((b) => b.text || "").join("")
     } else if (provider.format === "google") {
@@ -51,7 +68,11 @@ export async function generateTitle(userContent, provider) {
       body = JSON.stringify({
         systemInstruction: { parts: [{ text: system }] },
         contents: [{ role: "user", parts: [{ text }] }],
-        generationConfig: { maxOutputTokens: MAX_TITLE_TOKENS, thinkingConfig: { thinkingLevel: "none" } }, // IK9UZ8
+        generationConfig: {
+          maxOutputTokens: MAX_TITLE_TOKENS,
+          // google 格式自身的关思考形（wire 原生——非族别取形副本）；无有效 off 路径 ⇒ 零发
+          ...(offShape !== null ? { thinkingConfig: { thinkingLevel: "none" } } : {}),
+        }, // IK9UZ8
       })
       extract = (data) => data.candidates?.[0]?.content?.parts?.map((p) => p.text || "").join("")
     } else {
@@ -65,7 +86,9 @@ export async function generateTitle(userContent, provider) {
         // leave content empty (IK9UZ8). Providers that don't accept the field ignore it
         // (OpenAI-compatible convention). A 40-char title wants ~60–80 tokens, so 100 is
         // ~2.5x headroom (design decision — docs/core/design/SESSION.md §6.7).
-        thinking: { type: "disabled" },
+        // #363③：形自核单源（`thinkOffShape`——type 族 = `{type:"disabled"}`；无有效 off 路径
+        // 族不发——见上方 offShape 取形）。
+        ...(offShape !== null ? { thinking: offShape } : {}),
         max_tokens: MAX_TITLE_TOKENS,
         stream: false,
       }
@@ -113,7 +136,8 @@ export async function ensureSessionTitle(agent) {
     let firstUser = agent._recordStore?.firstUserMessage?.() ?? null
     if (!firstUser) firstUser = (agent._fullHistory ?? agent.history).find(isRealUserMsg)
     if (firstUser) {
-      const title = await generateTitle(firstUser.content, agent.provider)
+      // #632：读源处剥离（注入形不得入标题请求——与恢复面同读一函数，零第二实现）
+      const title = await generateTitle(stripAtRefs(firstUser.content), agent.provider)
       if (title) agent.title = title
     }
   } catch {

package/history-window.mjs

@@ -9,6 +9,11 @@
  *
  * 承接：会话数据面的「人读线」窗口切分（分段恢复 / 逐页回看）——与磁盘会话档
  * 同源（`{hash}.json.N`），本档只读数组、不触盘。
+ *
+ * 留档记录直通（opt-in · 消化面留档批 · #719）：`digest` ∕ `subagent` 两型记录
+ * 原样入窗（携 `idx`；字段零改名）；默认关 ⇒ 输出与改前逐字等价（CLI ∕ VSC 读面
+ * 零改零破）——`kindOf` 认 `kind` 键；形 / 在场 / 判据单源 =
+ * `docs/desktop/design/RENDERER.md` §1.1「留档记录」条。
  */
 
 /** Real user message predicate (shared by the slot metadata digest and the window).
@@ -32,7 +37,7 @@ function tsOf(m) {
 }
 
 function kindOf(m) {
-  return m?.type ?? m?.role
+  return m?.type ?? m?.role ?? m?.kind
 }
 
 function toolCallsOf(m) {
@@ -103,10 +108,16 @@ function pairToolEntries(history) {
  * takes the LAST page (first paint); otherwise the page [s, e) ending just before
  * `before`. Half-open [s, e) keeps loadOlder pages from re-rendering the boundary
  * message. `idx` values are GLOBAL history indexes — pagination never renumbers.
+ *
+ * `opts.records === true`（opt-in —— 留档批 · #719）⇒ `digest` ∕ `subagent` 两型
+ * 记录原样入窗（`{ ...record, idx }`，字段零改名）并占条目位（游标按条目推进）；
+ * 记录不参与 turn ∕ 可见性谓词（`visible` 面语义不动）。**默认关** ⇒ 输出与改前
+ * 逐字等价（负控腿）；缺 `opts` ∕ 非 `true` ⇒ 同默认径。
  */
-export function historyWindow(history, before, pageSize = HISTORY_PAGE_SIZE) {
+export function historyWindow(history, before, pageSize = HISTORY_PAGE_SIZE, opts = {}) {
   const total = Array.isArray(history) ? history.length : 0
   if (total === 0) return { messages: [], hasOlder: false }
+  const records = opts?.records === true
   const { frameResults, ownerOf } = pairToolEntries(history)
   const end = before == null ? total : Math.max(0, Math.min(before, total))
   const start = Math.max(0, end - pageSize)
@@ -161,6 +172,10 @@ export function historyWindow(history, before, pageSize = HISTORY_PAGE_SIZE) {
         turnStart: prevVisibleKind === null || prevVisibleKind === "user",
         tools,
       })
+    } else if (records && (kind === "digest" || kind === "subagent")) {
+      // 留档记录直通（opt-in）：人读线条目原样入窗 + 携位次（字段零改名 —— 形单源 =
+      // `docs/desktop/design/RENDERER.md` §1.1「留档记录」条）
+      messages.push({ ...m, idx: i })
     } else if (kind === "tool") {
       // A consumed tool entry produces no message of its own (rendered with its frame) —
       // only a true orphan falls back to the top level (rules 3/4)

package/i18n.mjs

@@ -46,6 +46,8 @@ export const CORE_MESSAGES = Object.freeze({
   "status.rateLimited": { en: "Rate-limited 429, retry in ${s}s", zh: "限流 429，${s}s 后重试" },
   "status.overloaded": { en: "Server overloaded, retrying in ${s}s", zh: "服务过载，${s}s 后重试" },
   "status.quota": { en: "quota exhausted: ${msg}", zh: "配额耗尽：${msg}" },
+  // ── 停滞轻显形（在飞回合静默读数——TUI.md §7.7 · stall-indicator 批 2026-09-29）──
+  "status.quiet": { en: "Quiet ${s}s", zh: "已静默 ${s}s" },
   // ── 异步池状态词 ──
   "sub.running": { en: "running", zh: "运行中" },
   "sub.queued": { en: "queued", zh: "排队中" },

package/index-discover.mjs

@@ -8,14 +8,14 @@
  * PORTABILITY VSC mirror · VP-9 (P9): the extension tables were 14 code + 5 doc
  * entries with no declaration surface — a project in any other mainstream language
  * was invisible AND undeclarable, silently. Now: the tables carry the CLI-aligned
- * additions, `.thincoder/conventions.json` (index.codeExtensions / index.docExtensions)
- * unions in project-specific extensions, and files whose extension is in NO list are
+ * additions, the manifest's `index.codeExtensions` / `index.docExtensions` union in
+ * project-specific extensions, and files whose extension is in NO list are
  * TALLIED (`collectUnlisted`) so "my .xyz files are not searchable" stops being
  * invisible (buildIndex → panel hint + a log event).
  */
 import { readdirSync } from "node:fs"
 import { join, relative } from "node:path"
-import { DEFAULT_CONVENTIONS, loadConventions } from "./conventions.mjs"
+import { DEFAULT_DECLARATION, loadProjectDeclaration } from "./conventions.mjs"
 
 const CODE_EXTS = new Set([
   ".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".py", ".rs", ".go", ".java", ".c", ".cpp", ".h", ".hpp",
@@ -36,11 +36,11 @@ function extensionOf(p) {
 }
 
 /** Effective extension sets for one conventions object: defaults ∪ declared
- *  (declaration is a UNION — §4.1: index.*Extensions APPEND). Cached per frozen
+ *  (declaration is a UNION — §3.1: index.*Extensions APPEND). Cached per frozen
  *  conventions object (the loader hands out stable per-root instances). */
 const _knownCache = new WeakMap()
 function knownExtensions(conv) {
-  const key = conv ?? DEFAULT_CONVENTIONS
+  const key = conv ?? DEFAULT_DECLARATION
   let hit = _knownCache.get(key)
   if (!hit) {
     const code = new Set(CODE_EXTS)
@@ -126,7 +126,7 @@ function isIndexableName(name, allExts) {
  *   files array (backward-compatible with needsRebuild / the memory self-check).
  */
 export function discoverFiles(cwd, signal, { collectUnlisted = false } = {}) {
-  const res = collectFiles(cwd, cwd, false, signal, loadConventions(cwd), collectUnlisted)
+  const res = collectFiles(cwd, cwd, false, signal, loadProjectDeclaration(cwd), collectUnlisted)
   return collectUnlisted ? res : res.files
 }
 
@@ -135,7 +135,7 @@ export function discoverFiles(cwd, signal, { collectUnlisted = false } = {}) {
 export function discoverFilesUnder(cwd, subdir, { collectUnlisted = false } = {}) {
   const base = String(subdir ?? "").replaceAll("\\", "/").replace(/\/+$/, "")
   if (!base) return collectUnlisted ? { files: [], unlisted: { count: 0, exts: [] } } : []
-  const res = collectFiles(join(cwd, base), cwd, false, undefined, loadConventions(cwd), collectUnlisted)
+  const res = collectFiles(join(cwd, base), cwd, false, undefined, loadProjectDeclaration(cwd), collectUnlisted)
   return collectUnlisted ? res : res.files
 }
 

package/ledger-cmd.mjs

@@ -1,15 +1,20 @@
 /**
- * ledger-cmd.mjs — 台账命令族（查询 = 只读全角色 / 写 = 仅主 agent 装配）+ 工具定义
- * （M2 模块拆分件——设计档 docs/core/design/modules/ENGINEERING-MODE-V2-MODULE-LEDGER.md §2.3 拆分计划）。
+ * ledger-cmd.mjs — 台账核心函数档（查询 = 只读全角色 / 写 = 仅主 agent 装配）。
+ * 工具定义 + 工具层参数守卫 = 拆分件 `thincoder-core/ledger-tools.mjs`（2026-09-28 守卫族微修批 ·
+ * 台账 #473——纯搬移、语义零变；拆分触发 = 本档 298 行贴 300 顾问线，本批读面守卫增量必越线）；
+ * 核函数（`ledgerQuery` / `ledgerCount` / `ledgerAdd` / `ledgerUpdate` / `ledgerClose`）留本档，
+ * 工具档消费之。
  *
- * 接线（设计档 §2.2 命令面接线）：查询命令 ← tools/index.mjs（assembleBuiltinTools 全角色面）；
- * 写命令 ← agent/family-tools.mjs（assembleFamilyTools 的 depthOnly 分支）——一律**动态 import** 本模块链
- * （ledger-db.mjs 静态 import node:sqlite ⇒ 消费侧静态 import 会破 W8 契约②）。
+ * 接线（设计档 §2.2 命令面接线）：族出口 = `ledger.mjs`（re-export 两源——KD-M2-3）；查询命令 ←
+ * tools/index.mjs（assembleBuiltinTools 全角色面）；写命令 ← agent/family-tools.mjs（assembleFamilyTools
+ * 的 depthOnly 分支）——一律**动态 import** 本模块链（ledger-db.mjs 静态 import node:sqlite ⇒
+ * 消费侧静态 import 会破 W8 契约②）。
  */
 import { statSync } from "node:fs"
-import { resolve } from "node:path"
+import { basename, 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"
 
 /** 查询（只读，全角色）：SELECT 行集（status/kind/board 过滤，缺省 = 全部行；id 升序）。库不在 = 空账。 */
 export function ledgerQuery({ cwd, status = null, kind = null, board = null } = {}) {
@@ -37,21 +42,31 @@ export function ledgerCount({ cwd } = {}) {
 /** 路径 = 存在的**档**？（目录 / 缺失 → false——写门存在性判据用）。 */
 const isFile = (p) => { try { return statSync(p).isFile() } catch { return false } }
 
-/** 写门·指针存在性（设计档 §6.1 · 台账 #38 · AC-M2-9）：写命令落盘前判**结果行**——`status ∈
- *  {在途, 待核销}` 且 `task_book` 非空 ⇒ 文件部分（首个 `§` 前子串，trim）须经基准 `resolve(base, …)`
- *  指向存在的档；缺文件部分（`§2` / 全空白）⇒ 拒；不在册 / 非文件 ⇒ 拒（throw，行不变）。
+/** 写门·指针存在性（设计档 §6.1 · 台账 #38 · AC-M2-10）：写命令落盘前判**结果行**——`status ∈
+ *  {在途, 待核销}` ⇒ 判 `task_book`：`null`（缺指针）⇒ 拒（「必填」文案）；非 `null` ⇒ 文件部分
+ *  （首个 `§` 前子串，trim）须经基准 `resolve(base, …)` 指向存在的档；缺文件部分（`§2` / 空串 /
+ *  全空白）⇒ 拒；不在册 / 非文件 ⇒ 拒（throw，行不变）。
  *  判位与迁移表判同层（落盘前）；文案前缀 = 调用函数名（与同函数既有两条文案同款）。
  *  基准 `base` = **与台账库关联键同源**（2026-09-18 fix 轮 · O1 收正）：`resolveProjectRoot(cwd) ??
  *  resolve(cwd ?? ".")`——同表达式见 `ledger-db.mjs` `ledgerDbPath`；容器根会话（锚 cwd 下唯一注册
- *  子仓 P）与子仓会话 ⇒ 库键与指针基准同取 P（同库同基准；原实现 `resolve(cwd, …)` = 原始 cwd 会误拒）。 */
+ *  子仓 P）与子仓会话 ⇒ 库键与指针基准同取 P（同库同基准；原实现 `resolve(cwd, …)` = 原始 cwd 会误拒）。
+ *  #832：声明源前缀形同判（§6.15——首段 = 声明公共仓目录名 ⇒ 于该声明根解析；可核 ⇒ 通过；缺位拒）。 */
 function assertTaskBookGate(cwd, fnName, status, taskBook) {
   if (status !== "在途" && status !== "待核销") return
-  if (taskBook == null || taskBook === "") 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)
-  if (!isFile(abs)) throw new Error(`${fnName}：task_book 指向的档不存在：${taskBook}（解析 = ${abs}）`)
+  // §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}）`)
 }
 
 /** 新增（写命令，仅主 agent）：INSERT——入待讨论（六态状态机入口）。 */
@@ -101,7 +116,9 @@ export function ledgerUpdate({ cwd, id, patch, executorSessionId }) {
   } finally { db.close() }
 }
 
-/** 收口（写命令，仅主 agent）：勾销（待核销 → 已核销）/ 撤回（任意态 → 已废弃），事务包裹；归档 = 软删除。 */
+/** 收口（写命令，仅主 agent）：核销两源（勾销：待核销 → 已核销；追认核销：待讨论 / 待设计 → 已核销，
+ *  行 `evidence` 非空，缺 / 全空白 ⇒ 拒）/ 撤回（任意态 → 已废弃），事务包裹；归档 = 软删除。
+ *  判序（同函数体同层）：目标集判 → 行取 → 源态判 → `evidence` 门 → UPDATE（LEDGER.md §3 收口两源）。 */
 export function ledgerClose({ cwd, id, status }) {
   if (status !== "已核销" && status !== "已废弃") throw new Error(`ledgerClose：目标态 ${status} ∉ {已核销, 已废弃}`)
   const db = openLedger(cwd, { create: true })
@@ -110,123 +127,14 @@ export function ledgerClose({ cwd, id, status }) {
     try {
       const row = db.prepare("SELECT * FROM items WHERE id = ?").get(id)
       if (!row) throw new Error(`ledgerClose：行 ${id} 不存在`)
-      if (status === "已核销" && row.status !== "待核销") throw new Error(`ledgerClose：勾销仅限待核销（现态 ${row.status}）`)
+      // 判序：源态判（核销仅三源——在途不可跳）→ 追认口 `evidence` 门（行字段非空，缺 / 全空白 ⇒ 拒）
+      if (status === "已核销" && !["待讨论", "待设计", "待核销"].includes(row.status)) throw new Error(`ledgerClose：核销仅限 待讨论 / 待设计 / 待核销（现态 ${row.status}）`)
+      if (status === "已核销" && ["待讨论", "待设计"].includes(row.status) && (row.evidence == null || String(row.evidence).trim() === "")) throw new Error(`ledgerClose：追认核销须带 evidence（现态 ${row.status}）`)
       const now = nowIso()
-      // 撤回（任意态 → 已废弃——含在途直撤）同步 executor = NULL（LEDGER.md §3.1 ④）；勾销路径 executor 已在离场迁移清空，零触碰
+      // 撤回（任意态 → 已废弃——含在途直撤）同步 executor = NULL（LEDGER.md §3.1 ④）；核销两源（勾销 / 追认）executor 零触碰（非在途出边）
       db.prepare("UPDATE items SET status = ?, closed_at = ?, updated_at = ?, executor = ? WHERE id = ?").run(status, now, now, status === "已废弃" ? null : row.executor, id)
       db.exec("COMMIT")
       return { id, status }
     } catch (e) { db.exec("ROLLBACK"); throw e }
   } finally { db.close() }
 }
-
-// ── 工具定义（接线：查询 → tools/index.mjs 全角色面；写 → family-tools.mjs depthOnly 分支） ──
-
-/** 工具 cwd 供值面（缺省 → 当前项目根）。 */
-const cwdOf = (ctx) => ctx?.agent?.cwd ?? ctx?.cwd ?? process.cwd()
-
-export const ledgerQueryTool = {
-  name: "ledger_query",
-  description: "台账查询（需求池 / 技术待办）——SQLite 行集，只读、全角色可用。未决四态 = 待讨论 / 待设计 / 在途 / 待核销；已核销 / 已废弃 = 归档态（软删除，行保留）。过滤参数缺省 = 全部行。",
-  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: "按归属板块过滤（需求档文档名）" },
-    },
-  },
-  readonly: true,
-  async execute(args, ctx) {
-    return JSON.stringify(ledgerQuery({ cwd: args.cwd ?? cwdOf(ctx), status: args.status, kind: args.kind, board: args.board }), null, 2)
-  },
-}
-
-export const ledgerCountTool = {
-  name: "ledger_count",
-  description: "台账计数单源：未决四态（待讨论 / 待设计 / 在途 / 待核销）COUNT(*)，只读、全角色可用。",
-  parameters: {
-    type: "object",
-    properties: { cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" } },
-  },
-  readonly: true,
-  async execute(args, ctx) {
-    return JSON.stringify({ count: ledgerCount({ cwd: args.cwd ?? cwdOf(ctx) }) })
-  },
-}
-
-export const ledgerAddTool = {
-  name: "ledger_add",
-  description: "台账新增条目（写命令，仅主 agent）——入待讨论（六态状态机入口）。kind = requirement（需求池）/ tech_todo（技术待办）；trigger = 归批 / 条件 / 认账不排期（可空）。",
-  parameters: {
-    type: "object",
-    required: ["kind", "title"],
-    properties: {
-      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
-      kind: { type: "string", enum: ["requirement", "tech_todo"], description: "类别" },
-      title: { type: "string", description: "条目标题" },
-      board: { type: "string", description: "归属板块（需求档文档名，可空）" },
-      req_doc: { type: "string", description: "需求档指针（可空）" },
-      task_book: { type: "string", description: "任务书指针（可空；在途 / 待核销必填——咬合 CHECK）" },
-      evidence: { type: "string", description: "最小证据行（可空）" },
-      trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "技术待办触发（可空）" },
-    },
-  },
-  readonly: false,
-  async execute(args, ctx) {
-    const { cwd, ...row } = args
-    const id = ledgerAdd({ cwd: cwd ?? cwdOf(ctx), row })
-    return JSON.stringify({ id, status: "待讨论" })
-  },
-}
-
-export const ledgerUpdateTool = {
-  name: "ledger_update",
-  description: "台账更新条目（写命令，仅主 agent）——状态迁移按六态允许迁移表：待讨论→待设计 / 待设计→在途 / 在途→待核销 / 待核销→已核销 / 任意态→已废弃；表外迁移被拒。status 缺省 = 仅更新字段。",
-  parameters: {
-    type: "object",
-    required: ["id"],
-    properties: {
-      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
-      id: { type: "number", description: "条目 id" },
-      status: { type: "string", description: "目标状态（六态之一，缺省 = 不变）" },
-      title: { type: "string", description: "标题（缺省 = 不变）" },
-      board: { type: "string", description: "归属板块（缺省 = 不变）" },
-      req_doc: { type: "string", description: "需求档指针（缺省 = 不变）" },
-      task_book: { type: "string", description: "任务书指针（缺省 = 不变）" },
-      evidence: { type: "string", description: "证据（缺省 = 不变）" },
-      trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "触发（缺省 = 不变）" },
-      executor: { type: "string", description: "执行者 sessionId（可选——接手改写归属用；缺省 = 按状态迁移语义：进在途自动写本会话 / 出在途自动清空 / 其余不变）" },
-    },
-  },
-  readonly: false,
-  async execute(args, ctx) {
-    const { cwd, id, ...patch } = args
-    let executorSessionId
-    if (patch.executor === undefined) {
-      // 动态 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: "台账收口（写命令，仅主 agent）——勾销：待核销 → 已核销；撤回：任意态 → 已废弃。归档 = 软删除（写 closed_at，行保留）。",
-  parameters: {
-    type: "object",
-    required: ["id", "status"],
-    properties: {
-      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
-      id: { type: "number", description: "条目 id" },
-      status: { type: "string", enum: ["已核销", "已废弃"], description: "目标态（勾销 / 撤回）" },
-    },
-  },
-  readonly: false,
-  async execute(args, ctx) {
-    return JSON.stringify(ledgerClose({ cwd: args.cwd ?? cwdOf(ctx), id: args.id, status: args.status }))
-  },
-}

package/ledger-db.mjs

@@ -18,7 +18,7 @@ import { join, resolve } from "node:path"
 import { DatabaseSync } from "node:sqlite"
 
 import { configDir } from "./config-io.mjs"
-import { resolveProjectRoot } from "./manifest.mjs"
+import { projectRootView, resolveProjectRoot } from "./manifest.mjs"
 // 归一步单源（KD-LN1——直引，不抽新 util：先例 = peer-domains.mjs / traces/trace-store.mjs）。
 import { normalizeCwd } from "./session-slots.mjs"
 
@@ -102,9 +102,17 @@ export function ensureExecutorColumn(db, { exists } = {}) {
 
 /** 开库（cwd = 项目根——仅作关联键）→ DatabaseSync 句柄 + 幂等建表 + 老库幂等迁移（executor 列）。
  *  读面（create=false）：库文件不存在 → 返回 null（空账——读面不建库、无副作用）。
- *  写面（create=true）：库文件不存在自动建（台账目录随之创建）；项目根目录不存在 → 抛友好错误。 */
+ *  写面（create=true）：库文件不存在自动建（台账目录随之创建）；项目根目录不存在 → 抛友好错误。
+ *  **歧义锚**（≥2 候选——`projectRootView` `ambiguous` 态）⇒ **显式拒**（列候选 + 显式项目根指引；
+ *  零写——不静默回退锚；族锚「项目不可解析」，AC-M2-17）；兜底 `resolve(cwd ?? ".")` 只属 none 态。 */
 export function openLedger(cwd, { create = 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 file = ledgerDbPath(dir)
   if (!existsSync(dir)) {
     throw new Error(`项目目录不存在：${dir}——cwd 请给存在的项目根（相对路径按当前工作目录解析；缺省 = 会话项目根）`)