dsh-prime-memory 0.14.0-beta.3 → 0.14.0-beta.5

package/dist/client.js

@@ -606,7 +606,7 @@ var __defProp = Object.defineProperty;
 		// client/src/tabs/ConflictsTab.tsx
 		var import_jsx_runtime = require("react/jsx-runtime");
 		var POLL_MS = 1e4;
-		var GONE = "（该记录已不在检索库：被合并或删除掉了）";
+		var GONE = "（该记录正文不可得：已不在主表，或被更早的清理清掉了）";
 		function ConflictsTab(props) {
 		  const rpc = props.rpc;
 		  const [view, setView] = (0, import_react2.useState)(null);
@@ -639,7 +639,7 @@ var __defProp = Object.defineProperty;
 		将要退场的记忆：
 		「${doomed}」
 		
-		它会从检索库移除（事实源保留，可从 L0 重建找回）。本操作不可覆盖。`
+		它会移出检索面（不再被召回），但记录仍保留 —— 可在「记忆」页的「已退场」区恢复。裁决结论本身不可覆盖。`
 		      );
 		      if (!ok) return;
 		    }
@@ -3214,24 +3214,25 @@ var __defProp = Object.defineProperty;
 		    const ids = Array.from(sel);
 		    if (ids.length === 0) return;
 		    if (!hiPriv) {
-		      setError("高权限模式未开启：请在右上「高权限：关」或概览页开关中开启后，再删除记忆。");
+		      setError("高权限模式未开启：请在右上「高权限：关」或概览页开关中开启后，再退场记忆。");
 		      return;
 		    }
 		    if (ids.length > DELETE_LIMIT) {
-		      setError("一次最多删除 " + DELETE_LIMIT + " 条（当前勾选 " + ids.length + " 条），请分批操作。");
+		      setError("一次最多退场 " + DELETE_LIMIT + " 条（当前勾选 " + ids.length + " 条），请分批操作。");
 		      return;
 		    }
-		    if (!window.confirm("删除勾选的 " + ids.length + " 条记忆？本操作不可逆（完整重建可能从 L0 复活，为已知边界）。")) return;
+		    if (!window.confirm("退场勾选的 " + ids.length + " 条记忆？\n\n它们会移出检索面（不再被召回），但记录仍保留 —— 可在下方「已退场」区恢复。")) return;
 		    rpc("dsh-memory/records-delete", { ids }).then((r) => {
 		      if (r && r.ok) {
 		        setSel(/* @__PURE__ */ new Set());
 		        if (expandedId && ids.indexOf(expandedId) >= 0) setExpandedId(null);
 		        fetchPage(last, 0, false);
-		      } else if (r) setError(r.error ? r.error.message : "删除失败");
+		        if (showRetired) loadRetired();
+		      } else if (r) setError(r.error ? r.error.message : "退场失败");
 		    }).catch((e) => setError(String(e && e.message || e)));
 		  };
 		  const deleteRecord = (id) => {
-		    if (!window.confirm("删除该条记忆？本操作不可逆（完整重建可能从 L0 复活，为已知边界）。")) return;
+		    if (!window.confirm("退场该条记忆？\n\n它会移出检索面（不再被召回），但记录仍保留 —— 可在下方「已退场」区恢复。")) return;
 		    rpc("dsh-memory/records-delete", { ids: [id] }).then((r) => {
 		      if (r && r.ok) {
 		        setSel((prev) => {
@@ -3241,9 +3242,42 @@ var __defProp = Object.defineProperty;
 		        });
 		        if (expandedId === id) setExpandedId(null);
 		        fetchPage(last, 0, false);
-		      } else if (r) setError(r.error ? r.error.message : "删除失败");
+		        if (showRetired) loadRetired();
+		      } else if (r) setError(r.error ? r.error.message : "退场失败");
 		    }).catch((e) => setError(String(e && e.message || e)));
 		  };
+		  const [retired, setRetired] = (0, import_react15.useState)([]);
+		  const [retiredTotal, setRetiredTotal] = (0, import_react15.useState)(0);
+		  const [showRetired, setShowRetired] = (0, import_react15.useState)(false);
+		  const [retiredBusy, setRetiredBusy] = (0, import_react15.useState)(false);
+		  const loadRetired = (0, import_react15.useCallback)(() => {
+		    setRetiredBusy(true);
+		    rpc("dsh-memory/records-retired", { limit: 100, offset: 0 }).then((r) => {
+		      if (r && r.ok) {
+		        setRetired(r.value.items);
+		        setRetiredTotal(r.value.total);
+		      } else if (r) setError(r.error ? r.error.message : "已退场列表加载失败");
+		    }).catch((e) => setError(String(e && e.message || e))).finally(() => setRetiredBusy(false));
+		  }, [rpc]);
+		  (0, import_react15.useEffect)(() => {
+		    if (showRetired) loadRetired();
+		  }, [showRetired, loadRetired]);
+		  const restoreRecords = (ids) => {
+		    if (ids.length === 0) return;
+		    setRetiredBusy(true);
+		    rpc("dsh-memory/records-restore", { ids }).then((r) => {
+		      if (r && r.ok) {
+		        loadRetired();
+		        fetchPage(last, 0, false);
+		      } else if (r) setError(r.error ? r.error.message : "恢复失败");
+		    }).catch((e) => setError(String(e && e.message || e))).finally(() => setRetiredBusy(false));
+		  };
+		  const RETIRE_REASON_LABEL = {
+		    conflict: "裁决退场",
+		    superseded: "被取代",
+		    manual: "人工退场",
+		    unknown: "已退场"
+		  };
 		  const countText = total !== null ? "共 " + total + " 条" : items.length + " 条" + (hasMore ? "+" : "");
 		  const selCount = sel.size;
 		  return /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)("div", { children: [
@@ -3405,6 +3439,24 @@ var __defProp = Object.defineProperty;
 		        m.id
 		      );
 		    }),
+		    /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)("div", { style: { ...S.flexRow, marginTop: 12 }, children: [
+		      /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(NButton, { onClick: () => setShowRetired((v) => !v), children: (showRetired ? "收起" : "展开") + "「已退场」（可恢复）" }),
+		      showRetired && retiredBusy ? /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("span", { style: S.muted, children: "加载中…" }) : null,
+		      showRetired && !retiredBusy && retiredTotal > 0 ? /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("span", { style: S.muted, children: "共 " + retiredTotal + " 条可恢复" }) : null
+		    ] }),
+		    showRetired ? /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("div", { style: { marginTop: 8 }, children: retired.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("p", { style: S.hint, children: retiredBusy ? " " : "没有已退场的记忆。" }) : /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)("div", { children: [
+		      retired.map((m) => /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)("div", { className: "dsh-mem-card", style: S.card, children: [
+		        /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)("div", { style: S.cardHead, children: [
+		          /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("span", { style: S.muted, children: RETIRE_REASON_LABEL[m.retiredReason] || m.retiredReason }),
+		          m.verdict ? /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("span", { style: S.muted, children: "结论 " + m.verdict }) : null,
+		          /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("div", { style: S.grow }),
+		          /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("span", { style: S.muted, children: fmtTime(m.retiredAt) }),
+		          /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(NButton, { disabled: retiredBusy, title: "恢复到检索面", onClick: () => restoreRecords([m.id]), children: "恢复" })
+		        ] }),
+		        /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("div", { style: S.content, children: m.content })
+		      ] }, m.id)),
+		      retiredTotal > retired.length ? /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("p", { style: S.hint, children: "共 " + retiredTotal + " 条，此处显示 " + retired.length + " 条" }) : null
+		    ] }) }) : null,
 		    hasMore ? /* @__PURE__ */ (0, import_jsx_runtime15.jsxs)("div", { style: S.flexRow, children: [
 		      /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("div", { style: S.grow }),
 		      /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(

package/dist/conflict-service.d.ts

@@ -12,7 +12,7 @@ import type { L1Store } from './store/l1.js';
 import type { ConflictPairView, ConflictsResponse as ConflictsView, ConflictResolveResponse as ConflictResolutionView } from './contract.js';
 export type { ConflictPairView, ConflictsView, ConflictResolutionView };
 export interface ConflictResolveDeps {
-    l1: Pick<L1Store, 'listConflictPending' | 'resolveConflictPending' | 'deleteBatch' | 'syncGraphDisputed'>;
+    l1: Pick<L1Store, 'listConflictPending' | 'resolveConflictPending' | 'retire' | 'syncGraphDisputed'>;
     /** `conflictFreeze.enabled`。未开启时队列恒空,直接给出提示而非静默无操作。 */
     conflictFreezeEnabled: boolean;
 }
@@ -21,9 +21,11 @@ export interface ConflictResolveDeps {
  *
  * 顺序刻意如此:
  * ① **先打 `resolved_at` 再退场 loser**。反过来的话,退场成功但打标失败会留下
- *    "记录已消失、队列里那条仍在待裁决"的状态——人再点一次才发现无据可依。
+ *    "记录已退场、队列里那条仍在待裁决"的状态——人再点一次才发现无据可依。
  *    打标用 `WHERE resolved_at = ''`,天然防重复裁决:第二次调用拿到 0 行即中止。
  * ② 退场后才**重算**图谱 `disputed`(派生字段必须由当前事实重算,见 `syncDisputed`)。
+ * ③ 退场是**软删**(`retire`,可恢复),不是物理删除:主表行留着,`valid_to` 闭合 +
+ *    写取代标记,FTS/向量行撤掉。故"判错了"可以再恢复——裁决不可覆盖,但可以反悔。
  */
 export declare function resolveConflictPair(deps: ConflictResolveDeps, pairId: string, outcome: string): Promise<ConflictResolutionView>;
 /** 裁决结果的人类可读渲染(工具路径用)。schema 产出的是可选字段,故按部分取值渲染。 */

package/dist/conflict-service.js

@@ -7,9 +7,11 @@ function view(partial) {
  *
  * 顺序刻意如此:
  * ① **先打 `resolved_at` 再退场 loser**。反过来的话,退场成功但打标失败会留下
- *    "记录已消失、队列里那条仍在待裁决"的状态——人再点一次才发现无据可依。
+ *    "记录已退场、队列里那条仍在待裁决"的状态——人再点一次才发现无据可依。
  *    打标用 `WHERE resolved_at = ''`,天然防重复裁决:第二次调用拿到 0 行即中止。
  * ② 退场后才**重算**图谱 `disputed`(派生字段必须由当前事实重算,见 `syncDisputed`)。
+ * ③ 退场是**软删**(`retire`,可恢复),不是物理删除:主表行留着,`valid_to` 闭合 +
+ *    写取代标记,FTS/向量行撤掉。故"判错了"可以再恢复——裁决不可覆盖,但可以反悔。
  */
 export async function resolveConflictPair(deps, pairId, outcome) {
     const clean = outcome.trim();
@@ -41,8 +43,17 @@ export async function resolveConflictPair(deps, pairId, outcome) {
         // 并发/重复调用:这一对在本次读取与本次写入之间被裁决了
         return view({ pair_id: pairId, outcome: clean, notice: '该对已被裁决,本次未生效(裁决不可覆盖)。' });
     }
-    if (removedId)
-        await deps.l1.deleteBatch([removedId]);
+    if (removedId) {
+        // **软删**(退场),不是物理删除:主表行保留 + `valid_to` 闭合 + 写取代标记,
+        // FTS/向量行撤掉使其退出检索面。于是"判错了"可以再恢复,而不必去
+        // `records/*.jsonl` 事实源里手工捞——那是本功能上线前唯一的后悔药。
+        deps.l1.retire([removedId], {
+            at: resolvedAt,
+            reason: 'conflict',
+            verdict: clean,
+            pairId,
+        });
+    }
     // 图谱 disputed 重算:此刻仍未裁决的对才是争议集,已了结的节点自动复原 active
     const ids = new Set();
     for (const p of deps.l1.listConflictPending()) {
@@ -59,7 +70,7 @@ export function renderConflictResolution(v) {
     const outcome = v.outcome ?? '';
     const label = outcome === 'winner' ? '判定 LLM 建议的胜方为真' : outcome === 'loser' ? '判定败方为真' : '两者都保留(判为各自独立的事实)';
     const removed = v.removed_record_id
-        ? `\n退场记录:${v.removed_record_id}(已从检索中移除,事实源保留)`
+        ? `\n退场记录:${v.removed_record_id}(已移出检索面,**可恢复**——记忆列表里能找回)`
         : '\n未移除任何记录。';
     return `已裁决待裁决对 ${v.pair_id ?? ''}\n结论:${outcome}(${label})\n裁决时刻:${v.resolved_at ?? ''}${removed}`;
 }

package/dist/contract.d.ts

@@ -610,14 +610,76 @@ export interface ListRecordsResponse {
     /** 场景筛选下拉选项(仅 offset===0 时附带)。 */
     scenes?: string[];
 }
-/** dsh-memory/records-delete(面板高权限删除指定记忆;须 memoryMutate 开启)。 */
+/** dsh-memory/records-delete(面板高权限退场指定记忆;须 memoryMutate 开启)。 */
 export interface RecordsDeleteRequest {
-    /** 要删除的 L1 record id 列表(≤200)。 */
+    /** 要**退场(软删)**的 L1 record id 列表(≤200)。不是物理删除,可恢复。 */
     ids: string[];
 }
 export interface RecordsDeleteResponse {
     deleted: number;
 }
+/**
+ * 已退场记录的一条(在浏览卡片之上补退场信息)。
+ *
+ * `retiredReason` 用宽松 `string` 而非字面量联合:契约要能在**客户端**那一档
+ * (`types: []`)独立编译,不该反向依赖宿主 store 的类型;严格联合留在 store 侧,
+ * 面板只做展示。新增原因时面板不认识也能照常显示,不会编译失败。
+ */
+export interface RetiredRecordView extends UiRecord {
+    /** 退场时刻(ISO 8601)。 */
+    retiredAt: string;
+    /** 退场原因:`conflict`(裁决) / `superseded`(去重取代) / `manual`(人工)。 */
+    retiredReason: string;
+    /** 裁决结论(仅 reason=conflict)。 */
+    verdict?: string;
+    /** 取代它的新记录 id(仅 reason=superseded)。 */
+    supersededBy?: string;
+}
+/** dsh-memory/records-retired(已退场列表;面板据此展示"可恢复"区)。 */
+export interface RecordsRetiredRequest {
+    limit?: number;
+    offset?: number;
+}
+export interface RecordsRetiredResponse {
+    items: RetiredRecordView[];
+    total: number;
+}
+/** dsh-memory/records-restore(把已退场记录送回检索面)。 */
+export interface RecordsRestoreRequest {
+    /** 要恢复的 record id 列表(≤200)。 */
+    ids: string[];
+}
+export interface RecordsRestoreResponse {
+    restored: number;
+    /** 成功补回向量的条数(嵌入不可用时可能小于 `restored`)。 */
+    vectorsWritten: number;
+}
+/**
+ * dsh-memory/cleanup-retired(物理清理已退场记录)。
+ *
+ * **默认干跑**:`dryRun` 省略即视为 `true`,只报"将要清理多少条"。
+ * 真要物理删除必须显式 `dryRun:false` —— 这是本插件唯一不可逆的动作。
+ * 即便显式执行,也要先落快照并校验通过,否则中止(`aborted:true`)。
+ */
+export interface CleanupRetiredRequest {
+    /** 限定要清理的 id;省略 = 全部已退场记录。 */
+    ids?: string[];
+    /** 默认 true(干跑)。显式 false 才真正删除。 */
+    dryRun?: boolean;
+}
+export interface CleanupRetiredResponse {
+    dryRun: boolean;
+    /** 本次涉及(干跑)或实际处理(真跑)的条数。 */
+    targets: number;
+    /** 真正物理删除的条数(干跑恒为 0;中止恒为 0)。 */
+    purged: number;
+    /** 门禁未通过而中止。 */
+    aborted: boolean;
+    /** 快照目录(真跑时非空)。 */
+    dir: string;
+    /** 中止原因(仅 aborted 时非空)。 */
+    diffs: string[];
+}
 /** dsh-memory/graph-search(图谱节点检索;紧凑节点卡)。 */
 export interface GraphSearchRequest {
     /** 自然语言查询(≤4096 字符;空查询返回空)。 */
@@ -903,6 +965,9 @@ export interface DshMemoryRequestMap {
     'dsh-memory/embedding-runtime-cancel': Record<string, never>;
     'dsh-memory/embedding-reindex': Record<string, never>;
     'dsh-memory/embedding-reindex-cancel': Record<string, never>;
+    'dsh-memory/records-retired': RecordsRetiredRequest;
+    'dsh-memory/records-restore': RecordsRestoreRequest;
+    'dsh-memory/cleanup-retired': CleanupRetiredRequest;
 }
 export interface DshMemoryResponseMap {
     'dsh-memory/stats': StatsResponse;
@@ -938,6 +1003,9 @@ export interface DshMemoryResponseMap {
     'dsh-memory/embedding-runtime-cancel': EmbeddingCancelResponse;
     'dsh-memory/embedding-reindex': EmbeddingReindexStartResponse;
     'dsh-memory/embedding-reindex-cancel': EmbeddingCancelResponse;
+    'dsh-memory/records-retired': RecordsRetiredResponse;
+    'dsh-memory/records-restore': RecordsRestoreResponse;
+    'dsh-memory/cleanup-retired': CleanupRetiredResponse;
 }
 /** 全部端点名(client 调用与 host case 表的共用字面量来源)。 */
 export type DshMemoryEndpoint = keyof DshMemoryResponseMap;

package/dist/pipeline/anchors.d.ts

@@ -47,3 +47,18 @@ export declare function withSourceAnchors(metadata: Record<string, unknown> | un
  * 宁可报告"无锚点",也不把半截坐标喂给下游的证据读取器。
  */
 export declare function readSourceAnchors(metadata: unknown): ConversationAnchor[] | undefined;
+/**
+ * 锚点的人类可读标签:**UI 契约(`UiRecord.sourceAnchors`)要的字符串形态**。
+ *
+ * 格式即 `t<turn>` / `t<turn> s<step>`(与 `reconcile.ts` 的证据行同一写法,
+ * 见 contract.ts 对 `sourceAnchors` 的说明)。`step` 缺失就**不写**——
+ * 不得用 0 或相邻事件的 step 补齐(红线 2:坐标永不推算)。
+ *
+ * 刻意**不带 sessionId**:该字段用于跨会话归并排序,而 UI 一行里只有
+ * "这条记忆出在会话内哪个位置",带上 id 反而把可用信息挤掉。
+ */
+export declare function anchorLabel(anchor: ConversationAnchor): string;
+/** 读侧一步到位:`l1_records.metadata_json` → UI 契约的标签数组。
+ *  无锚点返回**空数组**(`UiRecord.sourceAnchors` 的契约语义是"空数组 = 无锚点",
+ *  与 `readSourceAnchors` 的 `undefined` 区分开,故此处完成转换)。 */
+export declare function sourceAnchorLabels(metadata: unknown): string[];

package/dist/pipeline/anchors.js

@@ -88,3 +88,22 @@ export function readSourceAnchors(metadata) {
     }
     return out.length > 0 ? out : undefined;
 }
+/**
+ * 锚点的人类可读标签:**UI 契约(`UiRecord.sourceAnchors`)要的字符串形态**。
+ *
+ * 格式即 `t<turn>` / `t<turn> s<step>`(与 `reconcile.ts` 的证据行同一写法,
+ * 见 contract.ts 对 `sourceAnchors` 的说明)。`step` 缺失就**不写**——
+ * 不得用 0 或相邻事件的 step 补齐(红线 2:坐标永不推算)。
+ *
+ * 刻意**不带 sessionId**:该字段用于跨会话归并排序,而 UI 一行里只有
+ * "这条记忆出在会话内哪个位置",带上 id 反而把可用信息挤掉。
+ */
+export function anchorLabel(anchor) {
+    return anchor.step === undefined ? `t${anchor.turn}` : `t${anchor.turn} s${anchor.step}`;
+}
+/** 读侧一步到位:`l1_records.metadata_json` → UI 契约的标签数组。
+ *  无锚点返回**空数组**(`UiRecord.sourceAnchors` 的契约语义是"空数组 = 无锚点",
+ *  与 `readSourceAnchors` 的 `undefined` 区分开,故此处完成转换)。 */
+export function sourceAnchorLabels(metadata) {
+    return (readSourceAnchors(metadata) ?? []).map(anchorLabel);
+}

package/dist/pipeline/l1.js

@@ -272,7 +272,11 @@ anchorMap) {
             relatedIds.add(c.id);
     }
     const byId = new Map(store.getByIds([...relatedIds]).map((r) => [r.id, r]));
-    const deletedIds = new Set();
+    /**
+     * update/merge 取代掉的旧记录 → **取代它的**新记录 id。
+     * 用 Map 而非 Set:退场标记要带 `by`,否则"被谁取代"只能靠时间猜。
+     */
+    const supersededBy = new Map();
     const added = [];
     /** §C 本轮新冻结的冲突对(应用完新增记录后统一落盘)。 */
     const frozen = [];
@@ -323,11 +327,14 @@ anchorMap) {
             }
             continue;
         }
-        // update / merge:目标记录从检索库删除,合并结果作为新记录追加(版本 +1)
+        // update / merge:目标记录**退场(软删)**,合并结果作为新记录追加(版本 +1)
         // 候选召回按族隔离,合并产物保持新记忆的族标签
         const targets = (decision.target_ids ?? []).filter((id) => byId.has(id));
+        // 同一目标被多条新记录取代时保留**首个**取代者:与 retire 的幂等语义一致
+        // (已退场记录不重复写标记),故先到先得而不是被后者覆盖
         for (const id of targets)
-            deletedIds.add(id);
+            if (!supersededBy.has(id))
+                supersededBy.set(id, m.record_id);
         const targetVersion = targets.reduce((max, id) => Math.max(max, byId.get(id)?.version ?? 0), 0);
         const mergedTs = (decision.merged_timestamps ?? [])
             .map((t) => Date.parse(t))
@@ -356,13 +363,27 @@ anchorMap) {
         });
     }
     await store.appendNew(added);
-    if (deletedIds.size > 0)
-        await store.deleteBatch([...deletedIds]);
-    // §C 自动裁决的执行面:LLM 的 loser 从检索库退场(winner 存活)。
+    if (supersededBy.size > 0) {
+        // **软删**(取代):不是物理删除——主表行保留 + `valid_to` 闭合 + 取代标记,
+        // FTS/向量撤出检索面。于是"合并错了"也能恢复,而不必去 `records/*.jsonl` 手工捞。
+        // 按取代者分组落盘(一次事务一组),避免逐条开事务。
+        const retiredAt = new Date(now).toISOString();
+        const byNewRecord = new Map();
+        for (const [targetId, newId] of supersededBy) {
+            const arr = byNewRecord.get(newId) ?? [];
+            arr.push(targetId);
+            byNewRecord.set(newId, arr);
+        }
+        for (const [newId, ids] of byNewRecord) {
+            store.retire(ids, { at: retiredAt, reason: 'superseded', by: newId });
+        }
+    }
+    // §C 自动裁决的执行面:LLM 的 loser 从检索面退场(winner 存活),同为**软删**。
     // 排在 appendNew 之后——若 loser 恰是**本轮新记忆**(LLM 判定新记忆更差),
-    // 也必须先让它进库再退场,以保证"本轮新增"与"本轮删除"的账面一致。
-    if (autoLosers.size > 0)
-        await store.deleteBatch([...autoLosers]);
+    // 也必须先让它进库再退场,以保证"本轮新增"与"本轮退场"的账面一致。
+    if (autoLosers.size > 0) {
+        store.retire([...autoLosers], { at: new Date(now).toISOString(), reason: 'conflict', verdict: 'auto' });
+    }
     // ── §C 冻结对落盘(排在 appendNew 之后) ──
     // 顺序有讲究:先让新记忆真正进 L1,再登记"它和谁构成待裁决对"。反过来的话,
     // 落盘失败会留下一条指向**不存在记录**的裁决请求,人工打开队列只会看到悬空 id。
@@ -404,7 +425,7 @@ anchorMap) {
         states[f].memoriesSinceL3 += addedByFamily[f];
     }
     markExtracted(states, mode, lastScene);
-    logger.info(`[memory] L1 抽取完成(mode=${mode}):消息 ${pending.length} 条,抽取 ${extracted.length} 条,去重后新增 ${added.length} 条(替换 ${deletedIds.size} 条,chat=${addedByFamily.chat}/work=${addedByFamily.work}),累计 chat=${states.chat.totalExtracted}/work=${states.work.totalExtracted}`);
+    logger.info(`[memory] L1 抽取完成(mode=${mode}):消息 ${pending.length} 条,抽取 ${extracted.length} 条,去重后新增 ${added.length} 条(取代退场 ${supersededBy.size} 条,chat=${addedByFamily.chat}/work=${addedByFamily.work}),累计 chat=${states.chat.totalExtracted}/work=${states.work.totalExtracted}`);
     return { stored: added.length, skipped: false, sceneName: lastScene, newRecords: added };
 }
 /** auto 档取最近活跃的族 checkpoint(情境链/计数锚点)。 */

package/dist/stats.d.ts

@@ -22,7 +22,7 @@ export interface MemoryStatusSource {
     pending(): number;
 }
 /**
- * 端点全集运行时清单(33 个,与 tests/contract-keys.test.ts 的 ENDPOINTS 及
+ * 端点全集运行时清单(36 个,与 tests/contract-keys.test.ts 的 ENDPOINTS 及
  * contract.ts 类型映射表三方对齐,漂移由键集 diff 测试暴露)。
  * 注意:本清单同时是 HTTP 前缀路由 `/dsh-memory/rpc/<短名>` 的**放行白名单**
  * (见下方 SHORT_ENDPOINTS),漏一条 = 该端点在面板里静默消失(404 被客户端

package/dist/stats.js

@@ -21,14 +21,14 @@ import { buildRouteChain, decideSendableEffort, LAYER_DEFAULT_BUDGETS, layerChai
 import { projectDistillChain, validateDistillChain } from './settings.js';
 import { RECEIPTS_QUERY_LIMIT_MAX, dimensionOf, toReceiptView } from './store/receipts.js';
 import { resolveConflictPair, listConflictPairs } from './conflict-service.js';
-// R7:读回锚点走 anchors.ts 的**唯一入口**(形状校验从严),不在 UI 层自行解析 metadata。
-import { readSourceAnchors } from './pipeline/anchors.js';
+import { sourceAnchorLabels } from './pipeline/anchors.js';
+import { readSupersedeMarker } from './store/supersede.js';
 import { errDetail } from './util/filelog.js';
 import { snapshotTokenCost } from './token-cost.js';
 const require = createRequire(import.meta.url);
 export const PLUGIN_VERSION = require('../package.json').version;
 /**
- * 端点全集运行时清单(33 个,与 tests/contract-keys.test.ts 的 ENDPOINTS 及
+ * 端点全集运行时清单(36 个,与 tests/contract-keys.test.ts 的 ENDPOINTS 及
  * contract.ts 类型映射表三方对齐,漂移由键集 diff 测试暴露)。
  * 注意:本清单同时是 HTTP 前缀路由 `/dsh-memory/rpc/<短名>` 的**放行白名单**
  * (见下方 SHORT_ENDPOINTS),漏一条 = 该端点在面板里静默消失(404 被客户端
@@ -72,6 +72,9 @@ export const MEMORY_ENDPOINTS = [
     'dsh-memory/embedding-runtime-cancel',
     'dsh-memory/embedding-reindex',
     'dsh-memory/embedding-reindex-cancel',
+    'dsh-memory/records-retired',
+    'dsh-memory/records-restore',
+    'dsh-memory/cleanup-retired',
 ];
 /** HTTP 路由前缀(客户端 fetch `/dsh-memory/rpc/<短方法名>`)。 */
 const RPC_ROUTE_PREFIX = '/dsh-memory/rpc';
@@ -491,6 +494,7 @@ export async function handleEndpoint(endpoint, payload, deps) {
                     distillMode: '', directBaseURL: '', directApiKey: '',
                     embedRemoteBaseURL: '', embedRemoteApiKey: '', embedRemoteModel: '', embedRemoteDimensions: 0,
                     memoryMutate: false,
+                    conflictFreeze: live?.get()?.conflictFreeze === true,
                 }),
                 // 静态部署上限(cordis.patch.yml):运行时开关与它取 AND
                 ceilings: { capture: cfg.capture.enabled, distill: cfg.extract.enabled, recall: cfg.recall.enabled },
@@ -528,8 +532,8 @@ export async function handleEndpoint(endpoint, payload, deps) {
                 throw new Error('开关通道未初始化');
             const patch = (payload ?? {});
             const clean = {};
-            // 布尔开关组:memoryMutate(高权限写删门)与主开关同列
-            for (const key of ['enabled', 'capture', 'distill', 'recall', 'memoryMutate']) {
+            // 布尔开关组:memoryMutate(高权限写删门)与主开关同列;conflictFreeze(§C 人工冲突裁决)
+            for (const key of ['enabled', 'capture', 'distill', 'recall', 'memoryMutate', 'conflictFreeze']) {
                 if (typeof patch[key] === 'boolean')
                     clean[key] = patch[key];
             }
@@ -729,11 +733,17 @@ export async function handleEndpoint(endpoint, payload, deps) {
         // 未开启冻结时同样走返回体(enabled:false + notice)而非抛错,理由同上。
         case 'dsh-memory/conflicts': {
             const p = (payload ?? {});
-            return listConflictPairs({ l1: stores.l1, conflictFreezeEnabled: cfg.conflictFreeze?.enabled === true }, { limit: Number(p.limit) || undefined });
+            // 冻结开关只有**一个**事实源:与去重管线同一套 effectiveCfg 解析
+            // (live.conflictFreeze 覆盖静态 cfg.conflictFreeze.enabled)。此前这里直接读
+            // cfg.conflictFreeze.enabled —— 面板开关写的是 live,而部署静态值恒 false,
+            // 于是开关已开、settings.yaml 已落 true,本页仍报"矛盾冻结未开启"。
+            return listConflictPairs({ l1: stores.l1, conflictFreezeEnabled: effectiveCfg(cfg, live).conflictFreeze?.enabled === true }, { limit: Number(p.limit) || undefined });
         }
         // ── §C 矛盾冻结裁决(task_25):与 memory_resolve_conflict 工具共用同一形状 ──
         // 端点层同样不给"提示文案"出口的例外只有一条:**队列未开启**不是调用错误而是
         // 部署状态,故它走返回体(带 notice)而非抛错;pair_id/outcome 缺参才抛。
+        // 开关判定与上面 conflicts 同源(effectiveCfg):读端与写端必须看同一份状态,
+        // 否则会出现"列表说开着、裁决说没开"的自相矛盾。
         case 'dsh-memory/conflict-resolve': {
             const p = (payload ?? {});
             const pairId = typeof p.pairId === 'string' ? p.pairId.trim() : '';
@@ -742,10 +752,15 @@ export async function handleEndpoint(endpoint, payload, deps) {
                 throw new Error('需要 pairId(待裁决对的 pair_id)');
             if (!outcome)
                 throw new Error('需要 outcome(winner | loser | both)');
-            return await resolveConflictPair({ l1: stores.l1, conflictFreezeEnabled: cfg.conflictFreeze?.enabled === true }, pairId, outcome);
+            return await resolveConflictPair({ l1: stores.l1, conflictFreezeEnabled: effectiveCfg(cfg, live).conflictFreeze?.enabled === true }, pairId, outcome);
         }
         case 'dsh-memory/records-delete': {
-            // 面板高权限删除指定记忆;写入删权限门(memoryMutate)防御
+            // 面板高权限删除指定记忆;写入删权限门(memoryMutate)防御。
+            //
+            // **软删**(退场),不是物理删除:与裁决 / 取代共用同一原语。面板上的"删除"
+            // 因此可撤销;真要抹掉数据只能走 `cleanup-retired`(先落快照 + 校验通过才删)。
+            // 这样 `deleteL1Batch` 在整个代码里**只有一个调用方**(exportThenPurge),
+            // "物理删除必须先有可信导出物"就成了结构性事实,而不是一句约定。
             if (!live?.get().memoryMutate) {
                 throw new Error('记忆写删未开放:请在记忆库面板开启高权限模式');
             }
@@ -753,9 +768,101 @@ export async function handleEndpoint(endpoint, payload, deps) {
             const ids = (Array.isArray(p.ids) ? p.ids : []).filter((x) => typeof x === 'string').slice(0, 200);
             if (ids.length === 0)
                 throw new Error('ids 缺失');
-            await stores.l1.deleteBatch(ids);
-            deps.logger.info(`[memory] 高权限删除记忆 ${ids.length} 条(${ids.join('，')})`);
-            return { deleted: ids.length };
+            const n = stores.l1.retire(ids, { at: new Date().toISOString(), reason: 'manual' });
+            deps.logger.info(`[memory] 高权限退场(软删)记忆 ${n} 条(${ids.join('，')})`);
+            return { deleted: n };
+        }
+        // ── 记忆退场(软删)与清理:已退场列表 / 恢复 / 物理清理 ──
+        // 读方向**不开**权限门(与 conflicts 一致:看得见才知道要不要恢复);
+        // 恢复与物理清理由 memoryMutate 门控。
+        case 'dsh-memory/records-retired': {
+            const p = (payload ?? {});
+            const limit = Math.min(Math.max(Math.floor(Number(p.limit)) || 50, 1), 200);
+            const offset = Math.min(Math.max(Math.floor(Number(p.offset)) || 0, 0), 1_000_000);
+            const { items, total } = stores.l1.listRetired({ limit, offset });
+            const resp = {
+                items: items.map((r) => {
+                    const mark = readSupersedeMarker(r.metadata);
+                    const view = hitToUiRecord(r);
+                    return {
+                        ...view,
+                        // 标记缺失时退回 `valid_to`(软删的两条判据任一成立即算已退场)
+                        retiredAt: mark?.at ?? (r.validTo !== undefined ? new Date(r.validTo).toISOString() : ''),
+                        retiredReason: mark?.reason ?? 'unknown',
+                        ...(mark?.verdict ? { verdict: mark.verdict } : {}),
+                        ...(mark?.by ? { supersededBy: mark.by } : {}),
+                    };
+                }),
+                total,
+            };
+            return resp;
+        }
+        case 'dsh-memory/records-restore': {
+            if (!live?.get().memoryMutate) {
+                throw new Error('记忆写删未开放:请在记忆库面板开启高权限模式');
+            }
+            const p = (payload ?? {});
+            const ids = (Array.isArray(p.ids) ? p.ids : [])
+                .filter((x) => typeof x === 'string' && x !== '')
+                .slice(0, 200);
+            if (ids.length === 0)
+                throw new Error('ids 缺失');
+            const r = await stores.l1.restore(ids);
+            deps.logger.info(`[memory] 恢复已退场记忆 ${r.restored} 条(补向量 ${r.vectorsWritten} 条)`);
+            const resp = r;
+            return resp;
+        }
+        case 'dsh-memory/cleanup-retired': {
+            if (!live?.get().memoryMutate) {
+                throw new Error('记忆写删未开放:请在记忆库面板开启高权限模式');
+            }
+            const p = (payload ?? {});
+            // **默认干跑**:省略 `dryRun` 即视为 true。物理删除是本插件唯一不可逆的动作,
+            // 必须由调用方显式要求才做(与"所有破坏性动作必须默认可回滚"同一条纪律)。
+            const dryRun = p.dryRun !== false;
+            const explicit = (Array.isArray(p.ids) ? p.ids : [])
+                .filter((x) => typeof x === 'string' && x !== '')
+                .slice(0, 500);
+            let targets;
+            if (explicit.length > 0) {
+                // 显式 id 也要**复核**是否真的处于已退场态:防止调用方用一个 id 列表
+                // 把活动记忆绕过软删直接物理抹掉(那等于给了一条硬删后门)。
+                targets = explicit.filter((id) => stores.l1.getByIds([id]).some((r) => r.validTo !== undefined));
+            }
+            else {
+                targets = [];
+                for (let offset = 0;; offset += 200) {
+                    const page = stores.l1.listRetired({ limit: 200, offset });
+                    targets.push(...page.items.map((r) => r.id));
+                    if (page.items.length < 200)
+                        break;
+                }
+            }
+            if (dryRun) {
+                const resp = {
+                    dryRun: true,
+                    targets: targets.length,
+                    purged: 0,
+                    aborted: false,
+                    dir: '',
+                    diffs: [],
+                };
+                return resp;
+            }
+            if (targets.length === 0) {
+                const resp = { dryRun: false, targets: 0, purged: 0, aborted: false, dir: '', diffs: [] };
+                return resp;
+            }
+            const r = await stores.l1.purgeRetired(targets, 'cleanup-retired');
+            const resp = {
+                dryRun: false,
+                targets: targets.length,
+                purged: r.purged,
+                aborted: r.aborted,
+                dir: r.dir,
+                diffs: r.diffs,
+            };
+            return resp;
         }
         // ── 知识图谱(面板图谱视图;graph 未装配时返空不报错) ──
         case 'dsh-memory/graph-search': {
@@ -1058,11 +1165,16 @@ export async function handleEndpoint(endpoint, payload, deps) {
             return { cancelled: embedManager.cancelRuntimeInstall() };
         }
         case 'dsh-memory/embedding-reindex': {
+            // 手动触发重建(契约:`EmbeddingReindexStartResponse`,受理即返回,进度照旧轮询
+            // embedding-state-get 的 reindex 字段)。此前只登记了 -cancel:start 既不在白名单
+            // 也没有 case,于是 startReindex() 成了够不着的死代码,端点在面板上静默 404
+            // (契约门禁 tests/contract-keys.test.ts 早已为此标红)。
+            // 拒绝语义交给 startReindex 自己抛(已卸载/在跑/切源占锁/源未就绪),不在端点层复述。
             if (!embedManager)
-                throw new Error('嵌入管理器未初始化');
-            // 全部门槛判定收在 startReindex 里（含"未就绪时 reindex 会静默 0/0/0"这条），
-            // 此处不重复实现一遍——两处判定必然漂移，而这里漂移的后果是谎报成功。
-            return embedManager.startReindex();
+                throw new Error('嵌入管理器未初始化(存储不可用)');
+            const r = embedManager.startReindex();
+            deps.logger.info('[memory] 收到嵌入重建指令(设置页按钮)');
+            return r;
         }
         case 'dsh-memory/embedding-reindex-cancel': {
             if (!embedManager)
@@ -1087,19 +1199,14 @@ function hitToUiRecord(r) {
         createdAt: r.createdAt ? new Date(r.createdAt).toISOString() : null,
         updatedAt: r.updatedAt ? new Date(r.updatedAt).toISOString() : null,
         version: r.version ?? 0,
-        sourceAnchors: (readSourceAnchors(r.metadata) ?? []).map(formatAnchor),
+        // R7 来源锚点:契约字段是**标签数组**(`t12 s3`),由 metadata 的保留键读出。
+        // 此前这里仍在填已废弃的 `sourceMessageIds`——`l1_records` 从不存那一列,
+        // 该字段恒为 `[]`(死字段),而契约早已换成 `sourceAnchors`,于是
+        // `sourceAnchors` 永远缺失、来源行在 UI 上从未显示过。
+        sourceAnchors: sourceAnchorLabels(r.metadata),
         score: r.score ?? null,
     };
 }
-/**
- * 锚点的展示形态:`t12 s3` / 无 step 时 `t12`。
- *
- * 只做**可读化**,不携带 sessionId——单条记录的来源会话由记录自身语义决定,
- * 把 sessionId 塞进这一行会把 12 个字符的坐标变成 40 个字符。
- */
-function formatAnchor(a) {
-    return typeof a.step === 'number' ? `t${a.turn} s${a.step}` : `t${a.turn}`;
-}
 /**
  * 从文件尾反向分块读取最后 N 行:不整读全文件(轮转上限 2MB,整读会
  * 阻塞事件循环数毫秒)。原始 Buffer 拼接后再解码——分块边界可能切在