dsh-prime-memory 0.11.0 → 0.12.1

package/dist/stats.js

@@ -1,10 +1,12 @@
 /**
- * 状态面板数据通道:Host 侧注册 /rpc 通道的 dsh-memory/* 端点,
- * Client 设置页通过 ctx.connection.rpc.call('/rpc', 'dsh-memory/xxx') 拉取。
+ * 状态面板数据通道(0.1.5 契约):Host 半直接向 webServer 注册 prefix 路由
+ * `POST /dsh-memory/rpc/<method>`,Client 设置页用浏览器原生 fetch 拉取,
+ * 信封即 RpcResult({ok,value} | {ok,error})——不经过 connection.rpc
+ * (handle 前缀通道 0.1.5 静默 405;/api interceptor 单槽会被他插件抢占)。
  *
- * connection 是可选服务且可能晚于本插件就绪:先探测一次,未就绪则监听
+ * webServer 是可选服务且可能晚于本插件就绪:先探测一次,未就绪则监听
  * internal/service(事件携带 (name, impl),impl=undefined 即下线),服务
- * 上线、下线、替换实例三种迁移都会正确释放/重挂 RPC 注册。
+ * 上线、下线、替换实例三种迁移都会正确释放/重挂路由注册。
  *
  * 机密纪律:directApiKey / embedRemoteApiKey 永不出现在任何 RPC 响应与日志
  * (settings-get/set 走 sanitizeSettings 脱敏)。
@@ -17,10 +19,119 @@ import { effectiveCfg } from './pipeline/runner.js';
 import { emptyRecallStats } from './hooks/recall.js';
 import { buildRouteChain, decideSendableEffort, LAYER_DEFAULT_BUDGETS, layerChainOrNull, resolveModelContextWindow, resolveModelEfforts, resolveModelRoute } from './llm.js';
 import { projectDistillChain, validateDistillChain } from './settings.js';
+import { RECEIPTS_QUERY_LIMIT_MAX, dimensionOf, toReceiptView } from './store/receipts.js';
+import { resolveConflictPair } from './conflict-service.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;
+/**
+ * 端点全集运行时清单(31 个,与 tests/contract-keys.test.ts 的 ENDPOINTS 及
+ * contract.ts 类型映射表三方对齐,漂移由键集 diff 测试暴露)。
+ * 注意:本清单同时是 HTTP 前缀路由 `/dsh-memory/rpc/<短名>` 的**放行白名单**
+ * (见下方 SHORT_ENDPOINTS),漏一条 = 该端点在面板里静默消失(404 被客户端
+ * rpc 的 catch 吞掉,无任何报错),故必须与 contract.ts 的 DshMemoryRequestMap
+ * 严格逐项一致。
+ * 用途:0.1.5 共享通道 /api 的 interceptor 是单槽(多插件会抛 already has an
+ * interceptor),精确 Fetch 路由按路径 key 可共存且分发优先于 interceptor——
+ * 因此逐端点注册 `POST /api/<endpoint>` 精确路由,彻底绕开槽位竞争。
+ */
+export const MEMORY_ENDPOINTS = [
+    'dsh-memory/stats',
+    'dsh-memory/token-cost',
+    'dsh-memory/session-mode-get',
+    'dsh-memory/session-mode-set',
+    'dsh-memory/session-stats',
+    'dsh-memory/settings-get',
+    'dsh-memory/settings-set',
+    'dsh-memory/list-records',
+    'dsh-memory/records-delete',
+    'dsh-memory/receipts',
+    'dsh-memory/conflict-resolve',
+    'dsh-memory/graph-search',
+    'dsh-memory/graph-node-get',
+    'dsh-memory/scenes',
+    'dsh-memory/persona',
+    'dsh-memory/log-tail',
+    'dsh-memory/rebuild-status',
+    'dsh-memory/rebuild-start',
+    'dsh-memory/rebuild-cancel',
+    'dsh-memory/ruminate-status',
+    'dsh-memory/ruminate-start',
+    'dsh-memory/ruminate-cancel',
+    'dsh-memory/llm-providers',
+    'dsh-memory/llm-models',
+    'dsh-memory/embedding-state-get',
+    'dsh-memory/embedding-source-set',
+    'dsh-memory/embedding-download-start',
+    'dsh-memory/embedding-download-cancel',
+    'dsh-memory/embedding-model-delete',
+    'dsh-memory/embedding-runtime-cancel',
+    'dsh-memory/embedding-reindex-cancel',
+];
+/** HTTP 路由前缀(客户端 fetch `/dsh-memory/rpc/<短方法名>`)。 */
+const RPC_ROUTE_PREFIX = '/dsh-memory/rpc';
+/** 短方法名视图(MEMORY_ENDPOINTS 去掉 'dsh-memory/' 前缀,URL 段用)。 */
+const SHORT_ENDPOINTS = MEMORY_ENDPOINTS.map((e) => e.slice('dsh-memory/'.length));
+/** Host 头是否为 loopback 主机名(localhost / [::1] / 127.x.x.x)。 */
+function isLoopbackHostname(hostname) {
+    if (hostname === 'localhost' || hostname === '[::1]')
+        return true;
+    const parts = hostname.split('.');
+    return parts.length === 4 && parts[0] === '127' && parts.every((p) => /^\d{1,3}$/.test(p) && Number(p) <= 255);
+}
+/**
+ * API 信任围栏:DNS-rebinding / 跨站防护(非用户鉴权),语义对齐 connection
+ * /api 网关的 fence——Host 头必须指向 loopback。面板数据非机密(密钥字段
+ * 宿主侧已脱敏),故 loopback 即放行;跨站浏览器标记随 Host 校验一并拒绝。
+ */
+function apiFence(req) {
+    const host = req.headers.host;
+    if (typeof host !== 'string' || host.length === 0)
+        return false;
+    // 不写初值:catch 分支直接 return,初值在任何路径下都不会被读取
+    // (原 `let hostname = host` 是死存储,eslint no-useless-assignment)。
+    let hostname;
+    try {
+        hostname = new URL(`http://${host}`).hostname;
+    }
+    catch {
+        return false;
+    }
+    return isLoopbackHostname(hostname);
+}
+function writeJson(res, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(body));
+}
+/** 读取 JSON 请求体(上限 8MB:面板最大载荷为 list-records 分页与图谱检索)。 */
+function readJsonBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > 8 * 1024 * 1024) {
+                reject(new Error('request body too large'));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => {
+            const raw = Buffer.concat(chunks).toString('utf8');
+            if (raw.length === 0)
+                return resolve({});
+            try {
+                resolve(JSON.parse(raw));
+            }
+            catch {
+                reject(new Error('body is not JSON'));
+            }
+        });
+        req.on('error', reject);
+    });
+}
 /**
  * 组装端点 deps。抽成函数是为了让"哪个控制器落入哪个字段"成为可测接缝:
  * 反刍端点读 deps.ruminate,若此处漏注入,端点会静默恒返 {supported:false}(面板整块不渲染)。
@@ -49,35 +160,79 @@ ruminate) {
     const tryRegister = () => {
         if (holding)
             return;
-        const connection = ctx.get('connection');
-        if (!connection)
+        const webServer = ctx.get('webServer');
+        if (!webServer || typeof webServer.register !== 'function')
             return;
-        holding = true;
-        let active = true;
-        // handle() 同步注册并返回异步 disposer(() => Promise<void>)。
-        const dispose = connection.rpc.handle('/rpc', async (endpoint, payload) => {
-            try {
-                const value = await handleEndpoint(endpoint, payload, buildEndpointDeps({ ctx, cfg, stores, logger }, { status, live, modes, dataDir, rebuild, embedManager, sessionInfo }, ruminate));
-                return { ok: true, value };
-            }
-            catch (err) {
-                return {
-                    ok: false,
-                    error: { code: 'internal', message: err instanceof Error ? err.message : String(err), details: {} },
-                };
+        let dispose = () => { };
+        try {
+            holding = true;
+            let active = true;
+            // 端点处理器:HTTP 层与旧 connection.rpc 的 handler 共用同一分发。
+            const rpcHandler = async (endpoint, payload) => {
+                try {
+                    const value = await handleEndpoint(endpoint, payload, buildEndpointDeps({ ctx, cfg, stores, logger }, { status, live, modes, dataDir, rebuild, embedManager, sessionInfo }, ruminate));
+                    return { ok: true, value };
+                }
+                catch (err) {
+                    return {
+                        ok: false,
+                        error: { code: 'internal', message: err instanceof Error ? err.message : String(err), details: {} },
+                    };
+                }
+            };
+            // 0.1.5 契约(参考 better-sidebar main 分支的已验证实现):不再经过
+            // connection.rpc —— handle 前缀通道在 0.1.5 webServer 分发层静默 405
+            // (讨论区 #6337),/api 共享通道 interceptor 是单槽、会被其他 0.1.5 插件
+            // (如 dsh-live-token-stats)抢占。直接在插件自己的 fiber 上向 webServer
+            // 注册 prefix 路由(plain req/res + 自有 RpcResult 信封)。
+            // 鉴权面:同源浏览器的 DNS-rebinding 防护(Host 须 loopback),与
+            // connection /api 网关的 fence 语义一致;不做用户鉴权——面板数据非机密,
+            // 机密字段(directApiKey 等)在 settings-get 已由 sanitizeSettings 脱敏。
+            const registered = webServer.register({
+                kind: 'prefix',
+                path: RPC_ROUTE_PREFIX,
+                handler: async (req, res) => {
+                    if (!apiFence(req))
+                        return writeJson(res, 403, { ok: false, error: { code: 'forbidden', message: 'forbidden' } });
+                    if (req.method !== 'POST') {
+                        return writeJson(res, 405, { ok: false, error: { code: 'method-error', message: 'method not allowed' } });
+                    }
+                    const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname;
+                    if (!pathname.startsWith(`${RPC_ROUTE_PREFIX}/`)) {
+                        return writeJson(res, 404, { ok: false, error: { code: 'not-found', message: 'unknown api path' } });
+                    }
+                    const method = pathname.slice(RPC_ROUTE_PREFIX.length + 1);
+                    if (method.includes('/') || !SHORT_ENDPOINTS.includes(method)) {
+                        return writeJson(res, 404, { ok: false, error: { code: 'not-found', message: `unknown api method "${method}"` } });
+                    }
+                    try {
+                        const payload = await readJsonBody(req);
+                        const result = await rpcHandler(`dsh-memory/${method}`, payload);
+                        writeJson(res, 200, result);
+                    }
+                    catch (err) {
+                        writeJson(res, 400, { ok: false, error: { code: 'bad-request', message: err instanceof Error ? err.message : String(err) } });
+                    }
+                },
+            });
+            dispose = typeof registered === 'function' ? registered : () => { };
+            registeredImpl = webServer;
+            if (!active) {
+                void dispose();
+                holding = false;
+                return;
             }
-        }, { authority: 'loopback' });
-        registeredImpl = connection;
-        if (!active) {
-            void dispose();
-            return;
+            logger.info('[memory] 状态 API 已注册(POST /dsh-memory/rpc/<method>)');
+            disposers.push(() => {
+                active = false;
+                holding = false;
+                void dispose();
+            });
         }
-        logger.debug?.('[memory] 状态 RPC 已注册(/rpc → dsh-memory/*)');
-        disposers.push(() => {
-            active = false;
+        catch (err) {
             holding = false;
-            void dispose();
-        });
+            logger.warn(`[memory] 状态 API 注册失败(设置面板将不可用,其余功能不受影响): ${err instanceof Error ? err.message : String(err)}`);
+        }
     };
     /** 释放全部持有注册(handle 随旧服务实例失效,holding 复位以允许重挂)。 */
     const release = () => {
@@ -88,14 +243,14 @@ ruminate) {
     ctx.effect(() => {
         tryRegister();
         const off = ctx.on('internal/service', (name, impl) => {
-            if (name !== 'connection')
+            if (name !== 'webServer')
                 return;
             if (!impl) {
-                // 服务下线:旧 handle 已随旧服务实例失效——主动释放并复位,
-                // 服务恢复时本事件再触发即可重挂(否则 holding 恒真 → RPC 永久失联)
+                // 服务下线:旧路由注册已随旧服务实例失效——主动释放并复位,
+                // 服务恢复时本事件再触发即可重挂(否则 holding 恒真 → API 永久失联)
                 release();
                 registeredImpl = undefined;
-                logger.debug?.('[memory] connection 服务下线,RPC 注册已释放(待恢复重挂)');
+                logger.debug?.('[memory] webServer 服务下线,状态 API 注册已释放(待恢复重挂)');
                 return;
             }
             if (impl !== registeredImpl) {
@@ -543,6 +698,40 @@ export async function handleEndpoint(endpoint, payload, deps) {
             };
             return resp;
         }
+        // ── §B 决策凭证回溯(task_19):与 memory_receipts 工具共用同一形状 ──
+        // 端点层**不给"提示文案"这个出口**:工具是给模型用的,拒答必须变成可读的一句话;
+        // 端点是给程序/面板用的,缺参就是调用错误,静默返回空会让调用方以为"确实没有"。
+        case 'dsh-memory/receipts': {
+            const p = (payload ?? {});
+            const query = {
+                recordId: typeof p.recordId === 'string' && p.recordId.trim() ? p.recordId.trim() : undefined,
+                runId: typeof p.runId === 'string' && p.runId.trim() ? p.runId.trim() : undefined,
+            };
+            const dimension = dimensionOf(query);
+            if (dimension === 'none')
+                throw new Error('需要 recordId 或 runId 至少一个(不支持查全部凭证)');
+            const limit = Math.min(Math.max(Math.floor(Number(p.limit)) || 20, 1), RECEIPTS_QUERY_LIMIT_MAX);
+            const rows = stores.l1.listReceipts({ ...query, limit });
+            const resp = {
+                dimension,
+                items: rows.map(toReceiptView),
+                total: stores.l1.countReceipts(query),
+            };
+            return resp;
+        }
+        // ── §C 矛盾冻结裁决(task_25):与 memory_resolve_conflict 工具共用同一形状 ──
+        // 端点层同样不给"提示文案"出口的例外只有一条:**队列未开启**不是调用错误而是
+        // 部署状态,故它走返回体(带 notice)而非抛错;pair_id/outcome 缺参才抛。
+        case 'dsh-memory/conflict-resolve': {
+            const p = (payload ?? {});
+            const pairId = typeof p.pairId === 'string' ? p.pairId.trim() : '';
+            const outcome = typeof p.outcome === 'string' ? p.outcome.trim() : '';
+            if (!pairId)
+                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);
+        }
         case 'dsh-memory/records-delete': {
             // 面板高权限删除指定记忆;写入删权限门(memoryMutate)防御
             if (!live?.get().memoryMutate) {

package/dist/store/conflicts.d.ts

@@ -0,0 +1,62 @@
+/** 冻结对的格式版本。进入 pair_id 的摘要输入,使算法演进时不会静默让新旧 id 混同。 */
+export declare const CONFLICT_FORMAT = "c-conflict-pending/v1";
+/**
+ * 冻结对的稳定 id。
+ *
+ * **确定性**是刻意的:`runId + winner + loser` 三元组恒产同一 pair_id,
+ * 于是同一轮重复落盘被 `INSERT OR IGNORE` 吃掉——幂等来自**主键**而非调用方自觉。
+ * 沿用 §B 的 `receiptIdFor` 手法(同一哈希、同一长度前缀编码),不另造一套。
+ */
+export declare function conflictPairId(runId: string, winnerId: string, loserId: string): string;
+/**
+ * 裁决结论。
+ * - `winner` / `loser`:人工判定哪一方为真(另一方从检索库退场);
+ * - `both`:两条都保留——人工判定它们其实是**各自独立的事实**,不是矛盾
+ *   (LLM 判错的情形,必须有出口,否则只能被迫删掉一条正确记忆);
+ * - `auto`:**机器**按 LLM 给出的 winner/loser 自行了结(task_24 安全阀:
+ *   队列满或超时)。刻意与人工取值分开——§C 存在的理由就是"机器不该替人裁决",
+ *   若自动了结在人眼里与人工结论无从区分,那个行为会以"悄悄发生"的形式回来。
+ */
+export type ConflictResolution = 'winner' | 'loser' | 'both' | 'auto';
+/** 未裁决时 `resolved_at` / `resolution` 的取值(空串,不用 NULL)。 */
+export declare const CONFLICT_UNRESOLVED = "";
+/** 一条待裁决冲突对(与 `conflict_pending` 表一行同形)。 */
+export interface ConflictPair {
+    pairId: string;
+    /** 产生该冻结的 L1 蒸馏批次 id(接 §B 凭证链)。 */
+    runId: string;
+    /** LLM 建议的胜方 id。**只是进入待裁决对时的排序位,不代表最终结论**。 */
+    winnerId: string;
+    /** LLM 建议的败方 id。同上。 */
+    loserId: string;
+    createdAt: string;
+    /** 空串 = 未裁决。 */
+    resolvedAt: string;
+    /** 空串 = 未裁决;否则为 {@link ConflictResolution}。 */
+    resolution: string;
+}
+/** 构建冻结对所需的输入。 */
+export interface ConflictPairInput {
+    runId: string;
+    winnerId: string;
+    loserId: string;
+    createdAt: string;
+}
+/** 由输入构造一行待裁决冲突对(未裁决态)。纯函数,无 I/O。 */
+export declare function buildConflictPair(input: ConflictPairInput): ConflictPair;
+/**
+ * 校验 LLM 给出的 conflict 决策是否**够得着一条冻结对**。
+ *
+ * 三条都必需,缺一即无法停放,调用方须回落 `store`(信息绝不丢):
+ * ① winner / loser 都是非空 id;
+ * ② 二者**不同**——指向同一条记录是无效输出(承自 mneme 的 `validateDecisions`);
+ * ③ 其中**恰有一方是本条新记忆**(`recordId`),另一方是候选池里的已有记录
+ *    (由调用方用 `knownIds` 判定存活)。否则"对"无从成立:要么新记忆没有对手,
+ *    要么对侧是模型幻觉出来的 id。
+ *
+ * 返回规范化后的 `{ winnerId, loserId }`,或 `null`(表示不构成冻结对)。
+ */
+export declare function validateConflictPair(recordId: string, winner: unknown, loser: unknown, knownIds: ReadonlySet<string>): {
+    winnerId: string;
+    loserId: string;
+} | null;

package/dist/store/conflicts.js

@@ -0,0 +1,69 @@
+/**
+ * §C 矛盾冻结:待裁决冲突对(pending conflict pairs)。
+ *
+ * 语义承自 mneme 的 dream layer:*"the dream layer does **NOT** auto-adjudicate
+ * winner/loser — the conflicting pair is parked here until a human reviews it."*
+ * ——冻结**不是"拦住写入"**,而是"不自动裁决":新记忆照常入 L1,与冲突的旧记忆
+ * 作为**一对**停放在 `conflict_pending`,双方内容都不被改写,直到人工裁决。
+ *
+ * 与 §B 的关系:冻结产生的裁决结果需要凭证链才能审计——`run_id` 直接沿用该轮
+ * L1 蒸馏的 `runId`,故一条待裁决对被 `memory_receipts(run_id)` 一查即可看到
+ * 「这一轮到底判了什么」(findings.md §3 / §9)。
+ *
+ * 本文件承载契约中最纯的那一半:pair_id 的构造。
+ */
+import { inputDigest } from './receipts.js';
+/** 冻结对的格式版本。进入 pair_id 的摘要输入,使算法演进时不会静默让新旧 id 混同。 */
+export const CONFLICT_FORMAT = 'c-conflict-pending/v1';
+/**
+ * 冻结对的稳定 id。
+ *
+ * **确定性**是刻意的:`runId + winner + loser` 三元组恒产同一 pair_id,
+ * 于是同一轮重复落盘被 `INSERT OR IGNORE` 吃掉——幂等来自**主键**而非调用方自觉。
+ * 沿用 §B 的 `receiptIdFor` 手法(同一哈希、同一长度前缀编码),不另造一套。
+ */
+export function conflictPairId(runId, winnerId, loserId) {
+    return inputDigest([CONFLICT_FORMAT, runId, winnerId, loserId]);
+}
+/** 未裁决时 `resolved_at` / `resolution` 的取值(空串,不用 NULL)。 */
+export const CONFLICT_UNRESOLVED = '';
+/** 由输入构造一行待裁决冲突对(未裁决态)。纯函数,无 I/O。 */
+export function buildConflictPair(input) {
+    return {
+        pairId: conflictPairId(input.runId, input.winnerId, input.loserId),
+        runId: input.runId,
+        winnerId: input.winnerId,
+        loserId: input.loserId,
+        createdAt: input.createdAt,
+        resolvedAt: CONFLICT_UNRESOLVED,
+        resolution: CONFLICT_UNRESOLVED,
+    };
+}
+/**
+ * 校验 LLM 给出的 conflict 决策是否**够得着一条冻结对**。
+ *
+ * 三条都必需,缺一即无法停放,调用方须回落 `store`(信息绝不丢):
+ * ① winner / loser 都是非空 id;
+ * ② 二者**不同**——指向同一条记录是无效输出(承自 mneme 的 `validateDecisions`);
+ * ③ 其中**恰有一方是本条新记忆**(`recordId`),另一方是候选池里的已有记录
+ *    (由调用方用 `knownIds` 判定存活)。否则"对"无从成立:要么新记忆没有对手,
+ *    要么对侧是模型幻觉出来的 id。
+ *
+ * 返回规范化后的 `{ winnerId, loserId }`,或 `null`(表示不构成冻结对)。
+ */
+export function validateConflictPair(recordId, winner, loser, knownIds) {
+    if (typeof winner !== 'string' || typeof loser !== 'string')
+        return null;
+    const w = winner.trim();
+    const l = loser.trim();
+    if (!w || !l || w === l)
+        return null;
+    // ③ 恰有一方是新记忆,另一方必须是已知候选
+    const sides = w === recordId ? [[w, l]] : l === recordId ? [[l, w]] : [];
+    if (sides.length === 0)
+        return null;
+    const other = sides[0][0] === w ? l : w;
+    if (!knownIds.has(other))
+        return null;
+    return { winnerId: w, loserId: l };
+}

package/dist/store/graph-store.d.ts

@@ -1,6 +1,16 @@
 import type { DatabaseSync } from 'node:sqlite';
 import type { GraphEdge, GraphNode, GraphNodeSearchResult, GraphProjectionJob, GraphProjectionResult } from '../graph/types.js';
 import type { MemoryFamily, MemoryLogger, MemoryRecord } from '../types.js';
+/**
+ * 图谱**向量路**单条命中。刻意不复用词法路的 `GraphNodeSearchResult`:
+ * 那个类型要求 `matchedFields`(命中在哪些字段)与 `matchReason`(中文解释),
+ * 而向量检索**没有"命中哪个字段"这个概念**——塞一个空数组进去会违反该类型
+ * "无命中不返回、空数组不出现"的既有约定,把两种语义混成一个类型。
+ */
+export interface GraphNodeVecHit {
+    node: GraphNode;
+    score: number;
+}
 /** claim 的产出:job 元数据 + 本批真实存在的来源记录(已剔除被删者)。 */
 export interface GraphClaim {
     job: GraphProjectionJob;
@@ -16,13 +26,54 @@ export declare class GraphStore {
     private logger;
     private stmtInsertNode;
     private stmtInsertEdge;
+    /**
+     * §F 图谱节点向量列（vec0）。**结构性可选**：维度未定或 vec0 不可用时这三个
+     * 语句就是 `undefined`，该路整体 no-op——既不影响图谱的词法检索，也不向上抛。
+     */
+    private stmtInsertNodeVec?;
+    private stmtDeleteNodeVec?;
+    private stmtSearchNodeVec?;
     /** init 是否就绪(未就绪 = 图谱域整体 no-op,不抛错不传染)。 */
     get ready(): boolean;
     /**
      * 建表 + 语句缓存(MemoryDb.initSchema 内调用)。任何一步失败都只告警并保持
      * 未就绪——图谱域整体降级 no-op,检索主链路(L0/L1/FTS/向量)不受影响。
+     *
+     * @param vec §F 节点向量列的维度(来自 MemoryDb 的**既有**能力探测结果;
+     *   缺省/0 = 部署未启用向量 → 该路结构性不存在,不建表也不报错)。
+     */
+    init(db: DatabaseSync, logger?: MemoryLogger, vec?: {
+        dimensions: number;
+    }): void;
+    /**
+     * §F 图谱节点向量列：与 `l1_vec` **同模式**的 vec0 虚拟表——同一个 `vec-utils`
+     * 编码、同一种 `float[N] distance_metric=cosine` 声明。
+     *
+     * **内层 try/catch 是刻意的**（task_34）：vec0 扩展缺失时 `CREATE VIRTUAL TABLE`
+     * 会抛。若让它冒到外层，图谱会从"向量路不可用"退化成"**整个图谱域不可用**"——
+     * 词法检索、投影、裁决全部陪葬。外层那层 catch 是给"图谱表建不起来"用的，
+     * 不该被一个**可选**的向量列触发。
+     */
+    private prepareNodeVec;
+    /** 节点向量路是否可用。未就绪时下方两个方法的调用方**无需分支**——它们自身 no-op。 */
+    get nodeVecReady(): boolean;
+    /**
+     * 写入/覆盖节点向量(先删后插:vec0 不支持 ON CONFLICT)。
+     * 未就绪 / 零向量 / 单条失败 → **静默跳过**,绝不抛。
+     * @returns 实际写入条数(供调用方记账,不用于控制流)。
+     */
+    upsertNodeVectors(rows: ReadonlyArray<{
+        nodeId: string;
+        embedding: Float32Array;
+        updatedAt?: string;
+    }>): number;
+    /** 删除节点向量(节点删/合并时用)。未就绪 no-op。 */
+    deleteNodeVectors(nodeIds: readonly string[]): void;
+    /**
+     * 向量检索节点(按 cosine 距离升序,score = 1 - distance,与 L1 向量路同口径)。
+     * 未就绪返回**空数组**——调用方无需判断 `nodeVecReady`,降级是内建的。
      */
-    init(db: DatabaseSync, logger?: MemoryLogger): void;
+    searchNodesByVector(embedding: Float32Array, topK: number): GraphNodeVecHit[];
     /** 插件停机时清空连接引用(dispose 序调用,防悬空引用)。 */
     close(): void;
     /** 统一事务边界(immediate 供 complete 全程持写锁)。 */
@@ -89,6 +140,26 @@ export declare class GraphStore {
      * 之后;按 L1 存活集判定(而非本次删除集合),跨多次删除与历史孤儿一并收敛。
      */
     markSourcesDeleted(deletedIds: readonly string[]): void;
+    /**
+     * §C 矛盾冻结:把图谱的 `disputed` 状态**同步**到给定冲突集。
+     *
+     * 为什么是"同步"而不是"标记":裁决会**撤销**争议。只做单向标记的话,
+     * 一对已被人工裁决的对,其节点会永远停在 `disputed`——那是**派生投影在说谎**。
+     * 图谱是本仓库反复确认的 L1 **派生投影**,派生字段就必须**由当前事实重算**,
+     * 而不是靠一串增量事件累积(后者一旦漏一次就永久跑偏)。
+     *
+     * 判据(与 {@link markSourcesDeleted} 方向相反:那边问"来源是否**全部**消失",
+     * 这边问"来源是否**命中**冲突集",命中一条即存疑):
+     * - `active` 且来源命中冲突集 → `disputed`
+     * - `disputed` 且来源**不**命中冲突集 → 复原为 `active`
+     * - `archived` 墓碑两边都不动(墓碑是删除传播的产物,与争议无关)
+     *
+     * @returns 本次标记 / 复原的节点数。
+     */
+    syncDisputed(disputedRecordIds: readonly string[]): {
+        marked: number;
+        cleared: number;
+    };
     /** 清空全部图谱数据(L1 重建时调用——图谱是 L1 的投影,记录清空即图谱作废)。 */
     resetAll(): void;
 }