dsh-prime-memory 0.11.0 → 0.12.0

package/dist/store/graph-store.js

@@ -22,6 +22,7 @@ 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 { normPersistence } from '../types.js';
+import { isZeroVector, vecToBuffer } from './vec-utils.js';
 const TAG = '[memory][graph]';
 /** 坏 JSON 容忍解析:图谱表列损坏只损失该行派生信息,不抛。 */
 function parseJsonSafe(raw, fallback) {
@@ -134,6 +135,13 @@ export class GraphStore {
     logger;
     stmtInsertNode;
     stmtInsertEdge;
+    /**
+     * §F 图谱节点向量列（vec0）。**结构性可选**：维度未定或 vec0 不可用时这三个
+     * 语句就是 `undefined`，该路整体 no-op——既不影响图谱的词法检索，也不向上抛。
+     */
+    stmtInsertNodeVec;
+    stmtDeleteNodeVec;
+    stmtSearchNodeVec;
     /** init 是否就绪(未就绪 = 图谱域整体 no-op,不抛错不传染)。 */
     get ready() {
         return this.db !== null;
@@ -141,8 +149,11 @@ export class GraphStore {
     /**
      * 建表 + 语句缓存(MemoryDb.initSchema 内调用)。任何一步失败都只告警并保持
      * 未就绪——图谱域整体降级 no-op,检索主链路(L0/L1/FTS/向量)不受影响。
+     *
+     * @param vec §F 节点向量列的维度(来自 MemoryDb 的**既有**能力探测结果;
+     *   缺省/0 = 部署未启用向量 → 该路结构性不存在,不建表也不报错)。
      */
-    init(db, logger) {
+    init(db, logger, vec) {
         this.logger = logger;
         try {
             db.exec(`
@@ -225,6 +236,7 @@ export class GraphStore {
           source_record_ids_json=excluded.source_record_ids_json, updated_time=excluded.updated_time
       `);
             this.db = db;
+            this.prepareNodeVec(db, logger, vec);
             logger?.info(`${TAG} 图谱表就绪(5 表,projectorVersion=${GRAPH_PROJECTOR_VERSION})`);
         }
         catch (err) {
@@ -233,6 +245,114 @@ export class GraphStore {
             logger?.warn(`${TAG} 图谱表初始化失败,图谱功能停用(主存储不受影响): ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    /**
+     * §F 图谱节点向量列：与 `l1_vec` **同模式**的 vec0 虚拟表——同一个 `vec-utils`
+     * 编码、同一种 `float[N] distance_metric=cosine` 声明。
+     *
+     * **内层 try/catch 是刻意的**（task_34）：vec0 扩展缺失时 `CREATE VIRTUAL TABLE`
+     * 会抛。若让它冒到外层，图谱会从"向量路不可用"退化成"**整个图谱域不可用**"——
+     * 词法检索、投影、裁决全部陪葬。外层那层 catch 是给"图谱表建不起来"用的，
+     * 不该被一个**可选**的向量列触发。
+     */
+    prepareNodeVec(db, logger, vec) {
+        const dimensions = vec?.dimensions ?? 0;
+        this.stmtInsertNodeVec = undefined;
+        this.stmtDeleteNodeVec = undefined;
+        this.stmtSearchNodeVec = undefined;
+        // 部署未启用向量（或探测未通过）→ 该路**结构性不存在**：不建表、不告警、不抛。
+        // 这与"建了空表却永远查不到东西"是两回事——前者可断言，后者不可。
+        if (dimensions <= 0)
+            return;
+        try {
+            db.exec(`
+        CREATE VIRTUAL TABLE IF NOT EXISTS graph_node_vec USING vec0(
+          node_id TEXT PRIMARY KEY,
+          embedding float[${dimensions}] distance_metric=cosine,
+          updated_time TEXT DEFAULT ''
+        )
+      `);
+            this.stmtInsertNodeVec = db.prepare('INSERT INTO graph_node_vec (node_id, embedding, updated_time) VALUES (?, ?, ?)');
+            this.stmtDeleteNodeVec = db.prepare('DELETE FROM graph_node_vec WHERE node_id = ?');
+            this.stmtSearchNodeVec = db.prepare(`
+        SELECT node_id, distance
+        FROM graph_node_vec
+        WHERE embedding MATCH ? AND k = ?
+        ORDER BY distance
+      `);
+            logger?.info(`${TAG} 图谱节点向量表就绪(dim=${dimensions})`);
+        }
+        catch (err) {
+            logger?.warn(`${TAG} 图谱节点向量表不可用,向量路停用(图谱词法检索不受影响): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /** 节点向量路是否可用。未就绪时下方两个方法的调用方**无需分支**——它们自身 no-op。 */
+    get nodeVecReady() {
+        return this.stmtSearchNodeVec !== undefined;
+    }
+    /**
+     * 写入/覆盖节点向量(先删后插:vec0 不支持 ON CONFLICT)。
+     * 未就绪 / 零向量 / 单条失败 → **静默跳过**,绝不抛。
+     * @returns 实际写入条数(供调用方记账,不用于控制流)。
+     */
+    upsertNodeVectors(rows) {
+        const stmtInsert = this.stmtInsertNodeVec;
+        const stmtDelete = this.stmtDeleteNodeVec;
+        if (!this.db || !stmtInsert || !stmtDelete)
+            return 0;
+        let written = 0;
+        for (const row of rows) {
+            if (isZeroVector(row.embedding))
+                continue; // cosine 未定义,不入表
+            try {
+                stmtDelete.run(row.nodeId);
+                stmtInsert.run(row.nodeId, vecToBuffer(row.embedding), row.updatedAt ?? '');
+                written++;
+            }
+            catch (err) {
+                this.logger?.warn(`${TAG} 节点向量写入失败(跳过该条): ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return written;
+    }
+    /** 删除节点向量(节点删/合并时用)。未就绪 no-op。 */
+    deleteNodeVectors(nodeIds) {
+        const stmtDelete = this.stmtDeleteNodeVec;
+        if (!this.db || !stmtDelete)
+            return;
+        try {
+            for (const id of nodeIds)
+                stmtDelete.run(id);
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} 节点向量删除失败: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * 向量检索节点(按 cosine 距离升序,score = 1 - distance,与 L1 向量路同口径)。
+     * 未就绪返回**空数组**——调用方无需判断 `nodeVecReady`,降级是内建的。
+     */
+    searchNodesByVector(embedding, topK) {
+        const stmtSearch = this.stmtSearchNodeVec;
+        if (!this.db || !stmtSearch || topK <= 0)
+            return [];
+        try {
+            const rows = stmtSearch.all(vecToBuffer(embedding), topK);
+            const out = [];
+            for (const { node_id, distance } of rows) {
+                if (distance == null || Number.isNaN(distance))
+                    continue;
+                const node = this.getNode(node_id);
+                if (!node)
+                    continue;
+                out.push({ node, score: 1 - distance });
+            }
+            return out;
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} 节点向量检索失败(返回空): ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+    }
     /** 插件停机时清空连接引用(dispose 序调用,防悬空引用)。 */
     close() {
         this.db = null;
@@ -623,6 +743,50 @@ export class GraphStore {
             this.logger?.warn(`${TAG} 删除传播失败(忽略): ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    /**
+     * §C 矛盾冻结:把图谱的 `disputed` 状态**同步**到给定冲突集。
+     *
+     * 为什么是"同步"而不是"标记":裁决会**撤销**争议。只做单向标记的话,
+     * 一对已被人工裁决的对,其节点会永远停在 `disputed`——那是**派生投影在说谎**。
+     * 图谱是本仓库反复确认的 L1 **派生投影**,派生字段就必须**由当前事实重算**,
+     * 而不是靠一串增量事件累积(后者一旦漏一次就永久跑偏)。
+     *
+     * 判据(与 {@link markSourcesDeleted} 方向相反:那边问"来源是否**全部**消失",
+     * 这边问"来源是否**命中**冲突集",命中一条即存疑):
+     * - `active` 且来源命中冲突集 → `disputed`
+     * - `disputed` 且来源**不**命中冲突集 → 复原为 `active`
+     * - `archived` 墓碑两边都不动(墓碑是删除传播的产物,与争议无关)
+     *
+     * @returns 本次标记 / 复原的节点数。
+     */
+    syncDisputed(disputedRecordIds) {
+        if (!this.db)
+            return { marked: 0, cleared: 0 };
+        try {
+            const hit = new Set(disputedRecordIds);
+            const now = new Date().toISOString();
+            const nodes = this.loadGraph().nodes;
+            const toMark = nodes.filter((n) => n.status === 'active' && n.sourceRecordIds.some((id) => hit.has(id)));
+            // 冲突集为空 = 队列里没有未裁决对 → 所有 disputed 都该复原
+            const toClear = nodes.filter((n) => n.status === 'disputed' && !n.sourceRecordIds.some((id) => hit.has(id)));
+            if (toMark.length === 0 && toClear.length === 0)
+                return { marked: 0, cleared: 0 };
+            this.tx(() => {
+                for (const n of toMark) {
+                    this.db.prepare(`UPDATE graph_nodes SET status = 'disputed', updated_time = ? WHERE node_id = ?`).run(now, n.id);
+                }
+                for (const n of toClear) {
+                    this.db.prepare(`UPDATE graph_nodes SET status = 'active', updated_time = ? WHERE node_id = ?`).run(now, n.id);
+                }
+            });
+            this.logger?.info(`${TAG} 矛盾冻结同步:${toMark.length} 节点标 disputed,${toClear.length} 节点复原 active`);
+            return { marked: toMark.length, cleared: toClear.length };
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} 冻结状态同步失败(忽略): ${err instanceof Error ? err.message : String(err)}`);
+            return { marked: 0, cleared: 0 };
+        }
+    }
     /** 清空全部图谱数据(L1 重建时调用——图谱是 L1 的投影,记录清空即图谱作废)。 */
     resetAll() {
         if (!this.db)

package/dist/store/l1.d.ts

@@ -1,12 +1,27 @@
 import type { L1Hit, MemoryFamily, MemoryLogger, MemoryRecord } from '../types.js';
+import type { GraphNodeSearchResult } from '../graph/types.js';
+import type { L1Receipt, ReceiptQuery } from './receipts.js';
+import type { ConflictPair, ConflictResolution } from './conflicts.js';
 import { type EmbeddingService } from './embedding.js';
 import { type MemoryDb } from './sqlite.js';
 export type RecallStrategy = 'keyword' | 'embedding' | 'hybrid';
+/**
+ * 图谱路提供者(§D 第 3 路):按查询返回图谱命中(已按 score 降序)。
+ * 抽成注入式而非直接读 `db.graphStore`,是为了给 hybrid 融合留一个可替换的测试缝,
+ * 并让「未接线 = 恰为 2 路」成为默认行为(既有调用方零行为变化)。
+ */
+export type GraphLaneProvider = (query: string, limit: number, family?: MemoryFamily) => readonly GraphNodeSearchResult[];
 export interface L1SearchOptions {
     /** 按记忆类型精确过滤(后置过滤,官方做法)。 */
     type?: string;
     /** 按族过滤(undefined = 不过滤,即 auto 档与浏览路径;检索唯一缝的族语义)。 */
     family?: MemoryFamily;
+    /**
+     * §E 当前工作区标识(undefined = **不做可见范围过滤**,与改动前逐字一致)。
+     * 与 `family` 落在**同一条 SQL / 同一层回查**里(ADR-0008 组合关系):
+     * 若只在检索出口过滤而放任去重候选跨工作区相互污染,会产出「看不见但已影响决策」的记忆。
+     */
+    workspaceId?: string;
     /** 分数阈值(仅召回路径传;keyword/embedding 策略生效,FTS 含小语料例外;
      *  hybrid 按官方语义在 RRF 融合前不过滤)。 */
     scoreThreshold?: number;
@@ -23,9 +38,13 @@ export declare class L1Store {
     private readonly logger?;
     /** 时效衰减半衰期(天;0=关)。 */
     private readonly decayHalfLifeDays;
+    /** §D 第 3 路(图谱回链);缺省 = 不接,恰为 2 路。 */
+    private readonly graphLaneProvider?;
     constructor(dataDir: string, db: MemoryDb, embed?: EmbeddingService, strategy?: RecallStrategy, logger?: MemoryLogger, 
     /** 时效衰减半衰期(天;0=关)。缺省 30 与 config 默认一致。 */
-    decayHalfLifeDays?: number);
+    decayHalfLifeDays?: number, 
+    /** 图谱路提供者(§D 第 3 路);不传则该路不存在,融合退回双路。 */
+    graphLane?: GraphLaneProvider);
     init(): Promise<void>;
     /** 旧版单文件 records.jsonl 一次性导入检索库,成功后改名 .imported。 */
     private importLegacy;
@@ -34,6 +53,45 @@ export declare class L1Store {
     all(): MemoryRecord[];
     /** 按 id 精确取记录(去重决策的版本号查询用,避免全表扫描)。 */
     getByIds(ids: string[]): MemoryRecord[];
+    /**
+     * §B 决策凭证落盘(L1Store 的薄缝)。
+     * 刻意放在 store 上:`runExtraction` 已经持有 L1Store,凭证写入因此无需新增
+     * 构造参数或改动签名;同时它也是「写入失败不中断蒸馏」**可注入的测试缝**——
+     * 测试只需替换这一个方法就能模拟落盘故障,不必伪造整个 store。
+     */
+    recordReceipts(rows: readonly L1Receipt[]): number;
+    /**
+     * §B 双维回溯的读缝(task_19)。与 `recordReceipts` 同理由:
+     * 工具层与 RPC 层只认 L1Store,不直连 `db`——保持"检索库的入口只有一处"
+     * 这一既有不变量,也让未来的读缓存/裁剪如需介入仍只有一个落点。
+     */
+    listReceipts(opts: ReceiptQuery & {
+        limit: number;
+    }): L1Receipt[];
+    countReceipts(opts: ReceiptQuery): number;
+    /**
+     * §C 矛盾冻结落盘(thick 缝)。与 `recordReceipts` 同理由:管线已持有 L1Store,
+     * 无需新增构造参数;同时它是「冻结写失败不得中断蒸馏」可注入的测试缝。
+     */
+    recordConflictPending(rows: readonly ConflictPair[]): number;
+    /**
+     * §C 冻结的图谱侧同步:把 `disputed` 状态重算到给定冲突集(命中标记 / 不再命中复原)。
+     * 经 store 而非直取 `db.graphStore`,与图谱路 provider 的注入式设计同一理由
+     * (见本文件头部注释):图谱是**可选**的派生投影,开关关闭时必须是 no-op。
+     */
+    syncGraphDisputed(disputedRecordIds: readonly string[]): {
+        marked: number;
+        cleared: number;
+    };
+    /** §C 待裁决队列的未裁决条数(task_24 队列上限判据)。 */
+    countConflictPendingUnresolved(): number;
+    /** §C 取未裁决冲突对(task_24 超时扫描 / task_25 裁决工具)。 */
+    listConflictPending(opts?: {
+        createdBefore?: string;
+        limit?: number;
+    }): ConflictPair[];
+    /** §C 打上裁决结论(已裁决的不覆盖)。 */
+    resolveConflictPending(pairId: string, resolution: ConflictResolution, resolvedAt: string): number;
     /** 新记忆落盘:JSONL 按天追加(事实源)+ 检索库 upsert + 向量。 */
     appendNew(records: MemoryRecord[]): Promise<void>;
     /** 去重 update/merge 产出的记录:只更新检索库(JSONL 事实源不改写,官方语义)。 */
@@ -48,18 +106,48 @@ export declare class L1Store {
      * 融合完整列表(融合分已归一化 0~1,可直接用于展示/过滤)。
      */
     search(query: string, limit: number, opts?: L1SearchOptions): Promise<L1Hit[]>;
+    /**
+     * §D 第 4 路(时效路,hybrid 专用):把候选池按 `applyDecayWeight` 加权后的
+     * 顺序作为第 4 条**已排序**列表,复用与后处理同源的加权函数(不新增独立逻辑)。
+     *
+     * **时效是排序信号,不是召回信号**:本路只重排 `ftsList ∪ vecList` 里的既有
+     * 候选,**不引入任何新记录**。若让"无关但很新"的记忆靠时效进结果,会直接损害
+     * 检索精度——这条性质由 `tests/recency-lane.test.ts` 的 id 集合不变量钉住。
+     *
+     * **严禁进入 `searchCandidates`**(`search-utils.ts:26-27` 约定):写路径找同语义
+     * 旧记录必须**无视新旧**——一旦被时效加权,老的同义记录会被漏检,导致同事实双记录
+     * 累积。故本方法只被 `search()` 调用,去重候选路径不得引用。
+     */
+    private recencyLane;
+    /**
+     * §D 第 3 路(图谱路径,hybrid 专用):图谱命中 → `sourceRecordIds` 回链 →
+     * L1 记录,作为第 3 条**已排序**列表参与 RRF。
+     *
+     * 为什么值得:图谱是按实体/关系组织的**可重建派生投影**,能召回词法与向量
+     * 都命不中的记录(同义表述、关系可达)——这正是本路相对双路的增量。
+     *
+     * 三条边界:
+     * - **异常降级**:图谱是派生投影,不得因它失败而拖垮主检索 → 记 warn、返回空路,
+     *   融合退回双路(路数随之降为 2,分数回到既有量纲);
+     * - **族隔离**:图谱节点已按族过滤,但其来源记录可能跨族 → 这里再按 `family`
+     *   过滤一次。宁可漏不可串(与档位隔离同源,§A 的 P0 关注点);
+     * - **墓碑边界**:图谱行可能回链到已被删除的 L1 记录 → 取不到就跳过,
+     *   不补空占位(占位会在 RRF 里凭空加分)。
+     */
+    private graphLane;
     /**
      * 时效衰减加权(#29):三路共用的读路径后处理——阈值过滤之后、截断之前
      * (才能轮转名额,而不只是重排已截断的集合)。updated_at 经主表批量点查
      * 回填(FTS 表无该列;候选池 ≤ limit×3 条主键查询,微秒级)。关闭时零开销。
      */
     private applyDecay;
-    /** 浏览列表(UI 用):无关键词时按更新时间倒序分页,支持 Hall 过滤。 */
+    /** 浏览列表(UI 用):无关键词时按更新时间倒序分页,支持 Hall / 可见范围过滤。 */
     list(opts: {
         type?: string;
         scene?: string;
         family?: string;
         hall?: string;
+        workspaceId?: string;
         limit: number;
         offset: number;
     }): {
@@ -70,9 +158,14 @@ export declare class L1Store {
     distinctScenes(): string[];
     /**
      * 去重候选召回(官方 3 级):空库跳过 → 向量优先 → FTS 兜底。
-     * 传入 family 时只在同族记录里召回(去重永不跨族)。
+     * 传入 family 时只在同族记录里召回(去重永不跨族);传入 workspaceId 时
+     * 只在**本工作区可见**的记录里召回(§E)——**去重也不跨工作区**。
+     *
+     * 这一层是 ADR-0008 特意点名的接缝:"scope 过滤必须落在与族隔离同一层"。
+     * 理由:候选池决定**新的去重决策**,若此处跨工作区,产出的是「项目 B 里看不见、
+     * 但已经决定了项目 A 记忆去向」的记录——比不隔离更糟。
      */
-    searchCandidates(query: string, limit: number, family?: MemoryFamily): Promise<MemoryRecord[]>;
+    searchCandidates(query: string, limit: number, family?: MemoryFamily, workspaceId?: string): Promise<MemoryRecord[]>;
     /**
      * 增量重嵌入(embedding 配置变化 / 周期性补齐用):只处理缺失向量的记录,
      * 排除已判定"当前 provider 不可嵌入"的 skip 集。返回写入/失败/跳过数——

package/dist/store/l1.js

@@ -8,10 +8,11 @@
  */
 import { existsSync, promises as fs } from 'node:fs';
 import * as path from 'node:path';
-import { familyForType } from '../types.js';
+import { familyForType, isScopeVisible } from '../types.js';
+import { graphHitRecordIds } from '../graph/search.js';
 import { EmbedHelper, NoopEmbeddingService } from './embedding.js';
 import { appendJsonl, dayKey, ensureDir, readJsonl } from '../util/io.js';
-import { applyDecayWeight, RRF_K, rrfMerge } from './search-utils.js';
+import { applyDecayWeight, normalizeRrf, rrfMerge } from './search-utils.js';
 import { isZeroVector } from './sqlite.js';
 /** 官方过度召回倍数:候选池 = limit × 3(官方 tool 路径同款)。 */
 const CANDIDATE_MULTIPLIER = 3;
@@ -25,9 +26,13 @@ export class L1Store {
     logger;
     /** 时效衰减半衰期(天;0=关)。 */
     decayHalfLifeDays;
+    /** §D 第 3 路(图谱回链);缺省 = 不接,恰为 2 路。 */
+    graphLaneProvider;
     constructor(dataDir, db, embed = new NoopEmbeddingService(), strategy = 'hybrid', logger, 
     /** 时效衰减半衰期(天;0=关)。缺省 30 与 config 默认一致。 */
-    decayHalfLifeDays) {
+    decayHalfLifeDays, 
+    /** 图谱路提供者(§D 第 3 路);不传则该路不存在,融合退回双路。 */
+    graphLane) {
         this.db = db;
         this.strategy = strategy;
         this.recordsDir = path.join(dataDir, 'records');
@@ -36,6 +41,7 @@ export class L1Store {
         this.helper = new EmbedHelper(embed, logger);
         this.logger = logger;
         this.decayHalfLifeDays = decayHalfLifeDays ?? 30;
+        this.graphLaneProvider = graphLane;
     }
     async init() {
         await ensureDir(this.recordsDir);
@@ -84,6 +90,53 @@ export class L1Store {
     getByIds(ids) {
         return this.db.getL1ByIds(ids);
     }
+    /**
+     * §B 决策凭证落盘(L1Store 的薄缝)。
+     * 刻意放在 store 上:`runExtraction` 已经持有 L1Store,凭证写入因此无需新增
+     * 构造参数或改动签名;同时它也是「写入失败不中断蒸馏」**可注入的测试缝**——
+     * 测试只需替换这一个方法就能模拟落盘故障,不必伪造整个 store。
+     */
+    recordReceipts(rows) {
+        return this.db.recordReceipts(rows);
+    }
+    /**
+     * §B 双维回溯的读缝(task_19)。与 `recordReceipts` 同理由:
+     * 工具层与 RPC 层只认 L1Store,不直连 `db`——保持"检索库的入口只有一处"
+     * 这一既有不变量,也让未来的读缓存/裁剪如需介入仍只有一个落点。
+     */
+    listReceipts(opts) {
+        return this.db.listReceipts(opts);
+    }
+    countReceipts(opts) {
+        return this.db.countReceipts(opts);
+    }
+    /**
+     * §C 矛盾冻结落盘(thick 缝)。与 `recordReceipts` 同理由:管线已持有 L1Store,
+     * 无需新增构造参数;同时它是「冻结写失败不得中断蒸馏」可注入的测试缝。
+     */
+    recordConflictPending(rows) {
+        return this.db.recordConflictPending(rows);
+    }
+    /**
+     * §C 冻结的图谱侧同步:把 `disputed` 状态重算到给定冲突集(命中标记 / 不再命中复原)。
+     * 经 store 而非直取 `db.graphStore`,与图谱路 provider 的注入式设计同一理由
+     * (见本文件头部注释):图谱是**可选**的派生投影,开关关闭时必须是 no-op。
+     */
+    syncGraphDisputed(disputedRecordIds) {
+        return this.db.syncGraphDisputed(disputedRecordIds);
+    }
+    /** §C 待裁决队列的未裁决条数(task_24 队列上限判据)。 */
+    countConflictPendingUnresolved() {
+        return this.db.countConflictPendingUnresolved();
+    }
+    /** §C 取未裁决冲突对(task_24 超时扫描 / task_25 裁决工具)。 */
+    listConflictPending(opts = {}) {
+        return this.db.listConflictPending(opts);
+    }
+    /** §C 打上裁决结论(已裁决的不覆盖)。 */
+    resolveConflictPending(pairId, resolution, resolvedAt) {
+        return this.db.resolveConflictPending(pairId, resolution, resolvedAt);
+    }
     /** 新记忆落盘:JSONL 按天追加(事实源)+ 检索库 upsert + 向量。 */
     async appendNew(records) {
         if (records.length === 0)
@@ -146,28 +199,116 @@ export class L1Store {
         if (strategy === 'none')
             return [];
         if (strategy === 'keyword') {
-            const fts = this.db.searchL1Fts(query, candidateK, opts?.family);
+            const fts = this.db.searchL1Fts(query, candidateK, opts?.family, opts?.workspaceId);
             return this.postProcess(this.applyDecay(applyFtsThreshold(fts, threshold, limit)), opts?.type, limit);
         }
         if (strategy === 'embedding') {
             const vec = await this.helper.query(query, opts?.embeddingTimeoutMs);
             if (!vec) {
                 // embedding 调用失败:降级 FTS,不阻断
-                const fts = this.db.searchL1Fts(query, candidateK, opts?.family);
+                const fts = this.db.searchL1Fts(query, candidateK, opts?.family, opts?.workspaceId);
                 return this.postProcess(this.applyDecay(applyFtsThreshold(fts, threshold, limit)), opts?.type, limit);
             }
-            const vecHits = this.db.searchL1Vector(vec, candidateK, opts?.family);
+            const vecHits = this.db.searchL1Vector(vec, candidateK, opts?.family, opts?.workspaceId);
             return this.postProcess(this.applyDecay(filterScore(vecHits, threshold)), opts?.type, limit);
         }
-        // hybrid(官方语义):双路并行 → 完整列表 RRF 融合(融合前不过滤阈值)
-        // → 融合分归一化:rank1 双列表命中 = 1.0,单列表命中 ≤ 0.5,保持 0~1 语义
+        // hybrid(官方语义):多路并行 → 完整列表 RRF 融合(融合前不过滤阈值)
+        // → 融合分按**实际路数**归一化:全路 rank1 命中 = 1.0,双路单列表命中 ≤ 0.5
         const [ftsList, vecRaw] = await Promise.all([
-            Promise.resolve(this.db.searchL1Fts(query, candidateK, opts?.family)),
+            Promise.resolve(this.db.searchL1Fts(query, candidateK, opts?.family, opts?.workspaceId)),
             this.helper.query(query, opts?.embeddingTimeoutMs),
         ]);
-        const vecList = vecRaw ? this.db.searchL1Vector(vecRaw, candidateK, opts?.family) : [];
-        const merged = rrfMerge([ftsList, vecList], (h) => h.id);
-        return this.postProcess(this.applyDecay(merged.map(({ rrfScore, ...h }) => ({ ...h, score: normalizeRrf(rrfScore) }))), opts?.type, limit);
+        const vecList = vecRaw ? this.db.searchL1Vector(vecRaw, candidateK, opts?.family, opts?.workspaceId) : [];
+        // 第 3 路(图谱)仅在接线时**结构性存在**:未接线不占路数名额,故既有调用方
+        // 仍走 2 路、得分与改动前逐位一致(见 findings.md §12.1 的路数语义)
+        const lanes = [ftsList, vecList];
+        if (this.graphLaneProvider)
+            lanes.push(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);
+    }
+    /**
+     * §D 第 4 路(时效路,hybrid 专用):把候选池按 `applyDecayWeight` 加权后的
+     * 顺序作为第 4 条**已排序**列表,复用与后处理同源的加权函数(不新增独立逻辑)。
+     *
+     * **时效是排序信号,不是召回信号**:本路只重排 `ftsList ∪ vecList` 里的既有
+     * 候选,**不引入任何新记录**。若让"无关但很新"的记忆靠时效进结果,会直接损害
+     * 检索精度——这条性质由 `tests/recency-lane.test.ts` 的 id 集合不变量钉住。
+     *
+     * **严禁进入 `searchCandidates`**(`search-utils.ts:26-27` 约定):写路径找同语义
+     * 旧记录必须**无视新旧**——一旦被时效加权,老的同义记录会被漏检,导致同事实双记录
+     * 累积。故本方法只被 `search()` 调用,去重候选路径不得引用。
+     */
+    recencyLane(candidates) {
+        if (!(this.decayHalfLifeDays > 0) || candidates.length === 0)
+            return [];
+        const seen = new Set();
+        const deduped = [];
+        for (const h of candidates) {
+            if (seen.has(h.id))
+                continue;
+            seen.add(h.id);
+            deduped.push(h);
+        }
+        return this.applyDecay(deduped);
+    }
+    /**
+     * §D 第 3 路(图谱路径,hybrid 专用):图谱命中 → `sourceRecordIds` 回链 →
+     * L1 记录,作为第 3 条**已排序**列表参与 RRF。
+     *
+     * 为什么值得:图谱是按实体/关系组织的**可重建派生投影**,能召回词法与向量
+     * 都命不中的记录(同义表述、关系可达)——这正是本路相对双路的增量。
+     *
+     * 三条边界:
+     * - **异常降级**:图谱是派生投影,不得因它失败而拖垮主检索 → 记 warn、返回空路,
+     *   融合退回双路(路数随之降为 2,分数回到既有量纲);
+     * - **族隔离**:图谱节点已按族过滤,但其来源记录可能跨族 → 这里再按 `family`
+     *   过滤一次。宁可漏不可串(与档位隔离同源,§A 的 P0 关注点);
+     * - **墓碑边界**:图谱行可能回链到已被删除的 L1 记录 → 取不到就跳过,
+     *   不补空占位(占位会在 RRF 里凭空加分)。
+     */
+    graphLane(query, limit, family, workspaceId) {
+        const provider = this.graphLaneProvider;
+        if (!provider)
+            return [];
+        let hits;
+        try {
+            hits = 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 out = [];
+        for (const id of ids) {
+            const r = byId.get(id);
+            if (!r)
+                continue;
+            if (family !== undefined && r.family !== family)
+                continue;
+            // §E:与族隔离**同一层**再过滤一次。图谱节点自身没有 scope——归属由**来源记录**
+            // 决定(节点是 L1 的派生投影,它不该有独立于来源的可见范围)。
+            if (workspaceId !== undefined && !isScopeVisible(r.scope, r.workspaceId, workspaceId))
+                continue;
+            out.push({
+                id: r.id,
+                content: r.content,
+                type: r.type,
+                scene_name: r.scene_name,
+                priority: r.priority,
+                family: r.family,
+                // 占位分:RRF 只用 rank,此字段在融合时会被归一化分覆盖
+                score: 0,
+            });
+        }
+        return out;
     }
     /**
      * 时效衰减加权(#29):三路共用的读路径后处理——阈值过滤之后、截断之前
@@ -184,7 +325,7 @@ export class L1Store {
         }
         return applyDecayWeight(hits, this.decayHalfLifeDays, (h) => updatedAtById.get(h.id));
     }
-    /** 浏览列表(UI 用):无关键词时按更新时间倒序分页,支持 Hall 过滤。 */
+    /** 浏览列表(UI 用):无关键词时按更新时间倒序分页,支持 Hall / 可见范围过滤。 */
     list(opts) {
         return this.db.listL1(opts);
     }
@@ -194,9 +335,14 @@ export class L1Store {
     }
     /**
      * 去重候选召回(官方 3 级):空库跳过 → 向量优先 → FTS 兜底。
-     * 传入 family 时只在同族记录里召回(去重永不跨族)。
+     * 传入 family 时只在同族记录里召回(去重永不跨族);传入 workspaceId 时
+     * 只在**本工作区可见**的记录里召回(§E)——**去重也不跨工作区**。
+     *
+     * 这一层是 ADR-0008 特意点名的接缝:"scope 过滤必须落在与族隔离同一层"。
+     * 理由:候选池决定**新的去重决策**,若此处跨工作区,产出的是「项目 B 里看不见、
+     * 但已经决定了项目 A 记忆去向」的记录——比不隔离更糟。
      */
-    async searchCandidates(query, limit, family) {
+    async searchCandidates(query, limit, family, workspaceId) {
         if (this.db.countL1() === 0)
             return [];
         const caps = this.db.getCapabilities();
@@ -204,7 +350,7 @@ export class L1Store {
             try {
                 const vec = await this.helper.query(query);
                 if (vec) {
-                    const hits = this.db.searchL1Vector(vec, limit, family);
+                    const hits = this.db.searchL1Vector(vec, limit, family, workspaceId);
                     if (hits.length > 0)
                         return this.db.getL1ByIds(hits.map((h) => h.id));
                 }
@@ -213,7 +359,7 @@ export class L1Store {
                 this.logger?.warn(`[memory] 向量候选召回失败,降级 FTS: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
-        const fts = this.db.searchL1Fts(query, limit * 2, family);
+        const fts = this.db.searchL1Fts(query, limit * 2, family, workspaceId);
         return this.db.getL1ByIds(fts.map((h) => h.id));
     }
     /**
@@ -277,10 +423,6 @@ export class L1Store {
         return filtered.slice(0, limit);
     }
 }
-/** RRF 原始分归一化到 0~1:双列表 rank1 命中 = 2/(k+1) → 1.0。 */
-function normalizeRrf(rrfScore) {
-    return (rrfScore * (RRF_K + 1)) / 2;
-}
 /** FTS 阈值过滤(含官方小语料例外:全部低于阈值但结果数 ≤ maxResults 时保留)。 */
 function applyFtsThreshold(hits, threshold, maxResults) {
     if (threshold <= 0)