@thincoder/core 0.9.5 → 0.10.1

package/memory/code-sync.mjs

@@ -1,44 +1,58 @@
 /**
- * memory/code-sync.mjs — code index sync, retrieval, incremental update
+ * memory/code-sync.mjs — code index sync, incremental update (retrieval / tool generation → code-search.mjs; 2026-10-01 split; §6.15 声明根集展开 2026-10-03)
  */
+import { existsSync } from "node:fs"
 import { readFile, stat } from "node:fs/promises"
 import { join, relative } from "node:path"
-import { embed, cosine, toBlob, fromBlob } from "../embedding.mjs"
-import { scanVectors, createTopK } from "./scan.mjs"
+import { SCAN_YIELD_MS } from "./scan.mjs"
 import { normalizeOrigin } from "./origin.mjs"
-import { CODE_EXTS, DOC_EXTS, MAX_CODE_FILE_BYTES, MAX_DOC_FILE_BYTES } from "./schema.mjs"
-import { buildFtsQuery, ensureEmbeddings, EMBED_TEXT_MAX_LEN } from "./core.mjs"
+import { MAX_CODE_FILE_BYTES, MAX_DOC_FILE_BYTES } from "./schema.mjs"
+import { ensureEmbeddings, invalidateStaleEmbeddings } from "./core.mjs"
 import { detectLanguage, _upsertCodeFile, _upsertDocFile, yieldTick } from "./code-index.mjs"
-import { walkProjectFiles, isSkippedRelPath, extensionOf, createUnlistedTally, MAX_WALK_FILES } from "./file-walk.mjs"
-import { loadConventions } from "../conventions.mjs"
+import { isSkippedRelPath, extensionOf } from "./file-walk.mjs"
+import { createRowBudget, rowCountOfPath, sweepStaleRows } from "./sync-tail.mjs"
+import { loadProjectDeclaration, isExcludedRelPath, declaredPublicRoots } from "../conventions.mjs"
 import { logEvent } from "../log.mjs"
-import { safeSliceUTF16 } from "../text-budget.mjs"
+import { indexExtensions, listProjectFiles } from "./file-list.mjs"
 
 const DIFF_FULL_SYNC_THRESHOLD = 200
-const CODE_EMBED_BATCH = 64
 
-/**
- * Index extension sets = built-in tables ∪ project declaration
- * (`.thincoder/conventions.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 = loadConventions(dir)
-  return {
-    code: new Set([...CODE_EXTS, ...conv.index.codeExtensions]),
-    doc: new Set([...DOC_EXTS, ...conv.index.docExtensions]),
+/** per-origin 锚键（§6.14 M1）：`last_indexed_commit:<归一键>`——多 origin 互不覆盖；
+ *  旧单键在而本键缺 ⇒ 视为无锚（该 origin 全扫一次）；旧键清退 = 全部 origin 落锚后（ops）。 */
+const anchorKey = (origin) => `last_indexed_commit:${origin}`
+
+/** 声明公共仓根集（§6.15——入口 dir 之外；缺位整根跳过 + 一行 logEvent；归一去重保序）。 */
+export function declaredRootEntries(dir) {
+  const seen = new Set([normalizeOrigin(dir)])
+  const out = []
+  for (const abs of declaredPublicRoots(dir)) {
+    const o = normalizeOrigin(abs)
+    if (seen.has(o)) continue
+    seen.add(o)
+    if (!existsSync(abs)) { logEvent("index:root-missing", { dir, origin: o }); continue }
+    out.push(abs)
   }
+  return out
 }
 
-/**
- * git-driven incremental indexing: use git diff to find files changed since
- * the last index, and only rebuild FTS5 chunks for those files (vectors are untouched).
- * An order of magnitude faster than full mtime scanning.
- * Returns { updated, removed, skipped } or null (git unavailable).
- */
-export async function gitSync(memory, dir, { onProgress } = {}) {
+/** §6.15 同步展开（git 入口）：入口 dir + 声明公共仓逐根（一层不递归）；回执 = 入口根（契约零改）。
+ *  单根内胆 = `gitSyncDir`（git diff 增量——原 `gitSync` 体，零语义改动）；null = git 不可得。 */
+export async function gitSync(memory, dir, opts = {}) {
+  const res = await gitSyncDir(memory, dir, opts)
+  if (res === null) return null // 入口 dir null 契约保持——公共仓随调用方回退（codeSync ∥ docSync）展开覆盖
+  for (const root of declaredRootEntries(dir)) {
+    if ((await gitSyncDir(memory, root, opts)) !== null) continue // 增量可行 ⇒ 增量（per-origin 锚既有）
+    await codeSyncDir(memory, root, opts) // 增量不可行 ⇒ 全扫（同入口款）
+    const { syncDocRoot } = await import("./docs.mjs")
+    await syncDocRoot(memory, root, opts)
+  }
+  return res
+}
+
+/** 单根内胆（git 增量径）：原 `gitSync` 体——零语义改动。 */
+async function gitSyncDir(memory, dir, { onProgress } = {}) {
   const origin = normalizeOrigin(dir) // §6.11 写缝归一（git / 文件 I/O 用原样 dir；库面 origin 一律归一值）
+  const decl = loadProjectDeclaration(dir)
   const { execFile: _execFile } = await import("node:child_process")
   const { code: codeExts, doc: docExts } = indexExtensions(dir)
   const gitRun = (args) => new Promise((resolve, reject) => {
@@ -51,13 +65,15 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
   let head
   try { head = (await gitRun(["rev-parse", "HEAD"])).trim() } catch { return null }
 
-  const stored = memory.db.prepare(`SELECT value FROM meta WHERE key = 'last_indexed_commit'`).get()?.value
+  const stored = memory.db.prepare(`SELECT value FROM meta WHERE key = ?`).get(anchorKey(origin))?.value
   if (!stored) return null
 
   let diffOut
   try {
-    const committed = mergeDiff(await gitRun(["diff", "--name-only", "--diff-filter=ACMRTD", stored, "HEAD"]))
-    const dirty = mergeDiff(await gitRun(["diff", "--name-only", "--diff-filter=ACMRTD"]))
+    // §6.14 M2：`--relative`——diff 表收在 cwd 子树内且路径为 cwd 相对（与索引 path ∕ `codeSync` 同形；
+    // 无它则子目录 origin 下 `join(dir, rel)` 错位：真改动入删除支 ∕ 错内容入库 = 静默陈旧）。
+    const committed = mergeDiff(await gitRun(["diff", "--name-only", "--relative", "--diff-filter=ACMRTD", stored, "HEAD"]))
+    const dirty = mergeDiff(await gitRun(["diff", "--name-only", "--relative", "--diff-filter=ACMRTD"]))
     const lines = [...new Set([...committed, ...dirty])]
     diffOut = lines
   } catch {
@@ -66,9 +82,9 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
 
   if (diffOut.length > DIFF_FULL_SYNC_THRESHOLD) {
     // diff too large, incremental is useless — fall back to full sync and update anchor
-    await codeSync(memory, dir, { onProgress })
-    const { docSync } = await import("./docs.mjs")
-    await docSync(memory, dir, { onProgress })
+    await codeSyncDir(memory, dir, { onProgress })
+    const { syncDocRoot } = await import("./docs.mjs")
+    await syncDocRoot(memory, dir, { onProgress })
     return { updated: -1, removed: 0, skipped: 0, failed: 0, errors: [], fallback: true }
   }
 
@@ -79,7 +95,7 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
     const abs = join(dir, rel)
     const ext = extensionOf(rel)
 
-    if (isSkippedRelPath(rel)) continue
+    if (isSkippedRelPath(rel) || isExcludedRelPath(rel, decl, dir)) continue
 
     if (!codeExts.has(ext) && !docExts.has(ext)) { skipped++; continue }
 
@@ -115,8 +131,8 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
   }
 
   if (failed === 0) {
-    memory.db.prepare(`INSERT INTO meta (key, value) VALUES ('last_indexed_commit', ?)
-      ON CONFLICT (key) DO UPDATE SET value = excluded.value`).run(head)
+    memory.db.prepare(`INSERT INTO meta (key, value) VALUES (?, ?)
+      ON CONFLICT (key) DO UPDATE SET value = excluded.value`).run(anchorKey(origin), head)
   }
 
   onProgress?.({ phase: "done", total: diffOut.length, updated, removed, skipped, failed })
@@ -124,73 +140,19 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
 }
 
 /**
- * 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).
- * `truncated` = the non-git walk hit its file cap (capped trees are logged, never
- * silently indexed-partial). opts.maxFiles = the walk cap (test seam).
+ * §6.15 同步展开（写侧入口）：入口 dir + 声明公共仓逐根（一层不递归）；回执 = 入口根（契约零改）。
+ * 单根内胆 = `codeSyncDir`（原 `codeSync` 体——mtime 增量 + 行预算 + stale 收尾；opts seam 同 scan.mjs）。
  */
-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 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]), ...(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)) 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()
+export async function codeSync(memory, dir, opts = {}) {
+  const res = await codeSyncDir(memory, dir, opts)
+  for (const root of declaredRootEntries(dir)) await codeSyncDir(memory, root, opts)
+  return res
 }
 
-
-/**
- * Sync code index: scan all source files under dir → chunk → upsert into code_chunks.
- * Incremental by mtime — only rebuilds chunks for files that have changed.
- */
-export async function codeSync(memory, dir, { onProgress } = {}) {
+/** 单根内胆（code 全扫径）：原 `codeSync` 体——零语义改动。 */
+async function codeSyncDir(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 { code: exts } = indexExtensions(dir)
   const { entries, unlisted } = await listProjectFiles(dir, exts)
   const files = [] // { abs, rel, mtimeMs }
@@ -201,6 +163,8 @@ export async function codeSync(memory, dir, { onProgress } = {}) {
     if (st.size > MAX_CODE_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 code_chunks WHERE origin = ?`).all(origin).map((r) => [r.path, r.mtime_ms])
@@ -209,6 +173,11 @@ export async function codeSync(memory, dir, { onProgress } = {}) {
 
   onProgress?.({ phase: "scan", total: files.length, overSizeSkipped })
 
+  // §6.14 P2 行预算（基准 = 本 origin 库内行数 code+doc，开趟读一次；只停新增——存量行不失效；
+  // 跳过 = 不落行 ∕ 不记 mtime ⇒ 下趟重试）。WARN 一行可见（每趟至多一行）+ CAP 起跳过后列文件。
+  const budget = createRowBudget(memory, origin, "code", dir)
+  const budgetSkipped = []
+
   let updated = 0, removed = 0, skipped = 0, failed = 0
   const errors = []
   for (let i = 0; i < files.length; i++) {
@@ -219,12 +188,16 @@ export async function codeSync(memory, dir, { onProgress } = {}) {
       skipped++
       continue
     }
+    budget.note()
+    if (budget.over()) { budgetSkipped.push(rel); continue }
 
     try {
+      const before = rowCountOfPath(memory, "code_chunks", origin, rel)
       const text = await readFile(abs, "utf8")
       const lines = text.split("\n")
       const lang = detectLanguage(abs)
       _upsertCodeFile(memory, origin, rel, lines, lang, mtimeMs)
+      budget.add(rowCountOfPath(memory, "code_chunks", origin, rel) - before) // 净增行数——预算与「库内行数」同刻度
       updated++
     } catch (e) {
       failed++
@@ -237,154 +210,34 @@ export async function codeSync(memory, dir, { onProgress } = {}) {
     }
   }
 
-  for (const stale of indexed.keys()) {
-    if (!seen.has(stale)) {
-      memory.db.prepare(`DELETE FROM code_chunks WHERE origin = ? AND path = ?`).run(origin, stale)
-      removed++
-    }
-  }
+  // §6.14 B6 ∕ M3：收尾 stale 循环（同款让出 + 面① 收尾保护位）——机制单源 = `sync-tail.mjs`
+  removed = await sweepStaleRows(memory, { table: "code_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 维护口：模型键失配的失效**执行**（读面只判定降级——执行住同步尾；覆盖 /reindex ∕ 桌面 ∕ VSC 构建）
+  if (memory.embedder) { try { invalidateStaleEmbeddings(memory) } catch { /* 非阻塞 */ } }
+  await markIndexedCommit(memory, dir) // 锚推进 = 同步完成条件（§6.14 M1——原 fire-and-forget 竞态，T12 ∕ T14 判别面需确定性）
   if (unlisted.count > 0) {
     logEvent("index:unlisted", { dir, kind: "code", 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 }
 }
 
-/** Record current HEAD as the index anchor (gitSync incremental diff baseline); silently skip non-git repos */
+/** Record current HEAD as the index anchor (§6.14 M1: per-origin key `last_indexed_commit:<归一键>`); silently skip non-git repos */
 export async function markIndexedCommit(memory, dir) {
   try {
     const { execFile } = await import("node:child_process")
+    const origin = normalizeOrigin(dir)
     const head = await new Promise((resolve, reject) => {
       execFile("git", ["rev-parse", "HEAD"], { cwd: dir, encoding: "utf8", timeout: 5000, windowsHide: true }, (err, stdout) => {
         if (err) reject(err); else resolve(stdout)
       })
     })
-    memory.db.prepare(`INSERT INTO meta (key, value) VALUES ('last_indexed_commit', ?)
-      ON CONFLICT (key) DO UPDATE SET value = excluded.value`).run(head.trim())
+    memory.db.prepare(`INSERT INTO meta (key, value) VALUES (?, ?)
+      ON CONFLICT (key) DO UPDATE SET value = excluded.value`).run(anchorKey(origin), head.trim())
   } catch { /* not a git repo or git unavailable, skip */ }
 }
 
-/**
- * Code search: FTS5(BM25) + optional vector cosine, RRF merged.
- * Falls back to pure FTS when no embedder; falls back to pure vector when ftsQuery is empty and embedder is present.
- */
-export async function codeSearch(memory, query, { limit = 5 } = {}) {
-  const ftsQuery = buildFtsQuery(query)
-  if (!ftsQuery && !memory.embedder) return []
-
-  // §6.11 读缝归一（单点取名——函数体内一律用归一值）
-  const codeOrigin = normalizeOrigin(memory.codeOrigin)
-  const ftsOriginFilter = codeOrigin ? `AND c.origin = ?` : ""
-  const vecOriginFilter = codeOrigin ? `AND origin = ?` : ""
-  const originParams = codeOrigin ? [codeOrigin] : []
-
-  const ftsList = ftsQuery ? memory.db.prepare(`
-    SELECT c.rowid, c.path, c.language, c.symbol_name, c.content, c.line_start, c.line_end, bm25(code_chunks_fts) AS rank
-    FROM code_chunks_fts JOIN code_chunks c ON c.rowid = code_chunks_fts.rowid
-    WHERE code_chunks_fts MATCH ? ${ftsOriginFilter}
-    ORDER BY rank LIMIT ?
-  `).all(ftsQuery, ...originParams, Math.max(limit * 4, 20)) : []
-
-  if (!memory.embedder) return ftsList.slice(0, limit)
-
-  try { await ensureEmbeddings(memory) } catch (e) {
-    console.error(`[code] embedding ensure failed, falling back to FTS-only: ${e.message}`)
-    return ftsList.slice(0, limit)
-  }
-  let qvec
-  try { [qvec] = await embed(memory.embedder, [query]) } catch (e) {
-    console.error(`[code] query embedding failed, falling back to FTS-only: ${e.message}`)
-    return ftsList.slice(0, limit)
-  }
-  // 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 keyCols = cursorKey.join(", ")
-  const top = createTopK(Math.max(limit * 4, 20))
-  await scanVectors(memory.db, `SELECT rowid, ${keyCols}, embedding FROM code_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)) }),
-  })
-  const vecList = top.list().map((c) => ({ rowid: c.id, score: c.score }))
-
-  const K = 60
-  const scores = new Map()
-  ftsList.forEach((r, i) => scores.set(r.rowid, (scores.get(r.rowid) ?? 0) + 1 / (K + i + 1)))
-  vecList.forEach((r, i) => scores.set(r.rowid, (scores.get(r.rowid) ?? 0) + 1 / (K + i + 1)))
-
-  const fetchChunk = memory.db.prepare(`
-    SELECT path, language, symbol_name, content, line_start, line_end FROM code_chunks WHERE rowid = ?
-  `)
-  const sorted = [...scores.entries()]
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, limit)
-  return sorted
-    .map(([rowid, score]) => {
-      const chunk = fetchChunk.get(rowid)
-      if (!chunk) return null
-      chunk._score = Math.round(score * 100) / 100
-      return chunk
-    })
-    .filter(Boolean)
-}
-
-/** Lazily backfill missing vectors for code_chunks. Guarded against concurrent calls. */
-let _codeEmbedLock = null
-export function ensureCodeEmbeddings(memory) {
-  if (_codeEmbedLock) return _codeEmbedLock
-  _codeEmbedLock = _runEnsureCodeEmbeddings(memory).finally(() => { _codeEmbedLock = null })
-  return _codeEmbedLock
-}
-
-async function _runEnsureCodeEmbeddings(memory) {
-  if (!memory.embedder) return
-  const modelKey = memory.embedder.model
-  const stored = memory.db.prepare(`SELECT value FROM meta WHERE key = 'code_embedding_model'`).get()?.value
-  if (stored !== modelKey) {
-    memory.db.prepare(`UPDATE code_chunks SET embedding = NULL`).run()
-    memory.db.prepare(`INSERT INTO meta (key, value) VALUES ('code_embedding_model', ?)
-      ON CONFLICT (key) DO UPDATE SET value = excluded.value`).run(modelKey)
-  }
-
-  const pending = memory.db.prepare(`SELECT rowid, path, symbol_name, content FROM code_chunks WHERE embedding IS NULL LIMIT ${CODE_EMBED_BATCH}`).all()
-  if (pending.length === 0) return
-
-  const texts = pending.map((r) => `${r.path}${r.symbol_name ? " :: " + r.symbol_name : ""}\n${safeSliceUTF16(r.content, EMBED_TEXT_MAX_LEN)}`)
-  const vecs = await embed(memory.embedder, texts)
-
-  const update = memory.db.prepare(`UPDATE code_chunks SET embedding = ? WHERE rowid = ?`)
-  pending.forEach((r, i) => update.run(toBlob(vecs[i]), r.rowid))
-}
-
-/** Generate the code_search tool (read-only). */
-export function codeSearchTool(memory) {
-  return {
-    name: "code_search",
-    description:
-      "Search the project's source code for relevant code. Use this to find functions, classes, or code patterns across the codebase. Supports natural language queries and code snippets. Returns matching code chunks with file paths and line numbers. Prefer doc_search for the intended design (design docs, conventions); code_search for the implementation as written. " +
-      "For what was said in a session (conversation/chat history), use read_history.",
-    parameters: {
-      type: "object",
-      properties: {
-        query: { type: "string", description: "Natural language or code snippet to search for" },
-        limit: { type: "number", description: "Max results (default 5)" },
-      },
-      required: ["query"],
-    },
-    readonly: true,
-    async execute(args) {
-      const results = await codeSearch(memory, args.query, { limit: args.limit ?? 5 })
-      if (results.length === 0) return "(no matching code)"
-      return results.map((r) =>
-        `${r.path}${r.symbol_name ? ` :: ${r.symbol_name}` : ""} (L${r.line_start}-L${r.line_end}, relevance ${r._score?.toFixed(2) ?? "?"}):\n${r.content.slice(0, 2000)}`
-      ).join("\n\n---\n\n")
-    },
-  }
-}
-
 /**
  * Single-file incremental reindex: called after write/edit/delete, only rebuilds this one path.
  */
@@ -394,6 +247,7 @@ export async function reindexFile(memory, cwd, absPath) {
   const rel = relative(cwd, absPath).replaceAll("\\", "/")
   if (rel === ".." || rel.startsWith("../")) return
   if (isSkippedRelPath(rel)) return
+  if (isExcludedRelPath(rel, loadProjectDeclaration(cwd), cwd)) return // §6.14 面① 第三起效点（单文件缝零写）
   // Declared extensions count for the single-file path too (union with built-ins).
   const { code: codeExts, doc: docExts } = indexExtensions(cwd)
 
@@ -425,3 +279,8 @@ export async function reindexFile(memory, cwd, absPath) {
     try { await ensureEmbeddings(memory) } catch { /* embedding failure is non-blocking */ }
   }
 }
+
+// ─── 迁出面（2026-10-01 拆分批 · #755 ∥ #786）：检索面 → `memory/code-search.mjs`；清单面 →
+// `memory/file-list.mjs`——经本档转口保名（消费面 / 批内件 import 面零改），四起效点调用形零改。──────
+export { codeSearch, ensureCodeEmbeddings, codeSearchTool } from "./code-search.mjs"
+export { listProjectFiles, indexExtensions } from "./file-list.mjs"

package/memory/core.mjs

@@ -52,10 +52,15 @@ export async function search(memory, query, { limit = 5 } = {}) {
   if (!memory.embedder) return ftsList.slice(0, limit)
 
   // ---- vector channel ----
-  try { await ensureEmbeddings(memory) } catch (e) {
+  let ensured
+  try { ensured = await ensureEmbeddings(memory) } catch (e) {
     console.error(`[memory] embedding ensure failed, falling back to FTS-only: ${e.message}`)
     return ftsList.slice(0, limit)
   }
+  if (ensured?.mismatch) { // §6.14 B7 读面零写：模型键失配 ⇒ 本面向量通道降级 FTS-only + 一行可见（失效执行归维护口）
+    console.warn("[memory] embedding model mismatch — vector channel degraded to FTS-only this run (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(`[memory] query embedding failed, falling back to FTS-only: ${e.message}`)
@@ -143,7 +148,9 @@ export function fetchEntry(memory, uid) {
 
 /**
  * Lazy embedding: batch-compute vectors for entries that don't have them yet (slow first time, zero cost thereafter).
- * When the embedding model changes, clear all vectors and rebuild.
+ * When the embedding model changes the READ face performs ZERO writes (§6.14 B7): it only reports the
+ * mismatch back (`{ mismatch }`) so callers degrade to FTS-only; invalidation (clear + re-key) runs at
+ * the maintenance entry `invalidateStaleEmbeddings` (sync tail ∕ /reindex ∕ desktop ∕ VSC build).
  * Guarded by a module-level lock — concurrent fire-and-forget callers share the same promise,
  * so embedding API calls are never duplicated.
  */
@@ -157,39 +164,47 @@ export function ensureEmbeddings(memory) {
 async function _runEnsureEmbeddings(memory) {
   const modelKey = memory.embedder.model
   const stored = memory.db.prepare(`SELECT value FROM meta WHERE key = 'embedding_model'`).get()?.value
-  if (stored !== modelKey) {
-    // Invalidate all three tables + three meta keys in one go, to prevent stale vectors from dimension mismatch
-    memory.db.prepare(`UPDATE entries SET embedding = NULL`).run()
-    memory.db.prepare(`UPDATE files SET embedding = NULL`).run()
-    memory.db.prepare(`UPDATE code_chunks SET embedding = NULL`).run()
-    memory.db.prepare(`UPDATE doc_chunks SET embedding = NULL`).run()
-    const upsert = memory.db.prepare(`INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value`)
-    upsert.run("embedding_model", modelKey)
-    upsert.run("code_embedding_model", modelKey)
-    upsert.run("doc_embedding_model", modelKey)
+  // §6.14 B7 读面零写：失配 ⇒ **不执行**失效（不清向量 ∕ 不落键——执行归维护口）；本面回降级信号。
+  const mismatch = stored !== modelKey
+  if (!mismatch) {
+    const pendingEntries = memory.db.prepare(`SELECT id, title, content FROM entries WHERE embedding IS NULL LIMIT ${EMBED_BATCH_SIZE}`).all()
+    const pendingFiles = memory.db.prepare(`SELECT rowid, title, content FROM files WHERE embedding IS NULL LIMIT ${EMBED_BATCH_SIZE}`).all()
+    if (pendingEntries.length + pendingFiles.length > 0) {
+      const items = [...pendingEntries, ...pendingFiles]
+      const texts = items.map((r) => `${r.title}\n${safeSliceUTF16(r.content, EMBED_TEXT_MAX_LEN)}`)
+      const vecs = await embed(memory.embedder, texts)
+      const updateEntry = memory.db.prepare(`UPDATE entries SET embedding = ? WHERE id = ?`)
+      pendingEntries.forEach((r, i) => updateEntry.run(toBlob(vecs[i]), r.id))
+      const updateFile = memory.db.prepare(`UPDATE files SET embedding = ? WHERE rowid = ?`)
+      pendingFiles.forEach((r, i) => updateFile.run(toBlob(vecs[pendingEntries.length + i]), r.rowid))
+    }
   }
+  // 逐面判定 + 回填（code ∕ doc 面自持模型键——同判据；失配面同样零写回降级信号）
+  const { ensureCodeEmbeddings } = await import("./code-sync.mjs")
+  const { ensureDocEmbeddings } = await import("./docs.mjs")
+  const code = await ensureCodeEmbeddings(memory)
+  const doc = await ensureDocEmbeddings(memory)
+  return { mismatch, code: Boolean(code?.mismatch), doc: Boolean(doc?.mismatch) }
+}
 
-  const pendingEntries = memory.db.prepare(`SELECT id, title, content FROM entries WHERE embedding IS NULL LIMIT ${EMBED_BATCH_SIZE}`).all()
-  const pendingFiles = memory.db.prepare(`SELECT rowid, title, content FROM files WHERE embedding IS NULL LIMIT ${EMBED_BATCH_SIZE}`).all()
-  if (pendingEntries.length + pendingFiles.length === 0) {
-    // No pending memory entries — also backfill code and doc chunk vectors
-    await (await import("./code-sync.mjs")).ensureCodeEmbeddings(memory)
-    await (await import("./docs.mjs")).ensureDocEmbeddings(memory)
-    return
+/**
+ * 维护口失效**执行**（§6.14 B7 ∕ D-MEM25）：模型键失配的面 ⇒ 清该面向量 + 落键（一次性重写）。
+ * **读面禁调**（search ∕ codeSearch ∕ docSearch 只判定降级）；调用点 = 同步尾（codeSync ∕ docSync——
+ * 覆盖 /reindex ∕ 桌面 ∕ VSC 构建三条维护路径）。返回被清的面键（空数组 = 无失配，零写）。
+ */
+export function invalidateStaleEmbeddings(memory) {
+  if (!memory.embedder) return []
+  const modelKey = memory.embedder.model
+  const upsert = memory.db.prepare(`INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value`)
+  const faces = [["embedding_model", ["entries", "files"]], ["code_embedding_model", ["code_chunks"]], ["doc_embedding_model", ["doc_chunks"]]]
+  const invalidated = []
+  for (const [key, tables] of faces) {
+    if (memory.db.prepare(`SELECT value FROM meta WHERE key = ?`).get(key)?.value === modelKey) continue
+    for (const t of tables) memory.db.prepare(`UPDATE ${t} SET embedding = NULL`).run()
+    upsert.run(key, modelKey)
+    invalidated.push(key)
   }
-
-  const items = [...pendingEntries, ...pendingFiles]
-  const texts = items.map((r) => `${r.title}\n${safeSliceUTF16(r.content, EMBED_TEXT_MAX_LEN)}`)
-  const vecs = await embed(memory.embedder, texts)
-
-  const updateEntry = memory.db.prepare(`UPDATE entries SET embedding = ? WHERE id = ?`)
-  pendingEntries.forEach((r, i) => updateEntry.run(toBlob(vecs[i]), r.id))
-  const updateFile = memory.db.prepare(`UPDATE files SET embedding = ? WHERE rowid = ?`)
-  pendingFiles.forEach((r, i) => updateFile.run(toBlob(vecs[pendingEntries.length + i]), r.rowid))
-
-  // After each batch of embeddings, also backfill code and doc chunks
-  await (await import("./code-sync.mjs")).ensureCodeEmbeddings(memory)
-  await (await import("./docs.mjs")).ensureDocEmbeddings(memory)
+  return invalidated
 }
 
 /**