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

package/dist/config.d.ts

@@ -81,6 +81,15 @@ export interface MemoryConfig {
          *  同时为真才执行;图谱是 L1 的可重建投影,关闭不影响记忆主链路。 */
         enabled: boolean;
     };
+    /**
+     * 时效分级(expiry-tiering 门2):`tieringEnabled` 灰度闸，**默认关**。
+     * 关时被动注入与改前逐字一致(零漂移)；开时注入候选按 classifyValidity 现算态
+     * 剔除 `expired`(仍在索引可检索，只是不自动浮现)，`expired_suspect` 保留并带标注。
+     * 与部署 cfg.validity.tieringEnabled 取或的还有面板运行时开关(live.validityTiering)。
+     * 门1 解耦本身不受本闸控(它是 bugfix:误遮蔽历史应尽快恢复)。 */
+    validity: {
+        tieringEnabled: boolean;
+    };
     /** §C 矛盾冻结:去重判定"两边都像是对的、机器判不了"时不自动裁决,
      *  把冲突对停放到待人工裁决区(conflict_pending)。**默认关**——
      *  冻结消耗人的注意力,不可默认全开。 */

package/dist/config.js

@@ -87,6 +87,9 @@ export function liveSettingsSchema() {
         redistillEnabled: Schema.boolean().default(false),
         mdSyncEnabled: Schema.boolean().default(false),
         memportEnabled: Schema.boolean().default(false),
+        /** 时效分级门2 面板开关:与部署 cfg.validity.tieringEnabled 取或(任一为真即启用
+         *  注入侧 expired 过滤)。默认关;先面板验证再翻部署默认(照 keywordEnabled 先例)。 */
+        validityTiering: Schema.boolean().default(false),
         /**
          * 存量回填（keyword / redistill）LLM 批调用的**运行时并行度**覆盖：
          * `0` = 跟随部署 `cfg.backfill.concurrency`；1–8 = 直接覆盖。
@@ -156,6 +159,11 @@ export const memorySchema = Schema.object({
     graph: Schema.object({
         enabled: Schema.boolean().default(false),
     }),
+    // 时效分级门2 灰度闸:默认关(关=注入行为与改前逐字一致)。验后翻默认为 true 的
+    // 发版决策记在计划 findings(task_8.6)。
+    validity: Schema.object({
+        tieringEnabled: Schema.boolean().default(false),
+    }),
     // §C 矛盾冻结:默认关。开启后去重决策词表多出 conflict 动作,冲突对停放待人工裁决。
     conflictFreeze: Schema.object({
         enabled: Schema.boolean().default(false),

package/dist/contract.d.ts

@@ -116,6 +116,8 @@ export interface MemoryLiveSettings {
     mdSyncEnabled: boolean;
     /** 外部记忆来源 Connect 启用开关（概览区可拨）:true = 放行 memport-* 端点。与部署 cfg.memport.enabled 取或。 */
     memportEnabled: boolean;
+    /** 时效分级门2 启用开关（概览区可拨）:true = 被动注入剔除 expired。与部署 cfg.validity.tieringEnabled 取或；关=注入与改前逐字一致。 */
+    validityTiering: boolean;
     /** md 投射/后缀收敛的单次动作护栏运行时覆盖:0 = 跟随部署 `cfg.memExport.maxRecords`（默认 2000）。
      *  存在的理由：一次点完多少条属于“回填历史时才改一下”的旋钮，不该要求改 YAML + 重启。 */
     mdExportMaxRecords: number;
@@ -927,6 +929,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 +1237,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 +1850,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 +1917,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/embedding-child.cjs

@@ -0,0 +1,192 @@
+/**
+ * 本地嵌入子进程(fix #11):transformers.js 的模型加载与推理在 fork 出的独立
+ * 子进程执行,主线程只投递文本、收回向量。取代 worker_threads 的原因:
+ * 插件 runtime 的 sharp/libvips 与宿主 Electron 的 sharp/libvips 在同一进程内
+ * 加载会撞 libvips-42.dll 名字(OS LoadLibrary 层冲突,同名不同路径行为未定义)
+ * ——worker_thread 与主线程同进程,撞名前提仍在;子进程自带独立 DLL 表,物理隔离。
+ *
+ * 推理队列语义与 embedding-worker.cjs 完全一致(单线程串行、priority 插队、
+ * 条间 setImmediate 让路),只有 IPC 传输层不同:
+ *
+ * 协议(与 src/store/local-embedding.ts 的 RealChildChannel 配对;自增 id):
+ * - 启动配置:env DSH_EMBED_CFG(JSON 字符串:{runtimeDir,modelDir,pooling,dtype,
+ *   maxInputChars}——fork 的 env 只收标量,嵌套对象经序列化传递);
+ * - 入向:{id,type:'ping'} | {id,type:'warmup'} | {id,type:'embed',texts,priority}
+ * - 出向:{id,ok:true,type:'pong'|'ready'|'embedded',vectors?}(vectors 为
+ *   number[][],fork IPC 默认 JSON 序列化不支持 TypedArray,主线程侧重建
+ *   Float32Array;512d×32 条 ≈64KB,序列化 <5ms,瓶颈在推理不在传输)
+ *   | {id,ok:false,stage:'load'|'infer',error} | {type:'fatal',error}
+ *
+ * 信任边界(沿 AGENTS.md 审查记录):runtime/ 目录在数据目录信任边界内,
+ * 本进程按其 package.json createRequire 加载 transformers——对数据目录有写
+ * 权限的进程理论上可植入恶意模块;模型文件逐文件 sha256 锁定,运行时代码
+ * 无同级防护,完整修复需安装指纹设计,暂以文档化假设为准。
+ */
+'use strict';
+
+const path = require('node:path');
+const { createRequire } = require('node:module');
+
+// 必须由 fork 启动(需要 IPC channel);裸 node 执行时静默退出,不报 SyntaxError、不永挂。
+if (typeof process.send !== 'function') {
+  console.error('[embedding-child] 未经 fork 启动,无 IPC 通道,退出');
+  process.exit(0);
+}
+
+/** 错误消息归一化(Error 取 message,其余 String 化)。 */
+function errMsg(err) {
+  return err && err.message ? err.message : String(err);
+}
+
+const cfg = JSON.parse(process.env.DSH_EMBED_CFG || '{}');
+const RUNTIME_DIR = typeof cfg.runtimeDir === 'string' ? cfg.runtimeDir : '';
+const MODEL_DIR = typeof cfg.modelDir === 'string' ? cfg.modelDir : '';
+const POOLING = cfg.pooling === 'cls' ? 'cls' : 'mean';
+const DTYPE = typeof cfg.dtype === 'string' ? cfg.dtype : 'q8';
+const MAX_INPUT_CHARS = cfg.maxInputChars > 0 ? cfg.maxInputChars : 5000;
+
+let extractor = null; // pipeline('feature-extraction', …)
+let loadState = 'idle'; // idle | loading | ready | failed
+let loadPromise = null;
+let loadError = null;
+
+// ── 模型懒加载(首请求触发;失败后经 warmup 可重试,embed 请求失败快返回) ──
+function ensureLoaded() {
+  if (loadState === 'ready') return Promise.resolve();
+  if (loadState === 'loading' && loadPromise) return loadPromise;
+  loadState = 'loading';
+  loadError = null;
+  loadPromise = (async () => {
+    try {
+      if (!RUNTIME_DIR || !MODEL_DIR) throw new Error('DSH_EMBED_CFG 缺少 runtimeDir/modelDir');
+      const req = createRequire(path.join(RUNTIME_DIR, 'package.json'));
+      const mod = req('@huggingface/transformers');
+      if (mod.env) {
+        mod.env.allowRemoteModels = false;
+        if (mod.env.allowLocalModels !== undefined) mod.env.allowLocalModels = true;
+      }
+      extractor = await mod.pipeline('feature-extraction', MODEL_DIR, { dtype: DTYPE });
+      loadState = 'ready';
+    } catch (err) {
+      loadState = 'failed';
+      loadError = errMsg(err);
+      loadPromise = null; // 失败后下一次 warmup 重新走加载
+      throw err;
+    }
+  })();
+  return loadPromise;
+}
+
+// ── 推理队列(逐条 job;priority 插队;条间让路) ──
+const queue = []; // [{ request, index, text }]
+let pumping = false;
+
+function postReply(msg) {
+  // 通道已断(父进程退出/正在终止)时 send 抛错——静默即可,父进程侧有 exit 兜底
+  try {
+    process.send(msg);
+  } catch {
+    /* IPC 已关闭,回复无处可去 */
+  }
+}
+
+/** 请求全部条目完成 → 回执(Float32Array → number[] 序列化,IPC JSON 通道不支持 TypedArray)。 */
+function settle(request) {
+  if (request.failed || request.remaining !== 0) return;
+  postReply({
+    id: request.id,
+    ok: true,
+    type: 'embedded',
+    vectors: request.vectors.map((v) => Array.from(v)),
+  });
+}
+
+/** 首个失败即回执错误,并移除该请求尚未开跑的条目(正在跑的至多 1 条,算完即弃)。 */
+function failRequest(request, error, stage) {
+  if (request.failed) return;
+  request.failed = true;
+  for (let i = queue.length - 1; i >= 0; i--) {
+    if (queue[i].request === request) queue.splice(i, 1);
+  }
+  postReply({ id: request.id, ok: false, stage: stage, error: errMsg(error) });
+}
+
+async function pump() {
+  if (pumping) return;
+  pumping = true;
+  try {
+    while (queue.length > 0) {
+      const job = queue.shift();
+      if (job.request.failed) continue;
+      try {
+        const result = await extractor([job.text.slice(0, MAX_INPUT_CHARS)], { pooling: POOLING, normalize: true });
+        const data = result[0] && result[0].data;
+        job.request.vectors[job.index] = data instanceof Float32Array ? data : new Float32Array(data);
+        job.request.remaining -= 1;
+        settle(job.request);
+      } catch (err) {
+        failRequest(job.request, err, 'infer');
+      }
+      // 条间让路:交还本进程事件循环,新消息(含 priority 插队)可在批间被处理
+      await new Promise((resolve) => setImmediate(resolve));
+    }
+  } finally {
+    pumping = false;
+  }
+}
+
+function handleEmbed(msg) {
+  const texts = Array.isArray(msg.texts) ? msg.texts : [];
+  if (texts.length === 0) {
+    postReply({ id: msg.id, ok: true, type: 'embedded', vectors: [] });
+    return;
+  }
+  const request = { id: msg.id, vectors: new Array(texts.length), remaining: texts.length, failed: false };
+  // 单条请求(召回 query)插队到队首;批次追加到队尾(批内条目间仍会被后来的插队)
+  const priority = msg.priority === true && texts.length === 1;
+  for (let i = 0; i < texts.length; i++) {
+    const job = { request: request, index: i, text: String(texts[i] == null ? '' : texts[i]) };
+    if (priority) queue.unshift(job);
+    else queue.push(job);
+  }
+  void pump();
+}
+
+process.on('message', (msg) => {
+  if (!msg || typeof msg.id !== 'number' || typeof msg.type !== 'string') return;
+  if (msg.type === 'ping') {
+    postReply({ id: msg.id, ok: true, type: 'pong' });
+    return;
+  }
+  if (msg.type === 'warmup') {
+    ensureLoaded().then(
+      () => postReply({ id: msg.id, ok: true, type: 'ready' }),
+      () => postReply({ id: msg.id, ok: false, stage: 'load', error: loadError ?? '模型加载失败' }),
+    );
+    return;
+  }
+  if (msg.type === 'embed') {
+    void (async () => {
+      try {
+        await ensureLoaded();
+      } catch {
+        postReply({ id: msg.id, ok: false, stage: 'load', error: loadError ?? '模型加载失败' });
+        return;
+      }
+      handleEmbed(msg);
+    })();
+    return;
+  }
+});
+
+// 父进程disconnect(通道被主动关闭,如宿主优雅退出/RealChildChannel 前置断开):
+// 模型与 onnxruntime 都只服务于这条通道,留着就是孤儿常驻——直接退出。
+// taskkill /T /F 兜底覆盖"父进程被硬杀、无 disconnect"的路径。
+process.on('disconnect', () => process.exit(0));
+
+// 未捕获异常:尽力通知父进程后强制退出(父进程的 exit 处理会拒绝全部 pending
+// 并转入 failed 态)。不保持半死状态——半死的子进程只会让调用方挂到超时。
+process.on('uncaughtException', (err) => {
+  postReply({ type: 'fatal', error: errMsg(err) });
+  setTimeout(() => process.exit(1), 50);
+});

package/dist/embedding-worker.cjs

@@ -1,3 +1,5 @@
+// DEPRECATED: use embedding-child.cjs (subprocess isolation, fix #11)
+// 保留一版兼容(opts.useWorker 逃生门),下版删除。不再主动修改。
 /**
  * 本地嵌入 worker:transformers.js 的模型加载与推理在本线程执行,主线程只
  * 投递文本、收回向量。onnxruntime-node 的 run/loadModel 是 setImmediate 回调里

package/dist/graph/apply.d.ts

@@ -31,7 +31,16 @@ export declare function normalizeEntityName(name: string): string;
  * validTo → validFrom(时间增强列,新写入路径)→ metadata.activity_end_time →
  * metadata.activity_start_time(列迁移前的存量数据)→ timestamps 最新 → createdAt。
  * 全部无证据才用 fallback(now),绝不猜测。
+ *
+ * task_2.6(expiry-tiering):兜底 now 分支回传 `'fallback_now'` 证据等级——供图谱侧
+ * 同口径读时派生使用(落到 now 的 validFrom **不是**时间证据,与 activity_* 链的
+ * 'evidence' 必须可区分;否则假过期与真过期同形)。
  */
+export declare function anchorTimeFromRecordsDetailed(records: readonly MemoryRecord[], fallbackIso: string): {
+    iso: string;
+    source: 'evidence' | 'fallback_now';
+};
+/** {@link anchorTimeFromRecordsDetailed} 的旧签名封装(调用方只要时刻时的零改动通道)。 */
 export declare function anchorTimeFromRecords(records: readonly MemoryRecord[], fallbackIso: string): string;
 /** 应用一次投影提案(硬校验 + 消歧 + supersede + 状态重建)。 */
 export declare function applyGraphProjection(options: ApplyGraphProjectionOptions): ApplyGraphProjectionOutcome;

package/dist/graph/apply.js

@@ -66,8 +66,12 @@ function recordFamily(r) {
  * validTo → validFrom(时间增强列,新写入路径)→ metadata.activity_end_time →
  * metadata.activity_start_time(列迁移前的存量数据)→ timestamps 最新 → createdAt。
  * 全部无证据才用 fallback(now),绝不猜测。
+ *
+ * task_2.6(expiry-tiering):兜底 now 分支回传 `'fallback_now'` 证据等级——供图谱侧
+ * 同口径读时派生使用(落到 now 的 validFrom **不是**时间证据,与 activity_* 链的
+ * 'evidence' 必须可区分;否则假过期与真过期同形)。
  */
-export function anchorTimeFromRecords(records, fallbackIso) {
+export function anchorTimeFromRecordsDetailed(records, fallbackIso) {
     let latest = Number.NaN;
     const consider = (raw) => {
         const t = typeof raw === 'number' ? raw : typeof raw === 'string' ? Date.parse(raw) : Number.NaN;
@@ -85,7 +89,13 @@ export function anchorTimeFromRecords(records, fallbackIso) {
             consider(t);
         consider(r.createdAt);
     }
-    return Number.isNaN(latest) ? fallbackIso : new Date(latest).toISOString();
+    return Number.isNaN(latest)
+        ? { iso: fallbackIso, source: 'fallback_now' }
+        : { iso: new Date(latest).toISOString(), source: 'evidence' };
+}
+/** {@link anchorTimeFromRecordsDetailed} 的旧签名封装(调用方只要时刻时的零改动通道)。 */
+export function anchorTimeFromRecords(records, fallbackIso) {
+    return anchorTimeFromRecordsDetailed(records, fallbackIso).iso;
 }
 /** 来源集并集封顶(保最新:新引用追加在尾部,溢出丢头部最老引用)。 */
 function unionSourcesCapped(old, add) {

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;