@co-engram/core 0.1.0

package/dist/maintenance/engine.js

@@ -0,0 +1,291 @@
+/**
+ * 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 { DEFAULT_DEEP_INTERVAL_MS, DEFAULT_LIGHT_INTERVAL_MS, DEFAULT_REM_INTERVAL_MS, DEFAULT_RPE_LEARNING_RATE, DEFAULT_SIGNAL_PRUNE_AGE_MS, } from "./types.js";
+import { extractSignals, DEFAULT_RULES, } from "../signals/extract.js";
+import { applyRpeUpdate } from "../signals/rpe.js";
+import { applyMetacognition } from "../verification/metacognition.js";
+import { computePromptSignals, writePromptSignals, } from "../prompt-signals/index.js";
+/**
+ * Maintenance Engine
+ *
+ * 使用：
+ *   const engine = new MaintenanceEngine(deps, config)
+ *   engine.start()
+ *   // ... 应用运行期间自动维护
+ *   engine.stop()
+ *
+ * 或单次手动触发：
+ *   await engine.runLight()
+ */
+export class MaintenanceEngine {
+    deps;
+    resolvedConfig;
+    lightTimer = null;
+    deepTimer = null;
+    remTimer = null;
+    running = false;
+    constructor(deps, config = {}) {
+        this.deps = deps;
+        this.resolvedConfig = {
+            lightIntervalMs: config.lightIntervalMs ?? DEFAULT_LIGHT_INTERVAL_MS,
+            deepIntervalMs: config.deepIntervalMs ?? DEFAULT_DEEP_INTERVAL_MS,
+            remIntervalMs: config.remIntervalMs ?? DEFAULT_REM_INTERVAL_MS,
+            signalPruneAgeMs: config.signalPruneAgeMs ?? DEFAULT_SIGNAL_PRUNE_AGE_MS,
+            learningRate: config.learningRate ?? DEFAULT_RPE_LEARNING_RATE,
+            rules: config.rules ?? DEFAULT_RULES,
+            windowSize: config.windowSize ?? 10,
+            enabledStages: config.enabledStages ?? ["light", "deep", "rem"],
+            trash: config.trash ?? { enabled: false },
+        };
+    }
+    /** 暴露配置（测试/审计用） */
+    getConfig() {
+        return this.resolvedConfig;
+    }
+    /**
+     * Light 阶段：drain signals → extractSignals → applyRpeUpdate → sweepExpired
+     *
+     * 高频运行（默认 5 分钟）,负责把累积的行为信号转成 engram 的强化/衰减。
+     * 无论 events 是否为空,都会执行 prune（控制 signals.jsonl 体积）。
+     * 如果注入了 effectivenessTracker,会扫描超时观察窗口（写 retrieve_inconclusive）。
+     */
+    async runLight() {
+        return this.runStage("light", async () => {
+            const events = this.deps.signalSink.drain();
+            let signalsProcessed = 0;
+            let rpeUpdates = 0;
+            if (events.length > 0) {
+                const signals = extractSignals(events, this.resolvedConfig.rules, {
+                    windowSize: this.resolvedConfig.windowSize,
+                });
+                signalsProcessed = signals.length;
+                // 按 engramId 聚合：取每个 engram 的所有 source 信号求和
+                const byEngram = new Map();
+                for (const s of signals) {
+                    const entry = byEngram.get(s.engramId) ?? { sum: 0, count: 0 };
+                    entry.sum += s.weight;
+                    entry.count += 1;
+                    byEngram.set(s.engramId, entry);
+                }
+                for (const [engramId, agg] of byEngram) {
+                    // 读取该 engram 的 expected（lastRetrievalScore,缺失视为 0.5）
+                    let expected = 0.5;
+                    try {
+                        const engram = this.deps.repository.readEngram(engramId);
+                        expected = engram.lastRetrievalScore ?? 0.5;
+                    }
+                    catch {
+                        // engram 可能已被删除,跳过
+                        continue;
+                    }
+                    const effectiveness = (agg.sum + 1) / 2 - expected;
+                    applyRpeUpdate(this.deps.repository, engramId, effectiveness, this.resolvedConfig.learningRate);
+                    rpeUpdates += 1;
+                }
+            }
+            // 无论 events 是否为空都清理过期 events（控制 signals.jsonl 体积）
+            try {
+                await this.deps.signalSink.prune(this.resolvedConfig.signalPruneAgeMs);
+            }
+            catch {
+                // prune 失败不阻塞 light
+            }
+            // M1: 扫描超时观察窗口（如果配置了 effectivenessTracker）
+            let windowsClosed = 0;
+            if (this.deps.effectivenessTracker) {
+                try {
+                    const sweep = this.deps.effectivenessTracker.sweepExpired();
+                    windowsClosed = sweep.closed;
+                }
+                catch {
+                    // sweep 失败不阻塞 light
+                }
+            }
+            // 自进化 prompt signals:扫描 domainTags,生成 snapshot 写缓存
+            // 用于 promptBuilder 动态填充 "Frequent topics" 提示
+            let promptSignalsUpdated = false;
+            if (this.deps.dataRoot) {
+                try {
+                    const snapshot = computePromptSignals(this.deps.repository, {
+                        generatedBy: "light-stage",
+                    });
+                    await writePromptSignals(this.deps.dataRoot, snapshot);
+                    promptSignalsUpdated = true;
+                }
+                catch {
+                    // signals 更新失败不阻塞 light
+                }
+            }
+            return {
+                signalsProcessed,
+                rpeUpdates,
+                windowsClosed,
+                promptSignalsUpdated,
+            };
+        });
+    }
+    /**
+     * Deep 阶段：复用现有 runDeepDreaming
+     *
+     * 中频（默认 1 小时）,负责 decay + abstraction。
+     * 提交 9 实现（占位：抛错,提示 deps 缺 dreamingScheduler）。
+     */
+    async runDeep() {
+        return this.runStage("deep", async () => {
+            if (!this.deps.dreamingScheduler) {
+                throw new Error("dreamingScheduler not configured (required for deep stage)");
+            }
+            const record = this.deps.dreamingScheduler.trigger("deep");
+            return {
+                downstreamReport: record,
+            };
+        });
+    }
+    /**
+     * REM 阶段：runRemDreaming + metacognition
+     *
+     * 低频（默认 7 天）,负责 abstraction + verification 升降级。
+     *
+     * 1. 触发 dreamingScheduler.trigger('rem')（聚类 + 抽象）
+     * 2. 遍历所有未 refute 的 engram,调 applyMetacognition
+     *    - 元认知评分决定 verificationStatus 升级 / refute
+     */
+    async runRem() {
+        return this.runStage("rem", async () => {
+            if (!this.deps.dreamingScheduler) {
+                throw new Error("dreamingScheduler not configured (required for rem stage)");
+            }
+            // 1. 触发 REM Dreaming（聚类 + 抽象）
+            const dreamRecord = this.deps.dreamingScheduler.trigger("rem");
+            // 2. 对所有 active 且未 refuted 的 engram 跑 metacognition
+            //    遍历 unverified / plausible / probable / verified
+            const candidates = this.deps.repository.listByVerificationStatus([
+                "unverified",
+                "plausible",
+                "probable",
+                "verified",
+            ]);
+            let metacognitionApplied = 0;
+            for (const engram of candidates) {
+                try {
+                    const result = await applyMetacognition(this.deps.repository, engram.id);
+                    if (result.applied)
+                        metacognitionApplied += 1;
+                }
+                catch {
+                    // 单个 engram 失败不阻塞整体
+                }
+            }
+            return {
+                downstreamReport: {
+                    dream: dreamRecord,
+                    metacognitionApplied,
+                    metacognitionTotal: candidates.length,
+                },
+            };
+        });
+    }
+    /**
+     * 启动所有已启用阶段的定时调度
+     *
+     * 定时器都调 .unref(),进程退出时自动清理。
+     */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        const stages = new Set(this.resolvedConfig.enabledStages);
+        if (stages.has("light")) {
+            this.lightTimer = setInterval(() => {
+                this.runLight().catch(() => {
+                    // 单次失败不阻塞后续调度（错误已在 report 内记录）
+                });
+            }, this.resolvedConfig.lightIntervalMs);
+            this.lightTimer.unref?.();
+        }
+        if (stages.has("deep")) {
+            this.deepTimer = setInterval(() => {
+                this.runDeep().catch(() => { });
+            }, this.resolvedConfig.deepIntervalMs);
+            this.deepTimer.unref?.();
+        }
+        if (stages.has("rem")) {
+            this.remTimer = setInterval(() => {
+                this.runRem().catch(() => { });
+            }, this.resolvedConfig.remIntervalMs);
+            this.remTimer.unref?.();
+        }
+    }
+    /** 停止所有定时调度 */
+    stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        if (this.lightTimer) {
+            clearInterval(this.lightTimer);
+            this.lightTimer = null;
+        }
+        if (this.deepTimer) {
+            clearInterval(this.deepTimer);
+            this.deepTimer = null;
+        }
+        if (this.remTimer) {
+            clearInterval(this.remTimer);
+            this.remTimer = null;
+        }
+    }
+    /** 是否正在运行 */
+    isRunning() {
+        return this.running;
+    }
+    // ============================================================
+    // 内部辅助
+    // ============================================================
+    async runStage(stage, fn) {
+        const startedAt = Date.now();
+        const errors = [];
+        let body = {};
+        try {
+            body = await fn();
+        }
+        catch (err) {
+            errors.push({
+                stage,
+                message: err instanceof Error ? err.message : String(err),
+                at: Date.now(),
+            });
+        }
+        const finishedAt = Date.now();
+        const durationMs = finishedAt - startedAt;
+        // 阶段触发本身不写 audit —— 避免每 5 分钟一条噪音。
+        // 下游任务(sweep_to_trash / reinforce / forget / refute 等)自己写状态变更 audit。
+        return {
+            stage,
+            startedAt,
+            finishedAt,
+            durationMs,
+            errors,
+            signalsProcessed: body.signalsProcessed,
+            rpeUpdates: body.rpeUpdates,
+            windowsClosed: body.windowsClosed,
+            promptSignalsUpdated: body.promptSignalsUpdated,
+            downstreamReport: body.downstreamReport,
+        };
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/maintenance/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/maintenance/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,uBAAuB,EACvB,yBAAyB,EACzB,2BAA2B,GAC5B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,EACd,aAAa,GAEd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EACL,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,iBAAiB;IACX,IAAI,CAAkB;IACtB,cAAc,CAA8B;IACrD,UAAU,GAA0C,IAAI,CAAC;IACzD,SAAS,GAA0C,IAAI,CAAC;IACxD,QAAQ,GAA0C,IAAI,CAAC;IACvD,OAAO,GAAG,KAAK,CAAC;IAExB,YAAY,IAAqB,EAAE,SAA4B,EAAE;QAC/D,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,cAAc,GAAG;YACpB,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,yBAAyB;YACpE,cAAc,EAAE,MAAM,CAAC,cAAc,IAAI,wBAAwB;YACjE,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,uBAAuB;YAC9D,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,IAAI,2BAA2B;YACxE,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,yBAAyB;YAC9D,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,aAAa;YACpC,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,EAAE;YACnC,aAAa,EACX,MAAM,CAAC,aAAa,IAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAW;YAC7D,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE;SAC1C,CAAC;IACJ,CAAC;IAED,mBAAmB;IACnB,SAAS;QACP,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ;QACZ,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;YACvC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,EAAqB,CAAC;YAE/D,IAAI,gBAAgB,GAAG,CAAC,CAAC;YACzB,IAAI,UAAU,GAAG,CAAC,CAAC;YAEnB,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtB,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE;oBAChE,UAAU,EAAE,IAAI,CAAC,cAAc,CAAC,UAAU;iBAC3C,CAAC,CAAC;gBACH,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;gBAElC,2CAA2C;gBAC3C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA0C,CAAC;gBACnE,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;oBACxB,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;oBAC/D,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC;oBACtB,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;oBACjB,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;gBAClC,CAAC;gBAED,KAAK,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,QAAQ,EAAE,CAAC;oBACvC,qDAAqD;oBACrD,IAAI,QAAQ,GAAG,GAAG,CAAC;oBACnB,IAAI,CAAC;wBACH,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;wBACzD,QAAQ,GAAG,MAAM,CAAC,kBAAkB,IAAI,GAAG,CAAC;oBAC9C,CAAC;oBAAC,MAAM,CAAC;wBACP,mBAAmB;wBACnB,SAAS;oBACX,CAAC;oBAED,MAAM,aAAa,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;oBACnD,cAAc,CACZ,IAAI,CAAC,IAAI,CAAC,UAAU,EACpB,QAAQ,EACR,aAAa,EACb,IAAI,CAAC,cAAc,CAAC,YAAY,CACjC,CAAC;oBACF,UAAU,IAAI,CAAC,CAAC;gBAClB,CAAC;YACH,CAAC;YAED,kDAAkD;YAClD,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,gBAAgB,CAAC,CAAC;YACzE,CAAC;YAAC,MAAM,CAAC;gBACP,oBAAoB;YACtB,CAAC;YAED,2CAA2C;YAC3C,IAAI,aAAa,GAAG,CAAC,CAAC;YACtB,IAAI,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,CAAC;gBACnC,IAAI,CAAC;oBACH,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC,YAAY,EAAE,CAAC;oBAC5D,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC;gBAC/B,CAAC;gBAAC,MAAM,CAAC;oBACP,oBAAoB;gBACtB,CAAC;YACH,CAAC;YAED,mDAAmD;YACnD,6CAA6C;YAC7C,IAAI,oBAAoB,GAAG,KAAK,CAAC;YACjC,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACvB,IAAI,CAAC;oBACH,MAAM,QAAQ,GAAG,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE;wBAC1D,WAAW,EAAE,aAAa;qBAC3B,CAAC,CAAC;oBACH,MAAM,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;oBACvD,oBAAoB,GAAG,IAAI,CAAC;gBAC9B,CAAC;gBAAC,MAAM,CAAC;oBACP,wBAAwB;gBAC1B,CAAC;YACH,CAAC;YAED,OAAO;gBACL,gBAAgB;gBAChB,UAAU;gBACV,aAAa;gBACb,oBAAoB;aACrB,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAO;QACX,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,IAAI,EAAE;YACtC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBACjC,MAAM,IAAI,KAAK,CACb,4DAA4D,CAC7D,CAAC;YACJ,CAAC;YACD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC3D,OAAO;gBACL,gBAAgB,EAAE,MAAM;aACzB,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM;QACV,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE;YACrC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBACjC,MAAM,IAAI,KAAK,CACb,2DAA2D,CAC5D,CAAC;YACJ,CAAC;YAED,8BAA8B;YAC9B,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAE/D,oDAAoD;YACpD,qDAAqD;YACrD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,wBAAwB,CAAC;gBAC/D,YAAY;gBACZ,WAAW;gBACX,UAAU;gBACV,UAAU;aACX,CAAC,CAAC;YAEH,IAAI,oBAAoB,GAAG,CAAC,CAAC;YAC7B,KAAK,MAAM,MAAM,IAAI,UAAU,EAAE,CAAC;gBAChC,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,kBAAkB,CACrC,IAAI,CAAC,IAAI,CAAC,UAAU,EACpB,MAAM,CAAC,EAAE,CACV,CAAC;oBACF,IAAI,MAAM,CAAC,OAAO;wBAAE,oBAAoB,IAAI,CAAC,CAAC;gBAChD,CAAC;gBAAC,MAAM,CAAC;oBACP,oBAAoB;gBACtB,CAAC;YACH,CAAC;YAED,OAAO;gBACL,gBAAgB,EAAE;oBAChB,KAAK,EAAE,WAAW;oBAClB,oBAAoB;oBACpB,kBAAkB,EAAE,UAAU,CAAC,MAAM;iBACtC;aACF,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QAEpB,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;QAC1D,IAAI,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE;gBACjC,IAAI,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;oBACzB,+BAA+B;gBACjC,CAAC,CAAC,CAAC;YACL,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,eAAe,CAAC,CAAC;YACxC,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,CAAC;QAC5B,CAAC;QACD,IAAI,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACvB,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;gBAChC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACjC,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;YACvC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC;QAC3B,CAAC;QACD,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE;gBAC/B,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAChC,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;YACtC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,eAAe;IACf,IAAI;QACF,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC/B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACzB,CAAC;QACD,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC9B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACxB,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC7B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACvB,CAAC;IACH,CAAC;IAED,aAAa;IACb,SAAS;QACP,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,+DAA+D;IAC/D,OAAO;IACP,+DAA+D;IAEvD,KAAK,CAAC,QAAQ,CACpB,KAAuB,EACvB,EAA6C;QAE7C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAuB,EAAE,CAAC;QACtC,IAAI,IAAI,GAA+B,EAAE,CAAC;QAE1C,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC;gBACV,KAAK;gBACL,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;gBACzD,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;aACf,CAAC,CAAC;QACL,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC9B,MAAM,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;QAE1C,kCAAkC;QAClC,qEAAqE;QAErE,OAAO;YACL,KAAK;YACL,SAAS;YACT,UAAU;YACV,UAAU;YACV,MAAM;YACN,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,oBAAoB,EAAE,IAAI,CAAC,oBAAoB;YAC/C,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;SACxC,CAAC;IACJ,CAAC;CACF"}

package/dist/maintenance/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Maintenance 模块 barrel（P4 自动维护服务）
+ *
+ * @module @co-engram/core/maintenance
+ */
+export * from "./types.js";
+export * from "./engine.js";
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/maintenance/index.js

@@ -0,0 +1,8 @@
+/**
+ * Maintenance 模块 barrel（P4 自动维护服务）
+ *
+ * @module @co-engram/core/maintenance
+ */
+export * from "./types.js";
+export * from "./engine.js";
+//# sourceMappingURL=index.js.map

package/dist/maintenance/index.js.map

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

package/dist/maintenance/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Maintenance 模块类型定义（P4 B.2 + C.2 + D.1）
+ *
+ * MaintenanceEngine 三阶段配置：
+ *   - light: drain signals → extractSignals → applyRpeUpdate（高频,秒/分钟级）
+ *   - deep : 复用现有 runDeepDreaming（中频,小时级）
+ *   - rem  : runRemDreaming + metacognition（低频,天级）
+ *
+ * 设计原则：
+ *   1. 默认配置合理（可零配置启动）
+ *   2. 调度器内化在 engine.start()（setInterval + unref）,不依赖宿主 /loop
+ *   3. 三阶段独立触发,可单独调用
+ *
+ * @module @co-engram/core/maintenance
+ */
+import type { EngramRepository } from "../storage/repository.js";
+import type { SignalSink } from "../signals/types.js";
+import type { SignalRule } from "../signals/extract.js";
+import type { DreamingScheduler } from "../dreaming/scheduler.js";
+import type { EffectivenessTracker } from "../observability/effectiveness-tracker.js";
+import { DEFAULT_RPE_LEARNING_RATE } from "../signals/rpe.js";
+/** 维护阶段名 */
+export type MaintenanceStage = "light" | "deep" | "rem";
+/** 维护引擎依赖（注入式,便于测试） */
+export interface MaintenanceDeps {
+    readonly repository: EngramRepository;
+    readonly signalSink: SignalSink;
+    /**
+     * 复用现有 DreamingScheduler（deep/rem 阶段）。
+     * light 阶段不需要它,但 deep/rem 需要。
+     */
+    readonly dreamingScheduler?: DreamingScheduler;
+    /**
+     * 有效性追踪器（可选,light 阶段调用 sweepExpired）。
+     *
+     * 如果注入,每次 light 阶段会扫描超时观察窗口,
+     * 把 inconclusive 的 retrieve 信号写入 audit log。
+     */
+    readonly effectivenessTracker?: EffectivenessTracker;
+    /**
+     * team-memory 根路径（可选,light 阶段写 prompt-signals.json 用）。
+     *
+     * 如果注入,每次 light 阶段会扫描所有 engram 的 domainTags,
+     * 生成 PromptSignalSnapshot 写入 `<dataRoot>/.co-engram/prompt-signals.json`。
+     * promptBuilder 读取这份 snapshot 实现自进化提示词。
+     */
+    readonly dataRoot?: string;
+}
+/** 默认配置常量 */
+export declare const DEFAULT_LIGHT_INTERVAL_MS: number;
+export declare const DEFAULT_DEEP_INTERVAL_MS: number;
+export declare const DEFAULT_REM_INTERVAL_MS: number;
+export declare const DEFAULT_SIGNAL_PRUNE_AGE_MS: number;
+/** 复用 signals/rpe.ts 的学习率（重导出避免分裂） */
+export { DEFAULT_RPE_LEARNING_RATE };
+/** 维护引擎配置 */
+export interface MaintenanceConfig {
+    /** light 阶段调度间隔（默认 5 分钟） */
+    readonly lightIntervalMs?: number;
+    /** deep 阶段调度间隔（默认 1 小时） */
+    readonly deepIntervalMs?: number;
+    /** rem 阶段调度间隔（默认 7 天） */
+    readonly remIntervalMs?: number;
+    /** signals.jsonl 保留时长（默认 7 天） */
+    readonly signalPruneAgeMs?: number;
+    /** RPE 学习率（默认 0.1） */
+    readonly learningRate?: number;
+    /** 自定义信号规则（默认 DEFAULT_RULES） */
+    readonly rules?: readonly SignalRule[];
+    /** sliding window 大小（默认 10） */
+    readonly windowSize?: number;
+    /** 启用哪些阶段（默认全开） */
+    readonly enabledStages?: readonly MaintenanceStage[];
+    /** Trash sweep 配置。默认开启 → deep 阶段执行 trash sweep */
+    readonly trash?: TrashMaintenanceConfig;
+}
+/** Trash 在 maintenance 中的配置 */
+export interface TrashMaintenanceConfig {
+    /** 是否启用 trash sweep（默认 true,遵循 low-friction-defaults） */
+    readonly enabled?: boolean;
+    /** forgotten 后多少天才进入回收站（默认 30 天） */
+    readonly afterDays?: number;
+    /** 回收站中多少天后物理删除（默认 365 天）;0 或负数表示永不删除 */
+    readonly purgeAfterDays?: number;
+}
+/** 单次维护的报告 */
+export interface MaintenanceReport {
+    readonly stage: MaintenanceStage;
+    readonly startedAt: number;
+    readonly finishedAt: number;
+    readonly durationMs: number;
+    /** 处理的信号条数（light 阶段） */
+    readonly signalsProcessed?: number;
+    /** 产生的 RPE 更新数（light 阶段） */
+    readonly rpeUpdates?: number;
+    /** light 阶段关闭的观察窗口数（sweepExpired） */
+    readonly windowsClosed?: number;
+    /** light 阶段是否刷新了 prompt-signals.json */
+    readonly promptSignalsUpdated?: boolean;
+    /** deep/rem 阶段的下游报告 */
+    readonly downstreamReport?: unknown;
+    /** 错误（不抛,记录后继续） */
+    readonly errors: readonly MaintenanceError[];
+}
+/** 维护过程中的错误（不阻塞） */
+export interface MaintenanceError {
+    readonly stage: MaintenanceStage;
+    readonly message: string;
+    readonly at: number;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/maintenance/types.js

@@ -0,0 +1,24 @@
+/**
+ * Maintenance 模块类型定义（P4 B.2 + C.2 + D.1）
+ *
+ * MaintenanceEngine 三阶段配置：
+ *   - light: drain signals → extractSignals → applyRpeUpdate（高频,秒/分钟级）
+ *   - deep : 复用现有 runDeepDreaming（中频,小时级）
+ *   - rem  : runRemDreaming + metacognition（低频,天级）
+ *
+ * 设计原则：
+ *   1. 默认配置合理（可零配置启动）
+ *   2. 调度器内化在 engine.start()（setInterval + unref）,不依赖宿主 /loop
+ *   3. 三阶段独立触发,可单独调用
+ *
+ * @module @co-engram/core/maintenance
+ */
+import { DEFAULT_RPE_LEARNING_RATE } from "../signals/rpe.js";
+/** 默认配置常量 */
+export const DEFAULT_LIGHT_INTERVAL_MS = 5 * 60 * 1000; // 5 min
+export const DEFAULT_DEEP_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+export const DEFAULT_REM_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+export const DEFAULT_SIGNAL_PRUNE_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+/** 复用 signals/rpe.ts 的学习率（重导出避免分裂） */
+export { DEFAULT_RPE_LEARNING_RATE };
+//# sourceMappingURL=types.js.map

package/dist/maintenance/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/maintenance/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AA+B9D,aAAa;AACb,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,QAAQ;AAChE,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,SAAS;AACjE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,SAAS;AACzE,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,SAAS;AAE7E,sCAAsC;AACtC,OAAO,EAAE,yBAAyB,EAAE,CAAC"}

package/dist/observability/audit-log.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 行为审计日志（Audit Log）
+ *
+ * 记录 engram 状态变更 + 必要事件,为 co-engram 自身进化提供数据。
+ *
+ * 当前写入的事件:
+ *   - 状态变更: create/update/update_lifecycle/reinforce/report_failure/
+ *               forget/restore/sweep_to_trash/restore_from_trash/purge/
+ *               propose/accept/dismiss
+ *   - 必要性拒绝: necessity_rejected(Layer 2 评估拒绝,需要审计便于调参)
+ *   - 冲突标记: contradicted(供 EffectivenessTracker.effectiveness() 派生用)
+ *
+ * 不再写入的事件(避免淹没 audit.jsonl,详见 effectiveness-tracker.ts):
+ *   - noise_filtered(Layer 1 入口拒绝,每条对话消息都会产生)
+ *   - retrieve_hit / retrieve_effective / retrieve_inconclusive
+ *     (effectiveness 已从 observation-windows.jsonl 派生,无需冗余写 audit)
+ *
+ * AuditAction 枚举保留这些值以便读旧日志,但新代码不再 append 它们。
+ *
+ * 存储格式: $DATA_ROOT/.co-engram/audit.jsonl (append-only,gitignored)
+ * 每行一个 JSON 对象,~200 字节/条。
+ *
+ * @module @co-engram/core/observability
+ */
+/** 审计动作 */
+export type AuditAction = "create" | "update" | "update_lifecycle" | "reinforce" | "report_failure" | "forget" | "restore" | "sweep_to_trash" | "restore_from_trash" | "purge" | "propose" | "accept" | "dismiss" | "retrieve_hit" | "retrieve_effective" | "retrieve_inconclusive" | "contradicted" | "noise_filtered" | "necessity_rejected";
+/** 审计行为者 */
+export type AuditActor = "user" | "llm" | "system";
+/** 单条审计记录 */
+export interface AuditEntry {
+    /** ISO 时间戳 */
+    readonly ts: string;
+    /** 触发者 */
+    readonly actor: AuditActor;
+    /** 动作类型 */
+    readonly action: AuditAction;
+    /** 相关 engram id(状态变更必填;有效性必填) */
+    readonly engramId?: string;
+    /** 检索查询(仅 retrieve_* 事件) */
+    readonly query?: string;
+    /** 检索分数(仅 retrieve_hit) */
+    readonly score?: number;
+    /** 任意附加元数据 */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** 查询过滤条件 */
+export interface AuditQueryFilter {
+    /** 起始时间(包含) */
+    readonly since?: string;
+    /** 截止时间(不包含) */
+    readonly until?: string;
+    /** 按 action 过滤(单个或多个) */
+    readonly action?: AuditAction | readonly AuditAction[];
+    /** 按 engramId 过滤 */
+    readonly engramId?: string;
+    /** 返回上限(默认 1000) */
+    readonly limit?: number;
+}
+/**
+ * 审计日志
+ *
+ * 构造时传入 dataRoot,自动确定 audit.jsonl 路径。
+ * append 操作是 fire-and-forget,失败不阻塞调用方。
+ */
+export declare class AuditLog {
+    private readonly filePath;
+    constructor(dataRoot: string);
+    /** 追加一条记录(失败静默) */
+    append(entry: Omit<AuditEntry, "ts">): void;
+    /** 查询历史记录 */
+    query(filter?: AuditQueryFilter): readonly AuditEntry[];
+    /** 清空所有记录(测试用) */
+    clear(): void;
+    /** 文件绝对路径(测试/审计用) */
+    get path(): string;
+}
+//# sourceMappingURL=audit-log.d.ts.map

package/dist/observability/audit-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-log.d.ts","sourceRoot":"","sources":["../../src/observability/audit-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAWH,WAAW;AACX,MAAM,MAAM,WAAW,GAEnB,QAAQ,GACR,QAAQ,GACR,kBAAkB,GAClB,WAAW,GACX,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,gBAAgB,GAChB,oBAAoB,GACpB,OAAO,GACP,SAAS,GACT,QAAQ,GACR,SAAS,GAET,cAAc,GACd,oBAAoB,GACpB,uBAAuB,GACvB,cAAc,GAEd,gBAAgB,GAChB,oBAAoB,CAAC;AAEzB,YAAY;AACZ,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEnD,aAAa;AACb,MAAM,WAAW,UAAU;IACzB,cAAc;IACd,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,UAAU;IACV,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,WAAW;IACX,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc;IACd,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED,aAAa;AACb,MAAM,WAAW,gBAAgB;IAC/B,eAAe;IACf,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB;IAChB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,yBAAyB;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,WAAW,EAAE,CAAC;IACvD,oBAAoB;IACpB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,oBAAoB;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAKD;;;;;GAKG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,EAAE,MAAM;IAI5B,mBAAmB;IACnB,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,IAAI;IAa3C,aAAa;IACb,KAAK,CAAC,MAAM,GAAE,gBAAqB,GAAG,SAAS,UAAU,EAAE;IAsC3D,kBAAkB;IAClB,KAAK,IAAI,IAAI;IAMb,qBAAqB;IACrB,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/observability/audit-log.js

@@ -0,0 +1,101 @@
+/**
+ * 行为审计日志（Audit Log）
+ *
+ * 记录 engram 状态变更 + 必要事件,为 co-engram 自身进化提供数据。
+ *
+ * 当前写入的事件:
+ *   - 状态变更: create/update/update_lifecycle/reinforce/report_failure/
+ *               forget/restore/sweep_to_trash/restore_from_trash/purge/
+ *               propose/accept/dismiss
+ *   - 必要性拒绝: necessity_rejected(Layer 2 评估拒绝,需要审计便于调参)
+ *   - 冲突标记: contradicted(供 EffectivenessTracker.effectiveness() 派生用)
+ *
+ * 不再写入的事件(避免淹没 audit.jsonl,详见 effectiveness-tracker.ts):
+ *   - noise_filtered(Layer 1 入口拒绝,每条对话消息都会产生)
+ *   - retrieve_hit / retrieve_effective / retrieve_inconclusive
+ *     (effectiveness 已从 observation-windows.jsonl 派生,无需冗余写 audit)
+ *
+ * AuditAction 枚举保留这些值以便读旧日志,但新代码不再 append 它们。
+ *
+ * 存储格式: $DATA_ROOT/.co-engram/audit.jsonl (append-only,gitignored)
+ * 每行一个 JSON 对象,~200 字节/条。
+ *
+ * @module @co-engram/core/observability
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+/** 默认 limit */
+const DEFAULT_QUERY_LIMIT = 1000;
+/**
+ * 审计日志
+ *
+ * 构造时传入 dataRoot,自动确定 audit.jsonl 路径。
+ * append 操作是 fire-and-forget,失败不阻塞调用方。
+ */
+export class AuditLog {
+    filePath;
+    constructor(dataRoot) {
+        this.filePath = join(dataRoot, ".co-engram", "audit.jsonl");
+    }
+    /** 追加一条记录(失败静默) */
+    append(entry) {
+        try {
+            const fullEntry = { ts: new Date().toISOString(), ...entry };
+            const dir = dirname(this.filePath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            appendFileSync(this.filePath, `${JSON.stringify(fullEntry)}\n`, "utf8");
+        }
+        catch {
+            // intentional:审计失败不应阻塞业务逻辑
+        }
+    }
+    /** 查询历史记录 */
+    query(filter = {}) {
+        if (!existsSync(this.filePath)) {
+            return [];
+        }
+        const raw = readFileSync(this.filePath, "utf8");
+        const lines = raw.split("\n").filter((line) => line.trim().length > 0);
+        const actionSet = Array.isArray(filter.action)
+            ? new Set(filter.action)
+            : filter.action
+                ? new Set([filter.action])
+                : null;
+        const limit = filter.limit ?? DEFAULT_QUERY_LIMIT;
+        // 从尾部往前读,优先返回最新记录(常见用例)
+        const out = [];
+        for (let i = lines.length - 1; i >= 0 && out.length < limit; i--) {
+            let entry;
+            try {
+                entry = JSON.parse(lines[i]);
+            }
+            catch {
+                continue;
+            }
+            if (filter.since && entry.ts < filter.since)
+                continue;
+            if (filter.until && entry.ts >= filter.until)
+                continue;
+            if (actionSet && !actionSet.has(entry.action))
+                continue;
+            if (filter.engramId && entry.engramId !== filter.engramId)
+                continue;
+            out.push(entry);
+        }
+        // 反转回时间正序(便于人类阅读)
+        return out.reverse();
+    }
+    /** 清空所有记录(测试用) */
+    clear() {
+        if (existsSync(this.filePath)) {
+            writeFileSync(this.filePath, "", "utf8");
+        }
+    }
+    /** 文件绝对路径(测试/审计用) */
+    get path() {
+        return this.filePath;
+    }
+}
+//# sourceMappingURL=audit-log.js.map