dsh-lite-memory 0.16.2 → 0.17.0

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',
@@ -110,7 +122,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'),
@@ -148,6 +160,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 +180,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,
@@ -179,6 +207,7 @@ export function loadIndex(scope, options = {}) {
     __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,10 +219,11 @@ 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)) : [];
@@ -211,7 +241,7 @@ export function saveIndex(scope, index) {
   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);
+    applyFlat(scope, draft, index);
     const after = JSON.stringify([draft.entries, draft.candidates, draft.receipts, draft.suppressions, draft.lastSuggestedAt]);
     return { changed: before !== after };
   });
@@ -311,17 +341,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,7 +368,8 @@ 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'));
+  /** 凭据扫描必须覆盖完整原文：截短后的摘要看不出凭据，原文里有也不行。 */
+  const secret = detectSecret([title, summary, rawSummary, when, body, tags.join(' '), topicKey || ''].join('\n'));
   if (secret) throw new Error(`疑似凭据（${secret}），只记位置，不记值`);
   return {
     id,
@@ -347,7 +379,10 @@ export function normalizeDraft(source, options = {}) {
     body,
     summaryShortened,
     summaryRaw: rawSummary,
-    autoBody,
+    summaryFull,
+    /** 回执字段：完整原句已另存维护区（不是塞进正文）。 */
+    fullTextSaved: Boolean(summaryFull),
+    /** 兼容旧回执：正文里从来没有托管尾巴，这个字段恒为 false。 */
     fullTextInBody: false,
     kind: kind || 'note',
     tags,
@@ -381,9 +416,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 +451,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));
@@ -607,6 +846,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 +891,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 +912,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);
@@ -752,9 +991,13 @@ function applyDraft(scope, index, source, now, options = {}) {
   if (record) {
     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,7 +1007,8 @@ 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;
+      && next.body === oldBody
+      && summaryFull === (typeof record.summaryFull === 'string' ? record.summaryFull : '');
     if (noop) {
       return { record, merged: true, mergedFrom: null, similar: null, similarList, draft, noop: true, previousBody: oldBody, archived: [] };
     }
@@ -773,6 +1017,7 @@ function applyDraft(scope, index, source, now, options = {}) {
     const nextRecord = {
       ...record,
       ...next,
+      summaryFull,
       aliases: titles,
       versions,
       revision: (record.revision || 1) + 1,
@@ -782,6 +1027,11 @@ 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);
@@ -789,15 +1039,16 @@ function applyDraft(scope, index, source, now, options = {}) {
     return { record, merged: true, mergedFrom, similar: null, similarList, draft, noop: false, 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 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,
@@ -818,8 +1069,12 @@ 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);
@@ -1055,8 +1310,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);
@@ -1098,14 +1386,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 +1443,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 +1452,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 +1484,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 +1524,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 +1536,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 +1584,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,
@@ -1314,6 +1624,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 +1641,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 +2207,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 +2235,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 +2279,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) {
@@ -2456,9 +2821,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 +2838,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 +2865,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 +2899,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 +2918,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 (!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 +2967,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 +3005,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 : [])