@thincoder/core 0.9.5 → 0.10.2

package/memory/docs.mjs

@@ -1,29 +1,39 @@
 /**
- * memory/docs.mjs — doc index sync, retrieval, agent tool generation
+ * memory/docs.mjs — doc index sync (retrieval / tool generation → memory-tool.mjs; 2026-10-01 split)
  */
 
 import { readFile, stat } from "node:fs/promises"
-import { isAbsolute, join } from "node:path"
 import { embed, cosine, toBlob, fromBlob } from "../embedding.mjs"
-import { scanVectors, createTopK } from "./scan.mjs"
+import { scanVectors, createTopK, SCAN_YIELD_MS } from "./scan.mjs"
 import { normalizeOrigin } from "./origin.mjs"
-import { commitAndPush } from "../git/gitmem.mjs"
 import { MAX_DOC_FILE_BYTES } from "./schema.mjs"
-import { buildFtsQuery, put, search, putMarkdown, clearPersonal, EMBED_TEXT_MAX_LEN } from "./core.mjs"
-import { deleteByUid, matchMemoryRows, deleteWhere } from "./delete.mjs"
+import { buildFtsQuery, invalidateStaleEmbeddings, EMBED_TEXT_MAX_LEN } from "./core.mjs"
 import { _upsertDocFile, yieldTick } from "./code-index.mjs"
-import { markIndexedCommit, listProjectFiles, indexExtensions } from "./code-sync.mjs"
+import { markIndexedCommit, listProjectFiles, indexExtensions, declaredRootEntries } from "./code-sync.mjs"
+import { searchOrigins } from "./code-search.mjs"
+import { createRowBudget, rowCountOfPath, sweepStaleRows } from "./sync-tail.mjs"
+import { loadProjectDeclaration } from "../conventions.mjs" // 排除谓词本档不直调（经 `decl` 传 `sweepStaleRows`）
 import { logEvent } from "../log.mjs"
 import { safeSliceUTF16 } from "../text-budget.mjs"
+import { DESC } from "../tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/*.md（DESC 单解析面，缺档抛错语义不变）
 
 const DOC_EMBED_BATCH = 64
 
 /**
- * Sync doc index: scan all .md/.mdc/.txt/.rst/.adoc under dir → chunk → upsert into doc_chunks.
- * Incremental by mtime.
+ * §6.15 同步展开（写侧入口）：入口 dir + 声明公共仓逐根（一层不递归）；回执 = 入口根（契约零改）。
+ * 单根内胆 = `syncDocRoot`：.md/.mdc/.txt/.rst/.adoc → chunk → doc_chunks（mtime 增量；opts seam =
+ * `yieldFn` ∕ `nowFn` ∕ `yieldMs`——stale-loop 让出可确定性断言，同 scan.mjs）。
  */
-export async function docSync(memory, dir, { onProgress } = {}) {
+export async function docSync(memory, dir, opts = {}) {
+  const res = await syncDocRoot(memory, dir, opts)
+  for (const root of declaredRootEntries(dir)) await syncDocRoot(memory, root, opts)
+  return res
+}
+
+/** 单根内胆（doc 全扫径）：原 `docSync` 体——零语义改动；导出供 `gitSync` 两条回退支跨档调用（不展开声明根）。 */
+export async function syncDocRoot(memory, dir, { onProgress, yieldFn = yieldTick, nowFn = Date.now, yieldMs = SCAN_YIELD_MS } = {}) {
   const origin = normalizeOrigin(dir) // §6.11 写缝归一（目录/git I/O 用原样 dir；库面 origin 一律归一值）
+  const decl = loadProjectDeclaration(dir)
   const { entries, unlisted } = await listProjectFiles(dir, indexExtensions(dir).doc)
   const files = [] // { abs, rel, mtimeMs }
   let overSizeSkipped = 0
@@ -33,6 +43,8 @@ export async function docSync(memory, dir, { onProgress } = {}) {
     if (st.size > MAX_DOC_FILE_BYTES) { overSizeSkipped++; continue }
     files.push({ abs, rel, mtimeMs: Math.floor(st.mtimeMs) })
   }
+  // §6.14 P2：处理序钉死 = `rel` 字典序（现 walk ∕ git 列序不确定；预算跳过 = 列序后缀）
+  files.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0))
 
   const indexed = new Map(
     memory.db.prepare(`SELECT path, mtime_ms FROM doc_chunks WHERE origin = ?`).all(origin).map((r) => [r.path, r.mtime_ms])
@@ -41,6 +53,10 @@ export async function docSync(memory, dir, { onProgress } = {}) {
 
   onProgress?.({ phase: "scan", total: files.length, overSizeSkipped })
 
+  // §6.14 P2 行预算（单源 = createRowBudget：WARN 一行可见 ∕ CAP 跳过后列——只停新增，存量行不失效）
+  const budget = createRowBudget(memory, origin, "doc", dir)
+  const budgetSkipped = []
+
   let updated = 0, removed = 0, skipped = 0, failed = 0
   const errors = []
   for (let i = 0; i < files.length; i++) {
@@ -51,11 +67,15 @@ export async function docSync(memory, dir, { onProgress } = {}) {
       skipped++
       continue
     }
+    budget.note()
+    if (budget.over()) { budgetSkipped.push(rel); continue }
 
     try {
+      const before = rowCountOfPath(memory, "doc_chunks", origin, rel)
       const text = await readFile(abs, "utf8")
       const lines = text.split("\n")
       _upsertDocFile(memory, origin, rel, lines, mtimeMs)
+      budget.add(rowCountOfPath(memory, "doc_chunks", origin, rel) - before) // 净增行数——与「库内行数」同刻度
       updated++
     } catch (e) {
       failed++
@@ -68,19 +88,17 @@ export async function docSync(memory, dir, { onProgress } = {}) {
     }
   }
 
-  for (const stale of indexed.keys()) {
-    if (!seen.has(stale)) {
-      memory.db.prepare(`DELETE FROM doc_chunks WHERE origin = ? AND path = ?`).run(origin, stale)
-      removed++
-    }
-  }
+  // §6.14 B6 ∕ M3：收尾 stale 循环（同款让出 + 面① 收尾保护位）——机制单源 = `sync-tail.mjs`
+  removed = await sweepStaleRows(memory, { table: "doc_chunks", origin, indexed, seen, decl, base: dir, yieldFn, nowFn, yieldMs })
 
-  onProgress?.({ phase: "done", total: files.length, updated, removed, skipped, failed, overSizeSkipped })
-  markIndexedCommit(memory, dir)
+  onProgress?.({ phase: "done", total: files.length, updated, removed, skipped, failed, overSizeSkipped, budgetSkipped: budgetSkipped.length })
+  // §6.14 B7 维护口：模型键失配的失效**执行**（读面只判定降级——执行住同步尾）
+  if (memory.embedder) { try { invalidateStaleEmbeddings(memory) } catch { /* 非阻塞 */ } }
+  await markIndexedCommit(memory, dir) // 锚推进 = 同步完成条件（§6.14 M1——原 fire-and-forget 竞态）
   if (unlisted.count > 0) {
     logEvent("index:unlisted", { dir, kind: "doc", count: unlisted.count, exts: unlisted.exts.map((e) => e.ext) })
   }
-  return { updated, removed, skipped, failed, errors, total: files.length, overSizeSkipped, unlistedExts: unlisted }
+  return { updated, removed, skipped, failed, errors, total: files.length, overSizeSkipped, budgetSkipped, unlistedExts: unlisted }
 }
 
 /**
@@ -91,11 +109,10 @@ export async function docSearch(memory, query, { limit = 5 } = {}) {
   const ftsQuery = buildFtsQuery(query)
   if (!ftsQuery && !memory.embedder) return []
 
-  // §6.11 读缝归一（单点取名——函数体内一律用归一值）
-  const codeOrigin = normalizeOrigin(memory.codeOrigin)
-  const ftsOriginFilter = codeOrigin ? `AND d.origin = ?` : ""
-  const vecOriginFilter = codeOrigin ? `AND origin = ?` : ""
-  const originParams = codeOrigin ? [codeOrigin] : []
+  // §6.15 读面 origin 集（项目 ∪ 声明公共仓；单 origin ⇒ 逐字零行为——快径 SQL 形零改）
+  const origins = searchOrigins(memory)
+  const ftsOriginFilter = origins.length === 1 ? `AND d.origin = ?` : origins.length > 1 ? `AND d.origin IN (${origins.map(() => "?").join(", ")})` : ""
+  const originParams = origins
 
   const ftsList = ftsQuery ? memory.db.prepare(`
     SELECT d.rowid, d.path, d.language, d.heading, d.content, d.line_start, d.line_end, bm25(doc_chunks_fts) AS rank
@@ -106,10 +123,15 @@ export async function docSearch(memory, query, { limit = 5 } = {}) {
 
   if (!memory.embedder) return ftsList.slice(0, limit)
 
-  try { await ensureDocEmbeddings(memory) } catch (e) {
+  let docEnsured
+  try { docEnsured = await ensureDocEmbeddings(memory) } catch (e) {
     console.error(`[docs] embedding ensure failed, falling back to FTS-only: ${e.message}`)
     return ftsList.slice(0, limit)
   }
+  if (docEnsured?.mismatch) { // §6.14 B7 读面零写：模型键失配 ⇒ 本面向量通道降级 FTS-only（一行可见；失效执行归维护口）
+    console.warn("[docs] embedding model changed — vector channel degraded to FTS-only (rebuild runs at maintenance: sync tail / reindex)")
+    return ftsList.slice(0, limit)
+  }
   let qvec
   try { [qvec] = await embed(memory.embedder, [query]) } catch (e) {
     console.error(`[docs] query embedding failed, falling back to FTS-only: ${e.message}`)
@@ -118,13 +140,17 @@ export async function docSearch(memory, query, { limit = 5 } = {}) {
   // TUI-OOM-ROOTCAUSE（MEMORY.md §10.3）：分块扫描 + 有界 top-K（原全表 .all()——峰值 = 块 + K）
   // TUI 假死批（§6.10 修法 A1/A2）：游标 = PK 去等值过滤前缀列（有 origin 过滤 ⇒ 2 元组；
   // 无过滤 ⇒ 全 PK）；scanVectors = async（让出）。SELECT 须携键列（游标值源）。
-  const cursorKey = codeOrigin ? ["path", "line_start"] : ["origin", "path", "line_start"]
+  const cursorKey = origins.length > 0 ? ["path", "line_start"] : ["origin", "path", "line_start"]
   const keyCols = cursorKey.join(", ")
   const top = createTopK(Math.max(limit * 4, 20))
-  await scanVectors(memory.db, `SELECT rowid, ${keyCols}, embedding FROM doc_chunks WHERE embedding IS NOT NULL ${vecOriginFilter}`, originParams, {
-    cursorKey,
-    onRow: (r) => top.push({ id: r.rowid, rowid: r.rowid, score: cosine(qvec, fromBlob(r.embedding)) }),
-  })
+  // §6.15 多 origin ⇒ 逐 origin 分趟（每趟单 origin 等值 + 游标键去等值前缀列——与单 origin 快径同形）
+  const vecSql = `SELECT rowid, ${keyCols}, embedding FROM doc_chunks WHERE embedding IS NOT NULL ${origins.length ? "AND origin = ?" : ""}`
+  for (const origin of origins.length ? origins : [null]) {
+    await scanVectors(memory.db, vecSql, origin ? [origin] : [], {
+      cursorKey,
+      onRow: (r) => top.push({ id: r.rowid, rowid: r.rowid, score: cosine(qvec, fromBlob(r.embedding)) }),
+    })
+  }
   const vecList = top.list().map((c) => ({ rowid: c.id, score: c.score }))
 
   const K = 60
@@ -161,9 +187,9 @@ async function _runEnsureDocEmbeddings(memory) {
   const modelKey = memory.embedder.model
   const stored = memory.db.prepare(`SELECT value FROM meta WHERE key = 'doc_embedding_model'`).get()?.value
   if (stored !== modelKey) {
-    memory.db.prepare(`UPDATE doc_chunks SET embedding = NULL`).run()
-    memory.db.prepare(`INSERT INTO meta (key, value) VALUES ('doc_embedding_model', ?)
-      ON CONFLICT (key) DO UPDATE SET value = excluded.value`).run(modelKey)
+    // §6.14 B7 读面零写：只判定（返回降级信号）；失效**执行**（清向量 + 落键）归维护口
+    // `invalidateStaleEmbeddings`（同步尾 ∕ /reindex ∕ 桌面 ∕ VSC）。
+    return { mismatch: true }
   }
 
   const pending = memory.db.prepare(`SELECT rowid, path, heading, content FROM doc_chunks WHERE embedding IS NULL LIMIT ${DOC_EMBED_BATCH}`).all()
@@ -180,10 +206,7 @@ async function _runEnsureDocEmbeddings(memory) {
 export function docSearchTool(memory) {
   return {
     name: "doc_search",
-    description:
-      "Search the project's documentation (README, design docs, guides, markdown files) for relevant information. Use this to find design decisions, coding conventions, architecture docs, or project rules. Prefer this over code_search when you need to understand the project's intended design rather than existing implementation. " +
-      "Returns matching doc chunks: path, heading, line range, relevance score, content excerpt. " +
-      "For what was said in sessions (conversation/chat history — decisions, rulings), use read_history.",
+    description: DESC("doc_search"), // #15 外置：文本单点 = tool-docs/doc_search.md
     parameters: {
       type: "object",
       properties: {
@@ -203,229 +226,7 @@ export function docSearchTool(memory) {
   }
 }
 
-// ---------------------------------------------------------------- agent tools
-
-/** §6 shared tool surface — action enum / parameter shapes / descriptions byte-identical
- *  with thincoder-vscode/src/memory.mjs (MEMORY.md §6 D-M1/F-M6); layer VALUES per end
- *  (VS Code has no team layer and rejects it with CLI guidance). */
-const MEMORY_ACTIONS = ["search", "put", "list", "delete", "clear"]
-const MEMORY_LAYERS = ["personal", "project", "team"]
-const MEMORY_TOOL_DESCRIPTION =
-  "Manage long-term memory in ONE tool — the action parameter picks the operation:\n" +
-  "- search — find knowledge saved in previous sessions (query, optional layer/limit); result rows start with a [layer] tag and carry the entry id (id prefix = the layer)\n" +
-  "- put — save a piece of knowledge for future sessions (type: rule = coding standards, knowledge = project facts, decision = architecture decisions, pattern = debugging/workflow patterns; title/content/tags; layer defaults to personal)\n" +
-  "- list — inventory what memory holds (optional layer/type/keyword filters, limit default 50); one row per entry: [layer] id [type] title (date); a truncated list notes the full count\n" +
-  "- delete — SINGLE: {id, layer} removes the entry shown in put/search/list output — layer is optional: when passed it is validated against the id prefix (a mismatch is refused — guards against deleting the wrong entry); when omitted the id prefix routes the delete, so any id search/list returned is directly deletable. BATCH (no id): {layer, type and/or keyword} removes every matching entry in that layer — layer and at least one of type/keyword are required, plus confirm:true (without confirm it returns the count plus a preview); layer-wide wipes without filters are refused on every layer\n" +
-  "- clear — {layer: \"personal\", confirm: true} wipes ALL personal memory entries. clear is personal-only: a missing layer or a project/team layer is refused (use delete batch filters on shared layers)\n" +
-  "Layer is the memory tier: personal (private), project (shared via this repo's .thincoder/memory/), team (CLI only, git-synced). The [layer] tag on search/list result rows, the row's id prefix, and the layer parameter are the same concept — pass a result row's [layer] as layer, or omit it on a single delete to auto-route by the id prefix.\n" +
-  "Deleting project/team (CLI) entries removes the local markdown file and its index row — team deletion is local only and a later team sync may resurrect the file while the remote still has it.\n" +
-  "Save bugs, conventions, and preferences here — they persist across sessions.\n" +
-  "Session message history (what was said in this or past sessions) is NOT in memory — search session messages with read_history."
-
-function validateTypeFilter(type) {
-  if (type === undefined || type === null || type === "") return null
-  const t = String(type)
-  if (!["rule", "knowledge", "decision", "pattern"].includes(t)) throw new Error(`Invalid memory type "${t}"; expected one of: rule, knowledge, decision, pattern`)
-  return t
-}
+// ─── 迁出面（2026-10-01 拆分批 · #755 ∥ #786）：memory agent 工具面外提 `memory/memory-tool.mjs`——
+// 经本档转口保名（消费链 = `memory.mjs → docs.mjs → memory-tool.mjs`；消费面零改）。──────────────
+export { memoryTools } from "./memory-tool.mjs"
 
-function normalizeLimit(limit, dflt) {
-  const n = Number(limit)
-  return Number.isFinite(n) && n > 0 ? Math.floor(n) : dflt
-}
-
-function fmtDate(ts) {
-  return ts ? new Date(ts).toISOString().slice(0, 10) : "?"
-}
-
-const listRowLine = (r) => `[${r.layer}] ${r.id} [${r.type}] ${r.title}（${fmtDate(r.ts)}）`
-
-/**
- * Generate the memory agent tool — ONE `memory` tool with five actions (MEMORY.md §6 D-M1).
- * search/list are read-only actions (planMode pass / no permission ask — dispatch classifies
- * them action-level, same as subagent check/status); put keeps its side-effect permission
- * gate; batch delete/clear gate on confirm:true + layer inside the tool (direct-delete
- * ruling — the confirm parameter IS the gate) and stay non-readonly like the retired tools.
- * opts: { cwd, projectDir, author, team: { dir, name } | null }
- */
-export function memoryTools(memory, opts = {}) {
-  const projectDir = opts.projectDir ? (isAbsolute(opts.projectDir) ? opts.projectDir : join(opts.cwd ?? process.cwd(), opts.projectDir)) : null
-  // §6.11：dirs 保持原样（目录 I/O 基准）——归一落在各公共入口内（写缝 syncDir / indexMarkdownFile、
-  // 删缝 deleteByUid / matchMemoryRows、读缝 search / fetchEntry）⇒ 逐入口一行，非工具层预归一。
-  const dirs = { project: projectDir, team: opts.team?.dir ?? null }
-  return [
-    {
-      name: "memory",
-      description: MEMORY_TOOL_DESCRIPTION,
-      parameters: {
-        type: "object",
-        properties: {
-          action: { type: "string", enum: MEMORY_ACTIONS, description: "Operation to run (required)" },
-          layer: { type: "string", enum: MEMORY_LAYERS, description: "The memory layer: personal (private), project (shared via this repo's .thincoder/memory/), team (CLI only). Same concept as the [layer] tag and the id prefix on search/list result rows. put/search/list: optional (put defaults to personal; search/list omit = all layers). single delete: optional (omit = route by id prefix). batch delete/clear: required" },
-          type: { type: "string", enum: ["rule", "knowledge", "decision", "pattern"], description: "Entry type: put = what to save; list/delete batch = filter by type" },
-          title: { type: "string", description: "put: short title" },
-          content: { type: "string", description: "put: full content to remember" },
-          tags: { type: "string", description: "put: space-separated tags" },
-          query: { type: "string", description: "search: natural-language query" },
-          keyword: { type: "string", description: "list/delete batch: filter matching title/content" },
-          id: { type: "string", description: "delete single: the entry id from put/search/list output" },
-          limit: { type: "number", description: "Max rows: list 50 by default, search 5 by default" },
-          confirm: { type: "boolean", description: "delete batch/clear: must be true — without it the tool refuses" },
-        },
-        required: ["action"],
-      },
-      readonly: false,
-      async execute(args) {
-        const action = String(args?.action ?? "")
-        if (!MEMORY_ACTIONS.includes(action)) {
-          throw new Error(`memory: unknown action "${action}" — expected one of: ${MEMORY_ACTIONS.join("/")}`)
-        }
-        switch (action) {
-          case "search": return execSearch(memory, args)
-          case "put": return execPut(memory, args, opts, dirs)
-          case "list": return execList(memory, args, dirs)
-          case "delete": return execDelete(memory, args, dirs)
-          case "clear": return execClear(memory, args)
-        }
-      },
-    },
-  ]
-}
-
-/** action search — the retired search tool surface (read-only, same output contract). */
-async function execSearch(memory, args) {
-  const layer = args.layer
-  if (layer !== undefined && layer !== null && !MEMORY_LAYERS.includes(String(layer))) {
-    throw new Error(`memory search: invalid layer "${layer}"`)
-  }
-  const query = String(args.query ?? "").trim()
-  if (!query) return "(no matching memories)" // 空 query 短路——两端同语义（评审 code review #4）
-  const limit = normalizeLimit(args.limit, 5)
-  let results
-  if (!layer) {
-    results = await search(memory, query, { limit })
-  } else {
-    // layer filter: oversample then slice the requested layer (results keep global rank order).
-    // 窗口 = max(limit*4, 20) 是召回上限——大库 + 高 limit 时该层结果可能不足 limit（接受的取舍——评审 code review #3）
-    const wide = await search(memory, query, { limit: Math.max(limit * 4, 20) })
-    results = wide.filter((r) => r.layer === String(layer)).slice(0, limit)
-  }
-  if (results.length === 0) return "(no matching memories)"
-  return results.map((r) => `[${r.layer}][${r.type}] ${r.title} (id=${r.id})\n${r.content}`).join("\n\n")
-}
-
-/** action put — the retired put tool surface (side-effect gate, unchanged semantics). */
-async function execPut(memory, args, opts, dirs) {
-  const layer = String(args.layer ?? "personal")
-  if (!MEMORY_LAYERS.includes(layer)) throw new Error(`memory put: invalid layer "${layer}"`)
-  if (layer === "personal") {
-    const id = await put(memory, { type: args.type, title: args.title, content: args.content, tags: args.tags ?? "" })
-    return `Saved to personal memory (id=personal:${id}): [${args.type}] ${args.title}`
-  }
-  if (layer === "project") {
-    if (!dirs.project) throw new Error("project layer unavailable: no project directory configured")
-    const filename = await putMarkdown(memory, {
-      layer: "project",
-      dir: dirs.project,
-      type: args.type,
-      title: args.title,
-      content: args.content,
-      tags: (args.tags ?? "").split(/\s+/).filter(Boolean),
-      author: opts.author ?? "unknown",
-    })
-    return `Saved to project memory (id=project:${dirs.project}:${filename}): [${args.type}] ${args.title}`
-  }
-  if (!dirs.team) {
-    throw new Error("team layer not configured: set memory.team in ~/.thincoder/config.json")
-  }
-  const filename = await putMarkdown(memory, {
-    layer: "team",
-    dir: dirs.team,
-    type: args.type,
-    title: args.title,
-    content: args.content,
-    tags: (args.tags ?? "").split(/\s+/).filter(Boolean),
-    author: opts.author ?? "unknown",
-  })
-  await commitAndPush(dirs.team, filename, `memory: [${args.type}] ${args.title}`)
-  return `Saved to team memory and pushed (id=team:${dirs.team}:${filename}): [${args.type}] ${args.title}`
-}
-
-/** action list — new inventory action (read-only): layer/type/keyword filters + limit truncation note. */
-async function execList(memory, args, dirs) {
-  const layer = args.layer ?? null
-  if (layer && !MEMORY_LAYERS.includes(String(layer))) throw new Error(`memory list: invalid layer "${layer}"`)
-  const rows = await matchMemoryRows(memory, {
-    layer: layer ? String(layer) : null,
-    type: validateTypeFilter(args.type),
-    keyword: args.keyword ? String(args.keyword).trim() : null,
-    projectDir: dirs.project,
-    teamDir: dirs.team,
-  })
-  if (rows.length === 0) return "0 条匹配"
-  const limit = normalizeLimit(args.limit, 50)
-  const shown = rows.slice(0, limit)
-  const lines = shown.map(listRowLine)
-  if (rows.length > shown.length) lines.unshift(`${shown.length} 条——截断前 ${rows.length}`)
-  return lines.join("\n")
-}
-
-/** action delete — single ({ id, layer? } — MEMORY.md §6.2: layer OPTIONAL, validated when
- *  passed, else the id prefix routes the delete) + batch (layer + type/keyword + confirm). */
-async function execDelete(memory, args, dirs) {
-  const hasId = args.id !== undefined && args.id !== null && String(args.id) !== ""
-  if (hasId) return execDeleteSingle(memory, args, dirs)
-  // batch form
-  const layer = args.layer
-  if (!layer) throw new Error("batch delete requires layer plus type and/or keyword filter")
-  if (!MEMORY_LAYERS.includes(String(layer))) throw new Error(`memory delete: invalid layer "${layer}"`)
-  const type = validateTypeFilter(args.type)
-  const keyword = args.keyword ? String(args.keyword).trim() : null
-  if (!type && !keyword) {
-    throw new Error("batch delete requires type and/or keyword filter — a layer-wide wipe without filters is refused (personal full wipe is the clear action)")
-  }
-  if (layer === "project" && !dirs.project) throw new Error("project layer unavailable: no project directory configured")
-  if (layer === "team" && !dirs.team) throw new Error("team layer not configured: set memory.team in ~/.thincoder/config.json")
-  const filters = { layer: String(layer), type, keyword }
-  const rows = await matchMemoryRows(memory, { ...filters, projectDir: dirs.project, teamDir: dirs.team })
-  if (rows.length === 0) return "0 条匹配"
-  if (args.confirm !== true) {
-    const lines = [rows.length > 5 ? `将删 ${rows.length} 条：前 5 条预览` : `将删 ${rows.length} 条`]
-    lines.push(...rows.slice(0, 5).map(listRowLine))
-    if (rows.length > 5) lines.push(`5 条——截断前 ${rows.length}`)
-    lines.push("confirm:true required — re-send with it to execute the deletion")
-    return lines.join("\n")
-  }
-  const n = await deleteWhere(memory, filters, { dirs })
-  return `Deleted ${n} entries in layer ${layer}`
-}
-
-/** Single-entry delete — MEMORY.md §6.2: layer is OPTIONAL. When passed it is validated
- *  against the id prefix (mismatch refused — guards against deleting the wrong entry); when
- *  omitted the delete routes by the id prefix alone, so any id search/list returned is
- *  directly deletable (deleteByUid already resolves the layer from the uid prefix). */
-async function execDeleteSingle(memory, args, dirs) {
-  const uid = String(args.id)
-  const prefix = uid.split(":")[0]
-  const uidLayer = prefix === "personal" || prefix === "project" || prefix === "team" ? prefix : /^\d+$/.test(prefix) ? "personal" : null
-  if (!uidLayer) throw new Error(`invalid memory id: ${uid}`)
-  const layer = args.layer
-  if (layer !== undefined && layer !== null && String(layer) !== uidLayer) {
-    throw new Error(`id prefix ${prefix}: 与 layer ${layer} 不匹配`)
-  }
-  const entry = await deleteByUid(memory, uid, { dirs })
-  return `Deleted ${entry.id}: ${entry.title}\n${(entry.content ?? "").slice(0, 500)}`
-}
-
-/** action clear — personal-only full wipe (layer + confirm:true gates; project/team refused). */
-function execClear(memory, args) {
-  const layer = args.layer
-  if (!layer) throw new Error('clear requires layer "personal" — pass layer: "personal" plus confirm: true')
-  if (String(layer) !== "personal") {
-    if (!MEMORY_LAYERS.includes(String(layer))) throw new Error(`memory clear: invalid layer "${layer}"`)
-    throw new Error("shared layers don't support clear — use delete with type/keyword batch filters instead")
-  }
-  if (args.confirm !== true) throw new Error("clear requires confirm:true — this wipes ALL personal memory")
-  const n = clearPersonal(memory)
-  return `Cleared personal memory (${n} entries deleted)`
-}

package/memory/file-list.mjs

@@ -0,0 +1,89 @@
+/**
+ * memory/file-list.mjs — 项目文件清单面（自 `memory/code-sync.mjs` 迁出 · 2026-10-01 core 拆分批 #755 ∥ #786）。
+ * 内容 = `indexExtensions`（内置扩展名表 ∪ 项目声明并集）∥ `listProjectFiles`（git 列面 + 非 git walk
+ * 回退 + unlisted 计数；`index.excludePaths` §6.14 面① 双径过滤：git 列面筛行 ∥ walk 剪枝）——迁出块逐字。
+ * 原档 `memory/code-sync.mjs` 经 `export { … } from` 转口保名（消费面 / 批内件 import 面零改）。
+ */
+import { CODE_EXTS, DOC_EXTS } from "./schema.mjs"
+import { walkProjectFiles, isSkippedRelPath, extensionOf, createUnlistedTally, MAX_WALK_FILES } from "./file-walk.mjs"
+import { loadProjectDeclaration, isExcludedRelPath } from "../conventions.mjs"
+import { logEvent } from "../log.mjs"
+
+/**
+ * Index extension sets = built-in tables ∪ project declaration
+ * (`PROJECT-MANIFEST.json` → index.codeExtensions / index.docExtensions;
+ * PORTABILITY PO-9/§3.7 — a project may declare extensions this product does not
+ * ship a default for). Declaration only ADDS (union), never removes.
+ */
+export function indexExtensions(dir) {
+  const conv = loadProjectDeclaration(dir)
+  return {
+    code: new Set([...CODE_EXTS, ...conv.index.codeExtensions]),
+    doc: new Set([...DOC_EXTS, ...conv.index.docExtensions]),
+  }
+}
+
+/**
+ * List project files matching the given extensions.
+ * Preferred source = git (`git ls-files --cached --others --exclude-standard`:
+ * tracked + untracked-not-ignored, .gitignore respected). Projects WITHOUT git
+ * fall back to a filesystem walk (PORTABILITY FR15/P8) — before, the index was
+ * silently empty there. The walk cannot honour .gitignore (no git → no such
+ * concept) and skips the shared SKIP_DIRS/dot-directory set instead.
+ * Returns { entries, unlisted }: `entries` = { abs, rel } pairs (rel relative to
+ * dir); `unlisted` = files whose extension is in NO index list (count + sample),
+ * the visible signal behind "my .xyz files are not searchable" (PORTABILITY PO-9).
+ * Declared `index.excludePaths` (§6.14 面①) filters BOTH paths — git listing filters the
+ * line set; the walk prunes excluded subtrees during traversal (no expansion, no budget).
+ * `truncated` = the non-git walk hit its file cap (capped trees are logged, never
+ * silently indexed-partial). opts.maxFiles = the walk cap (test seam).
+ */
+export async function listProjectFiles(dir, exts, { maxFiles } = {}) {
+  const { execFile: _execFile } = await import("node:child_process")
+  const { join: joinPath } = await import("node:path")
+  const { code, doc } = indexExtensions(dir)
+  const decl = loadProjectDeclaration(dir)
+  const excluded = (rel) => isExcludedRelPath(rel, decl, dir)
+  const tally = createUnlistedTally(new Set([...code, ...doc]))
+
+  const files = []
+  const finish = (truncated = false) => ({ entries: files, unlisted: tally.result(), truncated })
+
+  // Git listing when available; a non-git project falls through to the walk.
+  let gitTop
+  try {
+    gitTop = (await new Promise((resolve, reject) => {
+      _execFile("git", ["rev-parse", "--show-toplevel"], { cwd: dir, encoding: "utf8", timeout: 5000, windowsHide: true },
+        (err, stdout) => { if (err) reject(err); else resolve(stdout.trim()) })
+    })).replace(/\\/g, "/")
+  } catch {
+    // Not a git repo → filesystem walk (FR15: the index must still be usable).
+    const walked = await walkProjectFiles(dir, exts, { knownExts: new Set([...code, ...doc]), isExcluded: excluded, ...(maxFiles !== undefined ? { maxFiles } : {}) })
+    files.push(...walked.files)
+    // The walk's cap must stay visible end-to-end (file-walk.mjs: "never silently
+    // dropped") — a capped listing says so in the log, not only in a discarded flag.
+    if (walked.truncated) {
+      logEvent("index:truncated", { dir, files: walked.files.length, maxFiles: maxFiles ?? MAX_WALK_FILES })
+    }
+    return { entries: files, unlisted: walked.unlisted, truncated: walked.truncated }
+  }
+
+  try {
+    const raw = await new Promise((resolve, reject) => {
+      _execFile("git", ["ls-files", "--cached", "--others", "--exclude-standard"],
+        { cwd: dir, encoding: "utf8", timeout: 15000, windowsHide: true, maxBuffer: 10 * 1024 * 1024 },
+        (err, stdout) => { if (err) reject(err); else resolve(stdout) })
+    })
+    for (const line of raw.trim().split("\n")) {
+      const p = line.trim()
+      if (!p) continue
+      const rel = p.replace(/\\/g, "/")
+      if (isSkippedRelPath(rel) || excluded(rel)) continue
+      const ext = extensionOf(rel)
+      if (!ext || !exts.has(ext)) { tally.note(rel); continue }
+      files.push({ abs: joinPath(dir, rel), rel })
+    }
+  } catch { /* ls-files failed */ }
+
+  return finish()
+}

package/memory/file-walk.mjs

@@ -68,12 +68,14 @@ export function createUnlistedTally(knownExts) {
  * silently dropped.
  * @param {string} dir — project root
  * @param {Set<string>} exts — extensions to keep (lower-case, leading dot)
- * @param {{maxFiles?: number, knownExts?: Set<string>|null}} [opts]
+ * @param {{maxFiles?: number, knownExts?: Set<string>|null, isExcluded?: ((rel: string) => boolean)|null}} [opts]
  *   knownExts → also tally files whose extension is in NO index list
+ *   isExcluded → caller-injected exclusion predicate (§6.14 面① 剪枝形): a hit prunes the
+ *   subtree (never expanded — zero readdir, no MAX_WALK_FILES budget spent) or drops the file
  * @returns {Promise<{files: {abs: string, rel: string}[], truncated: boolean,
  *   unlisted: {count: number, exts: {ext: string, count: number}[]}}>}
  */
-export async function walkProjectFiles(dir, exts, { maxFiles = MAX_WALK_FILES, knownExts = null } = {}) {
+export async function walkProjectFiles(dir, exts, { maxFiles = MAX_WALK_FILES, knownExts = null, isExcluded = null } = {}) {
   const files = []
   const tally = knownExts ? createUnlistedTally(knownExts) : null
   let truncated = false
@@ -88,10 +90,11 @@ export async function walkProjectFiles(dir, exts, { maxFiles = MAX_WALK_FILES, k
       const rel = cur.rel ? `${cur.rel}/${ent.name}` : ent.name
       if (ent.isSymbolicLink()) continue // never follow symlinks
       if (ent.isDirectory()) {
-        if (!isSkippedRelPath(rel)) stack.push({ abs: join(cur.abs, ent.name), rel })
+        // §6.14 面① 剪枝：排除子树零展开（不耗 MAX_WALK_FILES 预算）
+        if (!isSkippedRelPath(rel) && !isExcluded?.(rel)) stack.push({ abs: join(cur.abs, ent.name), rel })
         continue
       }
-      if (!ent.isFile() || isSkippedRelPath(rel)) continue
+      if (!ent.isFile() || isSkippedRelPath(rel) || isExcluded?.(rel)) continue
       const ext = extensionOf(ent.name)
       if (!ext || !exts.has(ext)) {
         tally?.note(rel)