@thincoder/core 0.9.5 → 0.10.2

package/manifest.mjs

@@ -1,5 +1,5 @@
 /**
- * manifest.mjs — M1 项目状态档（ENGINEERING-MODE v2 基础模块）。
+ * manifest.mjs — M1 项目状态档（项目级状态账——工程模式是其**读侧消费者**之一）。
  * 权威设计 = docs/core/design/MANIFEST.md §2
  * （机制代码在核，操作对象 = 被开发项目 cwd 根的 PROJECT-MANIFEST.json 数据档）。
  *
@@ -8,7 +8,11 @@
  *    读 + validateManifest(obj)；缺键 → 产 missingKeys（非拒）→ 补默认值 →
  *    再校验通过；整档缺失 → { ok:false, reason:'missing' }（不静默 fallback）。
  *  - validateManifest(obj) → { ok, errors, missingKeys }：枚举 / version 数值 /
- *    docRoot 子键值形态（串 | 数组，F7）——**纯函数、零 fs**；不落盘。
+ *    docRoot 子键值形态（串 | 数组，F7）+ checkConfig.lineCounts 元素层形态——**纯函数、零 fs**；不落盘。
+ *  - 三族声明键（`codePaths` / `index.{codeExtensions,docExtensions,publicRepos}` / `advisor.{docMap,standardsDoc}`——
+ *    KD-M1-31 / M1-32）：缺键补默认；形态错 = 档非法（fail-closed，与 docRoot 子键同款）；
+ *    读向 = `declaration.mjs`（2026-10-01 自 `conventions.mjs` 迁出——经其转口可达）经 `readManifest` /
+ *    `manifestFilePath` 投影（单向——KD-M1-33）；`index.publicRepos` 绝对根集 = `declaredPublicRoots`（§6.15）。
  *  - isValidDocRootValue(value) / docRootPaths(value, cwd)（F7 判据单源 KD-M1-8）：值形态谓词
  *    + 值 → 绝对路径数组（展开 / trim + `\` 归一 / 基数 = 项目根 / 去重保序）。
  *  - requireManifest(cwd) → 装配钩子入口 = readManifest(cwd)。
@@ -18,10 +22,11 @@
  *  - owningProject(target) → 归属形单点（沿祖先链取**最近带档目录**——KD-M1-30）。
  *  - projectView(target) → { state, root, path, manifest?, candidates?, errors?, matched }：**按用点解析**
  *    的读侧单点（归属 ∨ 发现兜底 / 五态 / 非抛错 / **零写**——KD-M1-24）。
- *  - resolveProjectRoot(cwd) = owningProject(cwd) ?? discoverProjects(cwd).root（KD-M1-30）。
+ *  - resolveProjectRoot(cwd)：项目根（归属 ∨ 发现——KD-M1-30）= `projectRootView(cwd).root`（薄委托）；
+ *    projectRootView(cwd) → { state: ok|ambiguous|none, root, candidates }：歧义直读形（判定单点——§2.2）。
  *  - resolveEngineeringManifest(cwd, { writer, init }) → 入口决策树（**非抛错**——KD-M1-20）：
  *    两端入口钩子与翻转面（拒翻）共用同一张树（判据单源；§2.8 F1）——失败码五枚
- *    `missing` / `invalid` / `no-project` / `ambiguous` / `init-failed`（KD-M1-28）。
+ *    `missing` / `invalid` / `no-project` / `ambiguous` / `init-failed`（KD-M1-28）。名中 `Engineering` = 历史命名（沿用不改名）；消费面 = 两端入口钩子 + 翻转面——**非**「模式拥有本模块」。
  *  - manifestFilePath(cwd) → 数据档绝对路径（档路径单源 KD-M1-18——读 / 写 / mtime 门控三处同源）。
  *  - initManifest(cwd, { writer = 'subagent' } = {}) → 经写门写 DEFAULT_MANIFEST，缺省拒。
  *  - writeManifest(cwd, manifest, { writer = 'subagent' } = {}) → 落盘前先校验（ok:false 拒
@@ -30,114 +35,14 @@
  * N1 零依赖：仅 node:fs / node:path + 标准库 JSON.parse——无第三方解析器、无 node:sqlite。
  * N3 可迁移：本模块不硬编码任何本仓路径（docRoot / checkConfig 由被开发项目声明）。
  */
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
-import { dirname, join, resolve } from "node:path"
-
-/** 数据档文件名（**每个项目一份**——项目根 = 带档目录；**git 非前提**。2026-09-17 / 2026-09-21 用户裁定）。 */
-export const MANIFEST_REL = "PROJECT-MANIFEST.json"
-/** 测试注入：强制项目根（测试 tmp 非 git 仓——同 ledger `_setLedgerDirForTest` 先例）。 */
-let _projectRootOverride = null
-export function _setProjectRootForTest(dir) { _projectRootOverride = dir }
-export function _resetProjectRootForTest() { _projectRootOverride = null }
-
-/**
- * 一层扫描内核（**模块私有**——两条梯表共用；KD-M1-23 / 设计 §2.2「单源结构」）：枚举锚的
- * **直接子目录**一层（不递归）+ 按名排序 + 谓词过滤 ⇒ 命中表（绝对路径）。
- * 全档唯一 `readdirSync` 落点（结构机判 T54）；锚不可读 ⇒ `[]`（不抛——调用方按「零命中」处置）。
- * @param {string} anchor 锚绝对路径
- * @param {(dir:string)=>boolean} isHit 子目录谓词
- * @returns {string[]} 命中子目录绝对路径（按名排序）
- */
-function scanChildren(anchor, isHit) {
-  try {
-    return readdirSync(anchor, { withFileTypes: true })
-      .filter((e) => e.isDirectory())
-      .map((e) => e.name)
-      .sort()
-      .map((e) => join(anchor, e))
-      .filter(isHit)
-  } catch { return [] }
-}
-
-/**
- * **项目发现**（项目梯五级——KD-M1-23 / 设计 `docs/core/design/MANIFEST.md` §2.2；**git 非前提**，
- * 2026-09-21 用户裁定）：① 锚自身带 `MANIFEST_REL` ⇒ 锚；② 锚含 `.git` ⇒ 锚（缺档 = 建档机会）；
- * ③ 直接子目录中**带档**者优先（非空即只看此级：恰一 ⇒ `unique` / ≥2 ⇒ `ambiguous`）；
- * ④ 零带档才看含 `.git` 的**裸仓**（同判）；⑤ 均无 ⇒ `none`（⇒ 建档流，落点 = 会话锚）。
- * `candidates` 一律**按名排序**（`self` / `none` ⇒ `[]`）；`matched` ∈ `manifest` / `git` / `null`
- * 记命中（或歧义）出自哪一级。**纯 fs**（只判存在性——不解析档内容）· **不抛** · **不向上** · **不递归**。
- * **覆盖位**（`_setProjectRootForTest` 在场）⇒ **头部短路**（测试注入面——先于真判据，同 `discoverRepos`）。
- * @param {string} [cwd] 会话锚（缺省 → 进程 cwd）
- * @returns {{kind:'self'|'unique'|'none'|'ambiguous', root:string|null, candidates:string[], matched:'manifest'|'git'|null}}
- */
-export function discoverProjects(cwd) {
-  if (_projectRootOverride) return { kind: "self", root: resolve(_projectRootOverride), candidates: [], matched: null }
-  const anchor = resolve(cwd ?? ".")
-  if (existsSync(join(anchor, MANIFEST_REL))) return { kind: "self", root: anchor, candidates: [], matched: "manifest" }
-  if (existsSync(join(anchor, ".git"))) return { kind: "self", root: anchor, candidates: [], matched: "git" }
-  const withManifest = scanChildren(anchor, (d) => existsSync(join(d, MANIFEST_REL)))
-  if (withManifest.length > 1) return { kind: "ambiguous", root: null, candidates: withManifest, matched: "manifest" }
-  if (withManifest.length === 1) return { kind: "unique", root: withManifest[0], candidates: [...withManifest], matched: "manifest" }
-  const bareRepos = scanChildren(anchor, (d) => existsSync(join(d, ".git")))
-  if (bareRepos.length > 1) return { kind: "ambiguous", root: null, candidates: bareRepos, matched: "git" }
-  if (bareRepos.length === 1) return { kind: "unique", root: bareRepos[0], candidates: [...bareRepos], matched: "git" }
-  return { kind: "none", root: null, candidates: [], matched: null }
-}
-
-/**
- * **仓发现**（仓梯——KD-M1-23 / `docs/core/design/TOOLS.md` §6.13；**单源** KD-M1-22——`git` 工具
- * 经此符号接线，禁第二份实现）：① 锚含 `.git` ⇒ 锚；② 直接子目录中 `.git` **∧** 带档者恰一 ⇒ 命中
- * （≥2 ⇒ 歧义）；③ **零个此类时才看**含 `.git` 的裸仓（恰一 ⇒ 命中 / ≥2 ⇒ 歧义）；④ 均无 ⇒ `none`。
- * 与 `discoverProjects` = **同一 walk 内核**（`scanChildren`）的两种梯表——差异只在谓词与级序。
- * `candidates` 按名排序；`matched` 记档位；纯 fs / 不抛 / 不递归 / 不向上；覆盖位 ⇒ 头部短路。
- * @param {string} [cwd] 会话锚（缺省 → 进程 cwd）
- * @returns {{kind:'self'|'unique'|'none'|'ambiguous', root:string|null, candidates:string[], matched:'manifest'|'git'|null}}
- */
-export function discoverRepos(cwd) {
-  if (_projectRootOverride) return { kind: "self", root: resolve(_projectRootOverride), candidates: [], matched: null }
-  const anchor = resolve(cwd ?? ".")
-  if (existsSync(join(anchor, ".git"))) return { kind: "self", root: anchor, candidates: [], matched: "git" }
-  const scoped = scanChildren(anchor, (d) => existsSync(join(d, ".git")) && existsSync(join(d, MANIFEST_REL)))
-  if (scoped.length > 1) return { kind: "ambiguous", root: null, candidates: scoped, matched: "manifest" }
-  if (scoped.length === 1) return { kind: "unique", root: scoped[0], candidates: [...scoped], matched: "manifest" }
-  const bare = scanChildren(anchor, (d) => existsSync(join(d, ".git")))
-  if (bare.length > 1) return { kind: "ambiguous", root: null, candidates: bare, matched: "git" }
-  if (bare.length === 1) return { kind: "unique", root: bare[0], candidates: [...bare], matched: "git" }
-  return { kind: "none", root: null, candidates: [], matched: null }
-}
-
-/**
- * **归属形单点**（KD-M1-30 / 设计 §2.9 A——2026-09-21 用户裁定「最近者优先」）：自 `target`
- * （目录含自身；文件路径自其父目录起）沿**祖先链**逐级上溯至盘根，取**最近**带 `MANIFEST_REL`
- * 的目录；无 ⇒ `null`（⇒ 调用方走发现兜底）。**嵌套合法**：子内归子、根其余归根。
- * **纯 fs**（只判存在性——不解析档内容 / 不问模式）· **不跨兄弟** · **无全局优先级**。
- * **覆盖位**（`_setProjectRootForTest` 在场）⇒ **头部短路**：直接返回覆盖值（不查档存在性——
- * 保「覆盖即覆盖值」语义，回归守卫 = `test/manifest.test.mjs` T42 覆盖断言）。
- * @param {string} [target] 目标路径（目录 / 文件）
- * @returns {string|null} 最近带档祖先目录绝对路径 / null
- */
-export function owningProject(target) {
-  if (_projectRootOverride) return resolve(_projectRootOverride)
-  let dir = resolve(target ?? ".")
-  for (;;) {
-    if (existsSync(join(dir, MANIFEST_REL))) return dir
-    const parent = dirname(dir)
-    if (parent === dir) return null // 盘根 → 祖先链无档
-    dir = parent
-  }
-}
-
-/**
- * 项目根解析（**归属 ∨ 发现**——KD-M1-30 / M1-24）：`owningProject(cwd) ?? discoverProjects(cwd).root`。
- * 带档路径与批前**逐字同**；变更面两条（设计 §2.2）：① 项目树内路径（祖先带档）⇒ **该项目根**
- * （批前回落 `resolve(cwd)`——错层建档面，本批修）；② 裸仓恰一 ⇒ 该仓根（零档降级 = 建档机会）。
- * `none` / `ambiguous` ⇒ `null`。调用方（`manifestFilePath` / `docRootBase` / `ledger-db.mjs` /
- * `ledger-cmd.mjs`）**零改**（行为随语义变更——设计 §2.5 键面条 / 错层条）。
- * @returns {string|null} 项目根绝对路径 / null
- */
-export function resolveProjectRoot(cwd) {
-  return owningProject(cwd) ?? discoverProjects(cwd).root
-}
+import { readFileSync, writeFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { DEFAULT_MANIFEST, isValidDocRootValue, validateManifest, fillDefaults } from "./manifest-schema.mjs"
+import { MANIFEST_REL, discoverProjects, owningProject, resolveProjectRoot } from "./manifest-discovery.mjs"
+// 同名 re-export（2026-09-29 structure-split-2 · 台账 #620——缝 = 同名再出口）：发现 ∕ 归属族与校验 ∕ 默认值族出档
+// `manifest-discovery.mjs` ∕ `manifest-schema.mjs`；全迁移导出经本档转口——消费者 import 面零改。
+export { MANIFEST_REL, discoverProjects, discoverRepos, owningProject, projectRootView, resolveProjectRoot, _setProjectRootForTest, _resetProjectRootForTest } from "./manifest-discovery.mjs"
+export { DEFAULT_MANIFEST, MANIFEST_SCHEMA, isValidDocRootValue, validateManifest } from "./manifest-schema.mjs"
 
 /**
  * **按用点解析**的读侧单点（KD-M1-24 / M1-30——**非抛错 / 零写 / 无缓存**）：两段合成——
@@ -188,19 +93,6 @@ export function docRootBase(cwd) {
   return resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")
 }
 
-/**
- * `docRoot` 子键**值形态判据**（F7 / KD-M1-6 / KD-M1-8——判据单源）：非空字符串（`trim` 后
- * 非空），或非空数组且元素皆非空字符串（**同款口径**：元素 `trim` 后非空）；其余（空串 /
- * 空白串 / 空数组 / 数组含非串 / 空串 / 空白串元素 / 非串非数组）为非法。
- * @param {unknown} value docRoot 某子键的值
- * @returns {boolean}
- */
-export function isValidDocRootValue(value) {
-  if (typeof value === "string") return value.trim() !== ""
-  if (!Array.isArray(value) || value.length === 0) return false
-  return value.every((p) => typeof p === "string" && p.trim() !== "")
-}
-
 /**
  * `docRoot` 子键值 → **绝对路径数组**（F7 / §2.7 解析管线——全在本模块一处）：展开（串 /
  * 数组统一成列表）→ 逐元素 `trim` + `\` 归一 → `resolve(docRootBase(cwd), p)`（基数 =
@@ -234,97 +126,6 @@ export function manifestFilePath(cwd) {
   return join(writeRoot(cwd), MANIFEST_REL)
 }
 
-/** 默认五键（架构 §2.3 E1 逐字）——整档初始化的写源与缺键 fallback 的补源。 */
-export const DEFAULT_MANIFEST = Object.freeze({
-  version: 1,
-  phase: "initial-dev",
-  docRoot: Object.freeze({
-    requirements: "docs/requirements",
-    specs: "docs/requirements/specs",
-    design: "docs/design",
-    modules: "docs/design/modules",
-    batches: "docs/batches",
-  }),
-  promptsLanding: "thincoder-core/prompts",
-  checkConfig: Object.freeze({
-    scanDirs: Object.freeze(["docs"]),
-    lineWidth: 300,
-    anchors: Object.freeze({ domain: "docs", exclude: Object.freeze(["_archive", "batches"]) }),
-    exemptions: Object.freeze([]),
-  }),
-})
-
-/** 校验判据（模块设计 §2.2）——枚举 / 键存在（fallback 用）；判据单源（KD-M1-4）。 */
-export const MANIFEST_SCHEMA = Object.freeze({
-  $anchor: "docs/core/design/MANIFEST.md",
-  enum: Object.freeze({
-    phase: Object.freeze(["initial-dev", "production"]),
-  }),
-  keys: Object.freeze(Object.keys(DEFAULT_MANIFEST)),
-  nestedKeys: Object.freeze({
-    docRoot: Object.freeze(Object.keys(DEFAULT_MANIFEST.docRoot)),
-    checkConfig: Object.freeze(Object.keys(DEFAULT_MANIFEST.checkConfig)),
-  }),
-})
-
-/**
- * 形状校验（模块设计 §2.2）——枚举 / version 数值恒做；**纯函数、零 fs**（原 `{ cwd }`
- * 指针腿已随字段整链裁撤——KD-M1-5 墓志）；不落盘。键存在性入 missingKeys（非拒）：
- * 缺键 = 便利 fallback（补默认值），不是错（与整档缺失两分——KD-M1-2）。
- * @param {object} obj 待校验 manifest 对象
- * @returns {{ok:boolean, errors:string[], missingKeys:string[]}}
- */
-export function validateManifest(obj) {
-  const errors = []
-  const missingKeys = []
-  if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
-    return { ok: false, errors: ["manifest 顶层必须是 JSON 对象"], missingKeys }
-  }
-  for (const key of MANIFEST_SCHEMA.keys) {
-    if (!(key in obj)) missingKeys.push(key)
-  }
-  for (const [nested, subkeys] of Object.entries(MANIFEST_SCHEMA.nestedKeys)) {
-    const value = obj[nested]
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-      missingKeys.push(nested) // 整键缺失/非对象 → 与整键缺同语义（整键补默认）
-      continue
-    }
-    for (const sub of subkeys) {
-      if (!(sub in value)) { missingKeys.push(`${nested}.${sub}`); continue } // 子键路径（AC-3 / T3b）
-      // docRoot 子键值形态（F7 / KD-M1-7）：串 | 非空串数组；非法 → 拒（不静默跳过）。
-      if (nested === "docRoot" && !isValidDocRootValue(value[sub])) {
-        errors.push(`docRoot.${sub} 值形态非法：${JSON.stringify(value[sub])}（须为非空字符串或非空字符串数组——KD-M1-6 / KD-M1-7）`)
-      }
-    }
-  }
-  if (obj.phase !== undefined && !MANIFEST_SCHEMA.enum.phase.includes(obj.phase)) {
-    errors.push(`phase 取值非法："${obj.phase}"（允许：${MANIFEST_SCHEMA.enum.phase.join(" | ")}）`)
-  }
-  if (obj.version !== undefined && (typeof obj.version !== "number" || !Number.isFinite(obj.version))) {
-    errors.push(`version 非法：${JSON.stringify(obj.version)}（须为数值）`)
-  }
-  return { ok: errors.length === 0, errors, missingKeys }
-}
-
-/** 缺键补默认值（module 设计 §2.2 管线）：顶层缺键补默认、docRoot/checkConfig 子键补默认
- *  （与整键缺同语义）；不覆写既有值。深拷贝默认源（structuredClone）——冻结常量永不外泄引用。 */
-function fillDefaults(obj) {
-  const out = structuredClone(DEFAULT_MANIFEST)
-  for (const key of MANIFEST_SCHEMA.keys) {
-    if (!(key in obj)) continue
-    if (key === "docRoot" || key === "checkConfig") {
-      const src = obj[key]
-      if (src === null || typeof src !== "object" || Array.isArray(src)) continue // 整键非对象 → 保持默认
-      for (const sub of Object.keys(out[key])) {
-        if (sub in src) out[key][sub] = src[sub]
-      }
-    } else {
-      out[key] = obj[key]
-    }
-  }
-  return out
-}
-
 /**
  * 读 cwd 根数据档（模块设计 §2.2）：读 + validateManifest(obj) → 缺键产
  * missingKeys（非拒）→ 补默认值 → 再校验通过。整档缺失 → { ok:false, reason:'missing' }
@@ -440,7 +241,7 @@ export function writeManifest(cwd, manifest, { writer = "subagent" } = {}) {
 }
 
 /**
- * 初始化 = 写默认五键档（模块设计 §2.2）：只提供机制，不包交互问答（问答归壳面）。
+ * 初始化 = 写默认八键档（模块设计 §2.2）：只提供机制，不包交互问答（问答归壳面）。
  * 落盘走同一写门（内部 writeManifest(cwd, DEFAULT_MANIFEST, { writer })）——与 AC-M1-5
  * 同一闸，无第二条写路径（KD-M1-4 / 评审 #12）。
  * @returns {object} 写入的默认 manifest

package/mcp.mjs

@@ -6,6 +6,7 @@ import { INIT_TIMEOUT_MS, withTimeout, sanitizeToolName } from "./mcp/helpers.mj
 import { stdioTransport } from "./mcp/transport-stdio.mjs"
 import { httpTransport } from "./mcp/transport-http.mjs"
 import { wsTransport } from "./mcp/transport-ws.mjs"
+import { resolveMcpServerSecrets } from "./env-ref.mjs"
 
 /** F6/D-5：config.token → `Authorization: Bearer <token>` 合成（仅当 headers 未显式给
  *  Authorization——显式优先，向后兼容）。合成发生在传给 transport 前，不写回 config。 */
@@ -52,7 +53,9 @@ export const _mcpHooks = {
 
 /** 按 config 创建并完成握手的 transport（findTransportConfig 与 vscode 对齐）。 */
 async function createConnectedTransport(rawConfig, serverName) {
-  const config = withBearerToken(rawConfig) // F6/D-5：token 合成（不写回原 config）
+  // #57（provider-config-family 批）：值位 `${env:VAR}` 消费侧解析（CONFIG.md §6.3）——传输建连单点
+  // （connect ∕ probe ∕ 重连同享）；指纹 ∕ 漂移比对仍按存储原文（connectMcpServer 的 configFingerprint 零改）。
+  const config = withBearerToken(resolveMcpServerSecrets(rawConfig)) // F6/D-5：token 合成（不写回原 config）
   let transport
   if (config.wsUrl) {
     transport = wsTransport(config.wsUrl, config.headers ?? {})

package/memory/code-search.mjs

@@ -0,0 +1,149 @@
+/**
+ * memory/code-search.mjs — 代码检索面（自 `memory/code-sync.mjs` 迁出 · 2026-10-01 core 拆分批 #755 ∥ #786）。
+ * 内容 = `CODE_EMBED_BATCH` ∥ `codeSearch`（FTS5(BM25) + 向量余弦，RRF 合并；无 embedder ⇒ 纯 FTS，
+ * ftsQuery 空且有 embedder ⇒ 纯向量）∥ `ensureCodeEmbeddings`（并发锁 + `_runEnsureCodeEmbeddings`）
+ * ∥ `codeSearchTool`——迁出块逐字；原档 `memory/code-sync.mjs` 经 `export { … } from` 转口保名
+ * （消费面 / 批内件 import 面零改）。
+ */
+import { embed, cosine, toBlob, fromBlob } from "../embedding.mjs"
+import { scanVectors, createTopK } from "./scan.mjs"
+import { normalizeOrigin } from "./origin.mjs"
+import { declaredPublicRoots } from "../conventions.mjs"
+import { buildFtsQuery, ensureEmbeddings, EMBED_TEXT_MAX_LEN } from "./core.mjs"
+import { safeSliceUTF16 } from "../text-budget.mjs"
+import { DESC } from "../tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/code_search.md
+
+const CODE_EMBED_BATCH = 64
+
+/** 读面 origin 集（§6.15）：项目 origin ∪ 声明公共仓 origin（归一 ∥ 去重 ∥ 升序——BINARY 序 = PK 序；趟序 ∕ 到达序无关）；无项目 ⇒ 空集。 */
+export function searchOrigins(memory) {
+  const project = normalizeOrigin(memory.codeOrigin)
+  if (!project) return []
+  const set = new Set([project, ...declaredPublicRoots(memory.codeOrigin).map((p) => normalizeOrigin(p))])
+  return [...set].sort((a, b) => Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8")))
+}
+
+/**
+ * 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.15 读面 origin 集（项目 ∪ 声明公共仓；单 origin ⇒ 逐字零行为——快径 SQL 形零改）
+  const origins = searchOrigins(memory)
+  const ftsOriginFilter = origins.length === 1 ? `AND c.origin = ?` : origins.length > 1 ? `AND c.origin IN (${origins.map(() => "?").join(", ")})` : ""
+  const originParams = origins
+
+  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)
+
+  let ensured
+  try { ensured = await ensureEmbeddings(memory) } catch (e) {
+    console.error(`[code] embedding ensure failed, falling back to FTS-only: ${e.message}`)
+    return ftsList.slice(0, limit)
+  }
+  if (ensured?.code) { // §6.14 B7 读面零写：模型键失配 ⇒ 本面向量通道降级 FTS-only（一行可见；失效执行归维护口）
+    console.warn("[code] 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(`[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 = origins.length > 0 ? ["path", "line_start"] : ["origin", "path", "line_start"]
+  const keyCols = cursorKey.join(", ")
+  const top = createTopK(Math.max(limit * 4, 20))
+  // §6.15 多 origin ⇒ 逐 origin 分趟（每趟单 origin 等值 + 游标键去等值前缀列——与单 origin 快径同形）
+  const vecSql = `SELECT rowid, ${keyCols}, embedding FROM code_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
+  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) {
+    // §6.14 B7 读面零写：只判定（返回降级信号——调用方 FTS-only + 一行可见）；失效**执行**
+    // （清向量 + 落键）归维护口 `invalidateStaleEmbeddings`（同步尾 ∕ /reindex ∕ 桌面 ∕ VSC）。
+    return { mismatch: true }
+  }
+
+  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: DESC("code_search"), // #15 外置：文本单点 = tool-docs/code_search.md
+    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")
+    },
+  }
+}