dsh-prime-memory 0.26.4 → 0.26.5

package/dist/clients/drsc.d.ts

@@ -0,0 +1,93 @@
+/**
+ * DrscClient(T8.4 读切,drsc-redact-memory-wiring task_18):memory 读历史
+ * 面的 dsh-reference-session-collector HTTP 客户端。
+ *
+ * 两个读点(R7):
+ * - 蒸馏背景窗(recentBySession 等价供给)→ `op=session&tail=N&redact=1`
+ *   (collector task_11 尾窗升序 + task_12 redact 臂);
+ * - 工具面 conversation_search → `op=search&redact=1`(命中基于原文 fts,
+ *   返回 snippet 取脱敏锚定文本)。
+ *
+ * 硬依赖纪律(对齐 T7.3 裁定):collector 缺席/超时/非 2xx/ok=false 一律抛
+ * {@link DrscClientError}——**绝不回退本地 l0**(表已退役,无退路);调用方
+ * 分口径处理:蒸馏背景窗空窗降级(runner),工具面显式报错(tools)。
+ *
+ * 同源 Host 解析(steward drs-source 的 resolveDrsBaseUrl 同款):
+ * 显式 baseUrl > 首个 trustedHosts 条目(补 http://)> `http://127.0.0.1:8080`
+ * (宿主缺省口)。Host 头回显首个 trustedHosts 条目:collector 信任门是精确
+ * 匹配,条目省略端口而 URL 带端口会失配。trustedHosts 惰性读取(webStartup
+ * 可能晚于本插件就绪),每次请求现算,无缓存陈旧面。
+ */
+import type { ConversationMessage } from '../types.js';
+/** collector API 路径(与其 DRS_API_PATH 字面一致;不跨包 import)。 */
+export declare const DRSC_API_PATH = "/api/dsh-reference-session-collector";
+/** 客户端缺省超时:loopback 正常 <10ms,5s 是给冷启动 GC/断点的天花板。 */
+export declare const DRSC_DEFAULT_TIMEOUT_MS = 5000;
+/** collector 缺席/超时/契约破损。显式报错,不回退本地。 */
+export declare class DrscClientError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 基址解析:显式配置 > 首个 trustedHosts 条目(补 http:// 前缀)>
+ * `http://127.0.0.1:8080`(宿主默认口;trustedHosts 缺席的老线 collector 门本就放行)。
+ */
+export declare function resolveDrscBaseUrl(explicit: string | undefined, trustedHosts?: readonly string[]): string;
+/** `op=session` 的一个 segment 行(redact=1 时 text 为脱敏正文;wire 蛇形直取)。 */
+export interface DrscSessionRow {
+    seq: number;
+    turn: number;
+    step: number;
+    kind: string;
+    role: string;
+    time: number;
+    text: string;
+}
+/** `op=search` 的一个命中(redact=1 时 snippet 为脱敏锚定文本)。 */
+export interface DrscSearchHit {
+    session_id: string;
+    seq: number;
+    kind: string;
+    rank: number;
+    snippet: string;
+    time: number;
+    on_surface: number;
+    turn: number;
+}
+/** kind → L0 角色词表(memory 只收 user/assistant 两类,其余(tool/* 等)不映射)。 */
+export declare function drscRoleOf(kind: string): 'user' | 'assistant' | undefined;
+/**
+ * session 行 → ConversationMessage 形状映射(蒸馏背景窗用)。
+ * - id:确定性合成 `drsc:<session>:<seq>`(跨次调用稳定,anchor 追溯可解释);
+ * - anchor:turn>0 才成立(与 ConversationAnchor 红线一致:没坐标不伪造);
+ * - 非 user/assistant 段(tool/call 等)返回 undefined,调用方跳过。
+ */
+export declare function drscRowToConversationMessage(row: DrscSessionRow, sessionId: string): ConversationMessage | undefined;
+export interface DrscClientOptions {
+    /** 显式基址(缺省走 trustedHosts → 127.0.0.1:8080,见 resolveDrscBaseUrl)。 */
+    baseUrl?: string;
+    /** trustedHosts 惰性读取(webStartup 服务可能晚于装配;每次请求现取)。 */
+    trustedHosts?: () => readonly string[] | undefined;
+    /** 注入面(单测);缺省全局 fetch。 */
+    fetchImpl?: typeof fetch;
+    /** 单请求超时 ms;缺省 {@link DRSC_DEFAULT_TIMEOUT_MS}。 */
+    timeoutMs?: number;
+}
+export declare class DrscClient {
+    private readonly options;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(options?: DrscClientOptions);
+    /** 每次请求现算基址与 Host 回显(trustedHosts 惰性;无缓存陈旧面)。 */
+    private base;
+    /** 一个 GET 的 JSON 包络(非 2xx / ok!==true / 超时 / 断网一律抛 DrscClientError)。 */
+    private getJson;
+    /**
+     * 会话尾窗:`op=session&session=<id>&tail=N&redact=1` → 脱敏消息行(升序)。
+     * collector 无此会话(session:null)返回空数组(新会话首轮的常态,非错误)。
+     */
+    sessionTail(sessionId: string, tail: number): Promise<DrscSessionRow[]>;
+    /** 原史检索:`op=search&q=<query>&limit=N&redact=1` → 脱敏 snippet 命中。 */
+    search(query: string, limit: number): Promise<DrscSearchHit[]>;
+}

package/dist/clients/drsc.js

@@ -0,0 +1,139 @@
+/** collector API 路径(与其 DRS_API_PATH 字面一致;不跨包 import)。 */
+export const DRSC_API_PATH = '/api/dsh-reference-session-collector';
+/** 客户端缺省超时:loopback 正常 <10ms,5s 是给冷启动 GC/断点的天花板。 */
+export const DRSC_DEFAULT_TIMEOUT_MS = 5_000;
+/** collector 缺席/超时/契约破损。显式报错,不回退本地。 */
+export class DrscClientError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'DrscClientError';
+    }
+}
+/**
+ * 基址解析:显式配置 > 首个 trustedHosts 条目(补 http:// 前缀)>
+ * `http://127.0.0.1:8080`(宿主默认口;trustedHosts 缺席的老线 collector 门本就放行)。
+ */
+export function resolveDrscBaseUrl(explicit, trustedHosts) {
+    const trimmed = explicit?.trim() ?? '';
+    const pick = trimmed !== '' ? trimmed : trustedHosts?.find((entry) => entry.trim() !== '')?.trim();
+    if (pick === undefined || pick === '')
+        return 'http://127.0.0.1:8080';
+    return /^https?:\/\//u.test(pick) ? pick : `http://${pick}`;
+}
+/** kind → L0 角色词表(memory 只收 user/assistant 两类,其余(tool/* 等)不映射)。 */
+export function drscRoleOf(kind) {
+    if (kind === 'user/message')
+        return 'user';
+    if (kind === 'assistant/message')
+        return 'assistant';
+    return undefined;
+}
+/**
+ * session 行 → ConversationMessage 形状映射(蒸馏背景窗用)。
+ * - id:确定性合成 `drsc:<session>:<seq>`(跨次调用稳定,anchor 追溯可解释);
+ * - anchor:turn>0 才成立(与 ConversationAnchor 红线一致:没坐标不伪造);
+ * - 非 user/assistant 段(tool/call 等)返回 undefined,调用方跳过。
+ */
+export function drscRowToConversationMessage(row, sessionId) {
+    const role = drscRoleOf(row.kind);
+    if (role === undefined)
+        return undefined;
+    const msg = {
+        id: `drsc:${sessionId}:${row.seq}`,
+        role,
+        content: row.text,
+        timestamp: row.time,
+    };
+    if (Number.isFinite(row.turn) && row.turn > 0) {
+        msg.anchor = { sessionId, turn: row.turn };
+        if (Number.isFinite(row.step) && row.step > 0)
+            msg.anchor.step = row.step;
+    }
+    return msg;
+}
+export class DrscClient {
+    options;
+    fetchImpl;
+    timeoutMs;
+    constructor(options = {}) {
+        this.options = options;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.timeoutMs = options.timeoutMs ?? DRSC_DEFAULT_TIMEOUT_MS;
+    }
+    /** 每次请求现算基址与 Host 回显(trustedHosts 惰性;无缓存陈旧面)。 */
+    base() {
+        const trusted = this.options.trustedHosts?.() ?? [];
+        const base = resolveDrscBaseUrl(this.options.baseUrl, trusted).replace(/\/+$/u, '');
+        const first = trusted.find((entry) => entry.trim() !== '')?.trim();
+        return { url: `${base}${DRSC_API_PATH}`, ...(first !== undefined ? { hostHeader: first } : {}) };
+    }
+    /** 一个 GET 的 JSON 包络(非 2xx / ok!==true / 超时 / 断网一律抛 DrscClientError)。 */
+    async getJson(query) {
+        const { url, hostHeader } = this.base();
+        let response;
+        try {
+            response = await this.fetchImpl(`${url}${query}`, {
+                headers: {
+                    accept: 'application/json',
+                    ...(hostHeader === undefined ? {} : { host: hostHeader }),
+                },
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (err) {
+            throw new DrscClientError(`collector 不可达(${query}): ${err instanceof Error ? err.message : String(err)}`, {
+                cause: err,
+            });
+        }
+        if (!response.ok)
+            throw new DrscClientError(`collector HTTP ${response.status}(${query})`);
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch (err) {
+            throw new DrscClientError(`collector 响应非 JSON(${query})`, { cause: err });
+        }
+        if (typeof body !== 'object' || body === null || body.ok !== true) {
+            const reason = typeof body === 'object' && body !== null
+                ? String(body.error ?? 'ok=false')
+                : '响应非对象';
+            throw new DrscClientError(`collector 包络异常(${query}): ${reason}`);
+        }
+        return body;
+    }
+    /**
+     * 会话尾窗:`op=session&session=<id>&tail=N&redact=1` → 脱敏消息行(升序)。
+     * collector 无此会话(session:null)返回空数组(新会话首轮的常态,非错误)。
+     */
+    async sessionTail(sessionId, tail) {
+        const body = await this.getJson(`?op=session&session=${encodeURIComponent(sessionId)}&tail=${Math.max(0, Math.floor(tail))}&redact=1`);
+        if (body['session'] === null || body['session'] === undefined)
+            return [];
+        const rows = Array.isArray(body['rows']) ? body['rows'] : [];
+        return rows.map((r) => ({
+            seq: Number(r['seq'] ?? 0),
+            turn: Number(r['turn'] ?? 0),
+            step: Number(r['step'] ?? 0),
+            kind: String(r['kind'] ?? ''),
+            role: String(r['role'] ?? ''),
+            time: Number(r['time'] ?? 0),
+            text: String(r['text'] ?? ''),
+        }));
+    }
+    /** 原史检索:`op=search&q=<query>&limit=N&redact=1` → 脱敏 snippet 命中。 */
+    async search(query, limit) {
+        const body = await this.getJson(`?op=search&q=${encodeURIComponent(query)}&limit=${Math.max(1, Math.floor(limit))}&redact=1`);
+        const hits = Array.isArray(body['hits']) ? body['hits'] : [];
+        return hits.map((h) => ({
+            session_id: String(h['session_id'] ?? ''),
+            seq: Number(h['seq'] ?? 0),
+            kind: String(h['kind'] ?? ''),
+            rank: Number(h['rank'] ?? 0),
+            snippet: String(h['snippet'] ?? ''),
+            time: Number(h['time'] ?? 0),
+            on_surface: Number(h['on_surface'] ?? 1),
+            turn: Number(h['turn'] ?? 0),
+        }));
+    }
+}

package/dist/contract.d.ts

@@ -927,6 +927,13 @@ export interface UiRecord {
      * 只在 `dsh-memory/session-recalled` 这条路径上有意义；缺省 = 无此概念（旧服务端）。
      */
     superseded?: boolean;
+    /**
+     * 路归因：hybrid 融合时这条命中来自哪几路（`'fts'|'vec'|'graph'|'recency'`）。
+     * 只在 `dsh-memory/session-recalled` 路径上有意义；缺省 = 无从归因
+     * （单路检索策略/旧文件条目/旧服务端），展示层不渲染徽标。纯投影字段，
+     * 存储侧落 `session-recalled.json` 的 lanes 键（读时拆管道串）。
+     */
+    lanes?: string[];
     /**
      * 成熟度(G3 读时派生):priority + 被用次数 + 老化权重合成。
      * 可选字段——旧 client 忽略=向后兼容；不参与存储/快照（纯投影）。
@@ -1228,6 +1235,69 @@ export interface GraphNodeGetResponse {
     /** 与该节点相连的 active 边。 */
     edges: GraphEdge[];
 }
+/** dsh-memory/graph-preview(面板图谱预览:缺省返回推荐种子榜,seedId 给定展开该节点邻域)。
+ *  候选只含 active|disputed 节点×active 边(与检索同判据);空图/未启用返全零结构不抛。 */
+export interface GraphPreviewRequest {
+    /** 给定即以该节点为唯一中心(悬挂 id 返空 seeds,不解析不抛——graph-node-get 同款宽容)。 */
+    seedId?: string;
+    /** 'full' = 响应附全图轻量块(mode:'full' 与大图星图共用同端点,一次 loadGraph 全供)。
+     *  非 'full' 一律按缺省——无 mode 响应形状与旧版逐字一致(可选键缺席=零漂移)。 */
+    mode?: 'full';
+}
+export interface GraphPreviewResponse {
+    seeds: Array<{
+        node: {
+            id: string;
+            name: string;
+            type: string;
+            degree: number;
+            causalDegree: number;
+        };
+        /** 因果边优先→邻居度数降序→updatedAt 新先;长度 ≤ GRAPH_PREVIEW_NEIGHBORS。 */
+        neighbors: Array<{
+            id: string;
+            name: string;
+            type: string;
+            relation: string;
+            causal: boolean;
+        }>;
+        truncated: boolean;
+    }>;
+    stats: {
+        nodes: number;
+        edges: number;
+        causalEdges: number;
+        /** 未定投影 job 数(pending/running/failed 退避中),>0 → UI 显"构建中 x/y"(x=jobsTotal-pendingJobs)。 */
+        pendingJobs: number;
+        /** 全量 job 数(含各状态),"构建中 x/y"的分母——名字即分母,不拿 done 冒充分子。 */
+        jobsTotal: number;
+        /** 永久失败作业数(dead),可选(零漂移先例);>0 → UI 拆成"完成/失败/排队"三档显示。 */
+        deadJobs?: number;
+    };
+    /** mode==='full' 才出现;全图星图轻量块(可见节点×active 边,截断标记 truncated)。
+     *  不带此键时响应与旧形状逐字节一致——消费方按需读 `res.full?`。 */
+    full?: {
+        nodes: Array<{
+            id: string;
+            name: string;
+            type: string;
+        }>;
+        edges: Array<{
+            from: string;
+            to: string;
+            relation: string;
+            causal: boolean;
+        }>;
+        truncated: boolean;
+    };
+}
+/** dsh-memory/graph-cleanup-dead(清理历史失败作业:删除 status='dead' 的行,不影响已重入队的记录)。 */
+export interface GraphCleanupDeadRequest {
+    olderThanMs?: number;
+}
+export interface GraphCleanupDeadResponse {
+    removed: number;
+}
 /** dsh-memory/scenes(两族拼接的混合视图)。 */
 export interface ScenesResponse {
     items: Array<{
@@ -1778,6 +1848,8 @@ export interface DshMemoryRequestMap {
     'dsh-memory/conflicts-rejected': ConflictRejectedRequest;
     'dsh-memory/graph-search': GraphSearchRequest;
     'dsh-memory/graph-node-get': GraphNodeGetRequest;
+    'dsh-memory/graph-preview': GraphPreviewRequest;
+    'dsh-memory/graph-cleanup-dead': GraphCleanupDeadRequest;
     'dsh-memory/scenes': Record<string, never>;
     'dsh-memory/persona': Record<string, never>;
     'dsh-memory/log-tail': LogTailRequest;
@@ -1843,6 +1915,8 @@ export interface DshMemoryResponseMap {
     'dsh-memory/conflicts-rejected': ConflictRejectedResponse;
     'dsh-memory/graph-search': GraphSearchResponse;
     'dsh-memory/graph-node-get': GraphNodeGetResponse;
+    'dsh-memory/graph-preview': GraphPreviewResponse;
+    'dsh-memory/graph-cleanup-dead': GraphCleanupDeadResponse;
     'dsh-memory/scenes': ScenesResponse;
     'dsh-memory/persona': PersonaResponse;
     'dsh-memory/log-tail': LogTailResponse;

package/dist/drs-anchor-backfill.d.ts

@@ -0,0 +1,88 @@
+/**
+ * DRS 历史锚点回填(三期接线 T8.2,一次性任务的纯核心)。
+ *
+ * 职责:`l0_conversations` 里 `turn IS NULL` 的旧行,按
+ * (session_id, role, 时间窗) 与 DRS 投影库 segments(turn/step/role/time)
+ * 最近邻匹配,补填 turn/step。
+ *
+ * 纪律(对齐 store/sqlite.ts R7 迁移注释,「旧行留 NULL ⇒ 无锚点,不伪造」):
+ * - 匹配不上留 NULL;同窗内出现**多个不同 turn** 的候选 = 歧义,也留 NULL;
+ * - UPDATE 恒带 `AND turn IS NULL`,已锚定行永不覆盖(与 upsert COALESCE 同向);
+ * - 行数不变式:回填只填列,绝不增删行;apply 报告给前后 COUNT 对账。
+ *
+ * DRS 来源契约:projection.db segments 只读直连——与 HTTP `op=session&turn=`
+ * 的检索面同字段(session_id/turn/step/role/time);离线一次性任务走只读
+ * SQLite,宿主不在线也可跑。role 词表两侧同形:DRS eventRole 只产
+ * user/assistant,l0 capture 只收 user/assistant(capture.ts L0Record)。
+ *
+ * 本模块零 cordis/运行时依赖:入参是结构化 SQLite 面(prepare/all/run),
+ * CLI(scripts/drs-anchor-backfill.mjs)喂真身,单测喂临时 DatabaseSync。
+ */
+/** 结构化 SQLite 面(node:sqlite DatabaseSync 的窄投影,方法双向可赋值)。 */
+export interface PreparedStatementLike {
+    all(...params: unknown[]): unknown[];
+    run(...params: unknown[]): unknown;
+}
+export interface SqliteLike {
+    prepare(sql: string): PreparedStatementLike;
+}
+/** 缺省时间窗:|l0.timestamp − segments.time| ≤ 90s 视为同一条消息。 */
+export declare const DEFAULT_WINDOW_MS = 90000;
+export interface AnchorBackfillOptions {
+    /** 只回填该会话;缺省全量。 */
+    sessionId?: string;
+    /** 本次最多处理的候选行数(防跑飞);缺省不限。 */
+    limit?: number;
+    /** 匹配时间窗(ms);缺省 {@link DEFAULT_WINDOW_MS}。 */
+    windowMs?: number;
+}
+/** 一条可回填的匹配(证据齐全:两侧时间与差值)。 */
+export interface AnchorFillRow {
+    recordId: string;
+    sessionId: string;
+    role: string;
+    l0Timestamp: number;
+    drsTime: number;
+    deltaMs: number;
+    turn: number;
+    step: number;
+}
+/** 一条被保守放弃的候选(宁缺毋伪造)。 */
+export interface AnchorSkipRow {
+    recordId: string;
+    sessionId: string;
+    reason: 'no-drs-session' | 'no-role-match' | 'out-of-window' | 'ambiguous-turn';
+}
+export interface AnchorBackfillPlan {
+    windowMs: number;
+    /** 扫到的候选数(turn IS NULL)。 */
+    candidates: number;
+    /** DRS 侧有投影的会话数。 */
+    drsSessions: number;
+    /** 已锚定(无需处理)行数——信息面,不是候选。 */
+    alreadyAnchored: number;
+    fills: AnchorFillRow[];
+    skips: AnchorSkipRow[];
+}
+/**
+ * 产出回填计划(纯只读,两个库都不写)。匹配规则:
+ * 同会话 + 同 role + |Δt| ≤ windowMs 的 DRS 行里,若候选 turn 唯一 → 取
+ * |Δt| 最近一条;turn 不唯一 → 歧义放弃;无行/无窗内行 → 如实分型放弃。
+ */
+export declare function planAnchorBackfill(input: {
+    memory: SqliteLike;
+    drs: SqliteLike;
+} & AnchorBackfillOptions): AnchorBackfillPlan;
+export interface AnchorApplyReport {
+    plan: AnchorBackfillPlan;
+    applied: number;
+    totalRowsBefore: number;
+    totalRowsAfter: number;
+    /** 行数不变式:回填只填列,前后 COUNT 必须相等。 */
+    invariantHolds: boolean;
+}
+/**
+ * 应用计划:逐条 UPDATE,恒带 `AND turn IS NULL`(已锚定行永不覆盖;
+ * plan→apply 之间若有新写入恰好锚定了同一行,该条自然落空,不报错)。
+ */
+export declare function applyAnchorBackfill(memory: SqliteLike, plan: AnchorBackfillPlan): AnchorApplyReport;

package/dist/drs-anchor-backfill.js

@@ -0,0 +1,150 @@
+/**
+ * DRS 历史锚点回填(三期接线 T8.2,一次性任务的纯核心)。
+ *
+ * 职责:`l0_conversations` 里 `turn IS NULL` 的旧行,按
+ * (session_id, role, 时间窗) 与 DRS 投影库 segments(turn/step/role/time)
+ * 最近邻匹配,补填 turn/step。
+ *
+ * 纪律(对齐 store/sqlite.ts R7 迁移注释,「旧行留 NULL ⇒ 无锚点,不伪造」):
+ * - 匹配不上留 NULL;同窗内出现**多个不同 turn** 的候选 = 歧义,也留 NULL;
+ * - UPDATE 恒带 `AND turn IS NULL`,已锚定行永不覆盖(与 upsert COALESCE 同向);
+ * - 行数不变式:回填只填列,绝不增删行;apply 报告给前后 COUNT 对账。
+ *
+ * DRS 来源契约:projection.db segments 只读直连——与 HTTP `op=session&turn=`
+ * 的检索面同字段(session_id/turn/step/role/time);离线一次性任务走只读
+ * SQLite,宿主不在线也可跑。role 词表两侧同形:DRS eventRole 只产
+ * user/assistant,l0 capture 只收 user/assistant(capture.ts L0Record)。
+ *
+ * 本模块零 cordis/运行时依赖:入参是结构化 SQLite 面(prepare/all/run),
+ * CLI(scripts/drs-anchor-backfill.mjs)喂真身,单测喂临时 DatabaseSync。
+ */
+/** 缺省时间窗:|l0.timestamp − segments.time| ≤ 90s 视为同一条消息。 */
+export const DEFAULT_WINDOW_MS = 90_000;
+/** DRS segments → 锚点行(只收 turn>0 且 role∈{user,assistant} 的行)。 */
+function loadDrsAnchors(drs, sessionId) {
+    const sql = sessionId === undefined
+        ? 'SELECT session_id, turn, step, role, time FROM segments WHERE turn > 0 AND role IN (?, ?) ORDER BY session_id, time'
+        : 'SELECT session_id, turn, step, role, time FROM segments WHERE turn > 0 AND role IN (?, ?) AND session_id = ? ORDER BY session_id, time';
+    const rows = drs.prepare(sql).all('user', 'assistant', ...(sessionId === undefined ? [] : [sessionId]));
+    const bySession = new Map();
+    for (const row of rows) {
+        if (typeof row.session_id !== 'string' || typeof row.turn !== 'number' || typeof row.time !== 'number')
+            continue;
+        const entry = {
+            sessionId: row.session_id,
+            turn: row.turn,
+            step: typeof row.step === 'number' ? row.step : 0,
+            role: typeof row.role === 'string' ? row.role : '',
+            time: row.time,
+        };
+        const bucket = bySession.get(entry.sessionId);
+        if (bucket === undefined)
+            bySession.set(entry.sessionId, [entry]);
+        else
+            bucket.push(entry);
+    }
+    return bySession;
+}
+function loadCandidates(memory, sessionId, limit) {
+    const sql = sessionId === undefined
+        ? 'SELECT record_id, session_id, role, timestamp FROM l0_conversations WHERE turn IS NULL AND role IN (?, ?) ORDER BY session_id, timestamp'
+        : 'SELECT record_id, session_id, role, timestamp FROM l0_conversations WHERE turn IS NULL AND role IN (?, ?) AND session_id = ? ORDER BY session_id, timestamp';
+    const rows = memory.prepare(sql).all('user', 'assistant', ...(sessionId === undefined ? [] : [sessionId]));
+    const out = [];
+    for (const row of rows) {
+        if (typeof row.record_id !== 'string' || typeof row.session_id !== 'string' || typeof row.timestamp !== 'number')
+            continue;
+        out.push({
+            recordId: row.record_id,
+            sessionId: row.session_id,
+            role: typeof row.role === 'string' ? row.role : '',
+            timestamp: row.timestamp,
+        });
+        if (limit !== undefined && out.length >= limit)
+            break;
+    }
+    return out;
+}
+/**
+ * 产出回填计划(纯只读,两个库都不写)。匹配规则:
+ * 同会话 + 同 role + |Δt| ≤ windowMs 的 DRS 行里,若候选 turn 唯一 → 取
+ * |Δt| 最近一条;turn 不唯一 → 歧义放弃;无行/无窗内行 → 如实分型放弃。
+ */
+export function planAnchorBackfill(input) {
+    const windowMs = input.windowMs ?? DEFAULT_WINDOW_MS;
+    const drsBySession = loadDrsAnchors(input.drs, input.sessionId);
+    const candidates = loadCandidates(input.memory, input.sessionId, input.limit);
+    const anchored = input.memory.prepare(input.sessionId === undefined
+        ? 'SELECT COUNT(*) AS n FROM l0_conversations WHERE turn IS NOT NULL'
+        : 'SELECT COUNT(*) AS n FROM l0_conversations WHERE turn IS NOT NULL AND session_id = ?').all(...(input.sessionId === undefined ? [] : [input.sessionId]));
+    const plan = {
+        windowMs,
+        candidates: candidates.length,
+        drsSessions: drsBySession.size,
+        alreadyAnchored: typeof anchored[0]?.n === 'number' ? anchored[0].n : 0,
+        fills: [],
+        skips: [],
+    };
+    for (const candidate of candidates) {
+        const rows = drsBySession.get(candidate.sessionId);
+        if (rows === undefined) {
+            plan.skips.push({ recordId: candidate.recordId, sessionId: candidate.sessionId, reason: 'no-drs-session' });
+            continue;
+        }
+        const sameRole = rows.filter(row => row.role === candidate.role);
+        if (sameRole.length === 0) {
+            plan.skips.push({ recordId: candidate.recordId, sessionId: candidate.sessionId, reason: 'no-role-match' });
+            continue;
+        }
+        const inWindow = sameRole
+            .map(row => ({ row, delta: Math.abs(row.time - candidate.timestamp) }))
+            .filter(entry => entry.delta <= windowMs);
+        if (inWindow.length === 0) {
+            plan.skips.push({ recordId: candidate.recordId, sessionId: candidate.sessionId, reason: 'out-of-window' });
+            continue;
+        }
+        const turns = new Set(inWindow.map(entry => entry.row.turn));
+        if (turns.size > 1) {
+            plan.skips.push({ recordId: candidate.recordId, sessionId: candidate.sessionId, reason: 'ambiguous-turn' });
+            continue;
+        }
+        const nearest = inWindow.reduce((best, entry) => (entry.delta < best.delta ? entry : best));
+        plan.fills.push({
+            recordId: candidate.recordId,
+            sessionId: candidate.sessionId,
+            role: candidate.role,
+            l0Timestamp: candidate.timestamp,
+            drsTime: nearest.row.time,
+            deltaMs: nearest.delta,
+            turn: nearest.row.turn,
+            step: nearest.row.step,
+        });
+    }
+    return plan;
+}
+/**
+ * 应用计划:逐条 UPDATE,恒带 `AND turn IS NULL`(已锚定行永不覆盖;
+ * plan→apply 之间若有新写入恰好锚定了同一行,该条自然落空,不报错)。
+ */
+export function applyAnchorBackfill(memory, plan) {
+    const countOf = (sql) => {
+        const rows = memory.prepare(sql).all();
+        return typeof rows[0]?.n === 'number' ? rows[0].n : 0;
+    };
+    const totalRowsBefore = countOf('SELECT COUNT(*) AS n FROM l0_conversations');
+    const update = memory.prepare('UPDATE l0_conversations SET turn = ?, step = ? WHERE record_id = ? AND turn IS NULL');
+    let applied = 0;
+    for (const fill of plan.fills) {
+        const result = update.run(fill.turn, fill.step, fill.recordId);
+        if (typeof result?.changes === 'number' && result.changes > 0)
+            applied += result.changes;
+    }
+    const totalRowsAfter = countOf('SELECT COUNT(*) AS n FROM l0_conversations');
+    return {
+        plan,
+        applied,
+        totalRowsBefore,
+        totalRowsAfter,
+        invariantHolds: totalRowsBefore === totalRowsAfter,
+    };
+}

package/dist/graph/constraints.d.ts

@@ -13,8 +13,10 @@ export declare const GRAPH_NODE_TYPE_SET: ReadonlySet<string>;
 /** 记录生命周期四态(节点/fact/边通用)。 */
 export declare const GRAPH_STATUSES: readonly GraphRecordStatus[];
 export declare const GRAPH_STATUS_SET: ReadonlySet<string>;
+/** 因果边四词单源(投影提示词枚举、校验与面板预览加权共用——防两处词表漂移)。 */
+export declare const GRAPH_CAUSAL_RELATIONS: readonly ["导致", "因为", "修复了", "取代"];
 /** 规范中文关系词(提示词给枚举;校验不做白名单——关系是开放词表,只做长度钳制)。
- *  后四个为因果边(导致/因为/修复了/取代)——让"前因后果"跨记录成链;仅当 graph.enabled 时
+ *  尾部即因果集 GRAPH_CAUSAL_RELATIONS——让"前因后果"跨记录成链;仅当 graph.enabled 时
  *  才参与投影(整块图谱默认关,不碰非图谱用户的蒸馏产物)。 */
 export declare const GRAPH_RELATION_WORDS: readonly ["使用", "属于", "创建", "参与", "贡献", "依赖", "位于", "相关", "导致", "因为", "修复了", "取代"];
 /** 提案字段上限(校验侧截断/丢弃与提示词内插共用同一组数字)。 */

package/dist/graph/constraints.js

@@ -4,10 +4,12 @@ export const GRAPH_NODE_TYPE_SET = new Set(GRAPH_NODE_TYPES);
 /** 记录生命周期四态(节点/fact/边通用)。 */
 export const GRAPH_STATUSES = ['active', 'superseded', 'disputed', 'archived'];
 export const GRAPH_STATUS_SET = new Set(GRAPH_STATUSES);
+/** 因果边四词单源(投影提示词枚举、校验与面板预览加权共用——防两处词表漂移)。 */
+export const GRAPH_CAUSAL_RELATIONS = ['导致', '因为', '修复了', '取代'];
 /** 规范中文关系词(提示词给枚举;校验不做白名单——关系是开放词表,只做长度钳制)。
- *  后四个为因果边(导致/因为/修复了/取代)——让"前因后果"跨记录成链;仅当 graph.enabled 时
+ *  尾部即因果集 GRAPH_CAUSAL_RELATIONS——让"前因后果"跨记录成链;仅当 graph.enabled 时
  *  才参与投影(整块图谱默认关,不碰非图谱用户的蒸馏产物)。 */
-export const GRAPH_RELATION_WORDS = ['使用', '属于', '创建', '参与', '贡献', '依赖', '位于', '相关', '导致', '因为', '修复了', '取代'];
+export const GRAPH_RELATION_WORDS = ['使用', '属于', '创建', '参与', '贡献', '依赖', '位于', '相关', ...GRAPH_CAUSAL_RELATIONS];
 /** 提案字段上限(校验侧截断/丢弃与提示词内插共用同一组数字)。 */
 export const GRAPH_CAP = {
     /** 提案内临时引用(ref)长度。 */