dsh-lite-memory 0.16.4 → 0.18.1

package/store.js

@@ -30,6 +30,12 @@ const SECRET_PATTERNS = [
 
 const SUGGESTION_ID = /^sug_[a-z0-9]{6,}$/;
 
+/**
+ * 旧版把超长摘要的原文托管在正文末尾，用这个标记分隔。
+ * 现在只拿它做保守识别：旧正文可以标记待整理，但绝不改写；新写入也不再产生尾巴。
+ */
+const LEGACY_SUMMARY_TAIL = '摘要原文：';
+
 /**
  * 实验来源的条目默认不属于普通记忆读取面：开关关闭、暂停或身份未知时，
  * 老 ID、病史查询和关联跳转都不能把正文带出来。管理面显式传 allowExperimental。
@@ -54,7 +60,11 @@ const bodyCache = new Map();
 
 function cacheBodies(scope, entries) {
   const map = new Map();
-  for (const entry of entries) map.set(entry.id, entry.current && entry.current.body);
+  for (const entry of entries) {
+    const body = entry.current && entry.current.body;
+    /** 空正文不进缓存：归档条目的正文可能冷存，读取时要能回冷存兜底。 */
+    if (typeof body === 'string' && body !== '') map.set(entry.id, body);
+  }
   bodyCache.set(scope.dir, map);
 }
 
@@ -77,6 +87,8 @@ function toFlat(entry) {
     id: entry.id,
     title: current.title || '',
     summary: current.summary || '',
+    /** 超长摘要的完整原句单独托管，不进正文；平铺出来供保存路径与回执核对。 */
+    summaryFull: typeof maintenance.summaryFull === 'string' ? maintenance.summaryFull : '',
     when: current.when || '',
     body: typeof current.body === 'string' ? current.body : '',
     kind: current.kind || 'note',
@@ -91,6 +103,10 @@ function toFlat(entry) {
     reviewState: maintenance.reviewState || 'active',
     created: entry.createdAt || '',
     updated: entry.updatedAt || '',
+    validFrom: typeof entry.validFrom === 'string' && entry.validFrom ? entry.validFrom : (entry.createdAt || ''),
+    validUntil: typeof entry.validUntil === 'string' ? entry.validUntil : '',
+    supersededBy: typeof entry.supersededBy === 'string' ? entry.supersededBy : '',
+    supersedeReason: typeof entry.supersedeReason === 'string' ? entry.supersedeReason : '',
     lastUsed: maintenance.lastUsed || entry.updatedAt || entry.createdAt || '',
     revision: Number(entry.revision) || 1,
     status: entry.status === 'archived' ? 'archived' : 'active',
@@ -110,7 +126,7 @@ function toFlat(entry) {
 
 function fromFlat(record, status) {
   const at = record.updated || record.created || new Date().toISOString();
-  return {
+  const entry = {
     id: record.id,
     revision: Number(record.revision) || 1,
     status: status || (record.status === 'archived' ? 'archived' : 'active'),
@@ -118,6 +134,10 @@ function fromFlat(record, status) {
     ownerProjectId: record.ownerProjectId || '',
     createdAt: record.created || at,
     updatedAt: at,
+    validFrom: typeof record.validFrom === 'string' && record.validFrom ? record.validFrom : (record.created || at),
+    validUntil: typeof record.validUntil === 'string' ? record.validUntil : '',
+    supersededBy: typeof record.supersededBy === 'string' ? record.supersededBy : '',
+    supersedeReason: typeof record.supersedeReason === 'string' ? record.supersedeReason : '',
     current: {
       title: record.title || '',
       summary: record.summary || '',
@@ -148,6 +168,13 @@ function fromFlat(record, status) {
       lastUsed: record.lastUsed || at,
     },
   };
+  /** 完整摘要是维护区字段：显式给了就覆盖，给了空串就清掉，不给则沿用旧值。 */
+  if (Object.prototype.hasOwnProperty.call(record, 'summaryFull')) {
+    const full = typeof record.summaryFull === 'string' ? record.summaryFull : '';
+    if (full) entry.maintenance.summaryFull = full;
+    else delete entry.maintenance.summaryFull;
+  }
+  return entry;
 }
 
 /**
@@ -161,7 +188,16 @@ export function loadIndex(scope, options = {}) {
   }
   const loaded = state.load(scope, options);
   const entries = loaded.state.entries.filter((entry) => entry.status === 'active').map(toFlat);
-  const archived = loaded.state.entries.filter((entry) => entry.status === 'archived').map(toFlat);
+  /**
+   * 归档条目只加载元数据，正文留在冷存里按需读：列表、图谱、宫殿、snapshot 都
+   * 不该为了显示标题去读归档正文，更不能因为某个旧归档缺冷存就把整层读失败。
+   */
+  const archived = loaded.state.entries.filter((entry) => entry.status === 'archived').map((entry) => {
+    const record = toFlat(entry);
+    record.cold = Boolean(entry.maintenance && entry.maintenance[COLD_MARK]);
+    record.coldBody = '';
+    return record;
+  });
   cacheBodies(scope, loaded.state.entries);
   const index = {
     version: 2,
@@ -175,10 +211,12 @@ export function loadIndex(scope, options = {}) {
     receipts: JSON.parse(JSON.stringify(loaded.state.receipts || [])),
     lastSuggestedAt: loaded.state.lastSuggestedAt || '',
     suppressions: JSON.parse(JSON.stringify(loaded.state.suppressions || [])),
+    conflicts: JSON.parse(JSON.stringify(loaded.state.conflicts || [])),
     __evolution: state.evolutionOf(loaded.state),
     __tasks: anchor.normalizeTasks(state.evolutionOf(loaded.state).tasks),
     __control: state.controlOf(loaded.state),
     __exists: loaded.exists === true,
+    __recovery: loaded.recovery || null,
   };
   index.__meta = {
     exists: loaded.exists,
@@ -190,14 +228,16 @@ export function loadIndex(scope, options = {}) {
 }
 
 /** 扁平索引 → v2 状态：整层重写，条目、候选、回执一次换完。 */
-function applyFlat(draft, index) {
+function applyFlat(scope, draft, index) {
   const next = [];
   for (const record of index.entries) next.push(fromFlat(record));
-  for (const record of index.archived || []) next.push(fromFlat(record, 'archived'));
+  /** 归档正文不写回热状态：先落冷存再摘空，冷存写失败就整次保存失败，不丢正文。 */
+  for (const record of index.archived || []) next.push(fromFlat(coldStored(scope, record), 'archived'));
   draft.entries = next;
   draft.candidates = Array.isArray(index.suggestions) ? JSON.parse(JSON.stringify(index.suggestions)) : [];
   draft.receipts = Array.isArray(index.receipts) ? JSON.parse(JSON.stringify(index.receipts)) : [];
   draft.suppressions = Array.isArray(index.suppressions) ? JSON.parse(JSON.stringify(index.suppressions)) : [];
+  draft.conflicts = Array.isArray(index.conflicts) ? JSON.parse(JSON.stringify(index.conflicts)) : [];
   draft.lastSuggestedAt = typeof index.lastSuggestedAt === 'string' ? index.lastSuggestedAt : draft.lastSuggestedAt || '';
   draft.scopeKey = draft.scopeKey || index.scope;
 }
@@ -210,9 +250,10 @@ export function saveIndex(scope, index) {
   const meta = index.__meta || { exists: false };
   const expected = meta.exists ? { generation: meta.generation, epoch: meta.epoch } : null;
   const result = state.transact(scope, { expected, expectCreate: !meta.exists }, (draft) => {
-    const before = JSON.stringify([draft.entries, draft.candidates, draft.receipts, draft.suppressions, draft.lastSuggestedAt]);
-    applyFlat(draft, index);
-    const after = JSON.stringify([draft.entries, draft.candidates, draft.receipts, draft.suppressions, draft.lastSuggestedAt]);
+    const stamp = () => JSON.stringify([draft.entries, draft.candidates, draft.receipts, draft.suppressions, draft.conflicts, draft.lastSuggestedAt]);
+    const before = stamp();
+    applyFlat(scope, draft, index);
+    const after = stamp();
     return { changed: before !== after };
   });
   const published = result.state;
@@ -291,6 +332,7 @@ export function normalizeDraft(source, options = {}) {
   const has = (key) => Object.prototype.hasOwnProperty.call(draft, key) && draft[key] !== undefined;
   const id = typeof draft.id === 'string' && /^mem_[a-z0-9]+$/.test(draft.id) ? draft.id : '';
   if (has('id') && !id) throw new Error('id 格式不对');
+  if (has('supersedes') && !/^mem_[a-z0-9]+$/.test(String(draft.supersedes ?? ''))) throw new Error('supersedes 要给被取代的 id');
   const when = has('when') ? textField(draft.when, LIMITS.whenChars, '前置条件') : '';
   const title = textField(cleanTitle(draft.title), LIMITS.titleChars, '标题');
   /** 带 id 是更新：省略的字段保持原值，标题也一样。 */
@@ -311,17 +353,18 @@ export function normalizeDraft(source, options = {}) {
   const mayOmitSummary = options.requireSummary === false || Boolean(id);
   if (!summary && !mayOmitSummary) throw new Error('摘要为空');
   /**
-   * 正文是否由调用方显式给出，和「摘要太长所以自动补一份」必须分开。
-   * 否则同名更新会被自动补出的正文当成显式覆盖，把原正文冲掉。
+   * 正文只属于调用方显式给出的内容：摘要超长时不再往正文里塞托管尾巴，
+   * 完整原句单独进维护区（maintenance.summaryFull），正文保持原样。
    */
   const bodyExplicit = has('body');
   const body = bodyExplicit ? String(draft.body ?? '').trim() : '';
-  const autoBody = !bodyExplicit && summaryShortened ? rawSummary : '';
-  const checked = bodyExplicit ? body : autoBody;
-  const bodyBytes = Buffer.byteLength(checked);
-  if (bodyBytes > LIMITS.entryBytes) {
-    throw new Error(autoBody
-      ? `摘要 ${rawSummary.length} 字，超过单条 ${LIMITS.entryBytes} 字节；先拆成两条写，别丢后半段`
+  const summaryFull = summaryShortened ? rawSummary : '';
+  const bodyBytes = Buffer.byteLength(body);
+  /** 预算按真正会存进去的正文 + 完整摘要算：超限就报错，不截断后谎报成功。 */
+  const storedBytes = bodyBytes + Buffer.byteLength(summaryFull);
+  if (storedBytes > LIMITS.entryBytes) {
+    throw new Error(summaryFull
+      ? `正文 ${bodyBytes} 字节加完整摘要 ${Buffer.byteLength(summaryFull)} 字节，超过单条 ${LIMITS.entryBytes} 字节；先拆成两条写，别丢后半段`
       : `正文 ${bodyBytes} 字节，超过单条 ${LIMITS.entryBytes} 字节；只留原则、判断规则和触发条件`);
   }
   const kind = has('kind') ? textField(draft.kind, 20, '类型') : 'note';
@@ -337,8 +380,9 @@ export function normalizeDraft(source, options = {}) {
   const links = view.normalizeLinks(draft.links, id);
   const applicability = view.normalizeApplicability(draft.applicability);
   const topicKey = has('topicKey') ? textField(draft.topicKey, LIMITS.tagChars, '主题') : undefined;
-  const secret = detectSecret([title, summary, when, body, tags.join(' '), topicKey || ''].join('\n'));
-  if (secret) throw new Error(`疑似凭据（${secret}），只记位置，不记值`);
+  /** 凭据扫描必须覆盖完整原文：截短后的摘要看不出凭据，原文里有也不行。 */
+  const secret = detectSecret([title, summary, rawSummary, when, body, tags.join(' '), topicKey || ''].join('\n'));
+  if (secret) throw new state.StateError('unsafe', `疑似凭据（${secret}），只记位置，不记值：正文里写「去哪取、怎么取」，不抄值`);
   return {
     id,
     title,
@@ -347,7 +391,10 @@ export function normalizeDraft(source, options = {}) {
     body,
     summaryShortened,
     summaryRaw: rawSummary,
-    autoBody,
+    summaryFull,
+    /** 回执字段：完整原句已另存维护区（不是塞进正文）。 */
+    fullTextSaved: Boolean(summaryFull),
+    /** 兼容旧回执：正文里从来没有托管尾巴，这个字段恒为 false。 */
     fullTextInBody: false,
     kind: kind || 'note',
     tags,
@@ -357,6 +404,8 @@ export function normalizeDraft(source, options = {}) {
     links,
     applicability,
     topicKey,
+    /** 显式取代：新记录写好后再给旧记录打 supersededBy/validUntil。 */
+    supersedes: has('supersedes') ? textField(draft.supersedes, 60, '取代目标') : '',
     has: {
       title: has('title') && Boolean(title),
       summary: has('summary'),
@@ -370,6 +419,7 @@ export function normalizeDraft(source, options = {}) {
       links: links !== undefined,
       applicability: applicability !== undefined,
       topicKey: topicKey !== undefined,
+      supersedes: has('supersedes'),
     },
   };
 }
@@ -381,9 +431,27 @@ function newId() {
 /** 正文就在状态里；缓存只是省一次读盘，得手时一律回状态读。 */
 function readBody(scope, id) {
   const cached = cachedBody(scope, id);
-  if (typeof cached === 'string') return cached;
+  if (typeof cached === 'string' && cached !== '') return cached;
   const found = state.readEntryBody(scope, id);
   if (!found) throw new Error(`记忆正文缺失：${id} 在索引里，但正文文件不在了`);
+  /**
+   * 归档正文不在热状态里：只有真要读这一条正文时才回冷存取，
+   * 缺文件/坏文件都报明确错误，不拿空正文冒充「这条没有正文」。
+   */
+  if (!found.body && found.entry && found.entry.status === 'archived') {
+    let payload = null;
+    try {
+      payload = readCold(scope, id, { required: true });
+    } catch (error) {
+      /** 旧版归档在正文为空时可能没写过冷存：这类老记录按空正文读回，不改写也不再报错。 */
+      const legacy = !(found.entry.maintenance && found.entry.maintenance.coldSaved === true);
+      if (!(legacy && error && error.code === 'cold_missing')) throw error;
+    }
+    if (payload && typeof payload.body === 'string' && payload.body) {
+      writeBody(scope, id, payload.body);
+      return payload.body;
+    }
+  }
   return found.body;
 }
 
@@ -398,6 +466,192 @@ function removeBody(scope, id) {
   if (map) map.delete(id);
 }
 
+/**
+ * 归档正文冷存：热状态只留元数据，正文和旧版本正文放 scope.dir/cold/<id>.json。
+ * 五百条归档 ≈ 2 MiB 时，只有真看过的那几条会回到内存，保存不再被整层预算卡死。
+ */
+const COLD_DIR = 'cold';
+const COLD_MARK = 'coldBody';
+
+function coldDirOf(scope) {
+  return path.join(scope.dir, COLD_DIR);
+}
+
+function coldFileOf(scope, id) {
+  return path.join(coldDirOf(scope), `${id}.json`);
+}
+
+function coldPayload(scope, record) {
+  return {
+    /** 冷存文件自带身份：读回来先核对是不是这一条、这一层，不靠文件名猜。 */
+    id: record.id,
+    scope: scope.key,
+    revision: Number(record.revision) || 1,
+    at: new Date().toISOString(),
+    body: typeof record.body === 'string' ? record.body : '',
+    versions: (Array.isArray(record.versions) ? record.versions : [])
+      .map((version) => ({ at: String((version && version.at) || ''), body: typeof (version && version.body) === 'string' ? version.body : '' }))
+      .filter((version) => version.body),
+  };
+}
+
+/**
+ * 冷存写失败就报错：宁可整次保存失败，也不能把正文悄悄丢掉。
+ * 落盘序列与 state.json 一致（fsync 文件 → rename → fsync 目录）：归档正文只在这里，
+ * 少一步 fsync，崩溃后就是「热状态说有归档、冷存文件是空的」。
+ */
+function writeCold(scope, record) {
+  const file = coldFileOf(scope, record.id);
+  try {
+    state.writeDurable(file, `${JSON.stringify(coldPayload(scope, record))}\n`);
+  } catch (error) {
+    throw new state.StateError('unavailable', `归档正文没写进冷存（${path.basename(file)}）：${(error && error.message) || 'IO 错误'}`);
+  }
+}
+
+/**
+ * 读冷存：文件缺失时按 required 决定返回 null 还是报错；JSON 损坏、身份不符
+ * 一律抛明确错误，绝不静默返回空正文冒充「这条没有正文」。
+ */
+function readCold(scope, id, options = {}) {
+  const required = options.required === true;
+  const file = coldFileOf(scope, id);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      if (!required) return null;
+      throw new state.StateError('cold_missing', `冷存里没有这条的正文备份（${file}）；先修复冷存再读，不拿空正文顶上`);
+    }
+    throw error;
+  }
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    throw new state.StateError('cold_corrupt', `冷存文件不是合法 JSON（${file}）；先修复再读，不拿空正文顶上`);
+  }
+  if (!payload || typeof payload !== 'object' || payload.id !== id || payload.scope !== scope.key || typeof payload.body !== 'string') {
+    throw new state.StateError('cold_corrupt', `冷存文件记录的条目不匹配这一条或这一层（${file}）；先修复再读，不拿空正文顶上`);
+  }
+  return payload;
+}
+
+/** 写回状态前把归档正文摘出去：只有正文/旧版本真变了才重写冷存文件。 */
+function coldStored(scope, record) {
+  if (record.status !== 'archived') return record;
+  const versions = Array.isArray(record.versions) ? record.versions : [];
+  const hasVersionBodies = versions.some((version) => typeof (version && version.body) === 'string' && version.body);
+  /** 内存记录的正文可能已经是空串（占位/摘过）：先按 coldBody、冷存文件、热状态顺序找回。 */
+  let body = typeof record.body === 'string' ? record.body : '';
+  const known = typeof record.coldBody === 'string' ? record.coldBody : null;
+  if (body || known !== null) {
+    body = body || known;
+  } else {
+    /** 冷存是唯一权威副本；它坏了先退回热状态里的正文（保存时会重写成好文件），两处都没有才报错。 */
+    let coldError = null;
+    try {
+      const payload = readCold(scope, record.id);
+      if (payload && typeof payload.body === 'string' && payload.body) body = payload.body;
+    } catch (error) {
+      coldError = error;
+    }
+    if (!body) {
+      const found = state.readEntryBody(scope, record.id);
+      if (found && typeof found.body === 'string') body = found.body;
+    }
+    if (coldError && !body) throw coldError;
+  }
+  /** 正文和冷存里的一致就不重写：五百条归档每次保存只动真变过的那几条。 */
+  const cached = record.cold === true && known !== null && known === body;
+  /** 空正文也要落一份冷存：只要标了 coldBody，就必须有自证身份的文件可读回。 */
+  if (!cached) writeCold(scope, { ...record, body });
+  return {
+    ...record,
+    body: '',
+    cold: true,
+    coldBody: body,
+    versions: versions.map((version) => ({ ...(version || {}), body: '' })),
+    maintenance: { ...(record.maintenance || {}), [COLD_MARK]: true, coldSaved: true },
+  };
+}
+
+/**
+ * 彻底删除是一个事务：先把要删的冷存文件按 id 精确移到层外的隔离区
+ * （state.purge 只扫 scope.dir，所以隔离区必须在层外），state.purge 成功后才丢弃隔离副本；
+ * 失败按错误类型恢复或留待重放收尾。绝不按标题/正文片段扫描别人的冷存文件。
+ */
+const PURGE_TRASH_DIR = '.purge-trash';
+
+function trashDirOf(scope) {
+  const safe = String(scope.key || '').replace(/[^A-Za-z0-9._-]/g, '_') || '_';
+  return path.join(memoryRoot(), PURGE_TRASH_DIR, safe);
+}
+
+/** 只搬走 ids 对应的 <id>.json；别的条目一个字节都不动。 */
+function isolateCold(scope, ids, operationId) {
+  const token = String(operationId || '').replace(/[^A-Za-z0-9._-]/g, '_') || crypto.randomBytes(8).toString('hex');
+  const dir = path.join(trashDirOf(scope), token);
+  const moved = [];
+  for (const id of ids || []) {
+    const from = coldFileOf(scope, id);
+    if (!fs.existsSync(from)) continue;
+    fs.mkdirSync(dir, { recursive: true });
+    const to = path.join(dir, `${id}.json`);
+    fs.renameSync(from, to);
+    moved.push({ from, to });
+  }
+  return { dir, moved };
+}
+
+function restoreCold(isolated) {
+  let restored = true;
+  for (const row of isolated.moved) {
+    try {
+      fs.renameSync(row.to, row.from);
+    } catch {
+      /** 恢复失败就保留整个隔离区：副本还在，重放/人工都能取回，不能顺手删掉。 */
+      restored = false;
+    }
+  }
+  if (restored) dropColdQuarantine(isolated);
+}
+
+function dropColdQuarantine(isolated) {
+  try {
+    fs.rmSync(isolated.dir, { recursive: true, force: true });
+  } catch {
+    /** 删不掉隔离目录不影响删除结果，下次收尾再清。 */
+  }
+}
+
+/** 删除确认后的收尾：清掉这一层隔离区里残留的副本（上一次做到一半留下的）。 */
+function cleanColdQuarantine(scope) {
+  try {
+    fs.rmSync(trashDirOf(scope), { recursive: true, force: true });
+  } catch {
+    /** 收尾清不掉不影响数据正确性。 */
+  }
+}
+
+/**
+ * 删除与冷存的一致顺序：隔离 → 发布删除 → 丢弃隔离副本。
+ * 发布失败（例如 purge_pending）时保留隔离副本，留给重放路径收尾。
+ */
+function purgeWithCold(scope, ids, run) {
+  const isolated = isolateCold(scope, ids);
+  try {
+    const result = run();
+    dropColdQuarantine(isolated);
+    return result;
+  } catch (error) {
+    if (error && error.code === 'purge_pending') throw error;
+    restoreCold(isolated);
+    throw error;
+  }
+}
+
 function entrySize(record, body) {
   const meta = [record.title || '', record.summary || '', record.when || '', (record.tags || []).join(',')].join('\n');
   return Buffer.byteLength(meta) + Buffer.byteLength(body || '') + Buffer.byteLength(state.fieldsBytesOf(record));
@@ -456,9 +710,9 @@ const STOP_GRAMS = new Set([
   '的话', '这里', '那里', '一个', '一些', '这样', '那样', '看看', '帮我看', '继续',
 ]);
 
-const asciiWordsOf = (text) => normalizeText(text, 400).toLowerCase().match(/[a-z][a-z0-9_-]{1,}/g) || [];
-
-const wordIn = (pool, word) => new RegExp(`(^|[^a-z0-9])${word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}($|[^a-z0-9])`).test(pool);
+/** 英文整词规则只有一份，放在 view：自动召回和手动搜索必须同一个判断。 */
+const asciiWordsOf = view.asciiWordsOf;
+const wordIn = view.wordIn;
 
 /** 查询按空格/标点切成段：多段按关键词处理，整句仍按相关度处理。 */
 function queryRuns(query) {
@@ -573,7 +827,16 @@ export function similarEntries(entries, title, summary, limit = 2) {
     const titleScore = Math.max(0, ...names.map((name) => similarity(name, title)));
     const summaryScore = similarity(item.summary, summary);
     const score = Math.max(titleScore, summaryScore);
-    if (score >= MERGE.near) rows.push({ id: item.id, title: item.title, summary: item.summary, when: item.when || '', score });
+    if (score >= MERGE.near) rows.push({
+      id: item.id,
+      title: item.title,
+      summary: item.summary,
+      when: item.when || '',
+      /** 候选要能自己解释「为什么像」：标题相近，还是同一主题槽位。 */
+      updated: item.updated || item.created || '',
+      reason: titleScore >= MERGE.near ? 'similar_title' : 'similar_summary',
+      score,
+    });
   }
   rows.sort((a, b) => b.score - a.score);
   return rows.slice(0, limit);
@@ -607,6 +870,7 @@ function snapshot(record, body) {
     at: record.updated || record.created || new Date().toISOString(),
     title: record.title,
     summary: record.summary,
+    summaryFull: typeof record.summaryFull === 'string' ? record.summaryFull : '',
     when: record.when || '',
     kind: record.kind || 'note',
     tags: [...(record.tags || [])],
@@ -651,12 +915,12 @@ function rulesOf(draft, body, index, foreign) {
   return rules;
 }
 
-/** 长摘要的尾部不能丢：正文里没有这段时补在末尾，已有则不动。 */
-function bodyWithSummaryTail(body, draft) {
-  const raw = String(draft.summaryRaw || '');
-  const current = String(body || '');
-  if (!raw || !draft.summaryShortened || current.includes(raw)) return { body: current, added: false };
-  return { body: current ? `${current}\n\n摘要原文：${raw}` : raw, added: true };
+/**
+ * 旧正文里可能留着「摘要原文：」尾巴：只识别、做标记，绝不改写。
+ * 猜不出来哪一段是托管内容，删错就是把用户原话删了。
+ */
+function hasLegacySummaryTail(text) {
+  return typeof text === 'string' && text.includes(LEGACY_SUMMARY_TAIL);
 }
 
 function mergedFields(draft, record, oldBody, index, writeMode = 'patch', foreign) {
@@ -672,9 +936,8 @@ function mergedFields(draft, record, oldBody, index, writeMode = 'patch', foreig
       selection: draft.has.selection ? draft.selection : null,
       links: draft.has.links ? draft.links : [],
       topicKey: draft.has.topicKey ? draft.topicKey : '',
-      body: bodyWithSummaryTail(draft.body, draft).body,
+      body: String(draft.body || ''),
     };
-    if (next.body !== draft.body) draft.fullTextInBody = true;
     next.applicability = view.validateApplicability(draft.has.applicability ? draft.applicability : undefined,
       next.conditions, next.selection, next.when);
     assertLinksVisible(next.links, index, foreign);
@@ -707,36 +970,74 @@ function mergedFields(draft, record, oldBody, index, writeMode = 'patch', foreig
   return next;
 }
 
+/** 已被取代或过了有效期：默认检索看不见，明确要 history 时仍可查到并读正文。 */
+function staleRecord(record, now = Date.now()) {
+  if (record.supersededBy) return true;
+  const until = Date.parse(record.validUntil || '');
+  return Number.isFinite(until) && until <= now;
+}
+
+/** 给旧记录打上取代链：正文快照交回调用方，放进新记录的 versions 链头。 */
+function stampSupersede(scope, target, nextId, now) {
+  if (target.supersededBy) {
+    throw new state.StateError('conflict', `这条记忆已经被 ${target.supersededBy} 取代，不能再取代一次`);
+  }
+  if (target.id === nextId) throw new Error('不能取代自己');
+  const versions = snapshot(target, readBody(scope, target.id));
+  target.validUntil = now;
+  target.supersededBy = nextId;
+  target.supersedeReason = 'user_replaced';
+  return versions;
+}
+
 /**
  * 一次写入的纯业务部分：校验、身份、字节预算、版本。不改盘（正文写入由调用方在同一把锁里做）。
  */
 function applyDraft(scope, index, source, now, options = {}) {
   const draft = normalizeDraft(source);
+  scanUnsafe(draft);
   const foreign = options.foreignEntries || [];
   const distinct = source && source.resolution === 'distinct';
+  /** 取代/过期记录不参与合并判断：新内容不该再合进一条已经不是现行的记录。 */
+  const live = index.entries.filter((item) => !staleRecord(item));
+  const supersedeTarget = (selfId) => {
+    if (!draft.supersedes) return null;
+    const target = index.entries.find((item) => item.id === draft.supersedes);
+    if (!target) throw new Error(`要取代的记忆不在这一层：${draft.supersedes}`);
+    if (target.id === selfId) throw new Error('不能取代自己');
+    return target;
+  };
   let record = draft.id ? index.entries.find((item) => item.id === draft.id) : null;
   if (draft.id && !record) throw new Error('没有这条记忆，改用新增');
   let mergedFrom = null;
   let similarList = [];
   if (!record) {
     /** distinct 是用户明确说的「这是另一条」：同名也另起一条，不被规范化后的精确同名吞掉。 */
-    const hit = distinct ? null : resolveTarget(index.entries, draft);
+    const hit = distinct ? null : resolveTarget(live, draft);
     if (hit) {
       record = hit.target;
       mergedFrom = hit.target.title === draft.title ? null : hit.target.title;
     } else if (draft.has.topicKey && draft.topicKey && !distinct) {
       /** 同一槽位只留一条现行规范：同层同 topicKey + 同条件必须确认是更新还是另一条。 */
-      const slot = index.entries.find((item) => (item.topicKey || '') === draft.topicKey
+      const slot = live.find((item) => (item.topicKey || '') === draft.topicKey
         && view.conditionsKey(item.conditions) === view.conditionsKey(draft.conditions));
       if (slot) {
-        const row = { id: slot.id, title: slot.title, summary: slot.summary || '', revision: slot.revision || 1 };
+        const row = {
+          id: slot.id,
+          title: slot.title,
+          summary: slot.summary || '',
+          when: slot.when || '',
+          updated: slot.updated || slot.created || '',
+          reason: 'same_topic',
+          revision: slot.revision || 1,
+        };
         return { needsResolution: true, sameTopic: true, similarList: [row], similar: row, draft, record: null, merged: false, previousBody: null, archived: [] };
       }
-      similarList = similarEntries(index.entries, draft.title, draft.summary, 2);
+      similarList = similarEntries(live, draft.title, draft.summary, 2);
     } else {
-      similarList = similarEntries(index.entries, draft.title, draft.summary, 2);
+      similarList = similarEntries(live, draft.title, draft.summary, 2);
       /** 同名不同前置条件是用户明确表达的另一条，不走确认；只有换个说法的相近标题才拦。 */
-      const sameName = index.entries.some((item) => [item.title, ...(item.aliases || [])]
+      const sameName = live.some((item) => [item.title, ...(item.aliases || [])]
         .some((name) => String(name || '').toLowerCase() === draft.title.toLowerCase()));
       if (similarList.length > 0 && !distinct && !sameName) {
         return { needsResolution: true, similarList, similar: similarList[0], draft, record: null, merged: false, previousBody: null, archived: [] };
@@ -750,11 +1051,16 @@ function applyDraft(scope, index, source, now, options = {}) {
     }
   }
   if (record) {
+    const target = supersedeTarget(record.id);
     const oldBody = readBody(scope, record.id);
     const next = mergedFields(draft, record, oldBody, index, writeMode, foreign);
-    const tail = bodyWithSummaryTail(next.body, draft);
-    next.body = tail.body;
-    if (tail.added) draft.fullTextInBody = true;
+    /** 正文原样保存：摘要再长也不往正文里补尾巴；完整原句进维护区。 */
+    draft.fullTextInBody = false;
+    /** 摘要这次被改过就按本次结果落 summaryFull：改短即清空，没改则保持原值。 */
+    const summaryFull = draft.has.summary
+      ? (draft.summaryShortened ? String(draft.summaryRaw || '') : '')
+      : (typeof record.summaryFull === 'string' ? record.summaryFull : '');
+    draft.fullTextSaved = Boolean(summaryFull);
     const noop = next.title === record.title && next.summary === record.summary
       && next.when === (record.when || '') && next.kind === (record.kind || 'note')
       && JSON.stringify(next.tags) === JSON.stringify(record.tags || [])
@@ -764,8 +1070,9 @@ function applyDraft(scope, index, source, now, options = {}) {
       && JSON.stringify(next.links) === JSON.stringify(record.links || [])
       && (next.topicKey || '') === (record.topicKey || '')
       && next.applicability === (record.applicability || 'all_in_scope')
-      && next.body === oldBody;
-    if (noop) {
+      && next.body === oldBody
+      && summaryFull === (typeof record.summaryFull === 'string' ? record.summaryFull : '');
+    if (noop && !target) {
       return { record, merged: true, mergedFrom: null, similar: null, similarList, draft, noop: true, previousBody: oldBody, archived: [] };
     }
     const versions = snapshot(record, oldBody);
@@ -773,6 +1080,7 @@ function applyDraft(scope, index, source, now, options = {}) {
     const nextRecord = {
       ...record,
       ...next,
+      summaryFull,
       aliases: titles,
       versions,
       revision: (record.revision || 1) + 1,
@@ -782,22 +1090,36 @@ function applyDraft(scope, index, source, now, options = {}) {
       status: 'active',
       source: record.source || (source && source.source) || 'user_explicit',
     };
+    nextRecord.maintenance = { ...(record.maintenance || {}) };
+    if (summaryFull) nextRecord.maintenance.summaryFull = summaryFull;
+    else delete nextRecord.maintenance.summaryFull;
+    /** 旧正文里的托管尾巴只标记待整理，绝不在这里改写用户正文。 */
+    if (hasLegacySummaryTail(next.body)) nextRecord.maintenance.legacySummaryTail = true;
     nextRecord.bytes = entrySize(nextRecord, next.body);
     const archived = assertFits(scope, index, nextRecord);
     writeBody(scope, record.id, next.body);
     Object.assign(record, nextRecord);
-    return { record, merged: true, mergedFrom, similar: null, similarList, draft, noop: false, previousBody: oldBody, archived };
+    /** 更新让这条重新成为现行版本：旧的取代链标记要摘掉。 */
+    delete record.supersededBy;
+    record.validUntil = '';
+    if (target) {
+      const chain = stampSupersede(scope, target, record.id, now);
+      record.versions = [...chain, ...(record.versions || [])].slice(0, 2);
+    }
+    return { record, merged: true, mergedFrom, similar: null, similarList, draft, noop: Boolean(noop), previousBody: oldBody, archived };
   }
   if (writeMode === 'replace_current') throw new Error('整份替换要先指明是哪条，不能用来新增');
-  const seed = draft.autoBody || draft.body;
-  const tail = bodyWithSummaryTail(seed, draft);
-  const createdBody = tail.body;
-  if (tail.added || draft.autoBody) draft.fullTextInBody = true;
+  /** 新建也只用调用方给的正文：超长摘要的完整原句进维护区，不混进正文。 */
+  const target = supersedeTarget('');
+  const createdBody = draft.body;
+  draft.fullTextInBody = false;
+  draft.fullTextSaved = Boolean(draft.summaryFull);
   const rules = rulesOf(draft, createdBody, index, foreign);
   const created = {
     id: newId(),
     title: draft.title,
     summary: draft.summary,
+    summaryFull: draft.summaryFull,
     when: draft.when,
     kind: draft.kind,
     tags: draft.tags,
@@ -811,6 +1133,10 @@ function applyDraft(scope, index, source, now, options = {}) {
     aliases: [],
     created: now,
     updated: now,
+    validFrom: now,
+    validUntil: '',
+    supersededBy: '',
+    supersedeReason: '',
     lastUsed: now,
     revision: 1,
     status: 'active',
@@ -818,15 +1144,52 @@ function applyDraft(scope, index, source, now, options = {}) {
     hits: 0,
     merges: 0,
     versions: [],
+    maintenance: {},
     bytes: 0,
   };
+  if (draft.summaryFull) created.maintenance.summaryFull = draft.summaryFull;
+  /** 旧正文里的托管尾巴只标记待整理，绝不改写用户正文。 */
+  if (hasLegacySummaryTail(createdBody)) created.maintenance.legacySummaryTail = true;
   created.bytes = entrySize(created, created.body);
   const archived = assertFits(scope, index, created);
   writeBody(scope, created.id, created.body);
   index.entries.push(created);
+  if (target) created.versions = stampSupersede(scope, target, created.id, now);
   return { record: created, merged: false, mergedFrom: null, similar: similarList[0] || null, similarList, draft, noop: false, previousBody: null, archived };
 }
 
+/**
+ * 写入前兜底扫描：记忆会被 memory_read 原样喂回模型，所以只拦形状明确的三类——
+ * 提示注入指令、凭据原文、不可见 Unicode；提到「凭据 / 指令」的正文不算。
+ */
+const UNSAFE_TEXT = [
+  { code: 'injection', why: '像提示注入的指令', fix: '把「指令」改成对规则的描述', test: /ignore\s+(?:all\s+)?(?:previous|prior|above)\s+(?:instructions?|rules?|prompts?)/i },
+  { code: 'injection', why: '像提示注入的指令', fix: '把「指令」改成对规则的描述', test: /忽略(?:上面|以上|此前|之前)?(?:的)?(?:所有)?(?:指令|指示|要求|规则)/ },
+  { code: 'injection', why: '像提示注入的指令', fix: '把「指令」改成对规则的描述', test: /<\/?(?:system|instructions?|prompt|tool_call)[^>]*>/i },
+  { code: 'injection', why: '像提示注入的指令', fix: '把「指令」改成对规则的描述', test: /(?:^|\n)\s*(?:system|assistant)\s*[:：]/i },
+];
+const INVISIBLE = /[\u200B-\u200F\u202A-\u202E\u2060-\u2064\u2066-\u2069\uFEFF]|[\u{E0000}-\u{E007F}]/u;
+const SCAN_FIELD_NAMES = { title: '标题', summary: '摘要', when: '适用场景', body: '正文', tags: '标签', triggers: '触发词', conditions: '条件', selection: '适用范围' };
+
+function scanUnsafe(draft) {
+  const fields = [
+    ['title', draft.title], ['summary', draft.summary], ['when', draft.when], ['body', draft.body],
+    ['tags', (draft.tags || []).join('\n')], ['triggers', (draft.triggers || []).join('\n')],
+    ['conditions', JSON.stringify(draft.conditions || [])], ['selection', JSON.stringify(draft.selection || null)],
+  ];
+  for (const [field, raw] of fields) {
+    const text = typeof raw === 'string' ? raw : '';
+    if (!text) continue;
+    const name = SCAN_FIELD_NAMES[field] || field;
+    if (INVISIBLE.test(text)) {
+      throw new state.StateError('unsafe', `${name}里有看不见的字符（零宽或方向控制）；它们会跟着记忆原样回到模型，删掉再存`);
+    }
+    for (const rule of UNSAFE_TEXT) {
+      if (rule.test.test(text)) throw new state.StateError('unsafe', `${name}${rule.why}；${rule.fix}`);
+    }
+  }
+}
+
 /**
  * 单条与记录序列化两档预算：新增与更新走同一套。
  * 整层条数/正文预算由 state.transact 在发布前裁决（腾最久没读的那条，不拒绝新记忆），
@@ -1055,8 +1418,41 @@ export function setTaskDefault(scope, defaults, options = {}) {
  * 返回的记录带着「本次检索之前」的 lastUsed，给 renderIndex 判断陈旧用；
  * 命中计数在返回前写入，所以同一次调用既改盘又不污染展示。
  */
+/** 「用过」的判定门槛：lastUsed 超过这么久才回写，检索不至于每次都抢锁落盘。 */
+const USED_TOUCH_MS = 10 * 60 * 1000;
+
+function usedStale(record, now) {
+  const at = Date.parse(String((record && (record.lastUsed || record.updated)) || ''));
+  return !Number.isFinite(at) || now - at >= USED_TOUCH_MS;
+}
+
+/**
+ * 真正被搜到/读过才算用过：只回写 lastUsed，不动 hits，也不改正文。
+ * 抢不到锁或并发冲突都吞掉——这个是提示字段，不该让检索/阅读失败。
+ */
+function touchUsed(scope, ids) {
+  const wanted = new Set((ids || []).filter((id) => typeof id === 'string' && id));
+  if (wanted.size === 0) return;
+  try {
+    withLock(scope, () => {
+      const index = loadIndex(scope);
+      const now = Date.now();
+      const stamp = new Date(now).toISOString();
+      let changed = false;
+      for (const record of index.entries) {
+        if (!wanted.has(record.id) || !usedStale(record, now)) continue;
+        record.lastUsed = stamp;
+        changed = true;
+      }
+      if (changed) saveIndex(scope, index);
+    });
+  } catch {
+    /* lastUsed 只是提示：失败不影响这次检索/阅读的结果。 */
+  }
+}
+
 export function search(scope, query, limit = 4, options = {}) {
-  return withLocks([scope, globalScope()], () => {
+  const found = withLocks([scope, globalScope()], () => {
     const grams = bigrams(query);
     if (grams.size === 0) return [];
     const runs = queryRuns(query);
@@ -1071,6 +1467,8 @@ export function search(scope, query, limit = 4, options = {}) {
       const collect = (pool, archived) => {
         for (const item of pool) {
           if (!readableRecord(item, options, index)) continue;
+          /** 被取代/过期待记录默认不出现；history:true 才列出，供模型看演化。 */
+          if (options.history !== true && staleRecord(item, options.now || Date.now())) continue;
           /** 已暂停、已过期或待确认的学习规则不进入检索结果，除非明确要病史。 */
           if (options.allowExperimental === true && options.history !== true
             && isExperimentalRecord(item) && !view.experimentalUsable(item, options.now)) continue;
@@ -1098,14 +1496,23 @@ export function search(scope, query, limit = 4, options = {}) {
       || Number(a.archived) - Number(b.archived)
       || String(b.item.lastUsed).localeCompare(String(a.item.lastUsed)));
     const chosen = visible.slice(0, limit);
-    /** 检索不改盘：hits/lastUsed 只在用户真的处理过结果时才算数。 */
+    /** hits 不在检索里记，lastUsed 也只在锁外补写；这里先把层信息和结果一起带出去。 */
     return chosen.map((row) => ({
-      ...row.item,
-      scope: row.source.key === 'global' ? 'global' : 'project',
-      status: row.archived ? 'archived' : view.statusOf(row.item, options.context || {}),
+      record: {
+        ...row.item,
+        scope: row.source.key === 'global' ? 'global' : 'project',
+        status: row.archived ? 'archived' : view.statusOf(row.item, options.context || {}),
+        archived: Boolean(row.archived),
+      },
+      source: row.source,
       archived: Boolean(row.archived),
     }));
   });
+  /** 锁外回写：在层锁里再抢同一层的锁会死锁。 */
+  for (const row of found) {
+    if (!row.archived) touchUsed(row.source, [row.record.id]);
+  }
+  return found.map((row) => row.record);
 }
 
 /**
@@ -1146,7 +1553,7 @@ export function peek(scope, query, limit = 3, options = {}) {
 }
 
 export function readEntry(scope, id, options = {}) {
-  return withLocks([scope, globalScope()], () => {
+  const found = withLocks([scope, globalScope()], () => {
     for (const source of [scope, globalScope()]) {
       const index = loadIndex(source);
       const record = index.entries.find((item) => item.id === id);
@@ -1155,14 +1562,22 @@ export function readEntry(scope, id, options = {}) {
       if (!readableRecord(record || archived, options, index)) continue;
       const body = readBody(source, id);
       return {
-        ...(record || archived),
-        scope: source.key === 'global' ? 'global' : 'project',
-        body,
-        status: archived ? 'archived' : view.statusOf(record, options.context || {}),
+        source,
+        archived: Boolean(archived),
+        record: {
+          ...(record || archived),
+          scope: source.key === 'global' ? 'global' : 'project',
+          body,
+          status: archived ? 'archived' : view.statusOf(record, options.context || {}),
+        },
       };
     }
     return null;
   });
+  if (!found) return null;
+  /** 读过才算用过；归档的不回写（看病史不等于「在用」）。 */
+  if (!found.archived) touchUsed(found.source, [id]);
+  return found.record;
 }
 
 /**
@@ -1179,7 +1594,9 @@ export function forget(scope, id, options = {}) {
       for (const source of [scope, globalScope()]) {
         const pending = state.purgeIntent(source);
         if (!pending) continue;
-        const result = state.purge(source, { resume: true });
+        /** 冷存里有待删条目的正文副本：先隔离，state.purge 的残留扫描才收得干净。 */
+        const result = purgeWithCold(source, pending.ids, () => state.purge(source, { resume: true }));
+        cleanColdQuarantine(source);
         removeBody(source, id);
         if (pending.ids.includes(id)) {
           replayed = {
@@ -1217,7 +1634,8 @@ export function forget(scope, id, options = {}) {
       }
       if (archived) {
         /** 归档条目也能彻底删除：state.purge 本来就按 id 清整份状态，只是以前没走到这里。 */
-        const result = state.purge(source, { ids: [id], operationId: options.operationId });
+        const result = purgeWithCold(source, [id], () => state.purge(source, { ids: [id], operationId: options.operationId }));
+        cleanColdQuarantine(source);
         removeBody(source, id);
         return {
           id,
@@ -1228,7 +1646,8 @@ export function forget(scope, id, options = {}) {
           scopeKey: source.key,
         };
       }
-      const result = state.purge(source, { ids: [id], operationId: options.operationId });
+      const result = purgeWithCold(source, [id], () => state.purge(source, { ids: [id], operationId: options.operationId }));
+      cleanColdQuarantine(source);
       removeBody(source, id);
       return {
         id,
@@ -1275,8 +1694,9 @@ function findCurrent(id, scope, options = {}) {
     const record = index.entries.find((item) => item.id === id && item.status !== 'archived');
     if (!record) continue;
     if (!readableRecord(record, options, index)) continue;
-    /** 关联目标也按本轮上下文判适用；条件未知、过期或暂停的目标不给标题。 */
-    if (view.statusOf(record, options.context || {}) !== 'ok') continue;
+    /** 关联目标与来源走同一资格门槛：项目归属、学习状态、条件适用缺一不可。 */
+    const gate = view.eligibility(record, options.runtime || {}, 'read', options.now || Date.now());
+    if (!gate.ok || gate.status !== 'ok') continue;
     if (isExperimentalRecord(record) && !view.experimentalUsable(record, options.now)) continue;
     return {
       id: record.id,
@@ -1284,6 +1704,8 @@ function findCurrent(id, scope, options = {}) {
       summary: record.summary || '',
       scope: source.key === 'global' ? 'global' : 'project',
       revision: record.revision || 1,
+      validUntil: record.validUntil || '',
+      supersededBy: record.supersededBy || '',
       status: 'ok',
     };
   }
@@ -1314,6 +1736,7 @@ export function undoChange(scope, id, options = {}) {
         ...record,
         title: last.title || record.title,
         summary: last.summary || record.summary,
+        summaryFull: typeof last.summaryFull === 'string' ? last.summaryFull : '',
         when: last.when || '',
         kind: last.kind || record.kind,
         tags: Array.isArray(last.tags) ? last.tags : record.tags,
@@ -1330,6 +1753,9 @@ export function undoChange(scope, id, options = {}) {
       };
       writeBody(source, record.id, last.body);
       Object.assign(record, restored);
+      record.maintenance = { ...(record.maintenance || {}) };
+      if (record.summaryFull) record.maintenance.summaryFull = record.summaryFull;
+      else delete record.maintenance.summaryFull;
       record.bytes = entrySize(record, last.body);
       try {
         saveIndex(source, index);
@@ -1893,6 +2319,27 @@ const ENVIRONMENT_KEYS = ['machine', 'targetOs', 'runtime', 'shell'];
  * 范围路由：用户明确说的范围最高；没有就按记忆类别提案，设备事实必须带设备条件。
  * 判不出来就返回 needsScope，让调用方问一句，而不是默默写进某一层。
  */
+/** 本机痕迹：路径、回环地址、端口。带这些字样的「通用」规则换个项目就用不了。 */
+const MACHINE_BOUND_PATTERNS = [
+  /(?:^|[\s(（'"`])(?:\/tmp|\/Users|\/home|\/opt|\/private|\/var|\/etc)(?:[\/]|$)/m,
+  /(?:^|[\s(（'"`])~\//m,
+  /(?:^|[^A-Za-z0-9])[A-Za-z]:\\/,
+  /(?:^|[^0-9])127\.0\.0\.1(?::\d+)?/,
+  /(?:^|[^A-Za-z0-9.])localhost(?::\d+)?/,
+  /\b\d{1,3}(?:\.\d{1,3}){3}:\d{2,5}\b/,
+];
+
+function machineBoundText(source) {
+  const text = [source?.title, source?.summary, source?.when, source?.body, source?.topicKey]
+    .filter((value) => typeof value === 'string' && value)
+    .join('\n');
+  return MACHINE_BOUND_PATTERNS.some((re) => re.test(text));
+}
+
+/**
+ * 适用范围判定：内容/依据的普适性优先，模型声明的 scope 只是提案。
+ * 模型说 global、但正文写死了本机路径或依据是本机文件时，先留在项目层（或问一次条件）。
+ */
 export function routeScope(draft, options = {}) {
   const source = draft || {};
   const explicit = source.scope === 'global' || source.scope === 'project' ? source.scope : '';
@@ -1900,9 +2347,30 @@ export function routeScope(draft, options = {}) {
   const projectReady = Boolean(options.project) && options.project.confirmed !== false;
   const cls = typeof source.memoryClass === 'string' ? source.memoryClass : '';
   const durability = typeof source.durability === 'string' ? source.durability : 'durable';
+  const evidence = typeof source.evidenceRef === 'string' ? source.evidenceRef.trim() : '';
+  /** 依据本身是本机文件/路径的，不能算通用流程；正文里带本机痕迹同理。 */
+  const machineBound = machineBoundText(source) || (evidence ? machineBoundText({ title: evidence }) : false);
   const base = { chosenScope: '', reasonCode: '', requiredConditions: [], needsScope: false, explicit };
+  /** 通用层拿不出普适证据时：有项目就留在项目层，没有就问一次运行环境。 */
+  const fallbackToProject = (reasonCode) => {
+    if (projectReady) return { ...base, chosenScope: 'project', reasonCode };
+    return {
+      ...base,
+      needsScope: true,
+      reasonCode: 'needs_environment',
+      requiredConditions: [{ key: 'machine', value: '' }, { key: 'runtime', value: '' }],
+    };
+  };
+  /** 人明确点过「就存全局」才算数；模型自己提的 global 不抵消本机痕迹。 */
+  const humanConfirmed = options.humanScope === true || source.scopeConfirmed === true;
   if (durability === 'task') return { ...base, needsScope: true, reasonCode: 'task_state' };
   if (explicit) {
+    /** 模型自己填的 global 只是提案：本机痕迹、项目事实、无依据的通用流程都按提案降级。 */
+    if (explicit === 'global' && !humanConfirmed) {
+      if (machineBound) return fallbackToProject('machine_bound_scope');
+      if (cls === 'project_fact') return fallbackToProject('model_global_project_fact');
+      if (cls === 'portable_procedure' && !evidence) return fallbackToProject('unbound_evidence');
+    }
     if (explicit === 'project' && !projectReady) {
       const reasonCode = options.project && options.project.confirmed === false ? 'unconfirmed_project' : 'no_project';
       return { ...base, needsScope: true, reasonCode, requiredConditions: [{ key: 'projectRoot', value: '' }] };
@@ -1923,8 +2391,17 @@ export function routeScope(draft, options = {}) {
     }
     return { ...base, chosenScope: 'project', reasonCode: 'class_project_fact' };
   }
-  if (cls === 'personal_preference') return { ...base, chosenScope: 'global', reasonCode: 'class_personal_preference' };
-  if (cls === 'portable_procedure') return { ...base, chosenScope: 'global', reasonCode: 'class_portable_procedure' };
+  if (cls === 'personal_preference') {
+    /** 偏好也分「我的习惯」和「这台机器上的习惯」：后者绑机器，不进通用层。 */
+    if (machineBound) return fallbackToProject('machine_bound_preference');
+    return { ...base, chosenScope: 'global', reasonCode: 'class_personal_preference' };
+  }
+  if (cls === 'portable_procedure') {
+    if (machineBound) return fallbackToProject('machine_bound_procedure');
+    /** 说能搬去别的项目，就要有能搬的依据；没有就先留在本项目。 */
+    if (!evidence) return fallbackToProject('unbound_evidence');
+    return { ...base, chosenScope: 'global', reasonCode: 'class_portable_procedure' };
+  }
   const conditions = view.normalizeConditions(source.conditions) || [];
   const scoped = conditions.some((item) => ENVIRONMENT_KEYS.includes(item.key));
   if (!scoped) {
@@ -1988,6 +2465,9 @@ function crossLayerSimilar(projectScope, targetScope, draft) {
     id: item.id,
     title: item.title,
     summary: item.summary || '',
+    when: item.when || '',
+    updated: item.updated || '',
+    reason: item.reason || 'similar_title',
     revision: item.revision || 1,
     scope: other.key === 'global' ? 'global' : 'project',
   }));
@@ -2004,6 +2484,49 @@ function bindSameTopic(projectScope, ref) {
   return { topicKey: view.topicSlot(record) };
 }
 
+
+/** 冲突队列：只记待办，不预写记忆；最多 20 条。 */
+const CONFLICT_LIMIT = 20;
+
+function queueConflictLocked(scope, draft, candidates) {
+  const index = loadIndex(scope);
+  const title = normalizeText(draft && draft.title, 120);
+  if (!title) return Array.isArray(index.conflicts) ? index.conflicts.length : 0;
+  const scopeKey = scope.key === 'global' ? 'global' : 'project';
+  const now = new Date().toISOString();
+  const rows = Array.isArray(index.conflicts) ? index.conflicts : [];
+  const view = candidates.slice(0, 2).map((item) => ({
+    id: item.id, title: item.title || '', when: item.when || '', reason: item.reason || 'similar_title',
+  }));
+  const hit = rows.find((row) => row.title === title && row.scope === scopeKey);
+  if (hit) {
+    hit.candidates = view;
+    hit.updatedAt = now;
+  } else {
+    rows.push({ id: `cf_${crypto.randomUUID().replace(/-/g, '').slice(0, 12)}`, title, scope: scopeKey, candidates: view, createdAt: now, updatedAt: now });
+  }
+  index.conflicts = rows.slice(-CONFLICT_LIMIT);
+  saveIndex(scope, index);
+  return index.conflicts.length;
+}
+
+function clearConflictLocked(scope, title) {
+  const index = loadIndex(scope);
+  const rows = Array.isArray(index.conflicts) ? index.conflicts : [];
+  const norm = normalizeText(title, 120);
+  const next = rows.filter((row) => !(row.title === norm && row.scope === (scope.key === 'global' ? 'global' : 'project')));
+  if (next.length === rows.length) return rows.length;
+  index.conflicts = next;
+  saveIndex(scope, index);
+  return next.length;
+}
+
+/** 当前层还有几条没处理的冲突。 */
+export function pendingConflictsOf(scope) {
+  const rows = loadIndex(scope).conflicts;
+  return Array.isArray(rows) ? rows.length : 0;
+}
+
 /**
  * 保存的唯一入口：先路由，再在两层里查重（完全相同 → existing_ref；只是相近 → 只给候选），
  * 最后才写。写之前判不出来的范围返回 needsScope，不替用户选。
@@ -2047,6 +2570,7 @@ export function saveEntry(projectScope, source) {
       }
       const near = crossLayerSimilar(projectScope, targetScope, draft);
       if (near.length) {
+        const pendingConflicts = queueConflictLocked(targetScope, draft, near);
         return {
           needsResolution: true,
           crossLayer: true,
@@ -2054,12 +2578,19 @@ export function saveEntry(projectScope, source) {
           similar: near[0],
           draft,
           needsScope: false,
+          pendingConflicts,
           chosenScope: targetScope.key === 'global' ? 'global' : 'project',
         };
       }
     }
     const foreign = targetScope.key === 'global' ? [] : loadIndex(globalScope()).entries;
     const result = upsertLocked(targetScope, next, { foreignEntries: foreign });
+    if (!result.needsResolution) clearConflictLocked(targetScope, draft ? draft.title : next.title);
+    if (result.needsResolution) {
+      const rows = Array.isArray(result.similarList) ? result.similarList : [];
+      const pendingConflicts = queueConflictLocked(targetScope, result.draft || draft, rows);
+      return { ...result, chosenScope: targetScope.key === 'global' ? 'global' : 'project', needsScope: false, reasonCode: routed.reasonCode, pendingConflicts };
+    }
     return { ...result, chosenScope: targetScope.key === 'global' ? 'global' : 'project', needsScope: false, reasonCode: routed.reasonCode };
   });
 }
@@ -2456,9 +2987,15 @@ function economyOf(ledger) {
 }
 
 /** 给整理器的候选规则：只读、有限，不跨项目。 */
+/** 整理器看到的规则顺序与扣尝试时一致：按状态/最近使用排序，不靠插入顺序。 */
+function orderedLearningRules(index) {
+  const visible = learningRulesOf(index).filter(visibleLearningRule);
+  return learning.orderOrganizerRules(visible, { limit: learning.LIMITS.organizerRules });
+}
+
 export function learningRulesForOrganizer(scope) {
   const index = loadIndex(scope);
-  return learningRulesOf(index).filter(visibleLearningRule).slice(0, 8).map(learningRuleView);
+  return orderedLearningRules(index).map(learningRuleView);
 }
 
 /**
@@ -2467,16 +3004,17 @@ export function learningRulesForOrganizer(scope) {
  */
 export function beginLearningAttempt(scope, options = {}) {
   const episodeId = String(options.episodeId || '');
-  if (!episodeId) return { ok: false, reason: '缺少作品标识' };
+  /** 项目层候选没有作品绑定：按项目身份记一次尝试，限额照样生效，不编造作品 id。 */
+  const attemptKey = episodeId || `project:${scope.key}`;
   const now = options.now || Date.now();
   return withLock(scope, () => {
     const index = loadIndex(scope);
     const evolution = index.__evolution;
     if (!evolution.enabled || evolution.compatible === false) return { ok: false, reason: '实验没有开启' };
     if (evolution.policyVersion !== learning.POLICY_VERSION) return { ok: false, reason: '实验策略版本不认' };
-    const check = learning.quota(evolution.learning, { episodeId, now });
+    const check = learning.quota(evolution.learning, { episodeId: attemptKey, now });
     if (!check.ok) return { ...check, learning: evolution.learning };
-    const next = learning.recordAttempt(evolution.learning, { episodeId, now });
+    const next = learning.recordAttempt(evolution.learning, { episodeId: attemptKey, now });
     try {
       const result = state.transact(scope, {
         operationId: options.operationId || '',
@@ -2493,7 +3031,7 @@ export function beginLearningAttempt(scope, options = {}) {
         generation: index.generation,
         episodeId,
         learning: next,
-        rules: learningRulesOf(index).filter(visibleLearningRule).slice(0, 8).map(learningRuleView),
+        rules: orderedLearningRules(index).map(learningRuleView),
         replayed: result.replayed === true,
       };
     } catch (error) {
@@ -2527,7 +3065,11 @@ export function commitLearning(scope, batch = {}) {
   const operationId = String(batch.operationId || '');
   const now = batch.now || Date.now();
   const at = new Date(now).toISOString();
-  if (!episodeId) return { ok: false, reason: '缺少作品标识' };
+  /**
+   * 没绑作品的候选（learning.candidateFrom 在项目层给的空 episodeId）按项目身份提交：
+   * 不编造作品 id，但必须由本项目发起；规则版本、epoch 与目标版本照旧要对得上。
+   */
+  if (!episodeId && String(batch.projectId || '') !== scope.key) return { ok: false, reason: '缺少作品标识' };
   if (!operationId) return { ok: false, reason: '缺少提交标识' };
   if (changes.length > learning.LIMITS.maxChanges) return { ok: false, reason: '一次改动太多' };
   return withLock(scope, () => {
@@ -2542,13 +3084,13 @@ export function commitLearning(scope, batch = {}) {
         if (!evolution || evolution.enabled !== true) throw new Error('实验没有开启，这次整理作废');
         if (evolution.policyVersion !== learning.POLICY_VERSION) throw new Error('实验策略版本不认');
         if (batch.epoch && evolution.epoch !== batch.epoch) throw new Error('实验已经重新开启过，这次整理作废');
-        const episode = episodeOfEvolution(evolution, episodeId);
-        if (!episode) throw new Error('作品已经失效，这次整理作废');
-        if (batch.sessionId) {
+        const episode = episodeId ? episodeOfEvolution(evolution, episodeId) : null;
+        if (episodeId && !episode) throw new Error('作品已经失效，这次整理作废');
+        if (episodeId && batch.sessionId) {
           const focus = evolution.tasks?.sessions?.[batch.sessionId];
           if (!focus || focus.episodeId !== episodeId) throw new Error('这期已经换到别的作品，这轮结果没采用');
         }
-        if (batch.episodeUpdatedAt && episode.updatedAt !== batch.episodeUpdatedAt) throw new Error('用户又改过这期，这次整理作废');
+        if (episode && batch.episodeUpdatedAt && episode.updatedAt !== batch.episodeUpdatedAt) throw new Error('用户又改过这期，这次整理作废');
         const prepared = new Map((Array.isArray(batch.preparedTargets) ? batch.preparedTargets : []).map((row) => [row.id, row]));
         let touched = 0;
         const currentRules = draft.entries.filter((entry) => entry.status === 'active' && isExperimentalRecord(toFlat(entry)));
@@ -2591,6 +3133,11 @@ export function commitLearning(scope, batch = {}) {
               messageIds: (batch.messageIds || []).slice(-3),
               at,
             };
+            /** 用户原句优先取本次改动带的摘录，其次取整批的：四处回执都能看到原话。 */
+            const excerpt = typeof change.sourceExcerpt === 'string'
+              ? change.sourceExcerpt
+              : (typeof batch.sourceExcerpt === 'string' ? batch.sourceExcerpt : '');
+            if (excerpt) evidence.sourceExcerpt = excerpt;
             merged.learning = {
               ...learning.nextLearningState({
                 existing: flat,
@@ -2624,6 +3171,11 @@ export function commitLearning(scope, batch = {}) {
               messageIds: (batch.messageIds || []).slice(-3),
               at,
             };
+            /** 用户原句优先取本次改动带的摘录，其次取整批的：四处回执都能看到原话。 */
+            const excerpt = typeof change.sourceExcerpt === 'string'
+              ? change.sourceExcerpt
+              : (typeof batch.sourceExcerpt === 'string' ? batch.sourceExcerpt : '');
+            if (excerpt) evidence.sourceExcerpt = excerpt;
             const merged = learning.mergeChange(null, change, { now });
             /** 同主题、同条件的新规则并进已有条目：整理器换个措辞不该长出第二条。 */
             const signature = (list) => (Array.isArray(list) ? list : [])