@co-engram/core 0.1.0

package/dist/signals/file-sink.js

@@ -0,0 +1,227 @@
+/**
+ * 默认信号收集器实现
+ *
+ * - FileSignalSink：JSONL 文件持久化（生产用，路径默认 <dataRoot>/.co-engram/signals.jsonl）
+ * - MemorySignalSink：内存数组（测试用，断言方便）
+ *
+ * 设计：
+ *   - append 只追加一行 JSON，不做 fsync（性能优先）
+ *   - drain 读取整个文件 + 截断（O(n)）
+ *   - prune 读取 + 过滤 + 重写（O(n)）
+ *
+ * 并发：单进程内 by-design 安全；多进程并发需要文件锁，留作 TODO（MVP 单进程场景够用）。
+ *
+ * @module @co-engram/core/signals
+ */
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+/**
+ * 进程级 exit handler 注册表(单例)
+ *
+ * 每个 FileSignalSink 实例都需要在进程退出前 flush 一次,但若每个实例都调
+ * process.once('beforeExit' / 'exit'),创建 N 个 sink 就会注册 2N 个 listener,
+ * 超过 Node 默认的 maxListeners=10 → 触发 MaxListenersExceededWarning。
+ *
+ * 测试场景会频繁创建 sink(每个用例一个),生产场景通常只 1 个,所以警告主要
+ * 污染测试日志。但监听器膨胀本身就是泄漏 + 让人误以为有真问题。
+ *
+ * 解决:模块级单 Set 跟踪所有 active sinks,只注册一次 exit handler,handler
+ * 内部遍历所有 sinks 调 flushSync。WeakSet 自动 GC 回收后的 sink 不会泄漏。
+ */
+const activeSinks = new Set();
+let exitHandlerRegistered = false;
+function registerGlobalExitHandlerOnce() {
+    if (exitHandlerRegistered)
+        return;
+    exitHandlerRegistered = true;
+    const handler = () => {
+        for (const sink of activeSinks) {
+            try {
+                sink.flushSync();
+            }
+            catch {
+                // ignore — best effort on exit
+            }
+        }
+    };
+    process.once("beforeExit", handler);
+    process.once("exit", handler);
+}
+/**
+ * JSONL 文件信号收集器
+ *
+ * 文件格式：每行一个 JSON object,字段对应 ToolCallEvent。
+ * drain() 会读取全部并截断文件；prune() 会保留最近 N ms 的事件。
+ */
+export class FileSignalSink {
+    filePath;
+    buffer = [];
+    flushTimer = null;
+    flushIntervalMs;
+    flushThreshold;
+    constructor(options) {
+        this.filePath = options.filePath;
+        this.flushIntervalMs = options.flushIntervalMs ?? 5_000;
+        this.flushThreshold = options.flushThreshold ?? 50;
+        // 注册到全局 exit handler(只真正注册一次 process listener)
+        activeSinks.add(this);
+        registerGlobalExitHandlerOnce();
+    }
+    append(event) {
+        this.buffer.push(event);
+        if (this.buffer.length >= this.flushThreshold) {
+            void this.flush();
+        }
+        else if (this.flushTimer === null) {
+            this.flushTimer = setInterval(() => {
+                void this.flush();
+            }, this.flushIntervalMs);
+            this.flushTimer.unref?.();
+        }
+    }
+    drain() {
+        // 同步 flush 缓冲，再读取整个文件
+        this.flushSync();
+        if (!existsSync(this.filePath))
+            return [];
+        const raw = readFileSync(this.filePath, "utf8").trim();
+        if (raw === "")
+            return [];
+        const events = [];
+        for (const line of raw.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                events.push(JSON.parse(trimmed));
+            }
+            catch {
+                // 跳过损坏行（部分写入）
+            }
+        }
+        // 清空文件
+        writeFileSync(this.filePath, "", "utf8");
+        return events;
+    }
+    async prune(olderThanMs) {
+        const cutoff = Date.now() - olderThanMs;
+        const events = this.drain();
+        const kept = events.filter((e) => e.at >= cutoff);
+        if (kept.length === 0) {
+            if (existsSync(this.filePath))
+                writeFileSync(this.filePath, "", "utf8");
+            return;
+        }
+        const lines = kept.map((e) => JSON.stringify(e)).join("\n");
+        writeFileSync(this.filePath, lines + "\n", "utf8");
+    }
+    /** 显式 flush（测试或进程退出时调） */
+    async flush() {
+        this.flushSync();
+    }
+    /**
+     * 主动从 exit handler 注销(测试结束后清理)
+     *
+     * 不强制要求调用,但测试中创建大量 sink 时调用可避免 Set 无限增长
+     * (生产中只有 1 个 sink,生命周期 = 进程生命周期,无所谓)。
+     */
+    dispose() {
+        activeSinks.delete(this);
+    }
+    flushSync() {
+        if (this.buffer.length === 0)
+            return;
+        if (this.flushTimer !== null) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        const pending = this.buffer.splice(0, this.buffer.length);
+        const lines = pending.map((e) => JSON.stringify(e)).join("\n") + "\n";
+        // 追加模式打开，避免覆盖已有数据
+        const fd = openSync(this.filePath, "a");
+        try {
+            writeFileSync(fd, lines, "utf8");
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+}
+/**
+ * 内存信号收集器（测试用）
+ *
+ * drain() 返回当前缓冲并清空，但不涉及文件 IO。
+ */
+export class MemorySignalSink {
+    events = [];
+    append(event) {
+        this.events.push(event);
+    }
+    drain() {
+        const drained = [...this.events];
+        this.events.length = 0;
+        return drained;
+    }
+    async prune(olderThanMs) {
+        const cutoff = Date.now() - olderThanMs;
+        const kept = this.events.filter((e) => e.at >= cutoff);
+        this.events.length = 0;
+        this.events.push(...kept);
+    }
+    /** 当前缓冲长度（不断言 drain 后的状态） */
+    get size() {
+        return this.events.length;
+    }
+    /** 查看当前缓冲（不消费） */
+    peek() {
+        return [...this.events];
+    }
+}
+/**
+ * 创建默认的 FileSignalSink（便捷工厂）
+ *
+ * 文件位置:`<dataRoot>/.co-engram/signals.jsonl`,与 audit.jsonl /
+ * proposals.jsonl / topic-clusters.jsonl / prompt-signals.json 等其它
+ * 状态文件保持一致。
+ *
+ * 历史遗留:0.x 版本曾写到 `<dataRoot>/signals.jsonl`(根目录),与其它状态
+ * 文件不在同一子目录,导致用户备份 `.co-engram/` 时会漏掉 signals。此处会
+ * 自动把根目录的旧文件迁移到新位置(只在首次创建 sink 时执行一次,代价极低)。
+ */
+export function createDefaultSignalSink(dataRoot) {
+    const newPath = join(dataRoot, ".co-engram", "signals.jsonl");
+    migrateLegacySignalFile(dataRoot, newPath);
+    return new FileSignalSink({ filePath: newPath });
+}
+/** 把 `<dataRoot>/signals.jsonl`(老路径)迁移到 `newPath`,如果老文件存在。
+ *  幂等:新路径已存在时不覆盖;老文件不存在时 no-op。 */
+function migrateLegacySignalFile(dataRoot, newPath) {
+    const legacyPath = join(dataRoot, "signals.jsonl");
+    if (!existsSync(legacyPath))
+        return;
+    // 新路径已存在:用户已经在新位置写过 → 不覆盖,只把老文件备份标识后留下
+    // (避免数据丢失;运维可以人工合并)
+    if (existsSync(newPath))
+        return;
+    try {
+        mkdirSync(dirname(newPath), { recursive: true });
+        renameSync(legacyPath, newPath);
+    }
+    catch {
+        // 迁移失败不阻塞 sink 创建;老文件依然可读,只是不一致
+    }
+}
+/** 仅用于测试：清空文件 */
+export function resetFileSignalSink(sink) {
+    // 用反射读取私有 filePath
+    const filePath = sink.filePath;
+    if (existsSync(filePath)) {
+        try {
+            unlinkSync(filePath);
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+//# sourceMappingURL=file-sink.js.map

package/dist/signals/file-sink.js.map

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

package/dist/signals/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Signals 模块 barrel（P4 自动维护服务）
+ *
+ * 行为信号提取：从工具调用事件流推断 engram 的"真实效用"，不依赖 agent 自律上报。
+ *
+ * @module @co-engram/core/signals
+ */
+export * from "./types.js";
+export * from "./file-sink.js";
+export * from "./extract.js";
+export * from "./rpe.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/signals/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC"}

package/dist/signals/index.js

@@ -0,0 +1,12 @@
+/**
+ * Signals 模块 barrel（P4 自动维护服务）
+ *
+ * 行为信号提取：从工具调用事件流推断 engram 的"真实效用"，不依赖 agent 自律上报。
+ *
+ * @module @co-engram/core/signals
+ */
+export * from "./types.js";
+export * from "./file-sink.js";
+export * from "./extract.js";
+export * from "./rpe.js";
+//# sourceMappingURL=index.js.map

package/dist/signals/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/signals/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC"}

package/dist/signals/rpe.d.ts

@@ -0,0 +1,60 @@
+/**
+ * RPE（Reward Prediction Error）有效性计算（P4 B）
+ *
+ * 人类多巴胺机制的工程化映射：
+ *
+ *   effectiveness = actual - expected
+ *
+ * 其中：
+ *   expected = 检索时算出的相关性分数（lastRetrievalScore，[0,1]）
+ *   actual   = 该 engram 在后续工具调用流中收到的累积信号（signalWeight，[-1,1]）
+ *
+ * effectiveness 为正 → 超预期（强化）；为负 → 失望（衰减）。
+ *
+ * @module @co-engram/core/signals
+ */
+import type { EngramRepository } from "../storage/repository.js";
+/** RPE 输入 */
+export interface RpeInput {
+    /** 检索时的相关性分数 [0,1]，作为"预期值" */
+    readonly expected: number;
+    /** 累积行为信号 [-1,1]，作为"实际值" */
+    readonly signalWeight: number;
+    /** 触发信号的次数（用于判断是否应更新） */
+    readonly signalCount: number;
+}
+/** 默认学习率（Δreinforcement 系数） */
+export declare const DEFAULT_RPE_LEARNING_RATE = 0.1;
+/** effectiveness 死区阈值：|eff| ≤ DEAD_ZONE 时不更新 */
+export declare const RPE_DEAD_ZONE = 0.05;
+/**
+ * 计算 RPE（不写库）
+ *
+ * - signalCount === 0 → 返回 0（无信号不更新）
+ * - actual = (clamp(signalWeight, -1, 1) + 1) / 2  // 归一化到 [0,1]
+ * - rpe = actual - expected                          // ∈ [-1, 1]
+ *
+ * @returns effectiveness ∈ [-1, 1]
+ */
+export declare function computeRpe(input: RpeInput): number;
+/**
+ * 应用一次 RPE 更新（写库）
+ *
+ * 根据 effectiveness 符号：
+ *   eff > 0.05  → effectiveRetrievals += 1, reinforcementScore += eff * lr
+ *   eff < -0.05 → failedUses += 1, reinforcementScore += eff * lr（负值,衰减）
+ *   |eff| ≤ 0.05 → 中性,不更新
+ *
+ * 不触发 version++。
+ *
+ * @returns 更新详情（供审计/日志）
+ */
+export declare function applyRpeUpdate(repo: EngramRepository, engramId: string, effectiveness: number, learningRate?: number): RpeUpdateResult;
+/** RPE 应用结果 */
+export interface RpeUpdateResult {
+    readonly engramId: string;
+    readonly effectiveness: number;
+    readonly action: "reinforced" | "penalized" | "neutral";
+    readonly delta: number;
+}
+//# sourceMappingURL=rpe.d.ts.map

package/dist/signals/rpe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpe.d.ts","sourceRoot":"","sources":["../../src/signals/rpe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,aAAa;AACb,MAAM,WAAW,QAAQ;IACvB,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4BAA4B;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,yBAAyB;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,+BAA+B;AAC/B,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C,gDAAgD;AAChD,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAMlD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,YAAY,GAAE,MAAkC,GAC/C,eAAe,CAqBjB;AAED,eAAe;AACf,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB"}

package/dist/signals/rpe.js

@@ -0,0 +1,68 @@
+/**
+ * RPE（Reward Prediction Error）有效性计算（P4 B）
+ *
+ * 人类多巴胺机制的工程化映射：
+ *
+ *   effectiveness = actual - expected
+ *
+ * 其中：
+ *   expected = 检索时算出的相关性分数（lastRetrievalScore，[0,1]）
+ *   actual   = 该 engram 在后续工具调用流中收到的累积信号（signalWeight，[-1,1]）
+ *
+ * effectiveness 为正 → 超预期（强化）；为负 → 失望（衰减）。
+ *
+ * @module @co-engram/core/signals
+ */
+/** 默认学习率（Δreinforcement 系数） */
+export const DEFAULT_RPE_LEARNING_RATE = 0.1;
+/** effectiveness 死区阈值：|eff| ≤ DEAD_ZONE 时不更新 */
+export const RPE_DEAD_ZONE = 0.05;
+/**
+ * 计算 RPE（不写库）
+ *
+ * - signalCount === 0 → 返回 0（无信号不更新）
+ * - actual = (clamp(signalWeight, -1, 1) + 1) / 2  // 归一化到 [0,1]
+ * - rpe = actual - expected                          // ∈ [-1, 1]
+ *
+ * @returns effectiveness ∈ [-1, 1]
+ */
+export function computeRpe(input) {
+    if (input.signalCount === 0)
+        return 0;
+    const clampedSignal = Math.max(-1, Math.min(1, input.signalWeight));
+    const actual = (clampedSignal + 1) / 2;
+    const expected = Math.max(0, Math.min(1, input.expected));
+    return actual - expected;
+}
+/**
+ * 应用一次 RPE 更新（写库）
+ *
+ * 根据 effectiveness 符号：
+ *   eff > 0.05  → effectiveRetrievals += 1, reinforcementScore += eff * lr
+ *   eff < -0.05 → failedUses += 1, reinforcementScore += eff * lr（负值,衰减）
+ *   |eff| ≤ 0.05 → 中性,不更新
+ *
+ * 不触发 version++。
+ *
+ * @returns 更新详情（供审计/日志）
+ */
+export function applyRpeUpdate(repo, engramId, effectiveness, learningRate = DEFAULT_RPE_LEARNING_RATE) {
+    if (Math.abs(effectiveness) <= RPE_DEAD_ZONE) {
+        return { engramId, effectiveness, action: "neutral", delta: 0 };
+    }
+    const delta = effectiveness * learningRate;
+    if (effectiveness > 0) {
+        repo.bumpRetrievalStats(engramId, {
+            effectiveDelta: 1,
+            reinforcementDelta: delta,
+            lastEffectiveAt: new Date().toISOString(),
+        });
+        return { engramId, effectiveness, action: "reinforced", delta };
+    }
+    repo.bumpRetrievalStats(engramId, {
+        failedDelta: 1,
+        reinforcementDelta: delta,
+    });
+    return { engramId, effectiveness, action: "penalized", delta };
+}
+//# sourceMappingURL=rpe.js.map

package/dist/signals/rpe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpe.js","sourceRoot":"","sources":["../../src/signals/rpe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAcH,+BAA+B;AAC/B,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAE7C,gDAAgD;AAChD,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC;AAElC;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,KAAe;IACxC,IAAI,KAAK,CAAC,WAAW,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACtC,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC;IACpE,MAAM,MAAM,GAAG,CAAC,aAAa,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC1D,OAAO,MAAM,GAAG,QAAQ,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAsB,EACtB,QAAgB,EAChB,aAAqB,EACrB,eAAuB,yBAAyB;IAEhD,IAAI,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,aAAa,EAAE,CAAC;QAC7C,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAClE,CAAC;IAED,MAAM,KAAK,GAAG,aAAa,GAAG,YAAY,CAAC;IAE3C,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;QACtB,IAAI,CAAC,kBAAkB,CAAC,QAAQ,EAAE;YAChC,cAAc,EAAE,CAAC;YACjB,kBAAkB,EAAE,KAAK;YACzB,eAAe,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SAC1C,CAAC,CAAC;QACH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;IAClE,CAAC;IAED,IAAI,CAAC,kBAAkB,CAAC,QAAQ,EAAE;QAChC,WAAW,EAAE,CAAC;QACd,kBAAkB,EAAE,KAAK;KAC1B,CAAC,CAAC;IACH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;AACjE,CAAC"}

package/dist/signals/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 行为信号数据模型（P4 自动维护服务 A 层）
+ *
+ * 从工具调用事件流中提取 implicit behavioral signals,不依赖 agent 主动上报。
+ *
+ * 数据流：
+ *   tools/*.execute → ctx.signalSink.append(ToolCallEvent)
+ *                  → signals.jsonl(JSONL, <dataRoot>/.co-engram/)
+ *   engine.runLight → sink.drain() → extractSignals(events) → BehavioralSignal[]
+ *
+ * @module @co-engram/core/signals
+ */
+/**
+ * 一次工具调用事件（recorded for later signal extraction）
+ *
+ * 写入时机：tools/wrapped.ts 包裹的 execute 在返回前 append。
+ * 写入是非阻塞的（fire-and-forget），失败不影响工具调用本身。
+ */
+export interface ToolCallEvent {
+    /** 工具名（engram_get / engram_search / synapse_create ...） */
+    readonly toolName: string;
+    /** 工具入参（只保留可序列化字段） */
+    readonly input: Readonly<Record<string, unknown>>;
+    /** 输出摘要（避免把整个 engram content 塞进事件流） */
+    readonly outputSummary?: string;
+    /** 工具结果涉及的 engram id 列表（如 engram_get 的返回 id、engram_search 的 hits） */
+    readonly retrievedEngramIds?: readonly string[];
+    /** 会话 id（每次工具调用生成新 UUID；extract 用 sliding window 替代会话边界） */
+    readonly sessionId: string;
+    /** 触发时间（epoch ms） */
+    readonly at: number;
+}
+/**
+ * 行为信号（从 ToolCallEvent 流提取的"这条 engram 有多被信任/有用"的归一化打分）
+ *
+ * weight ∈ [-1, 1]：
+ *   - 正值：engram 被认为有用（强正 ≥ 0.6、弱正 0.2-0.5）
+ *   - 负值：engram 被认为失败/错误（强负 ≤ -0.6、弱负 -0.2 - -0.5）
+ *   - 0：中性，通常不产生
+ */
+export interface BehavioralSignal {
+    /** 关联的 engram id */
+    readonly engramId: string;
+    /** 权重 [-1, 1] */
+    readonly weight: number;
+    /** 来源规则名（extract.ts 的 Rule.name） */
+    readonly source: string;
+    /** 证据（用于审计：触发事件、窗口大小、命中字段等） */
+    readonly evidence: Readonly<Record<string, unknown>>;
+    /** 触发事件所属的 sessionId */
+    readonly sessionId: string;
+    /** 信号生成时间（epoch ms） */
+    readonly at: number;
+}
+/**
+ * 信号收集器接口
+ *
+ * 宿主负责实现，core 提供默认 FileSignalSink(JSONL) 和 MemorySignalSink(测试用)。
+ */
+export interface SignalSink {
+    /**
+     * 追加一次工具调用事件
+     *
+     * 实现必须容忍失败（文件锁、磁盘满等），不应阻塞工具调用本身。
+     */
+    append(event: ToolCallEvent): Promise<void> | void;
+    /**
+     * 取出全部事件并清空内部缓冲
+     *
+     * 维护引擎 runLight 会调用此方法，拿到自上次维护以来的事件流。
+     */
+    drain(): readonly ToolCallEvent[];
+    /**
+     * 修剪过期事件
+     *
+     * 默认保留 7 天（runLight 末尾调用）。
+     */
+    prune(olderThanMs: number): Promise<void> | void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/signals/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/signals/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sBAAsB;IACtB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,uCAAuC;IACvC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qBAAqB;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oBAAoB;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iBAAiB;IACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+BAA+B;IAC/B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,wBAAwB;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uBAAuB;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAEnD;;;;OAIG;IACH,KAAK,IAAI,SAAS,aAAa,EAAE,CAAC;IAElC;;;;OAIG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAClD"}

package/dist/signals/types.js

@@ -0,0 +1,14 @@
+/**
+ * 行为信号数据模型（P4 自动维护服务 A 层）
+ *
+ * 从工具调用事件流中提取 implicit behavioral signals,不依赖 agent 主动上报。
+ *
+ * 数据流：
+ *   tools/*.execute → ctx.signalSink.append(ToolCallEvent)
+ *                  → signals.jsonl(JSONL, <dataRoot>/.co-engram/)
+ *   engine.runLight → sink.drain() → extractSignals(events) → BehavioralSignal[]
+ *
+ * @module @co-engram/core/signals
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/signals/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/signals/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/storage/engram-index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Engram Index — 派生缓存 {stableId → path/title/mtime/...}
+ *
+ * 设计见 docs/superpowers/specs/2026-06-22-per-edge-synapse-refactor-design.md。
+ *
+ * 文件位置:`.co-engram/engram-index.json`(gitignore)
+ * 用途:
+ *   - doctor 增量扫描(mtime 比对)
+ *   - repository 快速查 stableId → path
+ *   - graph 派生
+ *   - viewer 渲染
+ *
+ * @module @co-engram/core/storage
+ */
+import type { StableEngramId, EngramIndexEntry } from "../types/repository-types.js";
+import { type EngramFrontmatter } from "./engram-store.js";
+/** .co-engram/ 顶层缓存目录名 */
+export declare const CO_ENGRAM_CACHE_DIR = ".co-engram";
+/** engram-index.json 文件名 */
+export declare const ENGRAM_INDEX_FILENAME = "engram-index.json";
+/** engram-index.json 完整路径 */
+export declare function engramIndexPath(dataRoot: string): string;
+/** 内存中的 index 结构(用 Map 加速查询) */
+export interface EngramIndexMap {
+    readonly version: 1;
+    readonly entries: Map<StableEngramId, EngramIndexEntry>;
+    lastRebuiltAt: string;
+}
+/** 创建空 index */
+export declare function createEmptyEngramIndex(): EngramIndexMap;
+/**
+ * 从磁盘读取 index;不存在或损坏返回空 index。
+ */
+export declare function readEngramIndex(dataRoot: string): EngramIndexMap;
+/**
+ * 落盘 index(gitignore,但结构稳定以便人类 debug)。
+ */
+export declare function writeEngramIndex(dataRoot: string, index: EngramIndexMap): void;
+/**
+ * 从单条 engram 文件构建 index entry。
+ *
+ * - slug:frontmatter 显式则锁定,否则从 title slugify
+ * - domainTags:frontmatter 显式则锁定,否则从路径推断
+ * - mtime / contentHash 必须由调用者传入
+ */
+export declare function buildIndexEntryFromFrontmatter(params: {
+    readonly relativePath: string;
+    readonly frontmatter: EngramFrontmatter;
+    readonly mtime: number;
+    readonly contentHash: string;
+}): EngramIndexEntry;
+/**
+ * 扫描 dataRoot 下所有 .md,构建 engram-index。
+ *
+ * 规则:
+ * - 跳过 SKIP_DIRECTORIES 中的目录(.co-engram, node_modules, .git, synapses)
+ * - 无 frontmatter 的 .md 跳过(由 doctor 报告为 orphan_markdown)
+ * - frontmatter 缺 id 的 .md 跳过(由 doctor 报告为 orphan_markdown)
+ */
+export declare function rebuildEngramIndex(dataRoot: string, onOrphan?: (relativePath: string) => void): EngramIndexMap;
+/**
+ * 增量更新:仅更新单条 engram 的 index entry。
+ */
+export declare function upsertEngramIndexEntry(index: EngramIndexMap, entry: EngramIndexEntry): EngramIndexMap;
+/**
+ * 从 index 中删除一条 engram。
+ */
+export declare function removeEngramIndexEntry(index: EngramIndexMap, id: StableEngramId): boolean;
+/**
+ * 按 path 查 stableId(用于 doctor 检测文件移动)。
+ */
+export declare function findEngramIdByPath(index: EngramIndexMap, relativePath: string): StableEngramId | undefined;
+//# sourceMappingURL=engram-index.d.ts.map

package/dist/storage/engram-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engram-index.d.ts","sourceRoot":"","sources":["../../src/storage/engram-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAaH,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAEjB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAE3B,0BAA0B;AAC1B,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD,4BAA4B;AAC5B,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAyBzD,6BAA6B;AAC7B,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,gCAAgC;AAChC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC;IACxD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,gBAAgB;AAChB,wBAAgB,sBAAsB,IAAI,cAAc,CAMvD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAwBhE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,cAAc,GACpB,IAAI,CAaN;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE;IACrD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,GAAG,gBAAgB,CA6BnB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,GACxC,cAAc,CAgDhB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,gBAAgB,GACtB,cAAc,CAGhB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EACrB,EAAE,EAAE,cAAc,GACjB,OAAO,CAET;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,EACrB,YAAY,EAAE,MAAM,GACnB,cAAc,GAAG,SAAS,CAK5B"}