@thincoder/core 0.9.4 → 0.10.1

package/memory/memory-tool.mjs

@@ -0,0 +1,229 @@
+/**
+ * memory/memory-tool.mjs — memory agent 工具面（自 `memory/docs.mjs` 迁出 · 2026-10-01 core 拆分批 #755 ∥ #786）。
+ * 内容 = `MEMORY_ACTIONS` ∥ `MEMORY_LAYERS` ∥ 校验 / 格式化小件 ∥ `memoryTools`（单一 `memory` 工具，
+ * 五 action）+ 各 action 执行器（`execSearch` / `execPut` / `execList` / `execDelete` / `execDeleteSingle`
+ * / `execClear`）——迁出块逐字；原档 `memory/docs.mjs` 经 `export { … } from` 转口保名
+ * （消费链 `memory.mjs → docs.mjs → memory-tool.mjs` 零改）。
+ */
+import { isAbsolute, join } from "node:path"
+import { put, search, putMarkdown, clearPersonal } from "./core.mjs"
+import { deleteByUid, matchMemoryRows, deleteWhere } from "./delete.mjs"
+import { commitAndPush } from "../git/gitmem.mjs"
+import { DESC } from "../tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/memory.md
+
+// ---------------------------------------------------------------- agent tools
+
+/** §6 shared tool surface — action enum / parameter shapes / output contract shared with the
+ *  VS Code face (`thincoder-vscode/src/memory-tool.mjs`); the description is a per-end form —
+ *  core text lives in `tool-docs/memory.md` (DESC() load; #15 外置). 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"]
+
+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
+}
+
+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: DESC("memory"), // #15 外置：文本单点 = tool-docs/memory.md
+      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/schema.mjs

@@ -15,13 +15,18 @@ import { segmentCJK } from "../fts-text.mjs"
 export { segmentCJK } from "../fts-text.mjs"
 
 export const VALID_TYPES = new Set(["rule", "knowledge", "decision", "pattern"])
-export const SCHEMA_VERSION = 9
+export const SCHEMA_VERSION = 10
 export const SQLITE_BUSY_TIMEOUT = 3000
 /** WAL 回收后的文件截断上界（§6.12 修法①——防复胀；实测曾达 587 MB）。 */
 export const WAL_SIZE_LIMIT_BYTES = 64 * 1024 * 1024
 
+/** 索引行预算（§6.14 面③ P2——每 origin 库内行数 code+doc 合计）：WARN 线出**一行**可见警示
+ *  （≈0.5 s 趟量级）；CAP 线起同步跳过后列文件（只停新增——存量行不失效）。B3 ∕ B4 复用 WARN 值。 */
+export const INDEX_ORIGIN_ROW_WARN = 20000
+export const INDEX_ORIGIN_ROW_CAP = 100000
+
 // Code index: source file extensions. Curated DEFAULTS — a project can declare
-// more (union) through .thincoder/conventions.json → index.codeExtensions
+// more (union) through PROJECT-MANIFEST.json → index.codeExtensions
 // (PORTABILITY PO-9: an unlisted extension used to be invisible AND undeclarable).
 export const CODE_EXTS = new Set([
   ".mjs", ".js", ".cjs", ".mts", ".cts", ".ts", ".tsx", ".jsx",
@@ -87,7 +92,7 @@ export function createMemory({ dbPath }) {
   `)
 
   migrate(db)
-  return { db }
+  return { db, dbPath }
 }
 
 /** Step-by-step migration by user_version. Single transaction — any step failure rolls back, no half-finished schema left behind. */
@@ -445,6 +450,16 @@ export function migrate(db) {
     `)
     db.exec(`PRAGMA user_version = 9`)
   }
+  if (version < 10) {
+    // v10: 每回合 embedding 回填探针（B2）的部分索引——`WHERE embedding IS NULL` 改走 seek（原无索引全表扫）。
+    // 键列 = `embedding`（**`rowid` 不可作索引键列**——D-MEM22 本机实测 `no such column: rowid`）。
+    // 只增索引（无表结构 ∕ 行级变更）；探针调用点 SQL 形不变（计划改走索引——预期 `SEARCH … USING INDEX`）。
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS code_chunks_embedding_null ON code_chunks(embedding) WHERE embedding IS NULL;
+      CREATE INDEX IF NOT EXISTS doc_chunks_embedding_null ON doc_chunks(embedding) WHERE embedding IS NULL;
+    `)
+    db.exec(`PRAGMA user_version = 10`)
+  }
   db.exec("COMMIT")
   } catch (err) {
     db.exec("ROLLBACK")

package/memory/sweep.mjs

@@ -0,0 +1,289 @@
+/**
+ * memory/sweep.mjs — origin 级库治理（命令面 + 安全设计 · MEMORY.md §6.13 · 台账 #175 · 2026-09-25）。
+ *
+ * 命令面（CLI 壳 = `thincoder-cli/src/cli/memory-command.mjs`）：`thincoder memory sweep [--origin <o>] [--path <sub>] [--dry-run|--confirm]`。
+ * 两档判据（单源 = §6.13——本档不另立规则）：
+ *   · **全扫（缺省）** = 信号 A 折叠（`normalizeOrigin(o) !== o` ⇒ 并入归一形，**不删**）+ 信号 B 删除
+ *     （**树亡** = 原样 / 归一形两路径皆 ENOENT ⇒ 可删）；
+ *   · **`--origin` 档** = 靶向整档删除（显式点名 ≠ 树亡推断——不以树存活为判据、不走信号 A/B）：
+ *     范围 = 三表内 `normalizeOrigin(origin) = normalizeOrigin(<o>)` 的全部行（非归一变体随删；活树亦可整删）。
+ *   · **`--path` 档**（§6.14 面①-3 存量剪枝——须与 `--origin` 同用）：删除范围收窄至 `path` 前缀命中行
+ *     （恰等 ∨ 后随 `/`——与 `index.excludePaths` 同语义；code ∕ doc 两表，`files` 表不涉）。
+ * 安全三件（§6.13）：① **备份前置**（`VACUUM INTO <dbPath>.sweep-backup-<UTC yyyymmddHHMMSS>`，
+ * 判据 = 存在 ∧ 大小 > 0 ∧ `PRAGMA integrity_check` = ok；目标已存在 / 判据不过 ⇒ **中止零写**）；
+ * ② **干跑默认**（`--confirm` 才写；零写判据 = 库字节 / 行数不变）；③ **审计**（逐 origin 动作 + 计数 +
+ * 折叠映射 + 备份路径 + 写后回读判据）。
+ * **折叠规则单源 = §6.11 步 2**（同归一键内 `(path, line_start)`（`files` = `(layer, path)`）恰一行——
+ * 保留 `mtime_ms` 最大者，并列取 `rowid` 最小者；FTS 由既有触发器随行同步）。
+ * 探针 fail-safe：**仅 ENOENT 判亡**，其余错误（权限 / 非法路径）⇒ 保留（先例 `session-stale.mjs:124-127`）。
+ * 执行分工：真实库写 = 父侧 ops；本档只在传入的库句柄上作业，写闸 = `confirm` 单一入参。
+ */
+import { existsSync, statSync } from "node:fs"
+import { DatabaseSync } from "node:sqlite"
+import { normalizeOrigin } from "./origin.mjs"
+
+/** 面表（§6.13 面表）：三表 + 各表折叠唯一键（`files` 无 `line_start`——PK = (layer, origin, path)）。 */
+const TABLES = [
+  { key: "code", table: "code_chunks", dup: ["path", "line_start"] },
+  { key: "doc", table: "doc_chunks", dup: ["path", "line_start"] },
+  { key: "files", table: "files", dup: ["layer", "path"] },
+]
+const KEYS = TABLES.map((t) => t.key)
+const emptyCounts = () => ({ code: 0, doc: 0, files: 0 })
+const totalOf = (c) => c.code + c.doc + c.files
+
+/** 树存活探针（信号 B 单源）：`statSync` 成功 ⇒ "alive"；**仅 ENOENT** ⇒ "dead"；其余错误 ⇒ "unknown"。 */
+export function probeOriginPath(p) {
+  try { statSync(p); return "alive" } catch (e) { return e?.code === "ENOENT" ? "dead" : "unknown" }
+}
+
+/** 双路径树读数（原样 + 归一形）：alive 优先；两路径皆死才判亡；任一探针错误 ⇒ unknown（保留）。 */
+function treeState(o) {
+  const a = probeOriginPath(o), b = probeOriginPath(normalizeOrigin(o))
+  return { alive: a === "alive" || b === "alive", dead: a === "dead" && b === "dead", unknown: a === "unknown" || b === "unknown" }
+}
+
+/** 逐（原样 origin）行数：Map<origin, { code, doc, files }>——三表并集。 */
+function originCounts(db) {
+  const map = new Map()
+  for (const { key, table } of TABLES) {
+    for (const r of db.prepare(`SELECT origin, COUNT(*) AS n FROM ${table} GROUP BY origin`).all()) {
+      const cur = map.get(r.origin) ?? emptyCounts()
+      cur[key] = Number(r.n)
+      map.set(r.origin, cur)
+    }
+  }
+  return map
+}
+
+const ACTION_RANK = { delete: 0, fold: 1, keep: 2 }
+
+/** `--path` 前缀归一（与 `index.excludePaths` 同款：trim ∕ `\`→`/` ∕ 首部 `./` 剥离 ∕ 去尾斜杠）。 */
+function normalizePrefix(p) {
+  const s = String(p ?? "").trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "")
+  if (!s) throw new Error("memory sweep: `--path` 需要一个非空前缀")
+  return s
+}
+
+/** 前缀命中行数（恰等 ∨ 后随 `/`——与 §6.14 面① 谓词同语义；raws = 归入目标键的原样键集）。 */
+function pathHitCount(db, table, raws, sub) {
+  if (raws.length === 0) return 0
+  const ph = raws.map(() => "?").join(", ")
+  const { n } = db.prepare(`SELECT COUNT(*) AS n FROM ${table} WHERE origin IN (${ph}) AND (path = ? OR substr(path, 1, ?) = ?)`).get(...raws, sub, sub.length + 1, `${sub}/`)
+  return Number(n ?? 0)
+}
+
+/**
+ * 干跑计划（**零写**）。row = { origin（归一形）, raws（归入本键的原样键集）, foldFrom（信号 A 的原样键）,
+ * alive, unknown, action, code / doc / files / total }。
+ * 动作三态：`fold`（信号 A）/ `delete`（信号 B 树亡，或 `--origin` 档显式点名）/ `keep`（其余）。
+ */
+export function planSweep(memory, { origin = null, path = null } = {}) {
+  if (path !== null && origin === null) throw new Error("memory sweep: `--path` 须与 `--origin` 同用")
+  const counts = originCounts(memory.db)
+  const sub = path === null ? null : normalizePrefix(path)
+  const rows = []
+  if (origin !== null) {
+    const target = normalizeOrigin(origin)
+    const raws = [...counts.keys()].filter((o) => normalizeOrigin(o) === target)
+    const agg = emptyCounts()
+    if (sub === null) {
+      for (const o of raws) for (const k of KEYS) agg[k] += counts.get(o)[k]
+    } else {
+      // §6.14 面①-3：`--path` 档——计数收窄至两表前缀命中行（files 表不涉——记忆层非项目文件）
+      agg.code = pathHitCount(memory.db, "code_chunks", raws, sub)
+      agg.doc = pathHitCount(memory.db, "doc_chunks", raws, sub)
+    }
+    const state = treeState(target)
+    rows.push({
+      origin: target, raws, foldFrom: null, alive: state.alive, unknown: state.unknown,
+      action: totalOf(agg) > 0 ? "delete" : "keep", ...agg, total: totalOf(agg),
+    })
+  } else {
+    for (const [o, c] of counts) {
+      const norm = normalizeOrigin(o)
+      const state = treeState(o)
+      const variant = norm !== o
+      rows.push({
+        origin: norm, raws: [o], foldFrom: variant ? o : null, alive: state.alive, unknown: state.unknown,
+        action: variant ? "fold" : state.dead ? "delete" : "keep", ...c, total: totalOf(c),
+      })
+    }
+    rows.sort((a, b) => ACTION_RANK[a.action] - ACTION_RANK[b.action] || (a.origin < b.origin ? -1 : a.origin > b.origin ? 1 : 0))
+  }
+  const totals = emptyCounts()
+  for (const r of rows) for (const k of KEYS) totals[k] += r[k]
+  totals.total = totalOf(totals)
+  return { mode: origin !== null ? "origin" : "full", target: origin !== null ? normalizeOrigin(origin) : null, path: sub, rows, totals }
+}
+
+/** 备份路径（§6.13）：`<dbPath>.sweep-backup-<UTC yyyymmddHHMMSS>`（同目录）。 */
+export function backupPathFor(dbPath, now = new Date()) {
+  const p = (n) => String(n).padStart(2, "0")
+  const stamp = `${now.getUTCFullYear()}${p(now.getUTCMonth() + 1)}${p(now.getUTCDate())}${p(now.getUTCHours())}${p(now.getUTCMinutes())}${p(now.getUTCSeconds())}`
+  return `${dbPath}.sweep-backup-${stamp}`
+}
+
+/**
+ * 备份前置（`--confirm` 档且命中 > 0）：`VACUUM INTO` + 判据（存在 ∧ 大小 > 0 ∧ `integrity_check` = ok）。
+ * 目标已存在 / 判据不过 ⇒ 抛错（调用方在**任何写之前**收到 ⇒ 零写）。返回备份路径。
+ */
+function takeBackup(db, path) {
+  if (existsSync(path)) throw new Error(`memory sweep: backup target already exists (${path}) — aborted with zero writes`)
+  db.exec(`VACUUM INTO '${path.replaceAll("'", "''")}'`)
+  if (!existsSync(path) || statSync(path).size <= 0) throw new Error(`memory sweep: backup judgment failed (missing or empty: ${path}) — aborted with zero writes`)
+  const bdb = new DatabaseSync(path, { readOnly: true })
+  try {
+    const row = bdb.prepare("PRAGMA integrity_check").get()
+    if (Object.values(row ?? {})[0] !== "ok") throw new Error(`memory sweep: backup judgment failed (integrity_check ≠ ok: ${path}) — aborted with zero writes`)
+  } finally { bdb.close() }
+  return path
+}
+
+/** 单键折叠（§6.11 步 2 逐字口径）：同 (dup) 组恰一行——保留 `mtime_ms` 最大者、并列取 `rowid` 最小者。
+ *  先删非胜者、再改胜者 origin（PK 复用无冲突）；返回触碰行数（删除 + 改键）。 */
+function foldKey(db, key, raws) {
+  let touched = 0
+  const ph = raws.map(() => "?").join(", ")
+  for (const { table, dup } of TABLES) {
+    const rows = db.prepare(`SELECT rowid, ${dup.join(", ")}, mtime_ms FROM ${table} WHERE origin IN (${ph})`).all(...raws)
+    if (rows.length === 0) continue
+    const gk = (r) => dup.map((c) => String(r[c])).join("\u0001")
+    const best = new Map()
+    for (const r of rows) {
+      const cur = best.get(gk(r))
+      if (!cur || Number(r.mtime_ms) > Number(cur.mtime_ms) || (Number(r.mtime_ms) === Number(cur.mtime_ms) && r.rowid < cur.rowid)) best.set(gk(r), r)
+    }
+    const del = db.prepare(`DELETE FROM ${table} WHERE rowid = ?`)
+    const upd = db.prepare(`UPDATE ${table} SET origin = ? WHERE rowid = ?`)
+    for (const r of rows) if (best.get(gk(r)) !== r) { del.run(r.rowid); touched += 1 }
+    for (const r of best.values()) if (r.origin !== key) { upd.run(key, r.rowid); touched += 1 }
+  }
+  return touched
+}
+
+/** 写后回读判据（§6.13「按档分列」，不过 ⇒ 抛 ⇒ 事务回滚 ⇒ 零写）；`hitsByRaw` = `--path` 档逐原样键命中数。 */
+function readBack(db, plan, before, hitsByRaw = null) {
+  const { mode, target } = plan
+  const after = originCounts(db)
+  const totalBefore = [...before.values()].reduce((n, c) => n + totalOf(c), 0)
+  const totalAfter = [...after.values()].reduce((n, c) => n + totalOf(c), 0)
+  if (totalAfter > totalBefore) throw new Error(`memory sweep read-back failed: COUNT(*) grew (${totalBefore} → ${totalAfter})`)
+  if (mode === "origin" && plan.path) {
+    // `--path` 档：命中行 0（两表，目标原样键集）∧ 非目标键逐表等前值 ∧ 目标键：files 零变 ∕ code-doc 恰减命中数
+    const raws = [...new Set(plan.rows.flatMap((r) => r.raws))]
+    for (const t of ["code_chunks", "doc_chunks"]) {
+      if (pathHitCount(db, t, raws, plan.path) !== 0) throw new Error(`memory sweep read-back failed: --path hit rows remain in ${t}`)
+    }
+    for (const [o, c] of before) {
+      const now = after.get(o) ?? emptyCounts()
+      if (!raws.includes(o)) {
+        if (KEYS.some((k) => now[k] !== c[k])) throw new Error(`memory sweep read-back failed: non-target origin changed (${o})`)
+        continue
+      }
+      const hits = hitsByRaw?.get(o) ?? { code: 0, doc: 0 }
+      if (now.files !== c.files || now.code !== c.code - hits.code || now.doc !== c.doc - hits.doc) {
+        throw new Error(`memory sweep read-back failed: --path target rows changed beyond hits (${o})`)
+      }
+    }
+  } else if (mode === "origin") {
+    // `--origin` 档：目标归一键三表零命中 ∧ 非目标 origin 零变（逐键等前值）
+    for (const [o] of after) if (normalizeOrigin(o) === target) throw new Error(`memory sweep read-back failed: --origin target key still indexed (${o})`)
+    for (const [o, c] of before) {
+      if (normalizeOrigin(o) === target) continue
+      const now = after.get(o) ?? emptyCounts()
+      if (KEYS.some((k) => now[k] !== c[k])) throw new Error(`memory sweep read-back failed: non-target origin changed (${o})`)
+    }
+  } else {
+    // 折叠档：归一键集合 = 1（无残留非归一键）∧ 任一 (归一键, path[, line_start]) 恰一行（下循环）
+    for (const [o] of after) if (normalizeOrigin(o) !== o) throw new Error(`memory sweep read-back failed: non-normalized origin key remains (${o})`)
+  }
+  for (const { table, dup } of TABLES) {
+    const { n } = db.prepare(`SELECT COUNT(*) AS n FROM (SELECT 1 FROM ${table} GROUP BY origin, ${dup.join(", ")} HAVING COUNT(*) > 1)`).get()
+    if (Number(n) !== 0) throw new Error(`memory sweep read-back failed: duplicate rows per (origin, ${dup.join(", ")}) in ${table}`)
+  }
+}
+
+/** 写面（`--confirm` 档）：单事务 —— ① 折叠（先于删除，死树键的变体行随键级删除一并清掉）② 键级删除
+ *  （`--path` 档：仅两表前缀命中行，逐原样键记命中数供回读判据）③ 写后回读判据（不过 ⇒ 回滚 + 抛）。
+ *  返回实际触碰行数 { folded, deleted }。 */
+function applySweep(db, plan) {
+  const before = originCounts(db)
+  const foldGroups = new Map()
+  for (const r of plan.rows) {
+    if (r.action !== "fold") continue
+    // 折叠候选集 = 归一键**自身** + 其全部变体拼写（设计口径 = 同归一键内恰一行——
+    // 归一键行亦入组，否则胜者改键会与已在归一键上的同 dup 行撞 PK，整批回滚）
+    if (!foldGroups.has(r.origin)) foldGroups.set(r.origin, new Set([r.origin]))
+    for (const o of r.raws) foldGroups.get(r.origin).add(o)
+  }
+  const deleteKeys = plan.rows.filter((r) => r.action === "delete").map((r) => [...new Set([r.origin, ...r.raws])])
+  const affected = { folded: 0, deleted: 0 }
+  const hitsByRaw = plan.path ? new Map() : null
+  db.exec("BEGIN IMMEDIATE")
+  try {
+    for (const [key, raws] of foldGroups) affected.folded += foldKey(db, key, [...raws])
+    for (const raws of deleteKeys) {
+      const ph = raws.map(() => "?").join(", ")
+      if (plan.path) {
+        // §6.14 面①-3：仅 code ∕ doc 两表按前缀删（files 表不涉）；逐原样键记命中数
+        for (const raw of raws) {
+          const hits = { code: 0, doc: 0 }
+          for (const [t, k] of [["code_chunks", "code"], ["doc_chunks", "doc"]]) {
+            hits[k] = Number(db.prepare(`DELETE FROM ${t} WHERE origin = ? AND (path = ? OR substr(path, 1, ?) = ?)`).run(raw, plan.path, plan.path.length + 1, `${plan.path}/`).changes)
+          }
+          hitsByRaw.set(raw, hits)
+          affected.deleted += hits.code + hits.doc
+        }
+      } else {
+        for (const { table } of TABLES) affected.deleted += Number(db.prepare(`DELETE FROM ${table} WHERE origin IN (${ph})`).run(...raws).changes)
+      }
+    }
+    readBack(db, plan, before, hitsByRaw)
+    db.exec("COMMIT")
+  } catch (e) {
+    try { db.exec("ROLLBACK") } catch { /* 已回滚 / 事务未开 */ }
+    throw e
+  }
+  return affected
+}
+
+/**
+ * sweep 主入口。`confirm: false`（缺省）⇒ 纯干跑（零写、零备份）；`confirm: true` ⇒ 命中 > 0 时先取备份
+ * （判据不过即抛 ⇒ 零写），再单事务执行折叠 / 删除并跑写后回读判据。
+ * 返回：{ mode, target, dryRun, rows, totals, hits, backupPath, affected }。
+ */
+export function sweepMemory(memory, { origin = null, path = null, confirm = false, dbPath = null, now = new Date() } = {}) {
+  const plan = planSweep(memory, { origin, path })
+  const hits = plan.rows.reduce((n, r) => n + (r.action === "keep" ? 0 : r.total), 0)
+  const result = { mode: plan.mode, target: plan.target, path: plan.path, dryRun: !confirm, rows: plan.rows, totals: plan.totals, hits, backupPath: null, affected: null }
+  if (!confirm) return result
+  if (hits > 0) {
+    if (typeof dbPath !== "string" || !dbPath || dbPath === ":memory:") {
+      throw new Error("memory sweep: `--confirm` 需要文件型 dbPath（备份前置的命名依据）——拒绝无回退对象的写入")
+    }
+    result.backupPath = takeBackup(memory.db, backupPathFor(dbPath, now))
+  }
+  result.affected = applySweep(memory.db, plan)
+  return result
+}
+
+/** 审计输出形态（§6.13）：逐 origin 一行 `origin=<归一形> · 树存活=<是|否> · code / doc / files / 合计`
+ *  （活树附警示行）+ 折叠映射行 + 删除行数 + 末行合计 + 备份路径（`--confirm` 档）/ 实写读数。 */
+export function formatSweepReport(result) {
+  const mode = result.mode === "origin" ? `--origin ${result.target}${result.path ? ` --path ${result.path}` : ""}` : "全扫"
+  const lines = [`memory sweep ${mode} · ${result.dryRun ? "dry-run（零写）" : "confirm（写档）"}`]
+  for (const r of result.rows) {
+    lines.push(`origin=${r.origin} · 树存活=${r.alive ? "是" : "否"} · code=${r.code} / doc=${r.doc} / files=${r.files} / 合计=${r.total}`)
+    if (r.foldFrom) lines.push(`  折叠: ${r.foldFrom} → ${r.origin}（并入归一键）`)
+    if (r.unknown) lines.push("  ⚠ 探针错误——fail-safe 保留（仅 ENOENT 判亡）")
+    if (r.alive) lines.push(`  ⚠ 树存活——${result.mode === "origin" ? "显式点名整档删除（不以树存活为判据）" : "保留（全扫档仅删树亡 origin）"}`)
+    if (r.action === "delete") lines.push(`  删除: code=${r.code} / doc=${r.doc} / files=${r.files}（${r.total} 行）`)
+  }
+  const sum = (act) => result.rows.filter((r) => r.action === act).reduce((n, r) => n + r.total, 0)
+  const t = result.totals
+  lines.push(`合计: code=${t.code} / doc=${t.doc} / files=${t.files} / 合计=${t.total} · 删除 ${sum("delete")} 行 / 折叠 ${sum("fold")} 行 / 保留 ${sum("keep")} 行`)
+  if (result.affected) lines.push(`实写: 删除 ${result.affected.deleted} 行 / 折叠 ${result.affected.folded} 行`)
+  if (result.backupPath) lines.push(`备份: ${result.backupPath}`)
+  return lines
+}

package/memory/sync-tail.mjs

@@ -0,0 +1,81 @@
+/**
+ * memory/sync-tail.mjs — 同步收尾族（§6.14 面② B6 ∕ M3 收尾让出 + 面③ P2 行预算——**单源**）。
+ *
+ * 两个同步入口（`codeSync` ∕ `docSync`）共用的收尾机制都住本档（拆分点 = 批档 §2.12 补块 3 缝
+ * 「code-sync〔预算判定 + stale 收尾块〕」）：
+ *   · **P2 行预算**（`createRowBudget`）：基准 = 本 origin 库内行数（code+doc，开趟读一次）；过
+ *     `INDEX_ORIGIN_ROW_WARN` 出一行可见警示（每趟至多一行）＋ `logEvent`；过 `INDEX_ORIGIN_ROW_CAP`
+ *     由调用方跳过列序后缀（**只停新增**——存量行不失效；跳过 = 不落行 ∕ 不记 mtime ⇒ 下趟重试）。
+ *   · **stale 收尾循环**（`sweepStaleRows`）：同款时间片让出（§6.10 A2 口径——每 `SCAN_YIELD_CHECK_ROWS`
+ *     行读钟，累计 ≥ `yieldMs` 即让出）＋ 面① **收尾保护位**（`isExcludedRelPath` 命中路径短路——
+ *     被排除但存在的路径存量行不因声明删除，收敛仅经 `sweep --path`；缺省 `[]` ⇒ 恒不命中）。
+ *
+ * 零环：只引 `log.mjs` ∕ `conventions.mjs`（谓词）∕ `schema.mjs`（常量）∕ `scan.mjs`（预算常量）∕
+ * `code-index.mjs`（`yieldTick`）——不引 `code-sync.mjs` ∕ `docs.mjs`。作业皆经传入句柄，档内零状态。
+ */
+import { logEvent } from "../log.mjs"
+import { isExcludedRelPath } from "../conventions.mjs"
+import { INDEX_ORIGIN_ROW_WARN, INDEX_ORIGIN_ROW_CAP } from "./schema.mjs"
+import { SCAN_YIELD_CHECK_ROWS, SCAN_YIELD_MS } from "./scan.mjs"
+import { yieldTick } from "./code-index.mjs"
+
+/** 本 origin 库内行数（`code_chunks` + `doc_chunks` 合计——§6.14 P2 预算基准；开趟读一次）。 */
+export function originRowCount(memory, origin) {
+  const n = (t) => Number(memory.db.prepare(`SELECT COUNT(*) AS n FROM ${t} WHERE origin = ?`).get(origin)?.n ?? 0)
+  return n("code_chunks") + n("doc_chunks")
+}
+
+/** 单路径行数（预算差量用——PK 前缀范围扫描）。 */
+export function rowCountOfPath(memory, table, origin, rel) {
+  return Number(memory.db.prepare(`SELECT COUNT(*) AS n FROM ${table} WHERE origin = ? AND path = ?`).get(origin, rel)?.n ?? 0)
+}
+
+/** §6.14 P2 行预算（单源——codeSync ∕ docSync 同用）：`note()` 每趟至多一行 WARN 警示；`over()` =
+ *  已到 CAP（调用方跳过后列文件）；`add(delta)` = 本趟净增行数（新入 − 被替换——与「库内行数」同刻度）。 */
+export function createRowBudget(memory, origin, kind, dir) {
+  const base = originRowCount(memory, origin)
+  let landed = 0, warned = false, capped = false
+  const rows = () => base + landed
+  const pruneHint = `declare index.excludePaths in PROJECT-MANIFEST.json, or prune: thincoder memory sweep --origin "${origin}" --path <sub>`
+  return {
+    add: (delta) => { landed += delta },
+    over: () => rows() >= INDEX_ORIGIN_ROW_CAP,
+    note() {
+      if (!warned && rows() >= INDEX_ORIGIN_ROW_WARN) {
+        warned = true
+        console.warn(`[memory] index origin=${origin} rows≈${rows()} ≥ WARN ${INDEX_ORIGIN_ROW_WARN} — ${pruneHint}`)
+        logEvent("index:budget", { dir, kind, rows: rows(), warn: INDEX_ORIGIN_ROW_WARN })
+      }
+      if (!capped && rows() >= INDEX_ORIGIN_ROW_CAP) {
+        capped = true
+        console.warn(`[memory] index origin=${origin} rows≈${rows()} ≥ CAP ${INDEX_ORIGIN_ROW_CAP} — skipping remaining files this pass (existing rows are kept)`)
+        logEvent("index:budget-cap", { dir, kind, rows: rows(), cap: INDEX_ORIGIN_ROW_CAP })
+      }
+    },
+  }
+}
+
+/**
+ * §6.14 B6 ∕ M3：收尾 stale 删除循环（同款让出 + 收尾保护位）。返回删除行数（文件级）。
+ * @param {object} memory 句柄
+ * @param {{table: string, origin: string, indexed: Map<string, number>, seen: Set<string>, decl: object,
+ *   base?: string|null, yieldFn?: Function, nowFn?: Function, yieldMs?: number}} opts
+ *   `indexed` = 库内 path→mtime（开趟读）；`seen` = 本趟列文件；`decl` = `loadProjectDeclaration()` 回执；
+ *   `base` = `indexed`/`seen` 里 `rel` 的相对基（调用面 dir——#700 等价换算；缺省 = 根相对）
+ */
+export async function sweepStaleRows(memory, { table, origin, indexed, seen, decl, base = null, yieldFn = yieldTick, nowFn = Date.now, yieldMs = SCAN_YIELD_MS }) {
+  let removed = 0
+  let checked = 0
+  let lastYieldAt = nowFn()
+  for (const stale of indexed.keys()) {
+    if (!seen.has(stale) && !isExcludedRelPath(stale, decl, base)) {
+      memory.db.prepare(`DELETE FROM ${table} WHERE origin = ? AND path = ?`).run(origin, stale)
+      removed++
+    }
+    if (++checked >= SCAN_YIELD_CHECK_ROWS) {
+      checked = 0
+      if (nowFn() - lastYieldAt >= yieldMs) { await yieldFn(); lastYieldAt = nowFn() }
+    }
+  }
+  return removed
+}