@co-engram/core 0.1.0

package/dist/generative/hypothesis.js

@@ -0,0 +1,356 @@
+/**
+ * 生成式巩固（spec §5.3 机制 1，P3 4.1）
+ *
+ * 从一组相关 engram（同 topic / domain）通过 Provider 接口生成可验证 hypothesis。
+ *
+ * 流程：
+ *   1. 召集相关 engram（按 domainTags / contextTags 过滤；observation + fact 优先）
+ *   2. Provider.generate 生成候选假设（标题/正文/置信度/理由）
+ *   3. 自动采纳：confidence ≥ autoAdoptionThreshold → 创建 hypothesis engram
+ *      + derives_from synapse 连接每个 source
+ *   4. 验证流程：verifyHypothesis 把 verificationStatus 升级为
+ *      plausible / verified / refuted
+ *
+ * 与 REM 做梦（spec §3.2）的区别：
+ *   - REM 是被动 sleep-time consolidation，从相似 cluster 抽象出 pattern
+ *   - hypothesis 是主动 wake-time 推理，生成可证伪假设并保留多视角
+ *
+ * core 层不绑定 LLM；HypothesisProvider 由宿主注入。
+ *
+ * @module @co-engram/core/generative
+ */
+import { randomUUID } from "node:crypto";
+/** 默认配置 */
+const DEFAULT_MIN_SOURCES = 3;
+const DEFAULT_MAX_SOURCES = 10;
+const DEFAULT_ADOPTION_THRESHOLD = 0.6;
+/**
+ * 默认启发式假设生成器（无 LLM）
+ *
+ * 算法：
+ *   1. 收集所有 source 的 tokens（title + summary + content）
+ *   2. 找出 ≥ 半数 source 共现的关键词
+ *   3. title = "Hypothesis: 在 {topic} 中，{top1} 与 {top2} 相关"
+ *   4. confidence = 共现 token 数 / topTokens 期望
+ */
+export class LocalHeuristicHypothesisProvider {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    generate(input) {
+        const topTokens = this.options.topTokens ?? 5;
+        const minConfidence = this.options.minConfidence ?? 0.3;
+        if (input.engrams.length === 0) {
+            return {
+                title: `Hypothesis: <empty> (${input.topic})`,
+                content: "",
+                summary: "空候选",
+                confidence: 0,
+                reason: "no source engrams provided",
+            };
+        }
+        const tokenFreq = new Map();
+        for (const e of input.engrams) {
+            const tokens = extractTokens(`${e.title} ${e.summary} ${e.content}`);
+            const unique = new Set(tokens);
+            for (const t of unique) {
+                tokenFreq.set(t, (tokenFreq.get(t) ?? 0) + 1);
+            }
+        }
+        // 共现 = 至少出现在 2 个 source 中（或半数以上，取大者）
+        const threshold = Math.max(2, Math.ceil(input.engrams.length / 2));
+        const common = [...tokenFreq.entries()]
+            .filter(([, c]) => c >= threshold)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, topTokens)
+            .map(([t]) => t);
+        if (common.length === 0) {
+            return {
+                title: `Hypothesis: ${input.topic} 存在未被抽象的共同点`,
+                content: "候选 source 共现关键词不足，无法形成可验证假设",
+                summary: "低相似度候选",
+                confidence: minConfidence,
+                reason: "no common tokens above threshold",
+            };
+        }
+        const title = `Hypothesis: 在 ${input.topic} 中，${common.slice(0, 3).join(" / ")} 存在共现规律`;
+        const content = [
+            `# ${title}`,
+            "",
+            `**候选 source**：${input.engrams.length} 个 engram`,
+            "",
+            "**共现关键词**：",
+            ...common.map((t) => `- ${t}`),
+            "",
+            "**候选来源**：",
+            ...input.engrams.map((e) => `- [${e.id}] ${e.title}`),
+            "",
+            "---",
+            "",
+            "**验证建议**：",
+            `- 收集更多 ${common[0]} 相关 observation`,
+            "- 寻找反例（contradicts）",
+            `- 跨情境验证（不同 ${input.engrams[0].domainTags.join(",")} 域）`,
+        ].join("\n");
+        // confidence = 每个 common token 覆盖率的平均值（[0,1]）
+        //   覆盖率 = 出现该 token 的 source 数 / 总 source 数
+        // 例如 5 source 中 adb 全覆盖（1.0）、wireless 出现 3 次（0.6）
+        //   → avg = 0.8
+        const coverage = common.map((t) => tokenFreq.get(t) / input.engrams.length);
+        const confidence = coverage.reduce((a, b) => a + b, 0) / coverage.length;
+        return {
+            title,
+            content,
+            summary: `${common.length} 个共现关键词`,
+            confidence,
+            reason: `${common.length} common tokens across ${input.engrams.length} sources`,
+        };
+    }
+}
+/**
+ * 生成假设（主入口）
+ *
+ * 行为：
+ *   - 召集 source：按 domainTags/contextTags 过滤，observation/fact 优先
+ *   - source 数量 < minSources → 不生成（返回空 hypotheses）
+ *   - 调 Provider.generate → proposal
+ *   - confidence ≥ autoAdoptionThreshold → 创建 hypothesis engram + derives_from synapse
+ *
+ * @returns GenerateHypothesesResult
+ */
+export async function generateHypotheses(repo, provider, input) {
+    const startMs = Date.now();
+    const minSources = input.minSources ?? DEFAULT_MIN_SOURCES;
+    const maxSources = input.maxSources ?? DEFAULT_MAX_SOURCES;
+    const autoAdoptionThreshold = input.autoAdoptionThreshold ?? DEFAULT_ADOPTION_THRESHOLD;
+    const persist = input.persist ?? true;
+    const dryRun = input.dryRun ?? false;
+    const nowIso = input.nowIso ?? new Date().toISOString();
+    // 召集候选 source
+    const candidates = collectSources(repo, {
+        domainTags: input.domainTags,
+        contextTags: input.contextTags,
+        minSources,
+        maxSources,
+    });
+    if (candidates.length < minSources) {
+        return {
+            topic: input.topic,
+            candidateCount: candidates.length,
+            hypotheses: [],
+            durationMs: Date.now() - startMs,
+            persisted: false,
+        };
+    }
+    // Provider 生成
+    const providerInput = {
+        topic: input.topic,
+        engrams: candidates.map((e) => ({
+            id: e.id,
+            title: e.title,
+            content: e.content,
+            summary: e.summary,
+            domainTags: e.domainTags,
+            kind: e.kind,
+        })),
+    };
+    const output = await provider.generate(providerInput);
+    const proposal = {
+        ...output,
+        sourceIds: candidates.map((e) => e.id),
+    };
+    const adopted = !dryRun && output.confidence >= autoAdoptionThreshold;
+    let engramId = null;
+    let reason;
+    if (dryRun) {
+        reason = `dryRun; confidence=${output.confidence.toFixed(2)}`;
+    }
+    else if (!adopted) {
+        reason = `confidence ${output.confidence.toFixed(2)} < threshold ${autoAdoptionThreshold}`;
+    }
+    else {
+        // 自动采纳：创建 hypothesis engram
+        const domainTags = input.domainTags
+            ? [...input.domainTags]
+            : [...new Set(candidates.flatMap((e) => [...e.domainTags]))].sort();
+        const newEngram = repo.createEngram({
+            title: proposal.title,
+            content: proposal.content,
+            summary: proposal.summary,
+            kind: "hypothesis",
+            domainTags,
+            importance: 0.6,
+            confidence: proposal.confidence,
+            sourceType: "inferred",
+            createdBy: input.createdBy,
+        });
+        engramId = newEngram.id;
+        // 验证状态初始为 unverified
+        repo.updateVerificationStatus(newEngram.id, "unverified");
+        // derives_from 每个 source
+        for (const sourceId of proposal.sourceIds) {
+            const synapse = {
+                id: `hyp-${randomUUID().slice(0, 12)}`,
+                from: newEngram.id,
+                to: sourceId,
+                kind: "derives_from",
+                weight: 0.7,
+                direction: "directional",
+                evidence: [
+                    {
+                        description: `hypothesis generated from ${proposal.sourceIds.length} sources (confidence=${proposal.confidence.toFixed(2)})`,
+                        addedAt: nowIso,
+                        addedBy: input.createdBy,
+                        confidence: proposal.confidence,
+                    },
+                ],
+                createdBy: input.createdBy,
+                createdAt: nowIso,
+                updatedAt: nowIso,
+                retrievalWeight: 0.7,
+            };
+            repo.addOutgoingSynapse(newEngram.id, synapse);
+        }
+        persist; // no-op（保留语义）
+        reason = `adopted; confidence=${output.confidence.toFixed(2)}`;
+    }
+    return {
+        topic: input.topic,
+        candidateCount: candidates.length,
+        hypotheses: [
+            {
+                engramId,
+                proposal,
+                adopted,
+                reason,
+            },
+        ],
+        durationMs: Date.now() - startMs,
+        persisted: persist && !dryRun,
+    };
+}
+/**
+ * 验证假设（升级或反驳）
+ *
+ * verdict 对应 verificationStatus：
+ *   - plausible → plausible
+ *   - verified  → verified
+ *   - refuted   → refuted
+ *
+ * 行为：
+ *   1. 把 engram.verificationStatus 设为 newStatus
+ *   2. 追加 evidence 到所有 derives_from synapse（如果有）
+ *
+ * 注意：本函数只更新 engram 自身；如需对 source 触发 reliability
+ * 更新，由上层调用 provenance.applyProvenanceSignal。
+ */
+export function verifyHypothesis(repo, engramId, verdict, evidence, options = {}) {
+    if (!repo.exists(engramId)) {
+        throw new Error(`Engram not found: ${engramId}`);
+    }
+    const nowIso = options.nowIso ?? new Date().toISOString();
+    const engram = repo.readEngram(engramId);
+    if (engram.kind !== "hypothesis") {
+        throw new Error(`Engram ${engramId} is not a hypothesis (kind=${engram.kind})`);
+    }
+    const statusMap = {
+        plausible: "plausible",
+        verified: "verified",
+        refuted: "refuted",
+    };
+    const newStatus = statusMap[verdict];
+    const previousStatus = engram.verificationStatus;
+    repo.updateVerificationStatus(engramId, newStatus);
+    // 追加 evidence 到 derives_from synapse
+    const synapseFile = repo.readSynapses(engramId);
+    const derivesSynapse = synapseFile.outgoing.find((s) => s.kind === "derives_from");
+    let evidenceAppended = false;
+    let synapseId;
+    if (derivesSynapse) {
+        const newEvidence = [
+            ...derivesSynapse.evidence,
+            {
+                description: `[${verdict}] ${evidence.description}`,
+                addedAt: nowIso,
+                addedBy: evidence.verifiedBy,
+                confidence: evidence.confidence,
+            },
+        ];
+        repo.replaceSynapseEvidence(engramId, derivesSynapse.id, newEvidence);
+        evidenceAppended = true;
+        synapseId = derivesSynapse.id;
+    }
+    return {
+        engramId,
+        previousStatus,
+        newStatus,
+        evidenceAppended,
+        synapseId,
+    };
+}
+// ============================================================
+// 辅助函数
+// ============================================================
+/**
+ * 召集 source engram：按 domainTags/contextTags 过滤
+ *
+ * 优先级：observation > fact > pattern > procedure（不召回其他 hypothesis）
+ */
+function collectSources(repo, options) {
+    const kindPriority = {
+        observation: 0,
+        fact: 1,
+        pattern: 2,
+        procedure: 3,
+        hypothesis: 4, // 不召回其他 hypothesis
+    };
+    const all = repo.listEngrams();
+    const candidates = [];
+    for (const entry of all) {
+        const engram = repo.readEngram(entry.id);
+        if (engram.status !== "active")
+            continue;
+        if (engram.kind === "hypothesis")
+            continue;
+        // domainTags 过滤
+        if (options.domainTags && options.domainTags.length > 0) {
+            const hasOverlap = options.domainTags.some((t) => engram.domainTags.includes(t));
+            if (!hasOverlap)
+                continue;
+        }
+        // contextTags 过滤
+        if (options.contextTags && options.contextTags.length > 0) {
+            const hasOverlap = options.contextTags.some((t) => engram.contextTags.includes(t));
+            if (!hasOverlap)
+                continue;
+        }
+        candidates.push(engram);
+    }
+    // 排序：kind 优先级 + id 字典序（稳定）
+    candidates.sort((a, b) => {
+        const pa = kindPriority[a.kind];
+        const pb = kindPriority[b.kind];
+        if (pa !== pb)
+            return pa - pb;
+        return a.id < b.id ? -1 : 1;
+    });
+    return candidates.slice(0, options.maxSources);
+}
+/** 简易 token 提取（与 dedup / triggered 一致：英文 word + 中文 bigram） */
+function extractTokens(content) {
+    const trimmed = content.trim();
+    if (!trimmed)
+        return [];
+    const tokens = [];
+    const enWords = trimmed.match(/[A-Za-z][A-Za-z0-9_-]{1,}/g) ?? [];
+    tokens.push(...enWords.map((w) => w.toLowerCase()));
+    const cn = trimmed.match(/[一-鿿]+/g) ?? [];
+    for (const seg of cn) {
+        for (let i = 0; i < seg.length - 1; i++) {
+            tokens.push(seg.slice(i, i + 2));
+        }
+    }
+    return tokens;
+}
+//# sourceMappingURL=hypothesis.js.map

package/dist/generative/hypothesis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hypothesis.js","sourceRoot":"","sources":["../../src/generative/hypothesis.ts"],"names":[],"mappings":"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"}

package/dist/generative/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generative 模块 barrel（P3 4.1-4.3）
+ *
+ * @module @co-engram/core/generative
+ */
+export * from "./hypothesis.js";
+export * from "./gap-detector.js";
+export * from "./cross-pollinate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/generative/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generative/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}

package/dist/generative/index.js

@@ -0,0 +1,9 @@
+/**
+ * Generative 模块 barrel（P3 4.1-4.3）
+ *
+ * @module @co-engram/core/generative
+ */
+export * from "./hypothesis.js";
+export * from "./gap-detector.js";
+export * from "./cross-pollinate.js";
+//# sourceMappingURL=index.js.map

package/dist/generative/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/generative/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}

package/dist/graph/clustering.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Graph View 自动聚类（spec §12.8，P3 4.7.3）
+ *
+ * 当节点数超过阈值（默认 5000）时，按 domain 自动折叠为超节点（super-node）。
+ * 用户点击 super-node 时再展开子图。
+ *
+ * 聚类策略：
+ *   - 主聚类维度：domainTags[0]（与 domain-cluster 布局一致）
+ *   - 二级聚类：kind（同 domain 内按 kind 分子簇）
+ *   - 边聚合：跨簇的边被合并为簇间边（带 weight sum）
+ *
+ * 输出：ClusteredGraph（superNodes + superEdges）
+ *
+ * @module @co-engram/core/graph
+ */
+import type { GraphSnapshot, SnapshotNode, SnapshotEdge } from "./snapshot.js";
+/** 节点数阈值（spec §12.8：> 5000 节点时启用聚类） */
+export declare const DEFAULT_CLUSTER_THRESHOLD = 5000;
+/** 每个超节点最少包含的原始节点数（少于则不合并） */
+export declare const DEFAULT_MIN_CLUSTER_SIZE = 5;
+/** 超节点（聚类后的虚拟节点） */
+export interface SuperNode {
+    /** Cluster ID：`cluster:<domain>:<kind>` 或 `cluster:<domain>` */
+    readonly id: string;
+    /** 显示标签 */
+    readonly label: string;
+    /** 主 domain */
+    readonly domain: string;
+    /** 主 kind（如果按 kind 二级聚类） */
+    readonly kind?: string;
+    /** 包含的原始节点 ID 列表 */
+    readonly memberIds: readonly string[];
+    /** 成员数 */
+    readonly memberCount: number;
+    /** 派生：平均 importance */
+    readonly avgImportance: number;
+    /** 派生：平均 retrievalCount */
+    readonly totalRetrievalCount: number;
+    /** 派生：总 effectiveRetrievals */
+    readonly totalEffectiveRetrievals: number;
+    /** 派生：是否 hub 簇（memberCount ≥ hubClusterSize） */
+    readonly isHubCluster: boolean;
+}
+/** 超边（聚类后的虚拟边） */
+export interface SuperEdge {
+    readonly id: string;
+    readonly from: string;
+    readonly to: string;
+    /** 聚合的原始边数 */
+    readonly aggregatedCount: number;
+    /** 总 weight（求和） */
+    readonly totalWeight: number;
+    /** 主导 kind（出现频率最高的） */
+    readonly dominantKind: string;
+    /** 是否含 contradicts（至少一条原始边是 contradicts） */
+    readonly hasContradiction: boolean;
+}
+/** 聚类后的图 */
+export interface ClusteredGraph {
+    readonly superNodes: readonly SuperNode[];
+    readonly superEdges: readonly SuperEdge[];
+    /** 未被聚类的独立节点（memberCount < minClusterSize） */
+    readonly standaloneNodes: readonly SnapshotNode[];
+    /** 未被聚类的独立边 */
+    readonly standaloneEdges: readonly SnapshotEdge[];
+    readonly stats: ClusterStats;
+}
+export interface ClusterStats {
+    readonly totalSuperNodes: number;
+    readonly totalSuperEdges: number;
+    readonly totalStandaloneNodes: number;
+    /** 聚类压缩比 = superNodes / originalNodes */
+    readonly compressionRatio: number;
+    /** 最大簇大小 */
+    readonly maxClusterSize: number;
+    readonly avgClusterSize: number;
+}
+export interface ClusterOptions {
+    /** 启用阈值：节点数 > threshold 才聚类（默认 5000） */
+    readonly threshold?: number;
+    /** 最小簇大小（小于则作为 standalone 保留） */
+    readonly minClusterSize?: number;
+    /** hub 簇阈值（memberCount ≥ 此值视为 hub） */
+    readonly hubClusterSize?: number;
+    /** 二级聚类：同 domain 内按 kind 分子簇（默认 true） */
+    readonly secondaryByKind?: boolean;
+}
+export declare const DEFAULT_HUB_CLUSTER_SIZE = 50;
+/**
+ * 主聚类函数
+ *
+ * 行为：
+ *   1. 节点数 ≤ threshold → 直接返回（不聚类）
+ *   2. 按 domain 分组（domainTags[0]）
+ *   3. 可选：同 domain 内按 kind 二级分组
+ *   4. 每个 size ≥ minClusterSize 的组成为一个 SuperNode
+ *   5. 边聚合：跨 super-node 的边合并
+ *
+ * @returns ClusteredGraph
+ */
+export declare function clusterSnapshot(snapshot: GraphSnapshot, options?: ClusterOptions): ClusteredGraph;
+/**
+ * 展开一个 super-node：返回其成员节点的子图
+ *
+ * 用于"点击 super-node 展开子图"场景（spec §12.8）。
+ */
+export declare function expandSuperNode(snapshot: GraphSnapshot, superNode: SuperNode): {
+    readonly nodes: readonly SnapshotNode[];
+    readonly edges: readonly SnapshotEdge[];
+};
+/**
+ * 判断是否需要聚类
+ *
+ * 工具函数：UI 层可以根据节点数决定是否切换到聚类模式。
+ */
+export declare function shouldCluster(nodeCount: number, threshold?: number): boolean;
+//# sourceMappingURL=clustering.d.ts.map

package/dist/graph/clustering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clustering.d.ts","sourceRoot":"","sources":["../../src/graph/clustering.ts"],"names":[],"mappings":"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"}