@co-engram/core 0.1.0

package/dist/lineage/trace.js

@@ -0,0 +1,316 @@
+/**
+ * 进化血统追溯（spec §3.4 / §12.7 场景 6，P3 4.6）
+ *
+ * 语义级 commit history：通过 synapse 图谱追溯 engram 的"祖先"和"后代"。
+ *
+ * 支持的血统 synapse kind（spec §12.7）：
+ *   - derives_from：A 从 B 派生（如 hypothesis 从多个 observation 派生）
+ *   - consolidates：A 整合 B（如 pattern 从多个 fact 整合）
+ *   - supersedes：A 取代 B（如新版 procedure 取代旧版）
+ *
+ * 追溯方向：
+ *   - ancestors：当前 engram 的"来源"（沿 outgoing 这些 kind 找 to）
+ *     例如 hypothesis.derives_from → observation
+ *   - descendants：当前 engram 的"演化结果"（沿 incoming 找 from）
+ *     例如 observation 被 hypothesis.derives_from 引用
+ *
+ * 返回 DAG（防止环），按 BFS 保证最短路径。
+ *
+ * @module @co-engram/core/lineage
+ */
+/** 血统 synapse kind 集合 */
+export const LINEAGE_KINDS = new Set([
+    "derives_from",
+    "consolidates",
+    "supersedes",
+]);
+/** 类型守卫：将 SynapseKind 收窄为 LineageRelation */
+function asLineageRelation(kind) {
+    if (kind === "derives_from" ||
+        kind === "consolidates" ||
+        kind === "supersedes") {
+        return kind;
+    }
+    // 理论上不会到这（LINEAGE_KINDS.has 已过滤）
+    return "self";
+}
+const DEFAULT_MAX_DEPTH = 10;
+/**
+ * 获取 engram 的完整进化血统
+ *
+ * 算法：双向 BFS
+ *   - ancestors 方向：从 root 出发，沿 outgoing(d|c|s) 找 to（历史来源）
+ *   - descendants 方向：从 root 出发，遍历所有 engram 的 outgoing，找指向 root 的 synapse
+ *
+ * 防环：visited set 跟踪所有访问过的 engramId；同一 engram 可能从多条路径触达，
+ *      但只保留最短路径的 depth。
+ *
+ * @returns EvolutionLineage
+ */
+export function getEvolutionLineage(repo, engramId, options = {}) {
+    if (!repo.exists(engramId)) {
+        throw new Error(`Engram not found: ${engramId}`);
+    }
+    const direction = options.direction ?? "both";
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const allowedKinds = options.kinds
+        ? new Set(options.kinds)
+        : new Set([...LINEAGE_KINDS]);
+    const rootEngram = repo.readEngram(engramId);
+    // nodes map：engramId → LineageNode（保留最短 depth）
+    const nodesMap = new Map();
+    const edges = [];
+    // 全局 visited（ancestors + descendants 共享）
+    const globalVisited = new Set([engramId]);
+    // root
+    nodesMap.set(engramId, {
+        engramId,
+        title: rootEngram.title,
+        kind: rootEngram.kind,
+        depth: 0,
+        relation: "self",
+        createdAt: rootEngram.createdAt,
+        createdBy: rootEngram.createdBy,
+    });
+    // ============================================================
+    // ancestors 方向：root.outgoing(d|c|s).to
+    // ============================================================
+    if (direction === "ancestors" || direction === "both") {
+        const queue = [
+            { id: engramId, depth: 0 },
+        ];
+        while (queue.length > 0) {
+            const { id, depth } = queue.shift();
+            if (depth >= maxDepth)
+                continue;
+            const file = repo.readSynapses(id);
+            for (const syn of file.outgoing) {
+                if (!allowedKinds.has(syn.kind))
+                    continue;
+                if (!LINEAGE_KINDS.has(syn.kind))
+                    continue;
+                if (!repo.exists(syn.to))
+                    continue;
+                edges.push({
+                    from: id,
+                    to: syn.to,
+                    kind: syn.kind,
+                    synapseId: syn.id,
+                    direction: "ancestor",
+                });
+                if (globalVisited.has(syn.to)) {
+                    continue;
+                }
+                globalVisited.add(syn.to);
+                const ancestorEngram = repo.readEngram(syn.to);
+                nodesMap.set(syn.to, {
+                    engramId: syn.to,
+                    title: ancestorEngram.title,
+                    kind: ancestorEngram.kind,
+                    depth: depth + 1,
+                    relation: asLineageRelation(syn.kind),
+                    viaSynapseId: syn.id,
+                    createdAt: ancestorEngram.createdAt,
+                    createdBy: ancestorEngram.createdBy,
+                });
+                queue.push({ id: syn.to, depth: depth + 1 });
+            }
+        }
+    }
+    // ============================================================
+    // descendants 方向：扫描仓库的 outgoing，找指向当前节点的 synapse
+    // ============================================================
+    if (direction === "descendants" || direction === "both") {
+        const queue = [
+            { id: engramId, depth: 0 },
+        ];
+        const localVisited = new Set([engramId]);
+        while (queue.length > 0) {
+            const { id, depth } = queue.shift();
+            if (depth >= maxDepth)
+                continue;
+            for (const entry of repo.listEngrams()) {
+                if (entry.id === id)
+                    continue;
+                const file = repo.readSynapses(entry.id);
+                for (const syn of file.outgoing) {
+                    if (!allowedKinds.has(syn.kind))
+                        continue;
+                    if (!LINEAGE_KINDS.has(syn.kind))
+                        continue;
+                    if (syn.to !== id)
+                        continue;
+                    edges.push({
+                        from: entry.id,
+                        to: id,
+                        kind: syn.kind,
+                        synapseId: syn.id,
+                        direction: "descendant",
+                    });
+                    if (localVisited.has(entry.id)) {
+                        continue;
+                    }
+                    localVisited.add(entry.id);
+                    globalVisited.add(entry.id);
+                    const descEngram = repo.readEngram(entry.id);
+                    nodesMap.set(entry.id, {
+                        engramId: entry.id,
+                        title: descEngram.title,
+                        kind: descEngram.kind,
+                        depth: depth + 1,
+                        relation: asLineageRelation(syn.kind),
+                        viaSynapseId: syn.id,
+                        createdAt: descEngram.createdAt,
+                        createdBy: descEngram.createdBy,
+                    });
+                    queue.push({ id: entry.id, depth: depth + 1 });
+                }
+            }
+        }
+    }
+    // 简单的环检测：边数 > 节点数 * 2 时疑似有环
+    const hasCycle = edges.length > nodesMap.size * 2;
+    // 收集结果
+    const nodes = [...nodesMap.values()].sort((a, b) => {
+        if (a.depth !== b.depth)
+            return a.depth - b.depth;
+        return a.engramId < b.engramId ? -1 : 1;
+    });
+    const maxDepthFound = nodes.reduce((m, n) => Math.max(m, n.depth), 0);
+    // origins：ancestors 方向的叶子节点（深度 > 0 + 没有更深的 ancestor 出边）
+    const ancestorEdgeTargets = new Set(edges.filter((e) => e.direction === "ancestor").map((e) => e.to));
+    const ancestorEdgeSources = new Set(edges.filter((e) => e.direction === "ancestor").map((e) => e.from));
+    const origins = [...ancestorEdgeTargets].filter((id) => !ancestorEdgeSources.has(id));
+    // terminals：descendants 方向的叶子节点（作为 descendant 但没有更深的 descendant）
+    const descendantEdgeSources = new Set(edges.filter((e) => e.direction === "descendant").map((e) => e.from));
+    const descendantEdgeTargets = new Set(edges.filter((e) => e.direction === "descendant").map((e) => e.to));
+    const terminals = [...descendantEdgeSources].filter((id) => !descendantEdgeTargets.has(id));
+    return {
+        rootId: engramId,
+        nodes,
+        edges,
+        maxDepth: maxDepthFound,
+        totalNodes: nodes.length,
+        origins,
+        terminals,
+        hasCycle,
+    };
+}
+// ============================================================
+// 便捷函数
+// ============================================================
+/**
+ * 仅追溯祖先（直接、间接来源）
+ */
+export function getAncestors(repo, engramId, options = {}) {
+    return getEvolutionLineage(repo, engramId, {
+        ...options,
+        direction: "ancestors",
+    });
+}
+/**
+ * 仅追溯后代（直接、间接演化结果）
+ */
+export function getDescendants(repo, engramId, options = {}) {
+    return getEvolutionLineage(repo, engramId, {
+        ...options,
+        direction: "descendants",
+    });
+}
+/**
+ * 追溯到原 observation（最深的 ancestor 中 kind=observation 的）
+ *
+ * spec §4.6 验收：从 Skill 反向追溯到原 observation 的完整链路。
+ */
+export function traceToOriginObservations(repo, engramId, options = {}) {
+    const lineage = getEvolutionLineage(repo, engramId, {
+        ...options,
+        direction: "ancestors",
+    });
+    // 在 origins 中找 kind=observation
+    const result = [];
+    for (const originId of lineage.origins) {
+        const node = lineage.nodes.find((n) => n.engramId === originId);
+        if (node && node.kind === "observation") {
+            result.push(originId);
+        }
+    }
+    return result;
+}
+/**
+ * 从 root 到指定 ancestor 的路径（任一最短路径）
+ *
+ * @returns 节点序列；不存在时返回空
+ */
+export function findPathToAncestor(repo, fromId, toAncestorId, options = {}) {
+    const lineage = getEvolutionLineage(repo, fromId, {
+        ...options,
+        direction: "ancestors",
+    });
+    if (!lineage.nodes.some((n) => n.engramId === toAncestorId)) {
+        return [];
+    }
+    // 反向追溯：从 ancestor 回到 root
+    // ancestor 方向边：from=root-side, to=ancestor-side
+    // 所以 to 的 parent 是 from
+    const parentMap = new Map();
+    for (const edge of lineage.edges) {
+        if (edge.direction !== "ancestor")
+            continue;
+        if (!parentMap.has(edge.to)) {
+            parentMap.set(edge.to, edge.from);
+        }
+    }
+    const path = [toAncestorId];
+    let current = toAncestorId;
+    // 防止死循环
+    for (let i = 0; i < lineage.nodes.length + 1; i++) {
+        if (current === fromId)
+            break;
+        const parent = parentMap.get(current);
+        if (!parent)
+            break;
+        path.unshift(parent);
+        current = parent;
+    }
+    return current === fromId ? path : [];
+}
+export function computeLineageStats(repo) {
+    let totalEdges = 0;
+    const engramsWithLineage = new Set();
+    const allEngrams = repo.listEngrams();
+    for (const entry of allEngrams) {
+        const file = repo.readSynapses(entry.id);
+        for (const syn of file.outgoing) {
+            if (!LINEAGE_KINDS.has(syn.kind))
+                continue;
+            if (!repo.exists(syn.to))
+                continue;
+            totalEdges += 1;
+            engramsWithLineage.add(entry.id);
+            engramsWithLineage.add(syn.to);
+        }
+    }
+    let maxDepth = 0;
+    let depthSum = 0;
+    let counted = 0;
+    for (const entry of engramsWithLineage) {
+        const lineage = getEvolutionLineage(repo, entry, {
+            direction: "both",
+            maxDepth: 5,
+        });
+        if (lineage.maxDepth > maxDepth)
+            maxDepth = lineage.maxDepth;
+        depthSum += lineage.maxDepth;
+        counted += 1;
+    }
+    const avgDepth = counted > 0 ? depthSum / counted : 0;
+    return {
+        totalLineageEdges: totalEdges,
+        engramsWithLineage: engramsWithLineage.size,
+        orphanEngrams: allEngrams.length - engramsWithLineage.size,
+        avgDepth,
+        maxDepth,
+    };
+}
+//# sourceMappingURL=trace.js.map

package/dist/lineage/trace.js.map

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

package/dist/maintenance/engine.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Maintenance Engine（P4 B.2 + C.2 + D.1）
+ *
+ * 自动维护服务的核心调度器。三阶段：
+ *
+ *   - light（秒/分钟级）:drain signals → extractSignals → applyRpeUpdate
+ *   - deep （小时级）   :复用现有 runDeepDreaming
+ *   - rem  （天级）     :runRemDreaming + metacognition（P4 C.2 实现）
+ *
+ * 调度策略：
+ *   start() 内部 setInterval + unref(),不依赖宿主 /loop 或 cron。
+ *   进程退出时定时器自动清理。
+ *
+ * 错误隔离：单个阶段失败不阻塞其他阶段；失败信息记入 MaintenanceReport.errors。
+ *
+ * @module @co-engram/core/maintenance
+ */
+import type { MaintenanceConfig, MaintenanceDeps, MaintenanceReport } from "./types.js";
+/**
+ * Maintenance Engine
+ *
+ * 使用：
+ *   const engine = new MaintenanceEngine(deps, config)
+ *   engine.start()
+ *   // ... 应用运行期间自动维护
+ *   engine.stop()
+ *
+ * 或单次手动触发：
+ *   await engine.runLight()
+ */
+export declare class MaintenanceEngine {
+    private readonly deps;
+    private readonly resolvedConfig;
+    private lightTimer;
+    private deepTimer;
+    private remTimer;
+    private running;
+    constructor(deps: MaintenanceDeps, config?: MaintenanceConfig);
+    /** 暴露配置（测试/审计用） */
+    getConfig(): Readonly<Required<MaintenanceConfig>>;
+    /**
+     * Light 阶段：drain signals → extractSignals → applyRpeUpdate → sweepExpired
+     *
+     * 高频运行（默认 5 分钟）,负责把累积的行为信号转成 engram 的强化/衰减。
+     * 无论 events 是否为空,都会执行 prune（控制 signals.jsonl 体积）。
+     * 如果注入了 effectivenessTracker,会扫描超时观察窗口（写 retrieve_inconclusive）。
+     */
+    runLight(): Promise<MaintenanceReport>;
+    /**
+     * Deep 阶段：复用现有 runDeepDreaming
+     *
+     * 中频（默认 1 小时）,负责 decay + abstraction。
+     * 提交 9 实现（占位：抛错,提示 deps 缺 dreamingScheduler）。
+     */
+    runDeep(): Promise<MaintenanceReport>;
+    /**
+     * REM 阶段：runRemDreaming + metacognition
+     *
+     * 低频（默认 7 天）,负责 abstraction + verification 升降级。
+     *
+     * 1. 触发 dreamingScheduler.trigger('rem')（聚类 + 抽象）
+     * 2. 遍历所有未 refute 的 engram,调 applyMetacognition
+     *    - 元认知评分决定 verificationStatus 升级 / refute
+     */
+    runRem(): Promise<MaintenanceReport>;
+    /**
+     * 启动所有已启用阶段的定时调度
+     *
+     * 定时器都调 .unref(),进程退出时自动清理。
+     */
+    start(): void;
+    /** 停止所有定时调度 */
+    stop(): void;
+    /** 是否正在运行 */
+    isRunning(): boolean;
+    private runStage;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/maintenance/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/maintenance/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EAEf,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAqBpB;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA8B;IAC7D,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,EAAE,eAAe,EAAE,MAAM,GAAE,iBAAsB;IAgBjE,mBAAmB;IACnB,SAAS,IAAI,QAAQ,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IAIlD;;;;;;OAMG;IACG,QAAQ,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAsF5C;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAc3C;;;;;;;;OAQG;IACG,MAAM,IAAI,OAAO,CAAC,iBAAiB,CAAC;IA2C1C;;;;OAIG;IACH,KAAK,IAAI,IAAI;IA2Bb,eAAe;IACf,IAAI,IAAI,IAAI;IAiBZ,aAAa;IACb,SAAS,IAAI,OAAO;YAQN,QAAQ;CAqCvB"}