dsh-prime-memory 0.11.0

package/dist/contract.js

@@ -0,0 +1 @@
+export {};

package/dist/embedding-worker.cjs

@@ -0,0 +1,176 @@
+/**
+ * 本地嵌入 worker:transformers.js 的模型加载与推理在本线程执行,主线程只
+ * 投递文本、收回向量。onnxruntime-node 的 run/loadModel 是 setImmediate 回调里
+ * 的同步调用(Promise 包装不卸载计算),留在主线程会冻结宿主事件循环——
+ * dsh 页面一切交互无响应数秒的根因。
+ *
+ * 协议(与 src/store/local-embedding.ts 的 RealWorkerChannel 配对;自增 id):
+ * - 入向:{id,type:'ping'} | {id,type:'warmup'} | {id,type:'embed',texts,priority}
+ * - 出向:{id,ok:true,type:'pong'|'ready'|'embedded',vectors?}(向量经
+ *   transfer 列表零拷贝回传)| {id,ok:false,stage:'load'|'infer',error}
+ *   | {type:'fatal',error}
+ *
+ * 调度:单线程串行。embedBatch 拆成逐条 job、条间 setImmediate 让路——
+ * 单条请求(priority,即召回 query)unshift 插队,最坏只等"正在算的那一条",
+ * 不会被 reindex 批次(16/32 条 ≈5-10s)堵在队尾。
+ *
+ * 信任边界(沿 AGENTS.md 审查记录):runtime/ 目录在数据目录信任边界内,
+ * 本线程按其 package.json createRequire 加载 transformers——对数据目录有写
+ * 权限的进程理论上可植入恶意模块;模型文件逐文件 sha256 锁定,运行时代码
+ * 无同级防护,完整修复需安装指纹设计,暂以文档化假设为准。
+ */
+'use strict';
+
+const { parentPort, workerData } = require('node:worker_threads');
+const path = require('node:path');
+const { createRequire } = require('node:module');
+
+/** 错误消息归一化(Error 取 message,其余 String 化)。 */
+function errMsg(err) {
+  return err && err.message ? err.message : String(err);
+}
+
+const cfg = workerData || {};
+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('workerData 缺少 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, transfer) {
+  parentPort.postMessage(msg, transfer || []);
+}
+
+/** 请求全部条目完成 → 回执(transfer 向量缓冲零拷贝)。 */
+function settle(request) {
+  if (request.failed || request.remaining !== 0) return;
+  postReply(
+    { id: request.id, ok: true, type: 'embedded', vectors: request.vectors },
+    request.vectors.map((v) => v.buffer),
+  );
+}
+
+/** 首个失败即回执错误,并移除该请求尚未开跑的条目(正在跑的至多 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();
+}
+
+parentPort.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;
+  }
+});
+
+// 未捕获异常:尽力通知主线程后强制退出(主线程的 exit 处理会拒绝全部 pending
+// 并转入 failed 态)。不保持半死状态——半死的 worker 只会让调用方挂到超时。
+process.on('uncaughtException', (err) => {
+  try {
+    postReply({ type: 'fatal', error: errMsg(err) });
+  } catch {
+    /* 端口已坏,exit 处理兜底 */
+  }
+  setTimeout(() => process.exit(1), 50);
+});

package/dist/graph/apply.d.ts

@@ -0,0 +1,37 @@
+import type { MemoryRecord } from '../types.js';
+import type { GraphEdge, GraphNode, GraphProjectionResult } from './types.js';
+export interface ApplyGraphProjectionOptions {
+    /** 可变异的合并 scope(现有节点/边;调用方决定 scope 大小)。 */
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    /** 本批认领的记录(族判定与时间锚的证据来源)。 */
+    records: readonly MemoryRecord[];
+    result: GraphProjectionResult;
+    allowedRecordIds: ReadonlySet<string>;
+    /** 本次投影时刻(ISO;时间锚兜底与 updatedAt 的时间基准)。 */
+    now: string;
+    idFactory: (prefix: 'node' | 'edge' | 'gfact') => string;
+}
+export interface ApplyGraphProjectionOutcome {
+    nodeIds: string[];
+    edgeIds: string[];
+    /** 因无来源/形状非法被丢弃的提案条数(节点+fact+边;诊断日志用)。 */
+    dropped: number;
+}
+/**
+ * 实体名归一(NFKC + 小写 + 去空白/下划线/连字符):全角/半角、大小写、
+ * "张 三"与"张三"、"AI-agent"与"aiagent"视作同一实体的拼写变体。
+ * 归一后空串返回原串(防止空名互相合并)。
+ */
+export declare function normalizeEntityName(name: string): string;
+/**
+ * 时间锚:有效期为先,提及/入库时间为后。
+ *
+ * 逐条记录按六级证据取最晚,任何一级无法解析(缺字段/非法日期)即落到下一级:
+ * validTo → validFrom(时间增强列,新写入路径)→ metadata.activity_end_time →
+ * metadata.activity_start_time(列迁移前的存量数据)→ timestamps 最新 → createdAt。
+ * 全部无证据才用 fallback(now),绝不猜测。
+ */
+export declare function anchorTimeFromRecords(records: readonly MemoryRecord[], fallbackIso: string): string;
+/** 应用一次投影提案(硬校验 + 消歧 + supersede + 状态重建)。 */
+export declare function applyGraphProjection(options: ApplyGraphProjectionOptions): ApplyGraphProjectionOutcome;

package/dist/graph/apply.js

@@ -0,0 +1,270 @@
+/**
+ * 投影提案硬校验与落库语义(纯函数,无 I/O)。
+ *
+ * 这是图谱最核心的守门代码,唯一不变量:**零无来源事实**——每个节点/fact/边的
+ * sourceRecordIds 必须非空且全部属于本 job 认领的记录批次,否则整条提案静默丢弃。
+ * 图谱里不存在无法回溯到 L1 记录(进而到 JSONL 事实源)的结论。
+ *
+ * 其余语义:
+ * - 实体消歧:normalizeEntityName(NFKC + 小写 + 去空白/下划线/连字符)归一后同名
+ *   且类型一致才合并(别名累积去重);子串包含不算同一实体;
+ * - 状态历史:同 key 的新 fact 把旧 active fact 标 superseded 并闭合 validTo;
+ *   同 (from,relation) 指向新目标的旧边同样 supersede——保留时间区间,不覆盖历史;
+ * - currentState 只由 active facts 重建;
+ * - 时间锚四级链:activity_start_time → activity_end_time → timestamps 最新 →
+ *   createdAt,跨来源取最晚(ISO);无任何证据时才落到 now,不猜日期。
+ *
+ * 函数直接变异传入的 nodes/edges(merge scope),返回 touched id 集合——调用方
+ * (GraphStore.complete)在单事务内 load scope → apply → 写回,LLM 调用永远
+ * 不发生在该事务内。
+ */
+import { familyForType } from '../types.js';
+import { GRAPH_CAP, GRAPH_NODE_TYPE_SET, GRAPH_SOURCE_RECORDS_CAP, GRAPH_STATUS_SET, } from './constraints.js';
+/** 字符串字段归一:trim、折叠空白、截断;非字符串一律空串。 */
+function textOf(value, limit) {
+    return typeof value === 'string' ? value.trim().replace(/\s+/g, ' ').slice(0, limit) : '';
+}
+/** 字符串数组字段归一:逐项截断去空、跨项去重、截到条数上限。 */
+function stringsOf(value, itemCap, countCap) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value) {
+        const t = textOf(item, itemCap);
+        if (t && !out.includes(t))
+            out.push(t);
+        if (out.length >= countCap)
+            break;
+    }
+    return out;
+}
+/** 置信度钳制:非法值回到 0.8 中性档(提案没填 = 模型默认自信度)。 */
+function clampConfidence(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0.8;
+}
+/** 状态归一:非法值回 active(四态之外的表达一律不采信)。 */
+function clampStatus(value) {
+    return typeof value === 'string' && GRAPH_STATUS_SET.has(value) ? value : 'active';
+}
+/**
+ * 实体名归一(NFKC + 小写 + 去空白/下划线/连字符):全角/半角、大小写、
+ * "张 三"与"张三"、"AI-agent"与"aiagent"视作同一实体的拼写变体。
+ * 归一后空串返回原串(防止空名互相合并)。
+ */
+export function normalizeEntityName(name) {
+    const normalized = name.normalize('NFKC').toLowerCase().replace(/[\s_-]+/g, '');
+    return normalized || name;
+}
+/** 记录族兜底(record.family 缺失时按 type 前缀推导,与写入侧同一兜底链)。 */
+function recordFamily(r) {
+    return r.family ?? familyForType(r.type);
+}
+/**
+ * 时间锚:有效期为先,提及/入库时间为后。
+ *
+ * 逐条记录按六级证据取最晚,任何一级无法解析(缺字段/非法日期)即落到下一级:
+ * validTo → validFrom(时间增强列,新写入路径)→ metadata.activity_end_time →
+ * metadata.activity_start_time(列迁移前的存量数据)→ timestamps 最新 → createdAt。
+ * 全部无证据才用 fallback(now),绝不猜测。
+ */
+export function anchorTimeFromRecords(records, fallbackIso) {
+    let latest = Number.NaN;
+    const consider = (raw) => {
+        const t = typeof raw === 'number' ? raw : typeof raw === 'string' ? Date.parse(raw) : Number.NaN;
+        if (Number.isFinite(t) && t > 0 && (Number.isNaN(latest) || t > latest))
+            latest = t;
+    };
+    for (const r of records) {
+        // 时间增强列优先(新写入路径),再回落 metadata.activity_*(列迁移前的存量数据)
+        consider(r.validTo);
+        consider(r.validFrom);
+        const meta = r.metadata;
+        consider(meta?.activity_start_time);
+        consider(meta?.activity_end_time);
+        for (const t of r.timestamps ?? [])
+            consider(t);
+        consider(r.createdAt);
+    }
+    return Number.isNaN(latest) ? fallbackIso : new Date(latest).toISOString();
+}
+/** 来源集并集封顶(保最新:新引用追加在尾部,溢出丢头部最老引用)。 */
+function unionSourcesCapped(old, add) {
+    const merged = [...new Set([...old, ...add])];
+    return merged.length > GRAPH_SOURCE_RECORDS_CAP ? merged.slice(-GRAPH_SOURCE_RECORDS_CAP) : merged;
+}
+/** 同一实体判定:类型一致 + 名称/别名归一后的集合相交(子串包含不算)。 */
+function isSameEntity(node, name, aliases, type) {
+    if (node.type !== type)
+        return false;
+    const keys = new Set([normalizeEntityName(name), ...aliases.map(normalizeEntityName)]);
+    return [node.name, ...node.aliases].some((candidate) => keys.has(normalizeEntityName(candidate)));
+}
+/** 应用一次投影提案(硬校验 + 消歧 + supersede + 状态重建)。 */
+export function applyGraphProjection(options) {
+    const { nodes, edges, records, allowedRecordIds, now, idFactory } = options;
+    const refs = new Map();
+    const touchedNodes = new Set();
+    const touchedEdges = new Set();
+    let dropped = 0;
+    /** 来源引用校验:非空且全部属于本批(任一越批 = 整条提案不可信,返回空)。 */
+    const validSources = (value) => {
+        const requested = stringsOf(value, GRAPH_CAP.ref, GRAPH_CAP.proposalSources);
+        return requested.length > 0 && requested.every((id) => allowedRecordIds.has(id)) ? requested : [];
+    };
+    const recordById = new Map(records.map((r) => [r.id, r]));
+    const familiesOf = (sourceIds) => {
+        const families = new Set();
+        for (const id of sourceIds) {
+            const r = recordById.get(id);
+            if (r)
+                families.add(recordFamily(r));
+        }
+        return [...families];
+    };
+    // ── 节点提案 ──
+    for (const raw of Array.isArray(options.result.nodes) ? options.result.nodes : []) {
+        const ref = textOf(raw?.ref, GRAPH_CAP.ref);
+        const name = textOf(raw?.name, GRAPH_CAP.name);
+        const sources = validSources(raw?.sourceRecordIds);
+        if (!ref || !name || !GRAPH_NODE_TYPE_SET.has(raw?.type) || sources.length === 0) {
+            dropped++;
+            continue;
+        }
+        const aliases = stringsOf(raw?.aliases, GRAPH_CAP.alias, GRAPH_CAP.aliases).filter((alias) => normalizeEntityName(alias) !== normalizeEntityName(name));
+        const tags = stringsOf(raw?.tags, GRAPH_CAP.tag, GRAPH_CAP.tags);
+        const validFrom = textOf(raw?.validFrom, GRAPH_CAP.date) || anchorTimeFromRecords(sources.map((id) => recordById.get(id)).filter(Boolean), now);
+        const validTo = textOf(raw?.validTo, GRAPH_CAP.date) || undefined;
+        const status = clampStatus(raw?.status);
+        const confidence = clampConfidence(raw?.confidence);
+        // 消歧合并:同名同型已有节点就地更新;否则新建
+        let node = nodes.find((candidate) => isSameEntity(candidate, name, aliases, raw.type));
+        if (!node) {
+            node = {
+                id: idFactory('node'),
+                name,
+                type: raw.type,
+                aliases: [],
+                currentState: '',
+                facts: [],
+                status,
+                confidence,
+                sourceRecordIds: [],
+                families: [],
+                createdAt: now,
+                updatedAt: now,
+            };
+            nodes.push(node);
+        }
+        node.aliases = [...new Set([...node.aliases, ...aliases])];
+        if (tags.length > 0)
+            node.tags = [...new Set([...(node.tags ?? []), ...tags])].slice(0, GRAPH_CAP.tags);
+        node.status = status;
+        node.confidence = confidence;
+        node.sourceRecordIds = unionSourcesCapped(node.sourceRecordIds, sources);
+        node.families = [...new Set([...node.families, ...familiesOf(sources)])];
+        // 事实集:单行状态(state)归一为「状态」fact + 显式 facts 数组
+        const stateLine = textOf(raw?.state, GRAPH_CAP.state);
+        const explicitFacts = Array.isArray(raw?.facts) ? raw.facts : [];
+        const factProposals = [
+            ...(stateLine ? [{ key: '状态', value: stateLine }] : []),
+            ...explicitFacts,
+        ];
+        for (const fp of factProposals) {
+            const key = textOf(fp?.key, GRAPH_CAP.factKey);
+            const value = Array.isArray(fp?.value)
+                ? stringsOf(fp.value, GRAPH_CAP.factValue, GRAPH_CAP.factValueItems)
+                : textOf(fp?.value, GRAPH_CAP.factValue);
+            if (!key || (Array.isArray(value) ? value.length === 0 : !value))
+                continue;
+            // fact 级来源可选:未带则继承节点提案的来源(同样过批校验)
+            const factSources = fp && 'sourceRecordIds' in fp && fp.sourceRecordIds !== undefined
+                ? validSources(fp.sourceRecordIds)
+                : sources;
+            if (factSources.length === 0) {
+                dropped++;
+                continue;
+            }
+            // supersede:同 key 的旧 active fact 闭合(保留完整时间区间)
+            for (const old of node.facts) {
+                if (old.status === 'active' && old.key === key) {
+                    old.status = 'superseded';
+                    if (!old.validTo)
+                        old.validTo = validFrom;
+                    old.updatedAt = now;
+                }
+            }
+            const fact = {
+                id: idFactory('gfact'),
+                key,
+                value,
+                status,
+                validFrom,
+                ...(validTo ? { validTo } : {}),
+                confidence,
+                sourceRecordIds: unionSourcesCapped([], factSources),
+                createdAt: now,
+                updatedAt: now,
+            };
+            node.facts.push(fact);
+        }
+        // currentState 只由 active facts 重建(superseded/disputed/archived 不进状态串)
+        node.currentState = node.facts
+            .filter((f) => f.status === 'active')
+            .map((f) => `${f.key}: ${Array.isArray(f.value) ? f.value.join('、') : f.value}`)
+            .join('\n');
+        node.updatedAt = now;
+        refs.set(ref, node);
+        touchedNodes.add(node.id);
+    }
+    // ── 边提案 ──
+    for (const raw of Array.isArray(options.result.edges) ? options.result.edges : []) {
+        const from = refs.get(textOf(raw?.fromRef, GRAPH_CAP.ref));
+        const to = refs.get(textOf(raw?.toRef, GRAPH_CAP.ref));
+        const relation = textOf(raw?.relation, GRAPH_CAP.relation);
+        const sources = validSources(raw?.sourceRecordIds);
+        if (!from || !to || from.id === to.id || !relation || sources.length === 0) {
+            dropped++;
+            continue;
+        }
+        const status = clampStatus(raw?.status);
+        const confidence = clampConfidence(raw?.confidence);
+        const validFrom = textOf(raw?.validFrom, GRAPH_CAP.date) || anchorTimeFromRecords(sources.map((id) => recordById.get(id)).filter(Boolean), now);
+        const validTo = textOf(raw?.validTo, GRAPH_CAP.date) || undefined;
+        // supersede:同 (from,relation) 指向新目标 → 旧 active 边闭合
+        for (const old of edges) {
+            if (old.status === 'active' && old.fromNodeId === from.id && old.relation === relation && old.toNodeId !== to.id) {
+                old.status = 'superseded';
+                if (!old.validTo)
+                    old.validTo = validFrom;
+                old.updatedAt = now;
+                touchedEdges.add(old.id);
+            }
+        }
+        // 同 (from,to,relation,status) 已有边 → 合并来源;否则新建
+        const existing = edges.find((e) => e.fromNodeId === from.id && e.toNodeId === to.id && e.relation === relation && e.status === status);
+        if (existing) {
+            existing.sourceRecordIds = unionSourcesCapped(existing.sourceRecordIds, sources);
+            existing.confidence = confidence;
+            existing.updatedAt = now;
+            touchedEdges.add(existing.id);
+        }
+        else {
+            const edge = {
+                id: idFactory('edge'),
+                fromNodeId: from.id,
+                toNodeId: to.id,
+                relation,
+                status,
+                validFrom,
+                ...(validTo ? { validTo } : {}),
+                confidence,
+                sourceRecordIds: unionSourcesCapped([], sources),
+                createdAt: now,
+                updatedAt: now,
+            };
+            edges.push(edge);
+            touchedEdges.add(edge.id);
+        }
+    }
+    return { nodeIds: [...touchedNodes], edgeIds: [...touchedEdges], dropped };
+}

package/dist/graph/constraints.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 图谱域约束常量的单一事实源。
+ *
+ * 提示词(src/prompts/graph-projection.ts)与校验(src/graph/apply.ts)两侧都从
+ * 这里内插/引用——防"提示词说一套、校验执行另一套"的漂移。上限值从本项目自身
+ * 的序列化约束推导(L1 content 上限、fact 行渲染宽度、上下文装配预算),不对照
+ * 外部实现抄数。
+ */
+import type { GraphNodeType, GraphRecordStatus } from './types.js';
+/** 节点类型词汇表(提示词枚举与 apply 校验共用;超集即丢弃提案)。 */
+export declare const GRAPH_NODE_TYPES: readonly GraphNodeType[];
+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_RELATION_WORDS: readonly ["使用", "属于", "创建", "参与", "贡献", "依赖", "位于", "相关"];
+/** 提案字段上限(校验侧截断/丢弃与提示词内插共用同一组数字)。 */
+export declare const GRAPH_CAP: {
+    /** 提案内临时引用(ref)长度。 */
+    readonly ref: 120;
+    /** 节点显示名。 */
+    readonly name: 160;
+    /** 单个别名/标签/关系词。 */
+    readonly alias: 80;
+    readonly tag: 60;
+    readonly relation: 60;
+    /** 节点状态行与单条 fact 值(与召回注入的单条 maxCharsPerMemory 默认 500 同量级,给足余量)。 */
+    readonly state: 1200;
+    readonly factKey: 120;
+    readonly factValue: 1200;
+    /** fact 值为数组时的元素数与每元素长度。 */
+    readonly factValueItems: 40;
+    /** 单节点提案的别名/标签条数上限。 */
+    readonly aliases: 20;
+    readonly tags: 12;
+    /** 单提案允许引用的来源记录数(正常远小于批大小;钳到批上限的整数倍防畸形输出)。 */
+    readonly proposalSources: 64;
+    /** 单个日期字符串(validFrom/validTo)长度。 */
+    readonly date: 80;
+};
+/**
+ * 节点累计 sourceRecordIds 的并集封顶(保最新):图谱可重建,来源集只增会让
+ * 长寿命节点(如"用户本人")的来源数组无界增长;封顶后丢的是最老的来源引用,
+ * 状态仍由 active facts 决定,不影响可追溯性主体。
+ */
+export declare const GRAPH_SOURCE_RECORDS_CAP = 128;

package/dist/graph/constraints.js

@@ -0,0 +1,38 @@
+/** 节点类型词汇表(提示词枚举与 apply 校验共用;超集即丢弃提案)。 */
+export const GRAPH_NODE_TYPES = ['person', 'project', 'organization', 'tool', 'place'];
+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_RELATION_WORDS = ['使用', '属于', '创建', '参与', '贡献', '依赖', '位于', '相关'];
+/** 提案字段上限(校验侧截断/丢弃与提示词内插共用同一组数字)。 */
+export const GRAPH_CAP = {
+    /** 提案内临时引用(ref)长度。 */
+    ref: 120,
+    /** 节点显示名。 */
+    name: 160,
+    /** 单个别名/标签/关系词。 */
+    alias: 80,
+    tag: 60,
+    relation: 60,
+    /** 节点状态行与单条 fact 值(与召回注入的单条 maxCharsPerMemory 默认 500 同量级,给足余量)。 */
+    state: 1_200,
+    factKey: 120,
+    factValue: 1_200,
+    /** fact 值为数组时的元素数与每元素长度。 */
+    factValueItems: 40,
+    /** 单节点提案的别名/标签条数上限。 */
+    aliases: 20,
+    tags: 12,
+    /** 单提案允许引用的来源记录数(正常远小于批大小;钳到批上限的整数倍防畸形输出)。 */
+    proposalSources: 64,
+    /** 单个日期字符串(validFrom/validTo)长度。 */
+    date: 80,
+};
+/**
+ * 节点累计 sourceRecordIds 的并集封顶(保最新):图谱可重建,来源集只增会让
+ * 长寿命节点(如"用户本人")的来源数组无界增长;封顶后丢的是最老的来源引用,
+ * 状态仍由 active facts 决定,不影响可追溯性主体。
+ */
+export const GRAPH_SOURCE_RECORDS_CAP = 128;

package/dist/graph/search.d.ts

@@ -0,0 +1,16 @@
+import type { GraphEdge, GraphNode, GraphNodeSearchResult } from './types.js';
+/** 字段权重(检索命中计分;名称最高、关系词最低)。 */
+export declare const GRAPH_FIELD_WEIGHTS: {
+    readonly name: 6;
+    readonly aliases: 5;
+    readonly tags: 5;
+    readonly currentState: 4;
+    readonly facts: 4;
+    readonly relations: 3;
+    readonly type: 2;
+};
+/**
+ * 图谱节点检索:返回按 score 降序的命中(最多 limit 条;limit 钳制 1~20)。
+ * 候选节点 = active | disputed(superseded/archived 不进检索)。
+ */
+export declare function searchGraphNodes(nodes: readonly GraphNode[], edges: readonly GraphEdge[], query: string, limit: number): GraphNodeSearchResult[];