dsh-prime-memory 0.26.5-beta.0 → 0.26.6

package/dist/store/graph-store.js

@@ -19,9 +19,12 @@
  */
 import { randomBytes } from 'node:crypto';
 import { applyGraphProjection } from '../graph/apply.js';
-import { searchGraphNodes } from '../graph/search.js';
-import { GRAPH_JOB_BACKOFF_BASE_MS, GRAPH_JOB_BATCH, GRAPH_JOB_MAX_ATTEMPTS, GRAPH_PRIORITY_BACKFILL, GRAPH_PROJECTOR_VERSION, } from '../graph/types.js';
+import { expandHitRecordIds, searchGraphNodes } from '../graph/search.js';
+import { buildFullView, buildGraphPreview } from '../graph/preview.js';
+import { GRAPH_JOB_BACKOFF_BASE_MS, GRAPH_JOB_BATCH, GRAPH_JOB_MAX_ATTEMPTS, GRAPH_JOB_TRANSIENT_MAX_ATTEMPTS, GRAPH_PRIORITY_BACKFILL, GRAPH_PRIORITY_NEW, GRAPH_PROJECTOR_VERSION, GRAPH_VEC_SEED_CAP, } from '../graph/types.js';
 import { normPersistence } from '../types.js';
+import { classifyValidity, isExitedState, validToSourceOf } from './validity.js';
+import { readSupersedeMarker } from './supersede.js';
 import { isZeroVector, vecToBuffer } from './vec-utils.js';
 const TAG = '[memory][graph]';
 /** 坏 JSON 容忍解析:图谱表列损坏只损失该行派生信息,不抛。 */
@@ -460,6 +463,98 @@ export class GraphStore {
             : nodes;
         return searchGraphNodes(filtered, edges, query, limit);
     }
+    /**
+     * §D 第 3 路存储缝(回链记录 id 序;graphLane 直接消费):词法命中 ∪ 路内向量种子
+     * → 1-hop 边扩展 → 保序去重的 L1 记录 id 序列。
+     *
+     * - **向量种子是路内并集、不是新路**:embedding 由调用方传入(装配层惰性查
+     *   l1.embedText;未就绪/失败传 undefined = 纯词法路,与旧 searchNodes+直连回链
+     *   逐位一致);并集不占 RRF 路数名额,"未接线 = 恰为 2 路"不变量不动;
+     * - **种子序**:词法命中在前、向量种子追加在后(RRF 用 rank,顺序即权重),
+     *   同节点去重;向量种子同样过 visible 族集与 active|disputed 状态闸(宁可漏不可串);
+     * - **1-hop 邻居不按族预筛**:来源记录的跨族由 graphLane 尾部记录级 family/scope
+     *   双闸兜底(与本路既有纪律同源);
+     * - 降级(db 未就绪/空图)返回空数组,不抛。
+     *
+     * 返回记录 id 而非 hits 是刻意的:回链/扩展属于读路径细节,路侧只需排名序列。
+     */
+    searchLaneRecords(query, embedding, limit, families) {
+        if (!this.db)
+            return [];
+        const { nodes, edges } = this.loadGraph();
+        const visible = families && families.length > 0
+            ? nodes.filter((n) => n.families.some((f) => families.includes(f)))
+            : nodes;
+        const lexical = searchGraphNodes(visible, edges, query, limit);
+        let hits = lexical;
+        if (embedding && embedding.length > 0) {
+            const visibleIds = new Set(visible.map((n) => n.id));
+            const seenNodes = new Set(lexical.map((h) => h.node.id));
+            const extra = [];
+            for (const v of this.searchNodesByVector(embedding, GRAPH_VEC_SEED_CAP)) {
+                if (seenNodes.has(v.node.id) || !visibleIds.has(v.node.id))
+                    continue;
+                if (v.node.status !== 'active' && v.node.status !== 'disputed')
+                    continue;
+                seenNodes.add(v.node.id);
+                extra.push({ node: v.node, score: v.score, matchedFields: ['name'], matchReason: '向量种子命中' });
+            }
+            if (extra.length > 0)
+                hits = [...lexical, ...extra];
+        }
+        return expandHitRecordIds(hits, nodes, edges);
+    }
+    /**
+     * 面板图谱预览存储缝(契约 `dsh-memory/graph-preview` 的数据源):
+     * loadGraph 一次 + job 计数(pending/running/failed 未定项与全量分母)传入纯函数。
+     * 降级(db 未就绪)返**全零结构**不抛——预览是展示面,永不拖垮端点。
+     * mode==='full' 时响应附 `full` 轻量块;**缺省时该键缺席**(可选键零漂移纪律,
+     * 不是 undefined 占位——消费方 `'full' in res` 与 JSON 形状双判据都干净)。
+     */
+    buildPreview(seedId, mode) {
+        const zero = { seeds: [], stats: { nodes: 0, edges: 0, causalEdges: 0, pendingJobs: 0, jobsTotal: 0 } };
+        if (!this.db)
+            return mode === 'full' ? { ...zero, full: { nodes: [], edges: [], truncated: false } } : zero;
+        const { nodes, edges } = this.loadGraph();
+        let pendingJobs = 0;
+        let jobsTotal = 0;
+        let deadJobs = 0;
+        try {
+            pendingJobs = this.db
+                .prepare("SELECT COUNT(1) AS c FROM graph_projection_jobs WHERE status IN ('pending','running','failed')")
+                .get().c;
+            jobsTotal = this.db.prepare('SELECT COUNT(1) AS c FROM graph_projection_jobs').get().c;
+            deadJobs = this.db.prepare("SELECT COUNT(1) AS c FROM graph_projection_jobs WHERE status = 'dead'").get().c;
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} 预览 job 计数失败(计数回零): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const r = buildGraphPreview(nodes, edges, { seedId, pendingJobs, jobsTotal, deadJobs });
+        if (mode === 'full')
+            return { ...r, full: buildFullView(nodes, edges) };
+        return r;
+    }
+    /**
+     * 清理历史 dead 作业行（纯审计痕迹删除，不影响已重入队的记录）。
+     * olderThanMs: 只删早于 now-olderThanMs 的；缺省删全部 dead。
+     */
+    cleanupDead(olderThanMs) {
+        if (!this.db)
+            return 0;
+        try {
+            const cutoff = olderThanMs != null && olderThanMs > 0
+                ? new Date(Date.now() - olderThanMs).toISOString()
+                : undefined;
+            const result = cutoff
+                ? this.db.prepare("DELETE FROM graph_projection_jobs WHERE status = 'dead' AND updated_time < ?").run(cutoff)
+                : this.db.prepare("DELETE FROM graph_projection_jobs WHERE status = 'dead'").run();
+            return Number(result.changes ?? 0);
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} cleanupDead 失败(忽略): ${err instanceof Error ? err.message : String(err)}`);
+            return 0;
+        }
+    }
     // ============================
     // 投影 job 队列
     // ============================
@@ -472,8 +567,16 @@ export class GraphStore {
      * 记录跳过。返回实际新建的 job 数。
      */
     queueGraphProjection(recordIds, priority) {
+        return this.queueGraphProjectionDetailed(recordIds, priority).created;
+    }
+    /**
+     * 入队的详细形态(与 `queueGraphProjection` 同一实现,只是把新建 job id 也交出来):
+     * `memory_reproject` 工具面需要 `{queued, jobIds}` 回报,而既有调用方只数 created——
+     * 两个返回形状共享一份去重/分片逻辑,不漂移。
+     */
+    queueGraphProjectionDetailed(recordIds, priority) {
         if (!this.db || recordIds.length === 0)
-            return 0;
+            return { created: 0, jobIds: [] };
         try {
             const db = this.db;
             const ids = [...new Set(recordIds)];
@@ -492,10 +595,10 @@ export class GraphStore {
             }
             const fresh = ids.filter((id) => !blocked.has(id));
             if (fresh.length === 0)
-                return 0;
+                return { created: 0, jobIds: [] };
             const now = new Date().toISOString();
             return this.tx(() => {
-                let created = 0;
+                const jobIds = [];
                 for (let i = 0; i < fresh.length; i += GRAPH_JOB_BATCH) {
                     const batch = fresh.slice(i, i + GRAPH_JOB_BATCH);
                     const jobId = this.newJobId();
@@ -504,14 +607,121 @@ export class GraphStore {
                     for (const id of batch) {
                         db.prepare('INSERT OR REPLACE INTO graph_job_records (record_id, job_id) VALUES (?, ?)').run(id, jobId);
                     }
-                    created++;
+                    jobIds.push(jobId);
                 }
-                return created;
+                return { created: jobIds.length, jobIds };
             });
         }
         catch (err) {
             this.logger?.warn(`${TAG} 投影入队失败(忽略): ${err instanceof Error ? err.message : String(err)}`);
-            return 0;
+            return { created: 0, jobIds: [] };
+        }
+    }
+    /**
+     * 强制重投(计划 expiry-tiering R10 冻结契约 · 先行刀):
+     * 抹掉 `graph_projected_records` 里这些记录的"已按当前版本投过"凭证,再按
+     * 新蒸馏优先级入队——绕开 `projector_version` 的永久跳过,让"改了 L1 → 图谱跟随"
+     * 有一条不依赖重启/周期 sweep 的纠正通道。
+     *
+     * **不动在途 `graph_job_records` 映射**(与上游 task_7.5 字面的一处刻意偏差,
+     * 理由记入写面计划 findings):claim 在认领时才现读 L1 记录,在途 job 天然投的是
+     * **改后**内容;若把映射一并删掉,同一次调用稍后再来一次就会绕过 PK 去重,
+     * 堆出内容重叠的双 job——保留映射才是"重复调用不堆重 job"的构造性保证。
+     *
+     * 幂等:在途有 job → blocked 集吸收,`created=0`;job 已完成 → 凭证刚被
+     * `complete` 写回,本方法再删再投,是合法的新重投而非堆积。
+     */
+    forceReprojectRecord(recordIds) {
+        if (!this.db || recordIds.length === 0)
+            return { queued: 0, jobIds: [] };
+        const ids = [...new Set(recordIds)];
+        try {
+            this.tx(() => {
+                for (const chunk of chunkOf(ids)) {
+                    const ph = chunk.map(() => '?').join(',');
+                    this.db.prepare(`DELETE FROM graph_projected_records WHERE record_id IN (${ph})`).run(...chunk);
+                }
+            });
+            const r = this.queueGraphProjectionDetailed(ids, GRAPH_PRIORITY_NEW);
+            return { queued: r.created, jobIds: r.jobIds };
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} 强制重投入队失败(忽略): ${err instanceof Error ? err.message : String(err)}`);
+            return { queued: 0, jobIds: [] };
+        }
+    }
+    /**
+     * 确定性边提案落库面(graph-write-plane R4 兜底支路):把"工具传入的显式边提案"
+     * 当作一次确定性投影输入,经 `applyGraphProjection` **纯函数**校验后在同一事务内
+     * 写回——不是裸 UPDATE graph_edges:validSources 硬校验、同 (from,relation) 换目标
+     * 闭旧边的确定性支路、来源并集封顶,全部复用既有守门代码(R5 不变量由它保证)。
+     *
+     * 提案形态:两端节点按现有 name/type 重提(消歧合并会命中现有节点,不新铸实体),
+     * 边 (from → to, relation) 携调用方给的 sourceRecordIds。claim 同款现读 L1:
+     * allowedRecordIds = 命中的来源记录集,未命中的 id 会被纯函数整条拒掉(返回
+     * ok:false, reason='dropped')——工具面传的"非现存 L1"在这里撞上硬校验,而非静默落库。
+     */
+    applyRelationProposal(opts) {
+        const fail = (reason) => ({ ok: false, reason, closedEdgeIds: [], edgeIds: [], touchedNodeIds: [] });
+        if (!this.db)
+            return fail('graph-not-ready');
+        const relation = String(opts.relation ?? '').trim();
+        const sourceIds = [...new Set((opts.sourceRecordIds ?? []).map((s) => String(s).trim()).filter((s) => s.length > 0))];
+        if (!opts.fromNodeId || !opts.toNodeId || opts.fromNodeId === opts.toNodeId)
+            return fail('bad-nodes');
+        if (!relation || sourceIds.length === 0)
+            return fail('empty-relation-or-sources');
+        try {
+            return this.tx(() => {
+                const { nodes, edges } = this.loadGraphInTx();
+                const from = nodes.find((n) => n.id === opts.fromNodeId);
+                const to = nodes.find((n) => n.id === opts.toNodeId);
+                if (!from || !to)
+                    return fail('nodes-not-found');
+                const records = this.loadRecordsInTx(sourceIds);
+                if (records.length === 0)
+                    return fail('sources-not-in-l1');
+                const now = opts.now ?? new Date().toISOString();
+                const idFactory = (prefix) => `${prefix}_${Date.now()}_${randomBytes(3).toString('hex')}`;
+                const result = {
+                    reason: 'tool-explicit-proposal',
+                    nodes: [
+                        { ref: 'from', name: from.name, type: from.type, sourceRecordIds: sourceIds, status: 'active' },
+                        { ref: 'to', name: to.name, type: to.type, sourceRecordIds: sourceIds, status: 'active' },
+                    ],
+                    edges: [{ fromRef: 'from', toRef: 'to', relation, sourceRecordIds: sourceIds, status: 'active' }],
+                };
+                const statusBefore = new Map(edges.map((e) => [e.id, e.status]));
+                const outcome = applyGraphProjection({
+                    nodes,
+                    edges,
+                    records,
+                    result,
+                    allowedRecordIds: new Set(records.map((r) => r.id)),
+                    now,
+                    idFactory,
+                });
+                if (outcome.edgeIds.length === 0)
+                    return fail('proposal-dropped-by-validator');
+                const touchedNodes = nodes.filter((n) => outcome.nodeIds.includes(n.id));
+                const touchedEdges = edges.filter((e) => outcome.edgeIds.includes(e.id));
+                this.upsertTouchedInTx(touchedNodes, touchedEdges);
+                const closedEdgeIds = touchedEdges
+                    .filter((e) => e.status === 'superseded' && statusBefore.get(e.id) !== 'superseded')
+                    .map((e) => e.id);
+                const newEdgeIds = touchedEdges.filter((e) => e.status === 'active' && e.relation === relation).map((e) => e.id);
+                this.logger?.info(`${TAG} 确定性边提案落库:${newEdgeIds.length} 边 active,${closedEdgeIds.length} 旧边 superseded(来源 ${sourceIds.length} 条,校验丢弃 ${outcome.dropped} 项)`);
+                return {
+                    ok: true,
+                    closedEdgeIds,
+                    edgeIds: newEdgeIds,
+                    touchedNodeIds: touchedNodes.map((n) => n.id),
+                };
+            }, true);
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} 确定性边提案失败(整体回滚): ${err instanceof Error ? err.message : String(err)}`);
+            return fail('tx-error');
         }
     }
     /**
@@ -568,7 +778,7 @@ export class GraphStore {
                AND status IN ('pending', 'failed')
                AND (next_attempt_at IS NULL OR next_attempt_at <= ?)
              ORDER BY priority DESC, created_time ASC LIMIT 1`)
-                    .get(GRAPH_PROJECTOR_VERSION, GRAPH_JOB_MAX_ATTEMPTS, nowMs);
+                    .get(GRAPH_PROJECTOR_VERSION, GRAPH_JOB_TRANSIENT_MAX_ATTEMPTS, nowMs);
                 if (!row)
                     return null;
                 db.prepare(`UPDATE graph_projection_jobs SET status = 'running', attempts = attempts + 1, error = NULL, updated_time = ? WHERE job_id = ?`).run(nowIso, row.job_id);
@@ -599,10 +809,14 @@ export class GraphStore {
      * 校验)→ 写回 touched 行 → job 置 completed + 登记已投影记录 + 放掉 mapping。
      * job 非 running 态(已完成/已 dead/已回收)一律幂等 no-op;任何一步抛错整体
      * 回滚,不留半写。
+     *
+     * 返回 touched 节点中 active/disputed 的那批(写面向量收尾的输入,G-vec 缺陷修):
+     * 调用方只关心"哪些节点刚被写活",向量补算失败不回滚投影——返回值不参与控制流。
      */
     complete(jobId, result, opts) {
         if (!this.db)
-            return;
+            return [];
+        let touchedVecNodes = [];
         try {
             const db = this.db;
             const now = opts?.now ?? new Date().toISOString();
@@ -628,6 +842,9 @@ export class GraphStore {
                 const touchedNodes = nodes.filter((n) => outcome.nodeIds.includes(n.id));
                 const touchedEdges = edges.filter((e) => outcome.edgeIds.includes(e.id));
                 this.upsertTouchedInTx(touchedNodes, touchedEdges);
+                // 写面收尾的输入(只递交落库后的 active/disputed 节点):墓碑不需要向量,
+                // 读侧 searchNodesByVector 本就按状态闸过滤陈旧向量行。
+                touchedVecNodes = touchedNodes.filter((n) => n.status === 'active' || n.status === 'disputed');
                 db.prepare(`UPDATE graph_projection_jobs SET status = 'completed', error = NULL, updated_time = ? WHERE job_id = ?`).run(now, jobId);
                 for (const id of wanted) {
                     db.prepare('INSERT OR REPLACE INTO graph_projected_records (record_id, projector_version) VALUES (?, ?)').run(id, GRAPH_PROJECTOR_VERSION);
@@ -643,26 +860,30 @@ export class GraphStore {
             // 提交失败:job 仍在 running 态,下次启动 recoverRunning 回收重投
             this.logger?.warn(`${TAG} 投影提交失败(待启动回收重投): ${err instanceof Error ? err.message : String(err)}`);
         }
+        return touchedVecNodes;
     }
     /**
-     * 投影失败收尾:attempts 已在 claim 时 +1——封顶转 dead(放掉 mapping,允许
-     * 重新入队);未封顶转 failed + 指数退避 nextAttemptAt(mapping 保留防重复入队)。
+     * 投影失败收尾:attempts 已在 claim 时 +1——根据错误分类选不同封顶:
+     * - 永久错误(校验/解析):attempts >= GRAPH_JOB_MAX_ATTEMPTS(3) → dead
+     * - 瞬态错误(aborted/timeout/网络):attempts >= GRAPH_JOB_TRANSIENT_MAX_ATTEMPTS(6) → dead
+     * dead 放掉 mapping(允许下次 backfill 重新入队);未封顶转 failed + 指数退避。
      */
-    fail(jobId, error) {
+    fail(jobId, error, opts) {
         if (!this.db)
             return;
         try {
             const db = this.db;
             const nowMs = Date.now();
             const nowIso = new Date(nowMs).toISOString();
+            const cap = opts?.transient ? GRAPH_JOB_TRANSIENT_MAX_ATTEMPTS : GRAPH_JOB_MAX_ATTEMPTS;
             this.tx(() => {
                 const row = db.prepare('SELECT attempts FROM graph_projection_jobs WHERE job_id = ?').get(jobId);
                 if (!row)
                     return;
-                if (row.attempts >= GRAPH_JOB_MAX_ATTEMPTS) {
+                if (row.attempts >= cap) {
                     db.prepare(`UPDATE graph_projection_jobs SET status = 'dead', error = ?, updated_time = ? WHERE job_id = ?`).run(error.slice(0, 500), nowIso, jobId);
                     db.prepare('DELETE FROM graph_job_records WHERE job_id = ?').run(jobId);
-                    this.logger?.warn(`${TAG} 投影任务达重试上限,标记 dead(job=${jobId}): ${error.slice(0, 200)}`);
+                    this.logger?.warn(`${TAG} 投影任务达重试上限(${opts?.transient ? '瞬态' : '永久'}cap=${cap}),标记 dead(job=${jobId}): ${error.slice(0, 200)}`);
                 }
                 else {
                     const backoffMs = GRAPH_JOB_BACKOFF_BASE_MS * 2 ** (row.attempts - 1);
@@ -778,6 +999,94 @@ export class GraphStore {
             this.logger?.warn(`${TAG} 删除传播失败(忽略): ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    /**
+     * 退场传播(计划 expiry-tiering R9 冻结契约 · 先行刀):软删/取代后的图谱
+     * 来源活性重算清扫。
+     *
+     * 与 `markSourcesDeleted` 的分野:那边判"来源 row 是否还活着",对软删(主表行
+     * 一直在)结构性失效;这边判"来源是否全部处于**退场态**"——即
+     * `classifyValidity` ∈ {superseded, retired}。退场判据单源在 validity 层,
+     * 本方不再自写一份 valid_to/marker 比较(写面计划约束 §4)。
+     *
+     * 重算式 sweep(不是逐条事件改写):每次按当前 L1 全量判定候选节点/边,
+     * 双向收敛——
+     * - active/disputed 且来源全部退场(含 row 消失)→ `archived` 墓碑(保留行,
+     *   expand 可见,与物理删传播同落库形态);
+     * - archived 且来源全部复活(row 存在且非退场态)→ 回 `active`(restore 的回药;
+     *   被物理删清空来源的永不满 足此条,不会误复活)。
+     *
+     * `changedIds` 只作早退与诊断日志的口径,不参与判定(判定面 = 全图来源集)。
+     */
+    markSourcesRetired(changedIds) {
+        if (!this.db || changedIds.length === 0)
+            return;
+        try {
+            const { nodes, edges } = this.loadGraph();
+            const sourceIds = new Set();
+            for (const n of nodes)
+                for (const id of n.sourceRecordIds)
+                    sourceIds.add(id);
+            for (const e of edges)
+                for (const id of e.sourceRecordIds)
+                    sourceIds.add(id);
+            if (sourceIds.size === 0)
+                return;
+            // 现读 L1 行(含已退场软删行——主表行一直在,差别在 marker);
+            // 列形状按 l1SelectCols 同款容缺(独立测试夹具/旧库可能没有时间增强列)。
+            const now = Date.now();
+            const byId = new Map();
+            for (const chunk of chunkOf([...sourceIds])) {
+                const ph = chunk.map(() => '?').join(',');
+                for (const r of this.db
+                    .prepare(`SELECT ${l1SelectCols(this.db)} FROM l1_records WHERE record_id IN (${ph})`)
+                    .all(...chunk)) {
+                    byId.set(String(r.record_id), rowToRecord(r));
+                }
+            }
+            /** 单条来源是否处于退场态:row 消失也算(与物理删传播同口径,宁保守勿复活)。 */
+            const exited = (id) => {
+                const rec = byId.get(id);
+                if (!rec)
+                    return true;
+                const state = classifyValidity({
+                    marker: readSupersedeMarker(rec.metadata),
+                    persistence: rec.persistence,
+                    validTo: rec.validTo,
+                    validToSource: validToSourceOf(rec.metadata),
+                    now,
+                });
+                return isExitedState(state);
+            };
+            const allExited = (ids) => ids.length > 0 && ids.every(exited);
+            const allRevived = (ids) => ids.length > 0 && ids.every((id) => byId.has(id) && !exited(id));
+            const toArchive = nodes.filter((n) => (n.status === 'active' || n.status === 'disputed') && allExited(n.sourceRecordIds));
+            const toArchiveEdges = edges.filter((e) => (e.status === 'active' || e.status === 'disputed') && allExited(e.sourceRecordIds));
+            const toRevive = nodes.filter((n) => n.status === 'archived' && allRevived(n.sourceRecordIds));
+            const toReviveEdges = edges.filter((e) => e.status === 'archived' && allRevived(e.sourceRecordIds));
+            if (toArchive.length === 0 && toArchiveEdges.length === 0 && toRevive.length === 0 && toReviveEdges.length === 0)
+                return;
+            const nowIso = new Date(now).toISOString();
+            this.tx(() => {
+                for (const n of toArchive) {
+                    this.db.prepare(`UPDATE graph_nodes SET status = 'archived', updated_time = ? WHERE node_id = ?`).run(nowIso, n.id);
+                }
+                for (const e of toArchiveEdges) {
+                    this.db.prepare(`UPDATE graph_edges SET status = 'archived', updated_time = ? WHERE edge_id = ?`).run(nowIso, e.id);
+                }
+                for (const n of toRevive) {
+                    this.db.prepare(`UPDATE graph_nodes SET status = 'active', updated_time = ? WHERE node_id = ?`).run(nowIso, n.id);
+                }
+                for (const e of toReviveEdges) {
+                    this.db.prepare(`UPDATE graph_edges SET status = 'active', updated_time = ? WHERE edge_id = ?`).run(nowIso, e.id);
+                }
+            });
+            this.logger?.info(`${TAG} 退场传播(重算清扫):${toArchive.length + toArchiveEdges.length} 项标 archived,` +
+                `${toRevive.length + toReviveEdges.length} 项复活(触发记录 ${changedIds.length} 条)`);
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} 退场传播失败(忽略): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     /**
      * §C 矛盾冻结:把图谱的 `disputed` 状态**同步**到给定冲突集。
      *

package/dist/store/l1.d.ts

@@ -1,5 +1,4 @@
 import type { L1Hit, MemoryFamily, MemoryLogger, MemoryRecord, RoomCount } from '../types.js';
-import type { GraphNodeSearchResult } from '../graph/types.js';
 import type { L1Receipt, ReceiptQuery } from './receipts.js';
 import type { ConflictClaimGroup, ConflictPair, ConflictRejected, ConflictResolution, ConflictType } from './conflicts.js';
 import { type SupersedeInfo } from './supersede.js';
@@ -9,11 +8,13 @@ import { type L1MetaLite, type MemoryDb } from './sqlite.js';
 import type { L1FileSyncHook } from './memory-md-sync.js';
 export type RecallStrategy = 'keyword' | 'embedding' | 'hybrid';
 /**
- * 图谱路提供者(§D 第 3 路):按查询返回图谱命中(已按 score 降序)。
+ * 图谱路提供者(§D 第 3 路):按查询返回图谱回链的 L1 记录 id 有序列
+ * (向量种子并集与 1-hop 边扩展在 provider 内完成,见 graph-store.searchLaneRecords)。
  * 抽成注入式而非直接读 `db.graphStore`,是为了给 hybrid 融合留一个可替换的测试缝,
- * 并让「未接线 = 恰为 2 路」成为默认行为(既有调用方零行为变化)。
+ * 并让「未接线 = 恰为 2 路」成为默认行为(既有调用方零行为变化)。允许返回 Promise
+ * 是给向量种子的 embed 查询(装配层惰性取嵌入源);异常由 graphLane 吞并降级。
  */
-export type GraphLaneProvider = (query: string, limit: number, family?: MemoryFamily) => readonly GraphNodeSearchResult[];
+export type GraphLaneProvider = (query: string, limit: number, family?: MemoryFamily) => readonly string[] | Promise<readonly string[]>;
 export interface L1SearchOptions {
     /** 按记忆类型精确过滤(后置过滤,官方做法)。 */
     type?: string;
@@ -251,6 +252,11 @@ export declare class L1Store {
     };
     /** 按 id 精确取记录(去重决策的版本号查询用,避免全表扫描)。 */
     getByIds(ids: string[]): MemoryRecord[];
+    /**
+     * 反向取代链(task_4.4,门3):返回"被 newId 取代"的退场记录 id。
+     * 走 MemoryDb 的 LIKE 全扫缝(百~千量级;阈值告警在那边)。
+     */
+    findSupersededTargets(newId: string): string[];
     /** 外部导入幂等 pre-check(轨3-P0):ext_key 命中已存在记录则返回其 id,否则 undefined。 */
     findIdByExtKey(extKey: string): string | undefined;
     /**
@@ -424,17 +430,19 @@ export declare class L1Store {
      */
     private recencyLane;
     /**
-     * §D 第 3 路(图谱路径,hybrid 专用):图谱命中 → `sourceRecordIds` 回链 →
-     * L1 记录,作为第 3 条**已排序**列表参与 RRF。
+     * §D 第 3 路(图谱路径,hybrid 专用):provider 给出回链记录 id 序(路内向量种子
+     * 并集 + 1-hop 边扩展在 provider 内完成),本缝只做点查回形 + family/scope 双闸,
+     * 作为第 3 条**已排序**列表参与 RRF。
      *
      * 为什么值得:图谱是按实体/关系组织的**可重建派生投影**,能召回词法与向量
      * 都命不中的记录(同义表述、关系可达)——这正是本路相对双路的增量。
      *
      * 三条边界:
      * - **异常降级**:图谱是派生投影,不得因它失败而拖垮主检索 → 记 warn、返回空路,
-     *   融合退回双路(路数随之降为 2,分数回到既有量纲);
-     * - **族隔离**:图谱节点已按族过滤,但其来源记录可能跨族 → 这里再按 `family`
-     *   过滤一次。宁可漏不可串(与档位隔离同源,§A 的 P0 关注点);
+     *   融合退回双路(路数随之降为 2,分数回到既有量纲);await 在 try 内——
+     *   provider 的 Promise reject 与同步 throw 同路径降级;
+     * - **族隔离**:图谱节点已按族过滤(含向量种子),但 1-hop 邻居与来源记录可能跨族
+     *   → 这里再按 `family` 过滤一次。宁可漏不可串(与档位隔离同源,§A 的 P0 关注点);
      * - **墓碑边界**:图谱行可能回链到已被删除的 L1 记录 → 取不到就跳过,
      *   不补空占位(占位会在 RRF 里凭空加分)。
      */

package/dist/store/l1.js

@@ -9,8 +9,8 @@
 import { existsSync, mkdirSync, promises as fs, writeFileSync } from 'node:fs';
 import * as path from 'node:path';
 import { familyForType, isScopeVisible } from '../types.js';
-import { graphHitRecordIds } from '../graph/search.js';
 import { isRetired } from './supersede.js';
+import { stampValidity } from './validity.js';
 import { exportThenPurge, readSnapshotManifest, readSnapshotRecords, restoreL1Snapshot, selectSnapshotTargets, snapshotDirFor, listSnapshots as listSnapshotsIn } from './l1-snapshot.js';
 import { EmbedHelper, NoopEmbeddingService } from './embedding.js';
 import { appendJsonl, dayKey, ensureDir, readJsonl } from '../util/io.js';
@@ -393,6 +393,13 @@ export class L1Store {
     getByIds(ids) {
         return this.db.getL1ByIds(ids);
     }
+    /**
+     * 反向取代链(task_4.4,门3):返回"被 newId 取代"的退场记录 id。
+     * 走 MemoryDb 的 LIKE 全扫缝(百~千量级;阈值告警在那边)。
+     */
+    findSupersededTargets(newId) {
+        return this.db.findSupersededTargets(newId);
+    }
     /** 外部导入幂等 pre-check(轨3-P0):ext_key 命中已存在记录则返回其 id,否则 undefined。 */
     findIdByExtKey(extKey) {
         return this.db.findRecordIdByExtKey(extKey);
@@ -474,9 +481,14 @@ export class L1Store {
     async appendNew(records) {
         if (records.length === 0)
             return;
+        // 写侧标注汇流口(task_3.2):所有新写路径(pipeline / memory_add / import / memport /
+        // 重建保留…)都经这里，统一盖 dsh_validity 快照;源头盖过的行(pipeline 带 evidence、
+        // 工具带 llm_inferred)保留其 validToSource，未盖过的补 'unknown'(fail-open)。
+        const stampNow = Date.now();
         for (const r of records) {
             if (!r.family)
                 r.family = familyForType(r.type);
+            stampValidity(r, stampNow);
         }
         // 起名必须在**追加事实源之前**：名字是文件身份键，进了 JSONL 才能跟记录一起重生。
         // 这批还没进库，所以只算名字不落库（persist=false），由下面的 upsert 一并写。
@@ -507,7 +519,9 @@ export class L1Store {
     async upsert(record) {
         if (!record.family)
             record.family = familyForType(record.type);
-        // merge 分支会继承胜方的 name；两边都没名字时在这里补上，别让新铸的行继续带空名。
+        // 写侧标注汇流口(与 appendNew 同口径):merge 分支会继承胜方的 name；
+        // 两边都没名字时在这里补上，别让新铸的行继续带空名。
+        stampValidity(record, Date.now());
         this.assignMissingNames([record], { persist: false });
         const vec = (await this.helper.batch([record.content]))[0];
         if (!this.db.upsertL1(record, vec)) {
@@ -585,8 +599,9 @@ export class L1Store {
         // **只清理确实处于退场态的记录**。这道复核必须在删除发生的地方(而不是调用方):
         // 否则任何调用方传一个 id 列表就能绕过软删、把活动记忆直接物理抹掉——
         // 那等于给"先导出后清理"留了一条硬删后门。
+        // 门1 解耦:判据与全仓同为 marker 单源 `isRetired`(不再拿 valid_to 当退场凭据)。
         const known = new Map(this.db.getL1ByIds(ids).map((r) => [r.id, r]));
-        const retiredIds = ids.filter((id) => known.get(id)?.validTo !== undefined);
+        const retiredIds = ids.filter((id) => { const r = known.get(id); return r !== undefined && isRetired(r); });
         return exportThenPurge(this.db, this.dataDir, retiredIds, reason, this.logger, new Date(), opts);
     }
     // ───────────────────────────────────────────────────────────────────────────
@@ -735,14 +750,35 @@ export class L1Store {
         const vecList = vecRaw ? this.db.searchL1Vector(vecRaw, candidateK, opts?.family, opts?.workspaceId) : [];
         // 第 3 路(图谱)仅在接线时**结构性存在**:未接线不占路数名额,故既有调用方
         // 仍走 2 路、得分与改动前逐位一致(见 findings.md §12.1 的路数语义)
-        const lanes = [ftsList, vecList];
+        const lanes = [['fts', ftsList], ['vec', vecList]];
         if (this.graphLaneProvider)
-            lanes.push(this.graphLane(query, candidateK, opts?.family, opts?.workspaceId));
+            lanes.push(['graph', await this.graphLane(query, candidateK, opts?.family, opts?.workspaceId)]);
         // 第 4 路(时效)在衰减开启时**结构性存在**;关掉衰减 = 该路不存在
         if (this.decayHalfLifeDays > 0)
-            lanes.push(this.recencyLane([...ftsList, ...vecList]));
-        const merged = rrfMerge(lanes, (h) => h.id);
-        return this.postProcess(this.applyDecay(merged.map(({ rrfScore, ...h }) => ({ ...h, score: normalizeRrf(rrfScore, lanes.length) }))), opts?.type, limit);
+            lanes.push(['recency', this.recencyLane([...ftsList, ...vecList])]);
+        const laneLists = lanes.map(([, list]) => list);
+        // 路归因(与融合并行,不改 rrfMerge 本体):id → 命中路集合,按路构造序
+        // 去重追加(fts→vec→graph→recency,确定性输出)。命中对象在下方 map 里
+        // 新建(不往变回路的列表元素上写),挂 lanes 后随 postProcess/applyDecay 透传。
+        const lanesById = new Map();
+        for (const [name, list] of lanes) {
+            for (const h of list) {
+                const arr = lanesById.get(h.id);
+                if (arr) {
+                    if (!arr.includes(name))
+                        arr.push(name);
+                }
+                else {
+                    lanesById.set(h.id, [name]);
+                }
+            }
+        }
+        const merged = rrfMerge(laneLists, (h) => h.id);
+        return this.postProcess(this.applyDecay(merged.map(({ rrfScore, ...h }) => ({
+            ...h,
+            lanes: lanesById.get(h.id),
+            score: normalizeRrf(rrfScore, laneLists.length),
+        }))), opts?.type, limit);
     }
     /**
      * §D 第 4 路(时效路,hybrid 专用):把候选池按 `applyDecayWeight` 加权后的
@@ -770,36 +806,37 @@ export class L1Store {
         return this.applyDecay(deduped);
     }
     /**
-     * §D 第 3 路(图谱路径,hybrid 专用):图谱命中 → `sourceRecordIds` 回链 →
-     * L1 记录,作为第 3 条**已排序**列表参与 RRF。
+     * §D 第 3 路(图谱路径,hybrid 专用):provider 给出回链记录 id 序(路内向量种子
+     * 并集 + 1-hop 边扩展在 provider 内完成),本缝只做点查回形 + family/scope 双闸,
+     * 作为第 3 条**已排序**列表参与 RRF。
      *
      * 为什么值得:图谱是按实体/关系组织的**可重建派生投影**,能召回词法与向量
      * 都命不中的记录(同义表述、关系可达)——这正是本路相对双路的增量。
      *
      * 三条边界:
      * - **异常降级**:图谱是派生投影,不得因它失败而拖垮主检索 → 记 warn、返回空路,
-     *   融合退回双路(路数随之降为 2,分数回到既有量纲);
-     * - **族隔离**:图谱节点已按族过滤,但其来源记录可能跨族 → 这里再按 `family`
-     *   过滤一次。宁可漏不可串(与档位隔离同源,§A 的 P0 关注点);
+     *   融合退回双路(路数随之降为 2,分数回到既有量纲);await 在 try 内——
+     *   provider 的 Promise reject 与同步 throw 同路径降级;
+     * - **族隔离**:图谱节点已按族过滤(含向量种子),但 1-hop 邻居与来源记录可能跨族
+     *   → 这里再按 `family` 过滤一次。宁可漏不可串(与档位隔离同源,§A 的 P0 关注点);
      * - **墓碑边界**:图谱行可能回链到已被删除的 L1 记录 → 取不到就跳过,
      *   不补空占位(占位会在 RRF 里凭空加分)。
      */
-    graphLane(query, limit, family, workspaceId) {
+    async graphLane(query, limit, family, workspaceId) {
         const provider = this.graphLaneProvider;
         if (!provider)
             return [];
-        let hits;
+        let ids;
         try {
-            hits = provider(query, limit, family);
+            ids = await provider(query, limit, family);
         }
         catch (err) {
             this.logger?.warn(`[memory] 图谱路检索失败,本轮退回双路: ${err instanceof Error ? err.message : String(err)}`);
             return [];
         }
-        const ids = graphHitRecordIds(hits);
         if (ids.length === 0)
             return [];
-        const byId = new Map(this.db.getL1ByIds(ids).map((r) => [r.id, r]));
+        const byId = new Map(this.db.getL1ByIds([...ids]).map((r) => [r.id, r]));
         const out = [];
         for (const id of ids) {
             const r = byId.get(id);