memory-eternal 0.9.23 → 0.10.2

package/lib/vault.js

@@ -5,7 +5,7 @@
 
 import path from 'node:path'
 import fs from 'node:fs'
-import { getDb, enforceAudit } from './db.js'
+import { getDb, enforceAudit, nextCardId, MAIN_STATUS, QUARANTINE_STATUSES, tableForStatus } from './db.js'
 import { minhashSignature, lshCandidates } from './minhash.js'
 
 /** 主题目录根。 */
@@ -134,14 +134,34 @@ export function queryTerms(query) {
   return tokens
 }
 
-/** 在目标目录中找与候选文本最相似的现有卡（去重守卫）。比较正文。 */
+/**
+ * 在目标目录中找与候选文本最相似的现有卡（去重守卫）。比较正文。
+ *
+ * 只比对 **approved**（P0 修复）：命中后调用方会 `appendUpdate` 往这张卡里追加内容，
+ * 而 pending / rejected 是不该再长内容的状态——旧实现只按 `deleted_at IS NULL` 过滤，
+ * 会把新知识追加进待审垃圾卡或已被驳回的卡，等于绕过审核往废弃卡里灌数据。
+ */
 export async function dedupCheck(root, text, threshold = 0.62) {
+  return bestDuplicate(await mainStoreBodies(root), text, threshold)
+}
+
+/**
+ * 主库已审核卡的 `(path, body)` 快照。
+ *
+ * 批量写入（导入备份）必须用它做**导入前**基线：否则同一份备份里互相近似的卡会在写入
+ * 过程中互相判重，把备份当成「重复」丢掉一批（备份是真相源，不能被自己人吞）。
+ */
+export async function mainStoreBodies(root) {
   const db = getDb(root)
-  const rows = db.prepare('SELECT path, body FROM cards WHERE deleted_at IS NULL').all()
+  return db.prepare("SELECT path, body FROM cards WHERE status = 'approved' AND deleted_at IS NULL").all()
+}
+
+/** 在一组候选里找与给定文本最相似的一张（≥ 阈值）。候选集合由调用方提供，供快照比对复用。 */
+export function bestDuplicate(candidates, text, threshold = 0.62) {
   let best = null
-  for (const row of rows) {
-    const score = textSimilarity(text, row.body || '')
-    if (score >= threshold && (!best || score > best.score)) best = { path: row.path, score }
+  for (const row of Array.isArray(candidates) ? candidates : []) {
+    const score = textSimilarity(text, row?.body || '')
+    if (score >= threshold && (!best || score > best.score)) best = { path: row?.path, score }
   }
   return best
 }
@@ -220,21 +240,72 @@ function agentWhere(agent, args) {
   return "LOWER(COALESCE(submitted_by,'')) = ?"
 }
 
-/** WHERE 组装：状态白名单 + 可选 kind / agent。 */
-function cardsWhere({ want, kind, agent }) {
-  const args = [...want]
-  let where = `status IN (${want.map(() => '?').join(',')})`
-  if (kind) { where += ' AND kind = ?'; args.push(kind) }
-  if (agent) where += ' AND ' + agentWhere(agent, args)
-  return { where, args }
+// ---- 两套存储：主库（cards，只存 approved）/ 隔离区（quarantine，pending·rejected·deleted）--
+//
+// 下面三个函数负责「把状态白名单翻译成对两张表的查询」。读路径默认只碰主库：
+// 主库物理上不含非 approved 行，所以查主库**不需要写状态条件**，也就没有「漏写状态条件」这种 bug 面。
+
+/** 状态白名单 → 需要读的表清单。 */
+function storesFor(want) {
+  const hasMain = want.includes(MAIN_STATUS)
+  const hasQuarantine = want.some((s) => QUARANTINE_STATUSES.includes(s))
+  if (hasMain && !hasQuarantine) return [{ table: 'cards', statuses: null }]
+  if (hasQuarantine && !hasMain) return [{ table: 'quarantine', statuses: want.filter((s) => QUARANTINE_STATUSES.includes(s)) }]
+  return [
+    { table: 'cards', statuses: null },
+    { table: 'quarantine', statuses: want.filter((s) => QUARANTINE_STATUSES.includes(s)) },
+  ]
+}
+
+/**
+ * 生成一条「跨两套存储」的查询。
+ * @param sel    选择列表（如 '*' 或 'path, title'）
+ * @param stores storesFor() 的结果
+ * @param extra  { kind, agent, tail } —— tail 是 ORDER BY / LIMIT 片段（默认按 updated_at 倒序）
+ */
+function multiStoreQuery(sel, stores, { kind = '', agent = '', tail = 'ORDER BY updated_at DESC' } = {}) {
+  const parts = []
+  const args = []
+  for (const store of stores) {
+    const where = []
+    const wargs = []
+    if (store.statuses) {
+      where.push(`status IN (${store.statuses.map(() => '?').join(',')})`)
+      wargs.push(...store.statuses)
+    }
+    if (kind) { where.push('kind = ?'); wargs.push(kind) }
+    if (agent) where.push(agentWhere(agent, wargs))
+    parts.push(`SELECT ${sel} FROM ${store.table}${where.length ? ' WHERE ' + where.join(' AND ') : ''}`)
+    args.push(...wargs)
+  }
+  return { sql: parts.join(' UNION ALL ') + ' ' + tail, args }
+}
+
+/** 在两张表里按 path 找一行（跨存储读取用，返回 { table, row }）。 */
+function findCardRow(db, rel) {
+  const inMain = db.prepare('SELECT * FROM cards WHERE path = ?').get(rel)
+  if (inMain) return { table: 'cards', row: inMain }
+  const inQuarantine = db.prepare('SELECT * FROM quarantine WHERE path = ?').get(rel)
+  if (inQuarantine) return { table: 'quarantine', row: inQuarantine }
+  return null
+}
+
+/** 某个 path 是否已被占用（两张表任意一张里有，就算占用）。 */
+function pathTaken(db, rel) {
+  if (db.prepare('SELECT 1 FROM cards WHERE path = ?').get(rel)) return true
+  return !!db.prepare('SELECT 1 FROM quarantine WHERE path = ?').get(rel)
 }
 
 /** 标题排序用的中文排序器（拼音 + 数字感知）；固定 zh-Hans-CN，避免随进程 locale 漂移。 */
 export const TITLE_COLLATOR = new Intl.Collator('zh-Hans-CN', { numeric: true, sensitivity: 'base' })
 
 /**
- * 列出卡片（从 SQL）。
- * @param opts.status  状态白名单（默认 approved）
+ * 列出卡片。
+ *
+ * 两套存储下 status 的语义：'approved' → 只查主库（**不加状态条件**，主库物理上只有 approved）；
+ * 'pending'/'rejected'/'deleted' → 查隔离区；'all' → 两张表 UNION（审核中心用）。
+ *
+ * @param opts.status  状态白名单（默认 approved = 主库）
  * @param opts.kind    类型过滤（SQL）
  * @param opts.agent   署名过滤（服务端归一，如 deepseek-harness / claude）
  * @param opts.limit   返回条数上限（缺省=全部，供内部调用保持原语义）
@@ -242,35 +313,49 @@ export const TITLE_COLLATOR = new Intl.Collator('zh-Hans-CN', { numeric: true, s
  * @param opts.sort    'recent'（updated_at DESC，默认）| 'title'（拼音升序，跨页全局有序）
  */
 export async function listCards(root, { status, kind, agent, limit, offset = 0, sort = 'recent' } = {}) {
-  const want = status ?? ['approved']
+  const want = status ?? [MAIN_STATUS]
   const db = getDb(root)
-  const { where, args } = cardsWhere({ want, kind, agent })
+  const stores = storesFor(want)
+
   if (sort === 'title') {
     // SQLite 的 ORDER BY 是 UTF-8 字节序，中文标题看着就是乱的 → 只取 path/title 用拼音排好，
     // 再回表取这一页的正文（避免为了排序把所有正文读进内存）。
-    const light = db.prepare(`SELECT path, title FROM cards WHERE ${where}`).all(...args)
+    const { sql, args } = multiStoreQuery('path, title', stores, { kind, agent, tail: '' })
+    const light = db.prepare(sql).all(...args)
     light.sort((a, b) => TITLE_COLLATOR.compare(a.title || '', b.title || ''))
     const start = Math.max(0, offset | 0)
     const page = Number.isInteger(limit) && limit > 0 ? light.slice(start, start + limit) : light.slice(start)
     if (page.length === 0) return []
-    const ph = page.map(() => '?').join(',')
-    const rows = db.prepare(`SELECT * FROM cards WHERE path IN (${ph})`).all(...page.map((r) => r.path))
+    const paths = page.map((r) => r.path)
+    const rows = []
+    for (const store of stores) {
+      const ph = paths.map(() => '?').join(',')
+      rows.push(...db.prepare(`SELECT * FROM ${store.table} WHERE path IN (${ph})`).all(...paths))
+    }
     const byPath = new Map(rows.map((r) => [r.path, rowToCard(r)]))
     return page.map((r) => byPath.get(r.path)).filter(Boolean)
   }
-  if (Number.isInteger(limit) && limit > 0) {
-    const rows = db.prepare(`SELECT * FROM cards WHERE ${where} ORDER BY updated_at DESC LIMIT ? OFFSET ?`).all(...args, limit, Math.max(0, offset | 0))
-    return rows.map(rowToCard)
-  }
-  const rows = db.prepare(`SELECT * FROM cards WHERE ${where} ORDER BY updated_at DESC`).all(...args)
-  return rows.map(rowToCard)
+
+  const tail = Number.isInteger(limit) && limit > 0
+    ? `ORDER BY updated_at DESC LIMIT ? OFFSET ?`
+    : 'ORDER BY updated_at DESC'
+  // 注意：两张表的列数不同（quarantine 多 quarantined_at / quarantine_reason），
+  // UNION ALL 必须显式列出公共列，不能用 `*`（否则列会错位）。
+  const { sql, args } = multiStoreQuery(
+    'id, path, kind, title, tags, body, summary, status, source, submitted_by, severity, reason, created_at, updated_at, deleted_at',
+    stores,
+    { kind, agent, tail },
+  )
+  const finalArgs = Number.isInteger(limit) && limit > 0 ? [...args, limit, Math.max(0, offset | 0)] : args
+  return db.prepare(sql).all(...finalArgs).map(rowToCard)
 }
 
 /** 计数（分页接口要用 total 判断还有没有下一页）。 */
 export async function countCards(root, { status, kind, agent } = {}) {
   const db = getDb(root)
-  const { where, args } = cardsWhere({ want: status ?? ['approved'], kind, agent })
-  return db.prepare(`SELECT COUNT(*) n FROM cards WHERE ${where}`).get(...args).n
+  const stores = storesFor(status ?? [MAIN_STATUS])
+  const { sql, args } = multiStoreQuery('COUNT(*) n', stores, { kind, agent, tail: '' })
+  return db.prepare(`SELECT SUM(n) n FROM (${sql})`).get(...args).n || 0
 }
 
 /** 审核队列：status=pending 或 rejected。 */
@@ -279,10 +364,58 @@ export async function auditQueue(root) {
   return { pending: cards.filter((c) => c.status === 'pending'), rejected: cards.filter((c) => c.status === 'rejected') }
 }
 
-/** 回收站：status=deleted，按 deleted_at 倒序。 */
+/** 同一个事务里执行 fn（失败自动回滚）。跨表搬家必须原子，否则会丢卡。 */
+function inTransaction(db, fn) {
+  db.exec('BEGIN')
+  try {
+    const out = fn()
+    db.exec('COMMIT')
+    return out
+  } catch (e) {
+    try { db.exec('ROLLBACK') } catch { /* 已回滚 */ }
+    throw e
+  }
+}
+
+/**
+ * 把一张卡从一张表搬到另一张表（重建行、保住内容 / 时间戳 / 更新记录）。
+ *
+ * 为什么不用同一个 id：两张表共享 `path` 命名空间，但 id 由 `card_sequence` 单一发号器
+ * 保证**全库唯一**；跨表插入时旧 id 可能已被目标表占用（实测 `UNIQUE constraint failed`）。
+ * 所以搬家时重新领号，并把 `card_updates.card_id` 一起改绑 —— 用户视角「更新记录还在」。
+ * 之所以要原子：INSERT 成功而 DELETE 失败会留下重复卡；反过来则直接丢卡。
+ */
+function moveCardBetweenStores(db, from, to, rel, { status, deletedAt = null, quarantineReason = '', updatedAt } = {}) {
+  const now = updatedAt || new Date().toISOString()
+  return inTransaction(db, () => {
+    const src = db.prepare(`SELECT * FROM ${from} WHERE path = ?`).get(rel)
+    if (!src) throw new Error(`卡片不在 ${from}: ${rel}`)
+    const newId = nextCardId(db)
+
+    if (to === 'quarantine') {
+      db.prepare(`
+        INSERT INTO quarantine
+          (id, path, kind, title, tags, body, summary, status, source, submitted_by, severity, reason, created_at, updated_at, deleted_at, quarantined_at, quarantine_reason)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), ?)
+      `).run(newId, src.path, src.kind, src.title, src.tags, src.body, src.summary, status, src.source, src.submitted_by, src.severity, src.reason, src.created_at, now, deletedAt, quarantineReason)
+    } else {
+      db.prepare(`
+        INSERT INTO cards
+          (id, path, kind, title, tags, body, summary, status, source, submitted_by, severity, reason, created_at, updated_at, deleted_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(newId, src.path, src.kind, src.title, src.tags, src.body, src.summary, status, src.source, src.submitted_by, src.severity, src.reason, src.created_at, now, deletedAt)
+    }
+    // 更新记录跟着卡走（id 变了，按新 id 改绑）
+    db.prepare('UPDATE card_updates SET card_id = ? WHERE card_id = ?').run(newId, src.id)
+    db.prepare(`DELETE FROM ${from} WHERE path = ?`).run(rel)
+    return { ok: true, status, table: to, oldId: src.id, newId }
+  })
+}
+
+/** 回收站：隔离区里 status=deleted，按 deleted_at 倒序。 */
 export async function recycleList(root) {
   const db = getDb(root)
-  const rows = db.prepare('SELECT * FROM cards WHERE status = ? ORDER BY deleted_at DESC').all('deleted')
+  const rows = db.prepare('SELECT * FROM quarantine WHERE status = ? ORDER BY deleted_at DESC').all('deleted')
   return rows.map(rowToCard)
 }
 
@@ -290,7 +423,7 @@ export async function recycleList(root) {
 export async function purgeExpired(root, retentionDays = 30) {
   const db = getDb(root)
   const cut = new Date(Date.now() - retentionDays * 86400000).toISOString()
-  const rows = db.prepare('SELECT path FROM cards WHERE status = ? AND deleted_at IS NOT NULL AND deleted_at < ?').all('deleted', cut)
+  const rows = db.prepare('SELECT path FROM quarantine WHERE status = ? AND deleted_at IS NOT NULL AND deleted_at < ?').all('deleted', cut)
   let purged = 0
   for (const row of rows) {
     try { await deleteCard(root, row.path, { permanent: true }); purged++ } catch {}
@@ -298,113 +431,193 @@ export async function purgeExpired(root, retentionDays = 30) {
   return { ok: true, purged }
 }
 
-/** 读取一张卡（返回 Markdown 文本，兼容旧调用方）。 */
-export async function readCard(root, rel) {
+/**
+ * 读取一张卡（返回 Markdown 文本）。
+ *
+ * 两套存储下的语义：
+ * - 默认**只读主库**（主库物理上只含 approved）→ 想读未审核内容，必须显式 `allowUnapproved`。
+ * - `allowUnapproved: true` 时（审核中心 / 回收站预览）走两张表。
+ * 「不存在」与「存在但未审核」是两种不同的错误码，方便上层区分。
+ */
+export async function readCard(root, rel, { allowUnapproved = false } = {}) {
   const db = getDb(root)
-  const row = db.prepare('SELECT * FROM cards WHERE path = ?').get(rel)
-  if (!row) throw new Error('卡片不存在: ' + rel)
+  const mainRow = db.prepare('SELECT * FROM cards WHERE path = ?').get(rel)
+  let row = mainRow
+  if (!row && allowUnapproved) row = db.prepare('SELECT * FROM quarantine WHERE path = ?').get(rel)
+  if (!row) {
+    // path 可能在隔离区而不在主库 —— 这种情况不能当成「不存在」，否则审核中心会误判
+    const inQuarantine = db.prepare('SELECT status FROM quarantine WHERE path = ?').get(rel)
+    const err = new Error(inQuarantine
+      ? `卡片在隔离区（${statusLabel(inQuarantine.status)}），未通过审核不能读取正文：${rel}`
+      : `卡片不存在: ${rel}`)
+    err.code = inQuarantine ? 'CARD_NOT_APPROVED' : 'CARD_NOT_FOUND'
+    if (inQuarantine) err.status = inQuarantine.status
+    throw err
+  }
+  const status = String(row.status || '')
   const { text } = rowToMarkdown(row)
-  // 附加更新记录
   const updates = db.prepare('SELECT content, created_at FROM card_updates WHERE card_id = ? ORDER BY created_at ASC').all(row.id)
   if (updates.length > 0) {
     const updateLines = updates.map((u) => `- ${u.created_at.slice(0, 10)}：${u.content}`)
-    return text + '\n## 更新记录\n\n' + updateLines.join('\n') + '\n'
+    return { path: rel, status, store: mainRow ? 'main' : 'quarantine', text: text + '\n## 更新记录\n\n' + updateLines.join('\n') + '\n' }
   }
-  return text
+  return { path: rel, status, store: mainRow ? 'main' : 'quarantine', text }
+}
+
+/** 状态中文标签（错误信息与日志用）。 */
+function statusLabel(status) {
+  const s = String(status || '')
+  return s === 'pending' ? '待审核' : s === 'rejected' ? '已驳回' : s === 'deleted' ? '回收站中' : s
 }
 
-/** 软删卡片：status=deleted + deleted_at。 */
+/**
+ * 删除卡片。
+ * - 永久删除：从**任一张表**里抹掉（含更新记录，靠外键 CASCADE）。
+ * - 软删（默认）：主库卡 → 搬进隔离区并置 deleted；隔离区卡 → 原地置 deleted。
+ */
 export async function deleteCard(root, rel, { permanent = false } = {}) {
   const db = getDb(root)
   if (permanent) {
-    db.prepare('DELETE FROM cards WHERE path = ?').run(rel)
+    // 先按 path 取 id（两张表共享 id 空间），再清理按 id 关联的更新记录 —— card_updates
+    // 不带外键（卡会在两表间搬家），所以级联必须在这里手工做。
+    const ids = []
+    const mainRow = db.prepare('SELECT id FROM cards WHERE path = ?').get(rel)
+    if (mainRow) ids.push(mainRow.id)
+    const qRow = db.prepare('SELECT id FROM quarantine WHERE path = ?').get(rel)
+    if (qRow) ids.push(qRow.id)
+    if (!ids.length) throw new Error('卡片不存在: ' + rel)
+    inTransaction(db, () => {
+      for (const id of ids) {
+        db.prepare('DELETE FROM card_updates WHERE card_id = ?').run(id)
+        db.prepare('DELETE FROM feedback WHERE card_path = ?').run(rel)
+      }
+      db.prepare('DELETE FROM cards WHERE path = ?').run(rel)
+      db.prepare('DELETE FROM quarantine WHERE path = ?').run(rel)
+    })
     return { ok: true, permanent: true }
   }
+  const existing = findCardRow(db, rel)
+  if (!existing) throw new Error('卡片不存在: ' + rel)
+  if (existing.table === 'cards') {
+    const r = moveCardBetweenStores(db, 'cards', 'quarantine', rel, { status: 'deleted', deletedAt: new Date().toISOString(), quarantineReason: '移入回收站' })
+    db.prepare('INSERT INTO audit_log (card_path, old_status, new_status, changed_by, reason) VALUES (?, ?, ?, ?, ?)').run(rel, existing.row.status, 'deleted', 'delete', '软删进回收站')
+    return { ok: true, soft: true, ...r }
+  }
   const now = new Date().toISOString()
-  const info = db.prepare('UPDATE cards SET status = ?, deleted_at = ?, updated_at = ? WHERE path = ?').run('deleted', now, now, rel)
-  if (info.changes === 0) throw new Error('卡片不存在: ' + rel)
+  db.prepare('UPDATE quarantine SET status = ?, deleted_at = ?, updated_at = ? WHERE path = ?').run('deleted', now, now, rel)
+  db.prepare('INSERT INTO audit_log (card_path, old_status, new_status, changed_by, reason) VALUES (?, ?, ?, ?, ?)').run(rel, existing.row.status, 'deleted', 'delete', '软删进回收站')
   return { ok: true, soft: true }
 }
 
-/** 恢复软删卡：status=approved，清除 deleted_at。写审计日志。 */
+/** 恢复回收站的卡：从隔离区搬回主库，status=approved。写审计日志。 */
 export async function restoreCard(root, rel) {
   const db = getDb(root)
-  const now = new Date().toISOString()
-  const existing = db.prepare('SELECT status FROM cards WHERE path = ?').get(rel)
-  if (!existing) throw new Error('卡片不存在: ' + rel)
-  const info = db.prepare('UPDATE cards SET status = ?, deleted_at = NULL, updated_at = ? WHERE path = ?').run('approved', now, rel)
-  if (info.changes === 0) throw new Error('卡片不存在: ' + rel)
-  db.prepare('INSERT INTO audit_log (card_path, old_status, new_status, changed_by, reason) VALUES (?, ?, ?, ?, ?)').run(rel, existing.status, 'approved', 'restore', '回收站恢复')
-  return { ok: true, restored: true }
+  const existing = db.prepare('SELECT status FROM quarantine WHERE path = ?').get(rel)
+  if (!existing) throw new Error('卡片不在回收站/隔离区: ' + rel)
+  const r = moveCardBetweenStores(db, 'quarantine', 'cards', rel, { status: MAIN_STATUS, deletedAt: null })
+  db.prepare('INSERT INTO audit_log (card_path, old_status, new_status, changed_by, reason) VALUES (?, ?, ?, ?, ?)').run(rel, existing.status, MAIN_STATUS, 'restore', '回收站恢复')
+  return { ok: true, restored: true, ...r }
 }
 
-/** 更新卡状态（审核操作）。写审计日志，确保可追溯。 */
+/**
+ * 更新卡状态（审核操作，唯一入口）。写审计日志。
+ *
+ * 两套存储的关键点：status 决定这张卡**住在哪张表**。
+ * → approved：搬进主库（agent 可召回）；pending/rejected/deleted：留在/搬进隔离区。
+ */
 export async function setCardStatus(root, rel, status, { changedBy = 'system', reason = '' } = {}) {
   const db = getDb(root)
-  const now = new Date().toISOString()
-  const existing = db.prepare('SELECT status FROM cards WHERE path = ?').get(rel)
+  const target = String(status)
+  const existing = findCardRow(db, rel)
   if (!existing) throw new Error('卡片不存在: ' + rel)
-  const info = db.prepare('UPDATE cards SET status = ?, updated_at = ? WHERE path = ?').run(status, now, rel)
-  if (info.changes === 0) throw new Error('卡片不存在: ' + rel)
-  // 审计日志：记录每次 status 变更
-  db.prepare('INSERT INTO audit_log (card_path, old_status, new_status, changed_by, reason) VALUES (?, ?, ?, ?, ?)').run(rel, existing.status, status, changedBy, reason)
-  return { ok: true, status }
+
+  if (target === MAIN_STATUS) {
+    if (existing.table === 'cards') {
+      db.prepare('UPDATE cards SET status = ?, updated_at = ? WHERE path = ?').run(target, new Date().toISOString(), rel)
+    } else {
+      moveCardBetweenStores(db, 'quarantine', 'cards', rel, { status: target, deletedAt: null })
+    }
+  } else {
+    if (existing.table === 'cards') {
+      moveCardBetweenStores(db, 'cards', 'quarantine', rel, { status: target, deletedAt: target === 'deleted' ? new Date().toISOString() : null, quarantineReason: reason || '审核流转' })
+    } else {
+      db.prepare('UPDATE quarantine SET status = ?, deleted_at = ?, updated_at = ? WHERE path = ?')
+        .run(target, target === 'deleted' ? new Date().toISOString() : null, new Date().toISOString(), rel)
+    }
+  }
+  db.prepare('INSERT INTO audit_log (card_path, old_status, new_status, changed_by, reason) VALUES (?, ?, ?, ?, ?)').run(rel, existing.row.status, target, changedBy, reason)
+  return { ok: true, status: target, store: tableForStatus(target) }
 }
 
-/** 原子写卡；先去重，命中返回 {duplicate}。审核守卫在数据库层强制。 */
-export async function writeCard(root, { kind, title, tags = [], body, source = '', status = 'pending', submittedBy = '', severity = 'info', reason = '', deletedAt = '' }, { threshold = 0.62, dedup = true } = {}) {
+/**
+ * 原子写卡；先去重，命中返回 {duplicate}。审核守卫在数据库层强制。
+ *
+ * 两套存储：enforceAudit 判定出的 status 决定**写进哪张表** ——
+ * approved → 主库（可被召回）；pending/rejected/deleted → 隔离区（只有审核中心能看）。
+ *
+ * `dedupAgainst` 传入候选集合时，去重只跟**这些**卡比（导入备份用：基线取导入前的快照，
+ * 让同一批里互相近似的卡不会互吞）。
+ */
+export async function writeCard(root, { kind, title, tags = [], body, source = '', status = 'pending', submittedBy = '', severity = 'info', reason = '', deletedAt = '' }, { threshold = 0.62, dedup = true, dedupAgainst = null } = {}) {
   const db = getDb(root)
   const kindRoot = KIND_ROOTS[kind] || KIND_ROOTS.knowledge
 
   // 审核守卫：数据库层强制，调用方传的 status 仅作 fallback
   const enforcedStatus = enforceAudit(root, kind, submittedBy, status)
+  const targetTable = tableForStatus(enforcedStatus)
 
+  // 去重只在主库（approved）里找 —— 把新知识追加进隔离区里的待审/驳回卡是绕过审核
   if (dedup) {
-    const hit = await dedupCheck(root, body, threshold)
+    const hit = dedupAgainst ? bestDuplicate(dedupAgainst, body, threshold) : await dedupCheck(root, body, threshold)
     if (hit) return { ok: false, duplicate: { ...hit, path: hit.path } }
   }
 
   const slug = safeSlug(title)
   let rel = `${kindRoot}/${slug}.md`
   let index = 2
-  while (db.prepare('SELECT 1 FROM cards WHERE path = ?').get(rel)) {
+  while (pathTaken(db, rel)) {
     rel = `${kindRoot}/${slug}-${index}.md`
     index++
   }
 
   const now = new Date().toISOString()
   const summary = body.trim().slice(0, 200)
-  db.prepare(`
-    INSERT INTO cards (path, kind, title, tags, body, summary, status, source, submitted_by, severity, reason, created_at, updated_at, deleted_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(
-    rel,
-    kind,
-    title,
-    JSON.stringify(tags),
-    body.trim(),
-    summary,
-    enforcedStatus,
-    source,
-    submittedBy,
-    severity,
-    reason,
-    now,
-    now,
-    deletedAt || null,
-  )
-  return { ok: true, path: rel, kind }
+  const id = nextCardId(db) // 跨两张表唯一的 id，由 card_sequence 单一发号器分配
+  if (targetTable === 'cards') {
+    db.prepare(`
+      INSERT INTO cards (id, path, kind, title, tags, body, summary, status, source, submitted_by, severity, reason, created_at, updated_at, deleted_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      id, rel, kind, title, JSON.stringify(tags), body.trim(), summary,
+      enforcedStatus, source, submittedBy, severity, reason, now, now, deletedAt || null,
+    )
+  } else {
+    db.prepare(`
+      INSERT INTO quarantine (id, path, kind, title, tags, body, summary, status, source, submitted_by, severity, reason, created_at, updated_at, deleted_at, quarantined_at, quarantine_reason)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), ?)
+    `).run(
+      id, rel, kind, title, JSON.stringify(tags), body.trim(), summary,
+      enforcedStatus, source, submittedBy, severity, reason, now, now, deletedAt || null,
+      '新卡待审核',
+    )
+  }
+  return { ok: true, path: rel, kind, status: enforcedStatus, store: targetTable }
 }
 
-/** 向已存在的卡追加更新记录。 */
+/**
+ * 向已存在的卡追加更新记录（跨两张表找，因为审核流转会把卡搬表，但 id 不变）。
+ *
+ * 注意：调用方（沉淀管线）只在**主库命中去重**时才追加，所以这里不会把新知识灌进隔离区卡。
+ */
 export async function appendUpdate(root, rel, updateText) {
   const db = getDb(root)
-  const row = db.prepare('SELECT id FROM cards WHERE path = ?').get(rel)
-  if (!row) throw new Error('卡片不存在: ' + rel)
+  const found = findCardRow(db, rel)
+  if (!found) throw new Error('卡片不存在: ' + rel)
+  const row = found.row
   const now = new Date().toISOString()
   db.prepare('INSERT INTO card_updates (card_id, content, created_at) VALUES (?, ?, ?)').run(row.id, updateText.trim(), now)
-  db.prepare('UPDATE cards SET updated_at = ? WHERE id = ?').run(now, row.id)
-  return { ok: true, path: rel, updated: now }
+  db.prepare(`UPDATE ${found.table} SET updated_at = ? WHERE id = ?`).run(now, row.id)
+  return { ok: true, path: rel, updated: now, store: found.table }
 }
 
 /** 合并多张卡为一张。 */
@@ -415,8 +628,8 @@ export async function mergeCards(root, paths) {
 
   const rows = []
   for (const p of list) {
-    const row = db.prepare('SELECT * FROM cards WHERE path = ?').get(p)
-    if (row) rows.push(row)
+    const found = findCardRow(db, p)
+    if (found) rows.push(found.row)
   }
   if (rows.length < 2) return { ok: false, error: '读取失败' }
 
@@ -441,7 +654,8 @@ export async function search(root, query, { limit = 30, minScore = 0, semantic =
   const q = String(query || '').trim()
   if (!q) return []
   const db = getDb(root)
-  const rows = db.prepare("SELECT * FROM cards WHERE status = 'approved' ORDER BY updated_at DESC").all()
+  // 两套存储后这里**不再需要状态条件**：主库物理上只含 approved。
+  const rows = db.prepare('SELECT * FROM cards ORDER BY updated_at DESC').all()
   const wanted = queryTerms(q)
   const out = []
   for (const row of rows) {
@@ -493,13 +707,17 @@ export async function dailyCounts(root, days = 30) {
   return out
 }
 
-/** 导出全部卡片原始 Markdown。 */
+/**
+ * 导出全部卡片原始 Markdown（**含隔离区**：用户做备份/迁移时不应该只拿到主库）。
+ * 顺带给出 store 字段，导入方可以据此判断这张卡该回主库还是回隔离区。
+ */
 export async function exportCards(root) {
   const db = getDb(root)
-  const rows = db.prepare('SELECT * FROM cards ORDER BY updated_at DESC').all()
-  return rows.map((row) => {
+  const main = db.prepare('SELECT * FROM cards ORDER BY updated_at DESC').all().map((r) => ({ ...r, __store: 'main' }))
+  const quarantined = db.prepare('SELECT * FROM quarantine ORDER BY updated_at DESC').all().map((r) => ({ ...r, __store: 'quarantine' }))
+  return [...main, ...quarantined].map((row) => {
     const { text } = rowToMarkdown(row)
-    return { path: row.path, title: row.title, kind: row.kind, text }
+    return { path: row.path, title: row.title, kind: row.kind, status: row.status, store: row.__store, text }
   })
 }
 
@@ -560,10 +778,10 @@ export async function graph(root) {
     if (process.env.MEMORY_GRAPH_PROFILE === '1') console.error('[memory-eternal] graph: 命中磁盘缓存')
     return onDisk
   }
-  // 只选图谱需要的列，不读 body（大幅减少内存和传输量）
-  const rows = db.prepare("SELECT id, path, kind, title, tags, summary, status, updated_at FROM cards WHERE status = 'approved' ORDER BY updated_at DESC").all()
+  // 只选图谱需要的列，不读 body（大幅减少内存和传输量）。主库即 approved，无需状态条件。
+  const rows = db.prepare('SELECT id, path, kind, title, tags, summary, status, updated_at FROM cards ORDER BY updated_at DESC').all()
   // body 单独按需读取（只在需要 wikilink 匹配时）
-  const bodyRows = db.prepare("SELECT path, body FROM cards WHERE status = 'approved'").all()
+  const bodyRows = db.prepare('SELECT path, body FROM cards').all()
   const bodyMap = new Map(bodyRows.map((r) => [r.path, r.body]))
   const cards = rows.map((r) => ({
     path: r.path, kind: r.kind, title: r.title, tags: JSON.parse(r.tags || '[]'),
@@ -751,25 +969,30 @@ export async function graph(root) {
   return value
 }
 
-/** 统计。 */
+/** 统计（主库用量 + 隔离区计数，供侧栏徽标用）。 */
 export async function stats(root) {
   const db = getDb(root)
-  const totalRow = db.prepare("SELECT COUNT(*) as cnt FROM cards WHERE status = 'approved'").get()
-  const byKindRows = db.prepare("SELECT kind, COUNT(*) as cnt FROM cards WHERE status = 'approved' GROUP BY kind").all()
+  const totalRow = db.prepare('SELECT COUNT(*) as cnt FROM cards').get()
+  const byKindRows = db.prepare('SELECT kind, COUNT(*) as cnt FROM cards GROUP BY kind').all()
   const byKind = Object.fromEntries(byKindRows.map((r) => [r.kind, r.cnt]))
 
   const now = new Date()
   const dayAgo = new Date(now.getTime() - 86400000).toISOString()
   const weekAgo = new Date(now.getTime() - 7 * 86400000).toISOString()
-  const todayRow = db.prepare("SELECT COUNT(*) as cnt FROM cards WHERE status = 'approved' AND updated_at >= ?").get(dayAgo)
-  const weekRow = db.prepare("SELECT COUNT(*) as cnt FROM cards WHERE status = 'approved' AND updated_at >= ?").get(weekAgo)
-  const tagRows = db.prepare("SELECT tags FROM cards WHERE status = 'approved'").all()
+  const todayRow = db.prepare('SELECT COUNT(*) as cnt FROM cards WHERE updated_at >= ?').get(dayAgo)
+  const weekRow = db.prepare('SELECT COUNT(*) as cnt FROM cards WHERE updated_at >= ?').get(weekAgo)
+  const tagRows = db.prepare('SELECT tags FROM cards').all()
   const tagSet = new Set()
   for (const r of tagRows) { for (const t of JSON.parse(r.tags || '[]')) tagSet.add(t) }
 
-  const todayCardsRows = db.prepare("SELECT * FROM cards WHERE status = 'approved' AND updated_at >= ? ORDER BY updated_at DESC LIMIT 30").all(dayAgo)
+  const todayCardsRows = db.prepare('SELECT * FROM cards WHERE updated_at >= ? ORDER BY updated_at DESC LIMIT 30').all(dayAgo)
   const todayCards = todayCardsRows.map((row) => ({ path: row.path, title: row.title, kind: row.kind, updated: row.updated_at, summary: (row.summary || '').slice(0, 80) }))
 
+  // 隔离区：审核排队情况（侧栏「审核中心」徽标直接读这里）
+  const quarantineRows = db.prepare('SELECT status, COUNT(*) n FROM quarantine GROUP BY status').all()
+  const quarantine = { pending: 0, rejected: 0, deleted: 0 }
+  for (const r of quarantineRows) if (r.status in quarantine) quarantine[r.status] = r.n
+
   return {
     total: totalRow.cnt,
     today: todayRow.cnt,
@@ -777,6 +1000,7 @@ export async function stats(root) {
     tags: tagSet.size,
     byKind,
     todayCards,
+    quarantine,
   }
 }
 
@@ -895,10 +1119,15 @@ export async function addFeedback(root, rec) {
   return { ok: true }
 }
 
-/** 统计：按 kind + status。 */
+/**
+ * 概览：主库（正常区）+ 隔离区（异常区）两份统计。
+ *
+ * `total` / `byKind` / `recent` / `tags` 描述**主库**（agent 能看到的那部分）；
+ * `status` / `quarantine` 描述隔离区（审核中心与回收站）。
+ */
 export async function overview(root) {
   const db = getDb(root)
-  const cards = await listCards(root, { status: ['approved', 'pending', 'rejected'] })
+  const cards = await listCards(root, { status: [MAIN_STATUS] })
   const byKind = {}
   const statusCounts = {}
   for (const c of cards) { byKind[c.kind] = (byKind[c.kind] || 0) + 1; statusCounts[c.status] = (statusCounts[c.status] || 0) + 1 }
@@ -906,12 +1135,24 @@ export async function overview(root) {
   const recent = cards.filter((c) => c.mtime > week).length
   const tagSet = new Set()
   for (const c of cards) for (const t of c.tags) tagSet.add(t)
+
+  // 隔离区统计：按状态 + 按 kind
+  const quarantined = await listCards(root, { status: [...QUARANTINE_STATUSES] })
+  const quarantine = { pending: 0, rejected: 0, deleted: 0, total: quarantined.length }
+  const quarantineByKind = {}
+  for (const c of quarantined) {
+    if (c.status in quarantine) quarantine[c.status] += 1
+    quarantineByKind[c.kind] = (quarantineByKind[c.kind] || 0) + 1
+  }
+
   return {
     total: cards.length,
     byKind,
     recent,
     tags: tagSet.size,
     status: statusCounts,
+    quarantine,
+    quarantineByKind,
     roots: Object.fromEntries(Object.entries(KIND_ROOTS).map(([k, v]) => [k, `${v}/`])),
   }
 }