@co-engram/core 0.1.0

package/dist/learning/loop.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 闭合学习回路（spec §5.3.5：多巴胺闭环）
+ *
+ * closeLearningLoop：把使用结果（outcome + effectiveness）反馈到系统：
+ *   1. 更新 engram 的 importance / reinforcementScore / failedUses（LTP/LTD）
+ *   2. 触发相关 synapse 的 Hebbian 强化（成功时；失败不反向放大）
+ *   3. 触发 Provenance 奖惩回路更新（P2 3.7 接口预留）
+ *
+ * 业务场景：
+ *   - agent 使用 engram 后，主动上报 outcome（success/failure/partial）
+ *   - 这是"三信号追踪"的天然信号源（retrieved/effective/failed）
+ *
+ * @module @co-engram/core/learning
+ */
+import type { EngramRepository } from "../storage/repository.js";
+import { type ReinforcementConfig } from "../reinforcement/config.js";
+/** 使用结果分类 */
+export type LearningOutcome = "success" | "failure" | "partial";
+export interface CloseLearningLoopInput {
+    readonly engramId: string;
+    readonly outcome: LearningOutcome;
+    /** 有效性 [0,1]（partial 时必填，success 默认 1，failure 默认 0） */
+    readonly effectiveness?: number;
+    /** 失败原因（outcome=failure 时建议填写，供审计） */
+    readonly reason?: string;
+    /** 调用者标识 */
+    readonly reportedBy: string;
+}
+export interface CloseLearningLoopResult {
+    readonly engramId: string;
+    readonly outcome: LearningOutcome;
+    /** LTP/LTD 处理后的 importance */
+    readonly importance: number;
+    readonly importanceDelta: number;
+    readonly reinforcementScore: number;
+    readonly failedUses: number;
+    readonly effectiveRetrievals: number;
+    /** 触发的 Hebbian 邻居强化（仅 success/partial） */
+    readonly hebbianReinforcement: {
+        readonly triggered: boolean;
+        readonly reinforcedNeighborIds: readonly string[];
+        readonly skipped: number;
+    };
+    /** 触发的 Provenance 奖惩（stub，P2 3.7 接入） */
+    readonly provenanceUpdate: {
+        readonly triggered: boolean;
+        readonly message: string;
+    };
+    /** 是否触发自动降级（failedUses 达阈值） */
+    readonly shouldArchive: boolean;
+    readonly shouldForget: boolean;
+    /** 最终时间戳 */
+    readonly reportedAt: string;
+}
+/**
+ * 闭合学习回路
+ *
+ * 行为分支：
+ *   - success (effectiveness 默认 1):
+ *       recordRetrievalSuccess → reinforceRelated → provenanceReward
+ *   - partial (effectiveness 必填，通常 0.3-0.7):
+ *       同 success 但 effectiveness 较低 → 邻居强化按比例衰减
+ *   - failure:
+ *       recordRetrievalFailure → 不触发 reinforceRelated → provenancePenalty
+ *       检查 shouldArchive / shouldForget，但不自动执行（由调用方决定）
+ *
+ * Provenance 奖惩回路（P2 3.7）：
+ *   - 当前为 stub，只返回 triggered 标记
+ *   - 实际接入后：找到 engram.createdBy 对应的 source，更新 source.reliability
+ */
+export declare function closeLearningLoop(repo: EngramRepository, input: CloseLearningLoopInput, options?: {
+    readonly config?: ReinforcementConfig;
+    readonly archiveThreshold?: number;
+    readonly forgetThreshold?: number;
+    readonly nowIso?: string;
+    /** Provenance 回调（P2 3.7 接入时注入） */
+    readonly onProvenanceUpdate?: (engramId: string, outcome: LearningOutcome, effectiveness: number) => void;
+}): CloseLearningLoopResult;
+//# sourceMappingURL=loop.d.ts.map

package/dist/learning/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/learning/loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAQjE,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,4BAA4B,CAAC;AAEpC,aAAa;AACb,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,uDAAuD;IACvD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY;IACZ,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,8BAA8B;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,0CAA0C;IAC1C,QAAQ,CAAC,oBAAoB,EAAE;QAC7B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;QAC5B,QAAQ,CAAC,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;QAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,wCAAwC;IACxC,QAAQ,CAAC,gBAAgB,EAAE;QACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;QAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,+BAA+B;IAC/B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,YAAY;IACZ,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,sBAAsB,EAC7B,OAAO,GAAE;IACP,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,kCAAkC;IAClC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,eAAe,EACxB,aAAa,EAAE,MAAM,KAClB,IAAI,CAAC;CACN,GACL,uBAAuB,CA0GzB"}

package/dist/learning/loop.js

@@ -0,0 +1,116 @@
+/**
+ * 闭合学习回路（spec §5.3.5：多巴胺闭环）
+ *
+ * closeLearningLoop：把使用结果（outcome + effectiveness）反馈到系统：
+ *   1. 更新 engram 的 importance / reinforcementScore / failedUses（LTP/LTD）
+ *   2. 触发相关 synapse 的 Hebbian 强化（成功时；失败不反向放大）
+ *   3. 触发 Provenance 奖惩回路更新（P2 3.7 接口预留）
+ *
+ * 业务场景：
+ *   - agent 使用 engram 后，主动上报 outcome（success/failure/partial）
+ *   - 这是"三信号追踪"的天然信号源（retrieved/effective/failed）
+ *
+ * @module @co-engram/core/learning
+ */
+import { recordRetrievalSuccess } from "../reinforcement/ltp.js";
+import { recordRetrievalFailure, DEFAULT_ARCHIVE_THRESHOLD, DEFAULT_FORGET_THRESHOLD, } from "../reinforcement/ltd.js";
+import { reinforceRelated } from "../reinforcement/related.js";
+import { DEFAULT_CONFIG, } from "../reinforcement/config.js";
+/**
+ * 闭合学习回路
+ *
+ * 行为分支：
+ *   - success (effectiveness 默认 1):
+ *       recordRetrievalSuccess → reinforceRelated → provenanceReward
+ *   - partial (effectiveness 必填，通常 0.3-0.7):
+ *       同 success 但 effectiveness 较低 → 邻居强化按比例衰减
+ *   - failure:
+ *       recordRetrievalFailure → 不触发 reinforceRelated → provenancePenalty
+ *       检查 shouldArchive / shouldForget，但不自动执行（由调用方决定）
+ *
+ * Provenance 奖惩回路（P2 3.7）：
+ *   - 当前为 stub，只返回 triggered 标记
+ *   - 实际接入后：找到 engram.createdBy 对应的 source，更新 source.reliability
+ */
+export function closeLearningLoop(repo, input, options = {}) {
+    if (!repo.exists(input.engramId)) {
+        throw new Error(`Engram not found: ${input.engramId}`);
+    }
+    const config = options.config ?? DEFAULT_CONFIG;
+    const archiveThreshold = options.archiveThreshold ?? DEFAULT_ARCHIVE_THRESHOLD;
+    const forgetThreshold = options.forgetThreshold ?? DEFAULT_FORGET_THRESHOLD;
+    const nowIso = input.reportedBy
+        ? (options.nowIso ?? new Date().toISOString())
+        : (options.nowIso ?? new Date().toISOString());
+    // 根据 outcome 决定 effectiveness
+    let effectiveness;
+    switch (input.outcome) {
+        case "success":
+            effectiveness = input.effectiveness ?? 1;
+            break;
+        case "partial":
+            effectiveness = input.effectiveness ?? 0.5;
+            break;
+        case "failure":
+            effectiveness = 0;
+            break;
+    }
+    if (effectiveness < 0 || effectiveness > 1) {
+        throw new Error(`effectiveness must be in [0,1], got ${effectiveness}`);
+    }
+    let importanceDelta = 0;
+    let shouldArchive = false;
+    let shouldForget = false;
+    let reinforcedNeighborIds = [];
+    let skipped = 0;
+    if (input.outcome === "failure") {
+        // === LTD 路径 ===
+        const ltdResult = recordRetrievalFailure(repo, input.engramId, config, archiveThreshold, forgetThreshold, nowIso);
+        importanceDelta = ltdResult.importanceDelta;
+        shouldArchive = ltdResult.shouldArchive;
+        shouldForget = ltdResult.shouldForget;
+        // 不触发 Hebbian 强化（避免反向放大失败）
+    }
+    else {
+        // === LTP 路径（success / partial）===
+        const ltpResult = recordRetrievalSuccess(repo, input.engramId, effectiveness, config, nowIso);
+        importanceDelta = ltpResult.importanceDelta;
+        // Hebbian 邻居强化（仅当 importanceDelta > 0）
+        if (importanceDelta > 0) {
+            const relatedResult = reinforceRelated(repo, input.engramId, importanceDelta, config, nowIso);
+            reinforcedNeighborIds = relatedResult.reinforcedNeighborIds;
+            skipped = relatedResult.skipped;
+        }
+    }
+    // Provenance 奖惩（P2 3.7 stub）
+    let provenanceTriggered = false;
+    let provenanceMessage = "provenance update not configured";
+    if (options.onProvenanceUpdate) {
+        options.onProvenanceUpdate(input.engramId, input.outcome, effectiveness);
+        provenanceTriggered = true;
+        provenanceMessage = `provenance ${input.outcome} signal delivered`;
+    }
+    const finalEngram = repo.readEngram(input.engramId);
+    return {
+        engramId: input.engramId,
+        outcome: input.outcome,
+        importance: finalEngram.importance,
+        importanceDelta,
+        reinforcementScore: finalEngram.reinforcementScore,
+        failedUses: finalEngram.failedUses,
+        effectiveRetrievals: finalEngram.effectiveRetrievals,
+        hebbianReinforcement: {
+            triggered: reinforcedNeighborIds.length > 0,
+            reinforcedNeighborIds,
+            skipped,
+        },
+        provenanceUpdate: {
+            triggered: provenanceTriggered,
+            message: provenanceMessage,
+        },
+        shouldArchive,
+        shouldForget,
+        reportedAt: nowIso,
+    };
+}
+//# sourceMappingURL=loop.js.map

package/dist/learning/loop.js.map

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

package/dist/lifecycle/freshness.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Freshness 自动计算（P1：记忆生命周期）
+ *
+ * 神经科学依据：艾宾浩斯遗忘曲线 + 多级存储模型
+ *
+ * 计算规则（基于 spec §3.1）：
+ *   - freshness 由 lastEffectiveAt + decayHalfLifeDays 派生（不存储）
+ *   - halfLife 内 → fresh
+ *   - 1×~2×halfLife → aging
+ *   - 2×~4×halfLife → stale
+ *   - 4×+halfLife → forgotten（候选遗忘）
+ *
+ * decayHalfLifeDays = null 表示永不衰退，恒为 fresh
+ *
+ * @module @co-engram/core/lifecycle
+ */
+import type { EngramFreshness } from "../types/engram.js";
+/** 默认半衰期天数（与 EngramRepository 默认值一致） */
+export declare const DEFAULT_HALF_LIFE_DAYS = 90;
+/**
+ * 根据 lastEffectiveAt + decayHalfLifeDays 计算当前 freshness
+ *
+ * @param lastEffectiveAt - 最后一次有效检索时间（ISO），null 表示从未有效
+ * @param decayHalfLifeDays - 半衰期天数，null 表示永不衰退
+ * @param now - 当前时间（可注入用于测试），默认 new Date()
+ */
+export declare function computeFreshness(lastEffectiveAt: string | null | undefined, decayHalfLifeDays: number | null | undefined, now?: Date): EngramFreshness;
+/**
+ * 批量计算 freshness（用于派生索引重建）
+ */
+export declare function computeFreshnessBatch(items: ReadonlyArray<{
+    readonly lastEffectiveAt: string | null | undefined;
+    readonly decayHalfLifeDays: number | null | undefined;
+}>, now?: Date): EngramFreshness[];
+//# sourceMappingURL=freshness.d.ts.map

package/dist/lifecycle/freshness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness.d.ts","sourceRoot":"","sources":["../../src/lifecycle/freshness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,wCAAwC;AACxC,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC1C,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC5C,GAAG,GAAE,IAAiB,GACrB,eAAe,CA6BjB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,aAAa,CAAC;IACnB,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACvD,CAAC,EACF,GAAG,GAAE,IAAiB,GACrB,eAAe,EAAE,CAInB"}

package/dist/lifecycle/freshness.js

@@ -0,0 +1,60 @@
+/**
+ * Freshness 自动计算（P1：记忆生命周期）
+ *
+ * 神经科学依据：艾宾浩斯遗忘曲线 + 多级存储模型
+ *
+ * 计算规则（基于 spec §3.1）：
+ *   - freshness 由 lastEffectiveAt + decayHalfLifeDays 派生（不存储）
+ *   - halfLife 内 → fresh
+ *   - 1×~2×halfLife → aging
+ *   - 2×~4×halfLife → stale
+ *   - 4×+halfLife → forgotten（候选遗忘）
+ *
+ * decayHalfLifeDays = null 表示永不衰退，恒为 fresh
+ *
+ * @module @co-engram/core/lifecycle
+ */
+/** 默认半衰期天数（与 EngramRepository 默认值一致） */
+export const DEFAULT_HALF_LIFE_DAYS = 90;
+/**
+ * 根据 lastEffectiveAt + decayHalfLifeDays 计算当前 freshness
+ *
+ * @param lastEffectiveAt - 最后一次有效检索时间（ISO），null 表示从未有效
+ * @param decayHalfLifeDays - 半衰期天数，null 表示永不衰退
+ * @param now - 当前时间（可注入用于测试），默认 new Date()
+ */
+export function computeFreshness(lastEffectiveAt, decayHalfLifeDays, now = new Date()) {
+    // 永不衰退
+    if (decayHalfLifeDays === null || decayHalfLifeDays === undefined) {
+        return "fresh";
+    }
+    // 从未有效检索 → 视为 fresh（新创建的 engram）
+    if (!lastEffectiveAt) {
+        return "fresh";
+    }
+    const lastEffective = new Date(lastEffectiveAt).getTime();
+    if (Number.isNaN(lastEffective)) {
+        return "fresh";
+    }
+    const ageMs = now.getTime() - lastEffective;
+    if (ageMs < 0) {
+        // 时间倒流（时钟偏差）→ fresh
+        return "fresh";
+    }
+    const ageDays = ageMs / (1000 * 60 * 60 * 24);
+    const halfLife = decayHalfLifeDays;
+    if (ageDays <= halfLife)
+        return "fresh";
+    if (ageDays <= halfLife * 2)
+        return "aging";
+    if (ageDays <= halfLife * 4)
+        return "stale";
+    return "forgotten";
+}
+/**
+ * 批量计算 freshness（用于派生索引重建）
+ */
+export function computeFreshnessBatch(items, now = new Date()) {
+    return items.map((item) => computeFreshness(item.lastEffectiveAt, item.decayHalfLifeDays, now));
+}
+//# sourceMappingURL=freshness.js.map

package/dist/lifecycle/freshness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness.js","sourceRoot":"","sources":["../../src/lifecycle/freshness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,wCAAwC;AACxC,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,eAA0C,EAC1C,iBAA4C,EAC5C,MAAY,IAAI,IAAI,EAAE;IAEtB,OAAO;IACP,IAAI,iBAAiB,KAAK,IAAI,IAAI,iBAAiB,KAAK,SAAS,EAAE,CAAC;QAClE,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,iCAAiC;IACjC,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,IAAI,CAAC,eAAe,CAAC,CAAC,OAAO,EAAE,CAAC;IAC1D,IAAI,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC;QAChC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,aAAa,CAAC;IAC5C,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,oBAAoB;QACpB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,iBAAiB,CAAC;IAEnC,IAAI,OAAO,IAAI,QAAQ;QAAE,OAAO,OAAO,CAAC;IACxC,IAAI,OAAO,IAAI,QAAQ,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IAC5C,IAAI,OAAO,IAAI,QAAQ,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IAC5C,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAGE,EACF,MAAY,IAAI,IAAI,EAAE;IAEtB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CACxB,gBAAgB,CAAC,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,iBAAiB,EAAE,GAAG,CAAC,CACpE,CAAC;AACJ,CAAC"}

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 生命周期 barrel
+ *
+ * @module @co-engram/core/lifecycle
+ */
+export * from "./freshness.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lifecycle/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,gBAAgB,CAAC"}

package/dist/lifecycle/index.js

@@ -0,0 +1,7 @@
+/**
+ * 生命周期 barrel
+ *
+ * @module @co-engram/core/lifecycle
+ */
+export * from "./freshness.js";
+//# sourceMappingURL=index.js.map

package/dist/lifecycle/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lifecycle/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,gBAAgB,CAAC"}

package/dist/lineage/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Lineage 模块 barrel（P3 4.6）
+ *
+ * 进化血统追溯：通过 derives_from / consolidates / supersedes synapse
+ * 反向追溯 engram 的起源和演化路径。
+ *
+ * @module @co-engram/core/lineage
+ */
+export * from "./trace.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lineage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,YAAY,CAAC"}

package/dist/lineage/index.js

@@ -0,0 +1,10 @@
+/**
+ * Lineage 模块 barrel（P3 4.6）
+ *
+ * 进化血统追溯：通过 derives_from / consolidates / supersedes synapse
+ * 反向追溯 engram 的起源和演化路径。
+ *
+ * @module @co-engram/core/lineage
+ */
+export * from "./trace.js";
+//# sourceMappingURL=index.js.map

package/dist/lineage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lineage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,YAAY,CAAC"}

package/dist/lineage/trace.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 进化血统追溯（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
+ */
+import type { EngramRepository } from "../storage/repository.js";
+import type { EngramId, EngramKind } from "../types/engram.js";
+import type { SynapseKind } from "../types/synapse.js";
+/** 血统 synapse kind 集合 */
+export declare const LINEAGE_KINDS: ReadonlySet<SynapseKind>;
+/** 血统关系类型（self 或三种 lineage kind 之一） */
+export type LineageRelation = "self" | "derives_from" | "consolidates" | "supersedes";
+/** 单个血统节点 */
+export interface LineageNode {
+    readonly engramId: EngramId;
+    readonly title: string;
+    readonly kind: EngramKind;
+    /** 距离起点的深度（root=0） */
+    readonly depth: number;
+    /**
+     * 到达此节点的血统关系：
+     *   - 'self'：起点本身
+     *   - 'derives_from' / 'consolidates' / 'supersedes'：经过的 synapse kind
+     */
+    readonly relation: LineageRelation;
+    /** 触达此节点的 synapse ID（self 时为 undefined） */
+    readonly viaSynapseId?: string;
+    /** 创建时间（用于排序） */
+    readonly createdAt: string;
+    /** 创建者 */
+    readonly createdBy: string;
+}
+/** 单条血统边 */
+export interface LineageEdge {
+    readonly from: EngramId;
+    readonly to: EngramId;
+    readonly kind: SynapseKind;
+    readonly synapseId: string;
+    /** 边的方向：root → ancestor（追溯历史）或 descendant → root（演化结果） */
+    readonly direction: "ancestor" | "descendant";
+}
+/** 血统查询方向 */
+export type LineageDirection = "ancestors" | "descendants" | "both";
+/** 完整血统图 */
+export interface EvolutionLineage {
+    /** 起点 engram ID */
+    readonly rootId: EngramId;
+    /** 所有节点（包括 root） */
+    readonly nodes: readonly LineageNode[];
+    /** 所有边 */
+    readonly edges: readonly LineageEdge[];
+    /** 最大深度 */
+    readonly maxDepth: number;
+    /** 节点总数 */
+    readonly totalNodes: number;
+    /**
+     * 起源节点（ancestors 方向的叶子，无更深的 ancestor）
+     * 例：observation 是最原始的来源
+     */
+    readonly origins: readonly EngramId[];
+    /**
+     * 终点节点（descendants 方向的叶子，无更深的 descendant）
+     * 例：procedure / skill 是演化的最终形态
+     */
+    readonly terminals: readonly EngramId[];
+    /** 是否检测到环（边数异常多时） */
+    readonly hasCycle: boolean;
+}
+/** 查询选项 */
+export interface GetLineageOptions {
+    /** 追溯方向（默认 both） */
+    readonly direction?: LineageDirection;
+    /** 最大深度（默认 10） */
+    readonly maxDepth?: number;
+    /** 限制使用的 synapse kind（默认全部三种） */
+    readonly kinds?: readonly SynapseKind[];
+}
+/**
+ * 获取 engram 的完整进化血统
+ *
+ * 算法：双向 BFS
+ *   - ancestors 方向：从 root 出发，沿 outgoing(d|c|s) 找 to（历史来源）
+ *   - descendants 方向：从 root 出发，遍历所有 engram 的 outgoing，找指向 root 的 synapse
+ *
+ * 防环：visited set 跟踪所有访问过的 engramId；同一 engram 可能从多条路径触达，
+ *      但只保留最短路径的 depth。
+ *
+ * @returns EvolutionLineage
+ */
+export declare function getEvolutionLineage(repo: EngramRepository, engramId: EngramId, options?: GetLineageOptions): EvolutionLineage;
+/**
+ * 仅追溯祖先（直接、间接来源）
+ */
+export declare function getAncestors(repo: EngramRepository, engramId: EngramId, options?: Omit<GetLineageOptions, "direction">): EvolutionLineage;
+/**
+ * 仅追溯后代（直接、间接演化结果）
+ */
+export declare function getDescendants(repo: EngramRepository, engramId: EngramId, options?: Omit<GetLineageOptions, "direction">): EvolutionLineage;
+/**
+ * 追溯到原 observation（最深的 ancestor 中 kind=observation 的）
+ *
+ * spec §4.6 验收：从 Skill 反向追溯到原 observation 的完整链路。
+ */
+export declare function traceToOriginObservations(repo: EngramRepository, engramId: EngramId, options?: Omit<GetLineageOptions, "direction">): readonly EngramId[];
+/**
+ * 从 root 到指定 ancestor 的路径（任一最短路径）
+ *
+ * @returns 节点序列；不存在时返回空
+ */
+export declare function findPathToAncestor(repo: EngramRepository, fromId: EngramId, toAncestorId: EngramId, options?: Omit<GetLineageOptions, "direction">): readonly EngramId[];
+/**
+ * 统计：仓库的血统健康度
+ *
+ *   - totalLineageEdges：derives_from + consolidates + supersedes 总边数
+ *   - engramsWithLineage：有血统关系的 engram 数
+ *   - orphanEngrams：无任何血统关系的 engram 数（独立存在的）
+ *   - avgDepth：平均血统深度
+ */
+export interface LineageStats {
+    readonly totalLineageEdges: number;
+    readonly engramsWithLineage: number;
+    readonly orphanEngrams: number;
+    readonly avgDepth: number;
+    readonly maxDepth: number;
+}
+export declare function computeLineageStats(repo: EngramRepository): LineageStats;
+//# sourceMappingURL=trace.d.ts.map

package/dist/lineage/trace.d.ts.map

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