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

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/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)长度。 */

package/dist/graph/preview.d.ts

@@ -0,0 +1,92 @@
+import type { GraphEdge, GraphNode, GraphNodeType } from './types.js';
+export interface GraphSeedNode {
+    id: string;
+    name: string;
+    type: GraphNodeType;
+    /** active 边双向计数(两端都可见才计入,与 degreeMaps 同口径)。 */
+    degree: number;
+    /** 其中因果边(constraints.GRAPH_CAUSAL_RELATIONS)计数。 */
+    causalDegree: number;
+}
+export interface GraphSeedNeighbor {
+    id: string;
+    name: string;
+    type: GraphNodeType;
+    /** 该条边的关系词(平行多边各占一条,标注各画各的)。 */
+    relation: string;
+    causal: boolean;
+}
+export interface GraphSeedView {
+    node: GraphSeedNode;
+    /** 因果边优先→邻居度数降序→updatedAt 新先→id 升序;长度 ≤ neighborLimit。 */
+    neighbors: GraphSeedNeighbor[];
+    /** 邻居超上限被截断的标记(UI 画 "+n" 角标)。 */
+    truncated: boolean;
+}
+export interface GraphPreviewStats {
+    nodes: number;
+    edges: number;
+    causalEdges: number;
+    /** 未定投影 job 数(pending/running/failed),>0 → UI "构建中 x/y"。 */
+    pendingJobs: number;
+    /** 全量 job 数(分母)。 */
+    jobsTotal: number;
+    /** 永久失败(dead)作业数,可选(零漂移先例);>0 → UI 拆三档。 */
+    deadJobs?: number;
+}
+export interface GraphPreviewResult {
+    seeds: GraphSeedView[];
+    stats: GraphPreviewStats;
+}
+export interface PreviewOpts {
+    /** 给定即只展开该节点为唯一中心(悬挂/不可见 → 空 seeds,不抛)。 */
+    seedId?: string;
+    seedLimit?: number;
+    neighborLimit?: number;
+    pendingJobs?: number;
+    jobsTotal?: number;
+    deadJobs?: number;
+}
+/** S-2:邻接统计——active 边且两端都可见才计度(双向)。 */
+export interface DegreeMaps {
+    degree: Map<string, number>;
+    causal: Map<string, number>;
+}
+export declare function degreeMaps(nodes: readonly GraphNode[], edges: readonly GraphEdge[]): DegreeMaps;
+/**
+ * S-3/S-4:预览主函数。
+ * - seedId 视图:直接展开该节点(跳过挑选);不可见/悬挂 → 空 seeds。
+ * - 榜单视图:score = degree + causal×WEIGHT;同分链 causal→sources→updatedAt→id↑;
+ *   候选落入已选种子的"自身∪邻居"覆盖集则跳过(相邻合并,画布片不重复);
+ *   孤立节点(度 0)不入榜——画布只有中心一个点没有信息量。
+ */
+export declare function buildGraphPreview(nodes: readonly GraphNode[], edges: readonly GraphEdge[], opts?: PreviewOpts): GraphPreviewResult;
+/** 全图节点轻量项（星图渲染只需这三字段，facts/sources 不下发——带宽与隐私面同步收紧）。 */
+export interface FullViewNode {
+    id: string;
+    name: string;
+    type: GraphNodeType;
+}
+/** 全图边轻量项（causal 由单源词表判出，渲染侧不再抄词表）。 */
+export interface FullViewEdge {
+    from: string;
+    to: string;
+    relation: string;
+    causal: boolean;
+}
+export interface GraphFullView {
+    nodes: FullViewNode[];
+    edges: FullViewEdge[];
+    /** 任一维触顶即 true（截断标记而非硬拒；渲染侧可据此提示"仅画部分"）。 */
+    truncated: boolean;
+}
+export interface FullViewCaps {
+    nodeCap?: number;
+    edgeCap?: number;
+}
+/**
+ * 全图星图数据块（纯函数，不查库）：可见节点轻量投影 × active 边，
+ * 双上限截断。**顺序纪律**：节点按入参序截断（调用方 loadGraph 的行序），
+ * 悬挂边（端点之一被截掉/不可见）在截断前剔除——星图上不画悬空线。
+ */
+export declare function buildFullView(nodes: readonly GraphNode[], edges: readonly GraphEdge[], caps?: FullViewCaps): GraphFullView;

package/dist/graph/preview.js

@@ -0,0 +1,186 @@
+/**
+ * 面板图谱预览(读路径纯函数):种子推荐榜 + 指定节点邻域展开。
+ *
+ * 定位:图谱投影三表的"值得画哪些片"视图筛选,不查库、不落库、无 I/O——
+ * job 计数(pendingJobs/jobsTotal)由存储缝(graph-store.buildPreview)传入。
+ * 起点推荐有实证底座(2026-10-20 装机审计):关系全落规范词表、因果边 ~24%,
+ * 故 score 以 active 度数为主键、因果边加权——纯 top 度会漏"因→果"链。
+ *
+ * 判据与检索同源(search.ts):候选 = active|disputed 节点 × active 边;
+ * 确定性 = 同输入两次调用逐位一致(同分裁决链落到 id 升序兜底)。
+ */
+import { GRAPH_CAUSAL_RELATIONS } from './constraints.js';
+import { GRAPH_PREVIEW_CAUSAL_WEIGHT, GRAPH_PREVIEW_FULL_EDGES, GRAPH_PREVIEW_FULL_NODES, GRAPH_PREVIEW_NEIGHBORS, GRAPH_PREVIEW_SEEDS, } from './types.js';
+const CAUSAL_SET = new Set(GRAPH_CAUSAL_RELATIONS);
+/** 预览唯一判定的节点可见性(与 searchGraphNodes 候选集同式)。 */
+function visible(n) {
+    return n.status === 'active' || n.status === 'disputed';
+}
+export function degreeMaps(nodes, edges) {
+    const candidate = new Set(nodes.filter(visible).map((n) => n.id));
+    const degree = new Map();
+    const causal = new Map();
+    for (const e of edges) {
+        if (e.status !== 'active')
+            continue;
+        if (!candidate.has(e.fromNodeId) || !candidate.has(e.toNodeId))
+            continue;
+        const isCausal = CAUSAL_SET.has(e.relation);
+        for (const id of [e.fromNodeId, e.toNodeId]) {
+            degree.set(id, (degree.get(id) ?? 0) + 1);
+            if (isCausal)
+                causal.set(id, (causal.get(id) ?? 0) + 1);
+        }
+    }
+    return { degree, causal };
+}
+/** 种子卡装配:邻居条目 + 因果优先排序 + 截断。 */
+function seedView(center, edges, byId, dm, neighborLimit) {
+    const list = [];
+    for (const e of edges) {
+        if (e.status !== 'active')
+            continue;
+        let otherId;
+        if (e.fromNodeId === center.id)
+            otherId = e.toNodeId;
+        else if (e.toNodeId === center.id)
+            otherId = e.fromNodeId;
+        else
+            continue;
+        const o = byId.get(otherId);
+        if (!o || !visible(o))
+            continue;
+        list.push({
+            id: o.id,
+            name: o.name,
+            type: o.type,
+            relation: e.relation,
+            causal: CAUSAL_SET.has(e.relation),
+            _deg: dm.degree.get(o.id) ?? 0,
+            _upd: o.updatedAt,
+        });
+    }
+    list.sort((a, b) => {
+        if (a.causal !== b.causal)
+            return a.causal ? -1 : 1;
+        if (a._deg !== b._deg)
+            return b._deg - a._deg;
+        if (a._upd !== b._upd)
+            return a._upd < b._upd ? -1 : 1; // updatedAt 新(大)先
+        return a.id < b.id ? -1 : 1;
+    });
+    const truncated = list.length > neighborLimit;
+    return {
+        node: {
+            id: center.id,
+            name: center.name,
+            type: center.type,
+            degree: dm.degree.get(center.id) ?? 0,
+            causalDegree: dm.causal.get(center.id) ?? 0,
+        },
+        neighbors: list.slice(0, neighborLimit).map(({ _deg, _upd, ...view }) => view),
+        truncated,
+    };
+}
+/**
+ * S-3/S-4:预览主函数。
+ * - seedId 视图:直接展开该节点(跳过挑选);不可见/悬挂 → 空 seeds。
+ * - 榜单视图:score = degree + causal×WEIGHT;同分链 causal→sources→updatedAt→id↑;
+ *   候选落入已选种子的"自身∪邻居"覆盖集则跳过(相邻合并,画布片不重复);
+ *   孤立节点(度 0)不入榜——画布只有中心一个点没有信息量。
+ */
+export function buildGraphPreview(nodes, edges, opts = {}) {
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    const dm = degreeMaps(nodes, edges);
+    const visNodes = nodes.filter(visible);
+    const visEdges = edges.filter((e) => e.status === 'active');
+    const stats = {
+        nodes: visNodes.length,
+        edges: visEdges.length,
+        causalEdges: visEdges.filter((e) => CAUSAL_SET.has(e.relation)).length,
+        pendingJobs: opts.pendingJobs ?? 0,
+        jobsTotal: opts.jobsTotal ?? 0,
+        ...(opts.deadJobs != null && opts.deadJobs > 0 ? { deadJobs: opts.deadJobs } : {}),
+    };
+    const seedLimit = Math.min(Math.max(Math.floor(opts.seedLimit ?? GRAPH_PREVIEW_SEEDS), 1), 20);
+    const neighborLimit = Math.min(Math.max(Math.floor(opts.neighborLimit ?? GRAPH_PREVIEW_NEIGHBORS), 1), 40);
+    if (opts.seedId !== undefined) {
+        const target = byId.get(opts.seedId);
+        if (!target || !visible(target))
+            return { seeds: [], stats };
+        return { seeds: [seedView(target, edges, byId, dm, neighborLimit)], stats };
+    }
+    const scored = visNodes
+        .map((n) => ({
+        n,
+        score: (dm.degree.get(n.id) ?? 0) + (dm.causal.get(n.id) ?? 0) * GRAPH_PREVIEW_CAUSAL_WEIGHT,
+    }))
+        .sort((a, b) => {
+        if (a.score !== b.score)
+            return b.score - a.score;
+        const ca = dm.causal.get(a.n.id) ?? 0;
+        const cb = dm.causal.get(b.n.id) ?? 0;
+        if (ca !== cb)
+            return cb - ca;
+        const sa = a.n.sourceRecordIds.length;
+        const sb = b.n.sourceRecordIds.length;
+        if (sa !== sb)
+            return sb - sa;
+        if (a.n.updatedAt !== b.n.updatedAt)
+            return a.n.updatedAt < b.n.updatedAt ? 1 : -1;
+        return a.n.id < b.n.id ? -1 : 1;
+    });
+    const picked = [];
+    const covered = new Set();
+    for (const { n, score } of scored) {
+        if (picked.length >= seedLimit)
+            break;
+        if (score === 0)
+            continue; // 孤立点不入榜(score 单调降,continue 等价于提前结束)
+        if (covered.has(n.id))
+            continue; // 相邻合并:已被前一种子的邻域覆盖
+        picked.push(n);
+        covered.add(n.id);
+        for (const e of visEdges) {
+            if (e.fromNodeId === n.id)
+                covered.add(e.toNodeId);
+            else if (e.toNodeId === n.id)
+                covered.add(e.fromNodeId);
+        }
+    }
+    return {
+        seeds: picked.map((n) => seedView(n, edges, byId, dm, neighborLimit)),
+        stats,
+    };
+}
+/**
+ * 全图星图数据块（纯函数，不查库）：可见节点轻量投影 × active 边，
+ * 双上限截断。**顺序纪律**：节点按入参序截断（调用方 loadGraph 的行序），
+ * 悬挂边（端点之一被截掉/不可见）在截断前剔除——星图上不画悬空线。
+ */
+export function buildFullView(nodes, edges, caps = {}) {
+    const nodeCap = Math.max(1, Math.floor(caps.nodeCap ?? GRAPH_PREVIEW_FULL_NODES));
+    const edgeCap = Math.max(1, Math.floor(caps.edgeCap ?? GRAPH_PREVIEW_FULL_EDGES));
+    const visibleNodes = nodes.filter(visible);
+    const nodesTruncated = visibleNodes.length > nodeCap;
+    const drawn = visibleNodes.slice(0, nodeCap);
+    const keep = new Set(drawn.map((n) => n.id));
+    const outEdges = [];
+    let edgesTruncated = false;
+    for (const e of edges) {
+        if (e.status !== 'active')
+            continue;
+        if (!keep.has(e.fromNodeId) || !keep.has(e.toNodeId))
+            continue;
+        if (outEdges.length >= edgeCap) {
+            edgesTruncated = true;
+            break;
+        }
+        outEdges.push({ from: e.fromNodeId, to: e.toNodeId, relation: e.relation, causal: CAUSAL_SET.has(e.relation) });
+    }
+    return {
+        nodes: drawn.map((n) => ({ id: n.id, name: n.name, type: n.type })),
+        edges: outEdges,
+        truncated: nodesTruncated || edgesTruncated,
+    };
+}

package/dist/graph/search.d.ts

@@ -13,15 +13,32 @@ export declare const GRAPH_FIELD_WEIGHTS: {
  * 图谱命中 → L1 记录 id 序列(§D 第 3 路 RRF 的输入;纯函数,无 I/O)。
  *
  * 图谱是**可重建派生投影**,节点/fact 的 `sourceRecordIds` 是它回链 L1 的唯一凭证
- * (types.ts:6-7)。此处把"节点排名"翻译成"L1 记录排名":
+ * (types.ts:6-7)。此处把"节点排名"翻译成"L1 记录排名",分两段:
  *
- * - **保序**:按命中的 score 降序依次展开来源,先出现的记录 = 更高排名;
- * - **去重**:同一 L1 记录可能被多个节点/fact 引用,只占首次出现的位置
- *   (重复占位会凭空抬高该记录在 RRF 里的权重);
+ * - **直连段**:命中节点自身 + 其 active facts 的来源(task_9 原语义、原顺序);
+ * - **1-hop 段**:命中节点沿 **active 边**的双向邻居(邻居需 active|disputed)的
+ *   节点自身来源,按邻居 updatedAt 新→旧追加,整段新增封顶
+ *   `GRAPH_HOP_RECORD_CAP`——这是图路"关系可达"增量价值的兑现面。
+ *   hop 段只取邻居节点自身来源,不取 fact 来源(hop 是联想不是证据,噪声从紧)。
+ *
+ * 两段共用纪律:
+ * - **保序**:先出现的记录 = 更高排名(直连段恒先于 hop 段);已被直连段占位的
+ *   id 不重复计入、也**不吃 hop 名额**(关联额度不被身份来源挤占);
+ * - **去重**:同一 L1 记录被多个节点/fact 引用,只占首次出现的位置;
  * - **节点自身来源优先于其 fact 来源**:节点的 sourceRecordIds 是它的身份来源,
  *   而单个 fact 的来源可能引向与该查询无关的旁支记录;
  * - **只取 active fact**:superseded 是历史状态,不该把旧记录拉进当前检索结果;
- * - **不查库**:返回的 id 可能已被删除(墓碑边界),由调用方按"取不到的跳过"处理。
+ * - **不查库**:返回的 id 可能已被删除(墓碑边界),由调用方按"取不到的跳过"处理,
+ *   不得补空占位(占位会在 RRF 里凭空加分)。
+ *
+ * edges/nodes 由调用方传入(loadGraph 结果,百~千量级全扫即可;>2k 再考虑预建索引,
+ * 见文件头演进阶梯)。族过滤不在本函数:邻居节点可跨族,兜底在 graphLane 尾部的
+ * 记录级 family/scope 双闸(宁可漏不可串落在记录上)。
+ */
+export declare function expandHitRecordIds(hits: readonly GraphNodeSearchResult[], nodes: readonly GraphNode[], edges: readonly GraphEdge[]): string[];
+/**
+ * 直连段回链(无 hop)——保留 task_9 的原语义形状(既有测试继续钉住);
+ * 生产链路一律走 expandHitRecordIds(向量种子并集 + 1-hop)。
  */
 export declare function graphHitRecordIds(hits: readonly GraphNodeSearchResult[]): string[];
 /**

package/dist/graph/search.js

@@ -34,7 +34,7 @@
  * - score 只用于排序,不是事实置信度;无词法命中返回空,不兜底。
  */
 import { tokenize } from '../util/text.js';
-import { GRAPH_SEARCH_LIMIT_MAX } from './types.js';
+import { GRAPH_HOP_RECORD_CAP, GRAPH_SEARCH_LIMIT_MAX } from './types.js';
 /** 字段权重(检索命中计分;名称最高、关系词最低)。 */
 export const GRAPH_FIELD_WEIGHTS = {
     name: 6,
@@ -60,21 +60,37 @@ const FIELD_ORDER = ['name', 'aliases', 'tags', 'currentState', 'facts', 'relati
 function factValueText(value) {
     return Array.isArray(value) ? value.join(' ') : value;
 }
+/** 节点新度序(updatedAt 新→旧,同值按 id 升序——与检索结果排序同式)。 */
+function byNodeRecency(a, b) {
+    return a.updatedAt < b.updatedAt ? 1 : a.updatedAt > b.updatedAt ? -1 : a.id < b.id ? -1 : 1;
+}
 /**
  * 图谱命中 → L1 记录 id 序列(§D 第 3 路 RRF 的输入;纯函数,无 I/O)。
  *
  * 图谱是**可重建派生投影**,节点/fact 的 `sourceRecordIds` 是它回链 L1 的唯一凭证
- * (types.ts:6-7)。此处把"节点排名"翻译成"L1 记录排名":
+ * (types.ts:6-7)。此处把"节点排名"翻译成"L1 记录排名",分两段:
+ *
+ * - **直连段**:命中节点自身 + 其 active facts 的来源(task_9 原语义、原顺序);
+ * - **1-hop 段**:命中节点沿 **active 边**的双向邻居(邻居需 active|disputed)的
+ *   节点自身来源,按邻居 updatedAt 新→旧追加,整段新增封顶
+ *   `GRAPH_HOP_RECORD_CAP`——这是图路"关系可达"增量价值的兑现面。
+ *   hop 段只取邻居节点自身来源,不取 fact 来源(hop 是联想不是证据,噪声从紧)。
  *
- * - **保序**:按命中的 score 降序依次展开来源,先出现的记录 = 更高排名;
- * - **去重**:同一 L1 记录可能被多个节点/fact 引用,只占首次出现的位置
- *   (重复占位会凭空抬高该记录在 RRF 里的权重);
+ * 两段共用纪律:
+ * - **保序**:先出现的记录 = 更高排名(直连段恒先于 hop 段);已被直连段占位的
+ *   id 不重复计入、也**不吃 hop 名额**(关联额度不被身份来源挤占);
+ * - **去重**:同一 L1 记录被多个节点/fact 引用,只占首次出现的位置;
  * - **节点自身来源优先于其 fact 来源**:节点的 sourceRecordIds 是它的身份来源,
  *   而单个 fact 的来源可能引向与该查询无关的旁支记录;
  * - **只取 active fact**:superseded 是历史状态,不该把旧记录拉进当前检索结果;
- * - **不查库**:返回的 id 可能已被删除(墓碑边界),由调用方按"取不到的跳过"处理。
+ * - **不查库**:返回的 id 可能已被删除(墓碑边界),由调用方按"取不到的跳过"处理,
+ *   不得补空占位(占位会在 RRF 里凭空加分)。
+ *
+ * edges/nodes 由调用方传入(loadGraph 结果,百~千量级全扫即可;>2k 再考虑预建索引,
+ * 见文件头演进阶梯)。族过滤不在本函数:邻居节点可跨族,兜底在 graphLane 尾部的
+ * 记录级 family/scope 双闸(宁可漏不可串落在记录上)。
  */
-export function graphHitRecordIds(hits) {
+export function expandHitRecordIds(hits, nodes, edges) {
     const seen = new Set();
     const out = [];
     const take = (id) => {
@@ -83,6 +99,7 @@ export function graphHitRecordIds(hits) {
         seen.add(id);
         out.push(id);
     };
+    // 直连段(节点身份来源在前,active facts 在后)
     for (const h of hits) {
         for (const id of h.node.sourceRecordIds)
             take(id);
@@ -93,8 +110,53 @@ export function graphHitRecordIds(hits) {
                 take(id);
         }
     }
+    if (edges.length === 0)
+        return out;
+    // hop 段:active 边的双向邻居 ∉ 命中集,邻居去重,状态需 active|disputed
+    const hitNodeIds = new Set(hits.map((h) => h.node.id));
+    const nodeById = new Map(nodes.map((n) => [n.id, n]));
+    const seenNeighbor = new Set();
+    const neighbors = [];
+    for (const e of edges) {
+        if (e.status !== 'active')
+            continue;
+        const dirs = [
+            [e.fromNodeId, e.toNodeId],
+            [e.toNodeId, e.fromNodeId],
+        ];
+        for (const [self, other] of dirs) {
+            if (!hitNodeIds.has(self) || hitNodeIds.has(other) || seenNeighbor.has(other))
+                continue;
+            const n = nodeById.get(other);
+            if (!n || (n.status !== 'active' && n.status !== 'disputed'))
+                continue;
+            seenNeighbor.add(other);
+            neighbors.push(n);
+        }
+    }
+    neighbors.sort(byNodeRecency);
+    let hopTaken = 0;
+    for (const n of neighbors) {
+        if (hopTaken >= GRAPH_HOP_RECORD_CAP)
+            break;
+        for (const id of n.sourceRecordIds) {
+            if (seen.has(id))
+                continue; // 已被直连段占用:不计入、不吃名额
+            if (hopTaken >= GRAPH_HOP_RECORD_CAP)
+                break;
+            take(id);
+            hopTaken++;
+        }
+    }
     return out;
 }
+/**
+ * 直连段回链(无 hop)——保留 task_9 的原语义形状(既有测试继续钉住);
+ * 生产链路一律走 expandHitRecordIds(向量种子并集 + 1-hop)。
+ */
+export function graphHitRecordIds(hits) {
+    return expandHitRecordIds(hits, [], []);
+}
 /**
  * 图谱节点检索:返回按 score 降序的命中(最多 limit 条;limit 钳制 1~20)。
  * 候选节点 = active | disputed(superseded/archived 不进检索)。

package/dist/graph/types.d.ts

@@ -134,9 +134,34 @@ export declare const GRAPH_JOB_BATCH = 8;
 export declare const GRAPH_PRIORITY_NEW = 10000;
 /** 存量补投影的优先级(启动/周期补齐;恒低于新蒸馏)。 */
 export declare const GRAPH_PRIORITY_BACKFILL = 100;
-/** 单 job 最大尝试次数:claim 时 +1,达到即转 dead(不再重试)。 */
+/** 单 job 最大尝试次数(永久错误:校验/解析类——3 次不过就 dead)。
+ *  瞬态错误(aborted/timeout/网络)走 GRAPH_JOB_TRANSIENT_MAX_ATTEMPTS。 */
 export declare const GRAPH_JOB_MAX_ATTEMPTS = 3;
+/** 瞬态错误(attempt 不消耗到 3 即 dead):网关负载或超时引起的 aborted、
+ *  terminated、网络抖动、模型空输出——这些与 prompt/数据无关，退避后重试即恢复。
+ *  6 次 ≈ 5 轮退避(~30 分钟)覆盖 local-35 负载低谷。 */
+export declare const GRAPH_JOB_TRANSIENT_MAX_ATTEMPTS = 6;
+/** 图谱投影 LLM 单次调用超时(含整条回退链):沿用 llm.timeoutMs(120s) 在 8-record
+ *  批 + 上下文节点/边 + 12 关系词 prompt 下真机撞线(14 dead 全是 aborted×13 + terminated×1)。
+ *  照 backfill callTimeoutMs 先例给 240s,按「路由数 × 单路由耗时」留余量。 */
+export declare const GRAPH_PROJECTION_CALL_TIMEOUT_MS = 240000;
 /** 失败指数退避基数:第 n 次失败后 nextAttemptAt = now + base × 2^(n-1)。 */
 export declare const GRAPH_JOB_BACKOFF_BASE_MS = 60000;
 /** 单次检索返回上限的硬钳制(工具与 RPC 两侧共用同一钳制值)。 */
 export declare const GRAPH_SEARCH_LIMIT_MAX = 20;
+/** §D 第 3 路路内向量种子的节点条数上限(种子只是联想起点,独立于词法路 limit)。 */
+export declare const GRAPH_VEC_SEED_CAP = 10;
+/** 1-hop 边扩展回链的新增记录数封顶(hop 段专用名额,直连段不占;防 hub 节点邻接爆量)。 */
+export declare const GRAPH_HOP_RECORD_CAP = 64;
+/** 面板图谱预览:种子榜上限(画布片数)。 */
+export declare const GRAPH_PREVIEW_SEEDS = 6;
+/** 面板图谱预览:单种子绘制的邻居上限(超出置 truncated)。 */
+export declare const GRAPH_PREVIEW_NEIGHBORS = 10;
+/** 面板图谱预览:种子评分中因果边的权重(score = degree + causal×此值)——
+ *  因果链比共现邻接更值得画,预览侧单源读 GRAPH_CAUSAL_RELATIONS。 */
+export declare const GRAPH_PREVIEW_CAUSAL_WEIGHT = 2;
+/** 全图星图（mode:'full'）节点上限：超限截断并置 truncated（截断标记而非硬拒——
+ *  星图是展示面，宁可少画几颗也不报错；G6 舒适区 <2000 留余量）。 */
+export declare const GRAPH_PREVIEW_FULL_NODES = 1500;
+/** 全图星图 active 边上限（同一 truncated 语义；悬挂边已在截断前剔除）。 */
+export declare const GRAPH_PREVIEW_FULL_EDGES = 3000;

package/dist/graph/types.js

@@ -6,9 +6,34 @@ export const GRAPH_JOB_BATCH = 8;
 export const GRAPH_PRIORITY_NEW = 10000;
 /** 存量补投影的优先级(启动/周期补齐;恒低于新蒸馏)。 */
 export const GRAPH_PRIORITY_BACKFILL = 100;
-/** 单 job 最大尝试次数:claim 时 +1,达到即转 dead(不再重试)。 */
+/** 单 job 最大尝试次数(永久错误:校验/解析类——3 次不过就 dead)。
+ *  瞬态错误(aborted/timeout/网络)走 GRAPH_JOB_TRANSIENT_MAX_ATTEMPTS。 */
 export const GRAPH_JOB_MAX_ATTEMPTS = 3;
+/** 瞬态错误(attempt 不消耗到 3 即 dead):网关负载或超时引起的 aborted、
+ *  terminated、网络抖动、模型空输出——这些与 prompt/数据无关，退避后重试即恢复。
+ *  6 次 ≈ 5 轮退避(~30 分钟)覆盖 local-35 负载低谷。 */
+export const GRAPH_JOB_TRANSIENT_MAX_ATTEMPTS = 6;
+/** 图谱投影 LLM 单次调用超时(含整条回退链):沿用 llm.timeoutMs(120s) 在 8-record
+ *  批 + 上下文节点/边 + 12 关系词 prompt 下真机撞线(14 dead 全是 aborted×13 + terminated×1)。
+ *  照 backfill callTimeoutMs 先例给 240s,按「路由数 × 单路由耗时」留余量。 */
+export const GRAPH_PROJECTION_CALL_TIMEOUT_MS = 240_000;
 /** 失败指数退避基数:第 n 次失败后 nextAttemptAt = now + base × 2^(n-1)。 */
 export const GRAPH_JOB_BACKOFF_BASE_MS = 60_000;
 /** 单次检索返回上限的硬钳制(工具与 RPC 两侧共用同一钳制值)。 */
 export const GRAPH_SEARCH_LIMIT_MAX = 20;
+/** §D 第 3 路路内向量种子的节点条数上限(种子只是联想起点,独立于词法路 limit)。 */
+export const GRAPH_VEC_SEED_CAP = 10;
+/** 1-hop 边扩展回链的新增记录数封顶(hop 段专用名额,直连段不占;防 hub 节点邻接爆量)。 */
+export const GRAPH_HOP_RECORD_CAP = 64;
+/** 面板图谱预览:种子榜上限(画布片数)。 */
+export const GRAPH_PREVIEW_SEEDS = 6;
+/** 面板图谱预览:单种子绘制的邻居上限(超出置 truncated)。 */
+export const GRAPH_PREVIEW_NEIGHBORS = 10;
+/** 面板图谱预览:种子评分中因果边的权重(score = degree + causal×此值)——
+ *  因果链比共现邻接更值得画,预览侧单源读 GRAPH_CAUSAL_RELATIONS。 */
+export const GRAPH_PREVIEW_CAUSAL_WEIGHT = 2;
+/** 全图星图（mode:'full'）节点上限：超限截断并置 truncated（截断标记而非硬拒——
+ *  星图是展示面，宁可少画几颗也不报错；G6 舒适区 <2000 留余量）。 */
+export const GRAPH_PREVIEW_FULL_NODES = 1500;
+/** 全图星图 active 边上限（同一 truncated 语义；悬挂边已在截断前剔除）。 */
+export const GRAPH_PREVIEW_FULL_EDGES = 3000;

package/dist/hooks/recall.js

@@ -531,7 +531,14 @@ usage) {
                 usage?.recordAttempt(scoped.map((h) => h.id), fresh.slice(0, lines.length).map((h) => h.id));
                 // G-live:按 **sessionKey**(=agent.session?.id ?? agent.id，与 pill 的 sessionId / 投影 header.id 同源，
                 // 非 ownerId)记入本会话“活召回集”，供侧栏卡读取；压缩时同键 reset。
-                stores.recalled?.add(sessionKey, fresh.slice(0, lines.length).map((h) => h.id), injection.id);
+                // 路归因随注入透传(hybrid 融合才挂 lanes;单路策略下表空=不记,徽标无从渲染)。
+                const injectedHits = fresh.slice(0, lines.length);
+                const laneById = new Map();
+                for (const h of injectedHits) {
+                    if (h.lanes !== undefined && h.lanes.length > 0)
+                        laneById.set(h.id, h.lanes);
+                }
+                stores.recalled?.add(sessionKey, injectedHits.map((h) => h.id), injection.id, laneById);
                 // 入账在成功构造注入消息之后、返回 enter 之前——任何前置抛错路径账目零扰动
                 const led = ledgerFor(payload.agent.id);
                 recordRecallInjection(led, text.length);