@co-engram/core 0.1.2 → 0.1.4

package/dist/prompt-signals/cache.d.ts

@@ -14,10 +14,83 @@
  * @module @co-engram/core/prompt-signals
  */
 import type { PromptSignalSnapshot } from "./types.js";
+import type { PromptSignalBus } from "./event-bus.js";
 /**
  * 缓存文件名
  */
 export declare const PROMPT_SIGNALS_FILENAME = "prompt-signals.json";
+/**
+ * PromptSignalCache 配置
+ *
+ *   - bus:事件源,cache 订阅它的 emit
+ *   - rebuild:实际重算 snapshot 的回调(由消费方注入,
+ *     通常读 team-memory + computePromptSignals + writePromptSignals)
+ *   - debounceMs:事件触发后等多久才真的 rebuild(默认 200ms,
+ *     让 burst 事件合并成单次重算)
+ *   - initialSnapshot:启动时的初始值(默认 EMPTY_PROMPT_SIGNALS)
+ */
+export interface PromptSignalCacheOptions {
+    readonly bus: PromptSignalBus;
+    readonly rebuild: () => Promise<PromptSignalSnapshot>;
+    readonly debounceMs?: number;
+    readonly initialSnapshot?: PromptSignalSnapshot;
+}
+/**
+ * 事件驱动的 invalidating cache(Task 3.4 root cause AD)
+ *
+ * 旧实现:prompt-builder 直接读 prompt-signals.json,只在 maintenance light stage
+ * 周期跑(默认 5min)时刷新。engram_create / synapse_create / proposal accept 等
+ * 操作不会立即触发刷新,导致"刚创建的 engram 没出现在下次 prompt 的 topTags"。
+ *
+ * 新实现:cache 订阅 PromptSignalBus,任何相关事件都标记 stale + debounced rebuild,
+ * 保证下一次 promptBuilder.snapshot() 拿到最新数据。
+ *
+ * 失败策略:rebuild 抛错时保留旧 snapshot 并清掉 stale 标记(避免无限重试);
+ * 调用方可通过 getRevision() 观察是否真的更新过。
+ */
+export declare class PromptSignalCache {
+    private snapshotValue;
+    private revisionValue;
+    private staleValue;
+    private debounceMs;
+    private readonly rebuildFn;
+    private readonly unsubscribe;
+    private pendingTimer;
+    private disposed;
+    constructor(opts: PromptSignalCacheOptions);
+    /**
+     * 当前 snapshot 引用
+     *
+     * rebuild 成功后引用会替换,消费方可以用引用相等检测是否需要重读。
+     */
+    snapshot(): PromptSignalSnapshot;
+    /**
+     * rebuild 次数(成功才递增)
+     *
+     * 用于测试断言和监控:revision 没动 = 数据没变。
+     */
+    getRevision(): number;
+    /**
+     * 是否有事件触发但还未 rebuild 完成
+     *
+     * true 表示当前 snapshot 可能过时。
+     */
+    isStale(): boolean;
+    /**
+     * 手动触发 rebuild(忽略 stale 状态)
+     *
+     * 成功 → revision++ + 替换 snapshot + 清 stale;
+     * 失败 → 保留旧 snapshot + 清 stale(避免无限重试),不抛错。
+     */
+    rebuild(): Promise<void>;
+    /**
+     * 停止接收 bus 事件,清掉 pending timer
+     *
+     * dispose 后再调用 rebuild() 是 noop,snapshot() 返回最后一次成功的值。
+     */
+    dispose(): void;
+    private handleBusEvent;
+}
 /**
  * 读取 prompt signals 缓存
  *

package/dist/prompt-signals/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/prompt-signals/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAE7D;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GACzC,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAY3C;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,oBAAoB,EAC7B,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACzD,OAAO,CAAC,IAAI,CAAC,CAQf"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/prompt-signals/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAM7D;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,oBAAoB,CAAC;CACjD;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsC;IAChE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,QAAQ,CAAS;gBAEb,IAAI,EAAE,wBAAwB;IAO1C;;;;OAIG;IACH,QAAQ,IAAI,oBAAoB;IAIhC;;;;OAIG;IACH,WAAW,IAAI,MAAM;IAIrB;;;;OAIG;IACH,OAAO,IAAI,OAAO;IAIlB;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAa9B;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAUf,OAAO,CAAC,cAAc;CAWvB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GACzC,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAY3C;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,oBAAoB,EAC7B,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACzD,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/prompt-signals/cache.js

@@ -13,10 +13,112 @@
  *
  * @module @co-engram/core/prompt-signals
  */
+import { EMPTY_PROMPT_SIGNALS } from "./types.js";
 /**
  * 缓存文件名
  */
 export const PROMPT_SIGNALS_FILENAME = "prompt-signals.json";
+/**
+ * 事件驱动的 invalidating cache(Task 3.4 root cause AD)
+ *
+ * 旧实现:prompt-builder 直接读 prompt-signals.json,只在 maintenance light stage
+ * 周期跑(默认 5min)时刷新。engram_create / synapse_create / proposal accept 等
+ * 操作不会立即触发刷新,导致"刚创建的 engram 没出现在下次 prompt 的 topTags"。
+ *
+ * 新实现:cache 订阅 PromptSignalBus,任何相关事件都标记 stale + debounced rebuild,
+ * 保证下一次 promptBuilder.snapshot() 拿到最新数据。
+ *
+ * 失败策略:rebuild 抛错时保留旧 snapshot 并清掉 stale 标记(避免无限重试);
+ * 调用方可通过 getRevision() 观察是否真的更新过。
+ */
+export class PromptSignalCache {
+    snapshotValue;
+    revisionValue = 0;
+    staleValue = false;
+    debounceMs;
+    rebuildFn;
+    unsubscribe;
+    pendingTimer = null;
+    disposed = false;
+    constructor(opts) {
+        this.snapshotValue = opts.initialSnapshot ?? EMPTY_PROMPT_SIGNALS;
+        this.debounceMs = opts.debounceMs ?? 200;
+        this.rebuildFn = opts.rebuild;
+        this.unsubscribe = opts.bus.on(() => this.handleBusEvent());
+    }
+    /**
+     * 当前 snapshot 引用
+     *
+     * rebuild 成功后引用会替换,消费方可以用引用相等检测是否需要重读。
+     */
+    snapshot() {
+        return this.snapshotValue;
+    }
+    /**
+     * rebuild 次数(成功才递增)
+     *
+     * 用于测试断言和监控:revision 没动 = 数据没变。
+     */
+    getRevision() {
+        return this.revisionValue;
+    }
+    /**
+     * 是否有事件触发但还未 rebuild 完成
+     *
+     * true 表示当前 snapshot 可能过时。
+     */
+    isStale() {
+        return this.staleValue;
+    }
+    /**
+     * 手动触发 rebuild(忽略 stale 状态)
+     *
+     * 成功 → revision++ + 替换 snapshot + 清 stale;
+     * 失败 → 保留旧 snapshot + 清 stale(避免无限重试),不抛错。
+     */
+    async rebuild() {
+        if (this.disposed)
+            return;
+        try {
+            const fresh = await this.rebuildFn();
+            this.snapshotValue = fresh;
+            this.revisionValue += 1;
+        }
+        catch {
+            // 静默失败:保留旧 snapshot,清 stale 避免下一轮立刻重试
+        }
+        finally {
+            this.staleValue = false;
+        }
+    }
+    /**
+     * 停止接收 bus 事件,清掉 pending timer
+     *
+     * dispose 后再调用 rebuild() 是 noop,snapshot() 返回最后一次成功的值。
+     */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.unsubscribe();
+        if (this.pendingTimer !== null) {
+            clearTimeout(this.pendingTimer);
+            this.pendingTimer = null;
+        }
+    }
+    handleBusEvent() {
+        if (this.disposed)
+            return;
+        this.staleValue = true;
+        if (this.pendingTimer !== null) {
+            clearTimeout(this.pendingTimer);
+        }
+        this.pendingTimer = setTimeout(() => {
+            this.pendingTimer = null;
+            void this.rebuild();
+        }, this.debounceMs);
+    }
+}
 /**
  * 读取 prompt signals 缓存
  *

package/dist/prompt-signals/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/prompt-signals/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAgB,EAChB,MAA0C;IAE1C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,uBAAuB,CAAC,CAAC;QACvE,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;QAC1E,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAyB,CAAC;QAC3D,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;YACjE,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAgB,EAChB,OAA6B,EAC7B,OAA0D;IAE1D,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,uBAAuB,CAAC,CAAC;IACvE,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;IACxD,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC7B,OAAO;IACT,CAAC;IACD,MAAM,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACxC,CAAC;AAED,0BAA0B;AAE1B,KAAK,UAAU,eAAe,CAAC,IAAY;IACzC,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;IACtD,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC;AAED,KAAK,UAAU,gBAAgB,CAAC,IAAY,EAAE,OAAe;IAC3D,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;IAC9D,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;IAC9C,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,QAAQ,CAAC,GAAG,QAAkB;IACrC,OAAO,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AACjE,CAAC"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/prompt-signals/cache.ts"],"names":[],"mappings":"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"}

package/dist/prompt-signals/event-bus.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Prompt signals 事件总线(Task 3.4)
+ *
+ * 15 轮拉通分析 root cause AD「prompt 提示不刷新」的核心修复:
+ * 仓库状态变化(engram 创建/验证/reinforce、synapse 创建、proposal 决议、
+ * doctor 完成)应触发 prompt-signals 缓存失效并 debounced rebuild,
+ * 让下一次 prompt build 看到最新 signals。
+ *
+ * 设计:
+ *   - 基于 Node EventEmitter,零依赖
+ *   - 类型安全:event.type 是有限枚举,拼错编译期 fail
+ *   - on() 返回 unsubscribe,便于 cache.dispose() 解绑
+ *
+ * Phase A 只交付原语(event bus + cache class);
+ * Phase B 把 emit 点接入 close_learning_loop / synapse_create / repository 等。
+ *
+ * @module @co-engram/core/prompt-signals
+ */
+/**
+ * 触发 prompt-signals 失效的事件类型
+ *
+ * 每种事件对应一个"会改变 topTags / missedTopics / lowConfidenceTopics"的仓库操作:
+ *   - engram_created / engram_updated / engram_verified / engram_reinforced /
+ *     engram_failed:engram 增删改、验证状态变化、强化或失败信号
+ *   - synapse_created:新增 synapse 影响 graph 结构和 domain profile
+ *   - proposal_accepted / proposal_dismissed:proposal 决议改变 engram 集合
+ *   - doctor_completed:doctor 可能 sweep/forget,engram 集合变化
+ */
+export type PromptSignalEventType = "engram_created" | "engram_updated" | "engram_verified" | "engram_reinforced" | "engram_failed" | "synapse_created" | "proposal_accepted" | "proposal_dismissed" | "doctor_completed";
+/**
+ * 一条 prompt signal 事件
+ *
+ * engramId 可选:某些事件(如 doctor_completed)不针对单个 engram。
+ * at 是 ISO timestamp,由 emit 方填入(便于审计/调试)。
+ */
+export interface PromptSignalEvent {
+    readonly type: PromptSignalEventType;
+    readonly engramId?: string;
+    readonly at: string;
+}
+/**
+ * Prompt signals 事件总线
+ *
+ * 用法:
+ *   const bus = new PromptSignalBus();
+ *   const unsubscribe = bus.on((event) => console.log(event));
+ *   bus.emit({ type: "engram_created", engramId: "E1", at: new Date().toISOString() });
+ *   unsubscribe();
+ */
+export declare class PromptSignalBus {
+    private readonly emitter;
+    constructor();
+    /**
+     * 发布事件,同步通知所有订阅者
+     *
+     * 同步语义让 emit 方能在调试时立刻看到效果;
+     * cache 订阅者收到事件后会自己调度 debounced rebuild(异步)。
+     */
+    emit(event: PromptSignalEvent): void;
+    /**
+     * 订阅事件
+     *
+     * @returns unsubscribe 函数,调用后停止接收事件
+     */
+    on(handler: (event: PromptSignalEvent) => void): () => void;
+}
+export declare function getGlobalPromptSignalBus(): PromptSignalBus;
+/**
+ * 测试辅助:重置 singleton bus(让每个 test 隔离)
+ *
+ * 生产代码不应调用。cache.dispose() 不会自动调用此函数——
+ * 进程退出即清理,无需手动 reset。
+ */
+export declare function resetGlobalPromptSignalBus(): void;
+/**
+ * 安全 emit:任何异常都吞掉(bus 不应阻塞业务路径)
+ *
+ * 失败场景:listener 抛错(EventEmitter 默认会 uncaught),bus 写审计落盘失败,等。
+ * prompt signals 是派生数据,丢失一次刷新无影响——下次事件触发会再 rebuild。
+ */
+export declare function safeEmit(event: PromptSignalEvent): void;
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/prompt-signals/event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/prompt-signals/event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,GAC7B,gBAAgB,GAChB,gBAAgB,GAChB,iBAAiB,GACjB,mBAAmB,GACnB,eAAe,GACf,iBAAiB,GACjB,mBAAmB,GACnB,oBAAoB,GACpB,kBAAkB,CAAC;AAEvB;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;;IAO9C;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAIpC;;;;OAIG;IACH,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI;CAM5D;AAsBD,wBAAgB,wBAAwB,IAAI,eAAe,CAK1D;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAIjD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAMvD"}

package/dist/prompt-signals/event-bus.js

@@ -0,0 +1,105 @@
+/**
+ * Prompt signals 事件总线(Task 3.4)
+ *
+ * 15 轮拉通分析 root cause AD「prompt 提示不刷新」的核心修复:
+ * 仓库状态变化(engram 创建/验证/reinforce、synapse 创建、proposal 决议、
+ * doctor 完成)应触发 prompt-signals 缓存失效并 debounced rebuild,
+ * 让下一次 prompt build 看到最新 signals。
+ *
+ * 设计:
+ *   - 基于 Node EventEmitter,零依赖
+ *   - 类型安全:event.type 是有限枚举,拼错编译期 fail
+ *   - on() 返回 unsubscribe,便于 cache.dispose() 解绑
+ *
+ * Phase A 只交付原语(event bus + cache class);
+ * Phase B 把 emit 点接入 close_learning_loop / synapse_create / repository 等。
+ *
+ * @module @co-engram/core/prompt-signals
+ */
+import { EventEmitter } from "node:events";
+/**
+ * Prompt signals 事件总线
+ *
+ * 用法:
+ *   const bus = new PromptSignalBus();
+ *   const unsubscribe = bus.on((event) => console.log(event));
+ *   bus.emit({ type: "engram_created", engramId: "E1", at: new Date().toISOString() });
+ *   unsubscribe();
+ */
+export class PromptSignalBus {
+    emitter = new EventEmitter();
+    constructor() {
+        // prompt signals 不需要无限 listener,SetMaxListeners 避免开发期警告
+        this.emitter.setMaxListeners(20);
+    }
+    /**
+     * 发布事件,同步通知所有订阅者
+     *
+     * 同步语义让 emit 方能在调试时立刻看到效果;
+     * cache 订阅者收到事件后会自己调度 debounced rebuild(异步)。
+     */
+    emit(event) {
+        this.emitter.emit("signal", event);
+    }
+    /**
+     * 订阅事件
+     *
+     * @returns unsubscribe 函数,调用后停止接收事件
+     */
+    on(handler) {
+        this.emitter.on("signal", handler);
+        return () => {
+            this.emitter.off("signal", handler);
+        };
+    }
+}
+// ============================================================
+// Task 3.4 Phase B:进程级 singleton bus
+// ============================================================
+/**
+ * 进程级 singleton PromptSignalBus
+ *
+ * 设计权衡:
+ *   - 选 singleton 而非 DI:repository / proposalEngine / closeLearningLoop
+ *     都是高频核心路径,加 bus 参数会污染所有调用方签名。
+ *   - 进程内一致即可:prompt-signals 是宿主进程内部的派生缓存,
+ *     不跨进程、不持久化,singleton 不会引入全局状态污染问题。
+ *   - 测试隔离:resetGlobalPromptSignalBus() 让每个 test 拿干净 bus。
+ *
+ * 用法:
+ *   import { getGlobalPromptSignalBus } from ".../prompt-signals";
+ *   getGlobalPromptSignalBus().emit({ type: "engram_created", engramId, at });
+ */
+let globalPromptSignalBus = null;
+export function getGlobalPromptSignalBus() {
+    if (globalPromptSignalBus === null) {
+        globalPromptSignalBus = new PromptSignalBus();
+    }
+    return globalPromptSignalBus;
+}
+/**
+ * 测试辅助:重置 singleton bus(让每个 test 隔离)
+ *
+ * 生产代码不应调用。cache.dispose() 不会自动调用此函数——
+ * 进程退出即清理,无需手动 reset。
+ */
+export function resetGlobalPromptSignalBus() {
+    if (globalPromptSignalBus !== null) {
+        globalPromptSignalBus = null;
+    }
+}
+/**
+ * 安全 emit:任何异常都吞掉(bus 不应阻塞业务路径)
+ *
+ * 失败场景:listener 抛错(EventEmitter 默认会 uncaught),bus 写审计落盘失败,等。
+ * prompt signals 是派生数据,丢失一次刷新无影响——下次事件触发会再 rebuild。
+ */
+export function safeEmit(event) {
+    try {
+        getGlobalPromptSignalBus().emit(event);
+    }
+    catch {
+        // intentional:bus 失败不阻塞业务
+    }
+}
+//# sourceMappingURL=event-bus.js.map

package/dist/prompt-signals/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../src/prompt-signals/event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAmC3C;;;;;;;;GAQG;AACH,MAAM,OAAO,eAAe;IACT,OAAO,GAAG,IAAI,YAAY,EAAE,CAAC;IAE9C;QACE,wDAAwD;QACxD,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,KAAwB;QAC3B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACH,EAAE,CAAC,OAA2C;QAC5C,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACnC,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACtC,CAAC,CAAC;IACJ,CAAC;CACF;AAED,+DAA+D;AAC/D,qCAAqC;AACrC,+DAA+D;AAE/D;;;;;;;;;;;;;GAaG;AACH,IAAI,qBAAqB,GAA2B,IAAI,CAAC;AAEzD,MAAM,UAAU,wBAAwB;IACtC,IAAI,qBAAqB,KAAK,IAAI,EAAE,CAAC;QACnC,qBAAqB,GAAG,IAAI,eAAe,EAAE,CAAC;IAChD,CAAC;IACD,OAAO,qBAAqB,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B;IACxC,IAAI,qBAAqB,KAAK,IAAI,EAAE,CAAC;QACnC,qBAAqB,GAAG,IAAI,CAAC;IAC/B,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAwB;IAC/C,IAAI,CAAC;QACH,wBAAwB,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,0BAA0B;IAC5B,CAAC;AACH,CAAC"}

package/dist/prompt-signals/index.d.ts

@@ -8,5 +8,6 @@
 export type { PromptSignalSnapshot, PromptSignalStats } from "./types.js";
 export { EMPTY_PROMPT_SIGNALS } from "./types.js";
 export { computePromptSignals, type ComputePromptSignalsOptions, } from "./stats.js";
-export { readPromptSignals, writePromptSignals, PROMPT_SIGNALS_FILENAME, } from "./cache.js";
+export { readPromptSignals, writePromptSignals, PROMPT_SIGNALS_FILENAME, PromptSignalCache, type PromptSignalCacheOptions, } from "./cache.js";
+export { PromptSignalBus, type PromptSignalEvent, type PromptSignalEventType, getGlobalPromptSignalBus, resetGlobalPromptSignalBus, safeEmit, } from "./event-bus.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompt-signals/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EACL,oBAAoB,EACpB,KAAK,2BAA2B,GACjC,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompt-signals/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EACL,oBAAoB,EACpB,KAAK,2BAA2B,GACjC,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,KAAK,wBAAwB,GAC9B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,wBAAwB,EACxB,0BAA0B,EAC1B,QAAQ,GACT,MAAM,gBAAgB,CAAC"}

package/dist/prompt-signals/index.js

@@ -7,5 +7,6 @@
  */
 export { EMPTY_PROMPT_SIGNALS } from "./types.js";
 export { computePromptSignals, } from "./stats.js";
-export { readPromptSignals, writePromptSignals, PROMPT_SIGNALS_FILENAME, } from "./cache.js";
+export { readPromptSignals, writePromptSignals, PROMPT_SIGNALS_FILENAME, PromptSignalCache, } from "./cache.js";
+export { PromptSignalBus, getGlobalPromptSignalBus, resetGlobalPromptSignalBus, safeEmit, } from "./event-bus.js";
 //# sourceMappingURL=index.js.map

package/dist/prompt-signals/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompt-signals/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EACL,oBAAoB,GAErB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompt-signals/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EACL,oBAAoB,GAErB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,GAElB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EAGf,wBAAwB,EACxB,0BAA0B,EAC1B,QAAQ,GACT,MAAM,gBAAgB,CAAC"}

package/dist/reinforcement/ltp.d.ts

@@ -48,8 +48,22 @@ export declare function recordRetrievalSuccess(repo: EngramRepository, id: strin
  *
  * 用于 Hebbian 间接强化（邻居得到增益时），
  * 或外部队列触发的批量强化（如 Dreaming 周期）。
+ *
+ * P0-9 修复:Hebbian 邻居联动此前是"幽灵强化" —— 只改 importance,但
+ * effectiveRetrievals / retrievalCount / reinforcementScore 全为 0,且
+ * audit_log 无任何 reinforce 记录。新增 `withStats` 选项让邻居联动也走
+ * 完整统计更新(语义上,邻居被"间接有效检索")。
  */
-export declare function reinforceEngram(repo: EngramRepository, id: string, amount: number, nowIso?: string): {
+export declare function reinforceEngram(repo: EngramRepository, id: string, amount: number, nowIso?: string, options?: {
+    /**
+     * 是否同时更新 retrievalCount/effectiveRetrievals/reinforcementScore。
+     * 默认 false(向后兼容:Dreaming 周期批量强化不应污染检索统计)。
+     * Hebbian 邻居联动应传 true(P0-9:让邻居统计字段可观察)。
+     */
+    readonly withStats?: boolean;
+    /** 邻居联动的 effectiveness 值(默认 = amount,即把 importance 增益视作 effectiveness) */
+    readonly effectiveness?: number;
+}): {
     id: string;
     importanceDelta: number;
     importance: number;

package/dist/reinforcement/ltp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ltp.d.ts","sourceRoot":"","sources":["../../src/reinforcement/ltp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,gBAAgB,EACtB,EAAE,EAAE,MAAM,EACV,aAAa,EAAE,MAAM,EACrB,MAAM,GAAE,mBAAoC,EAC5C,MAAM,GAAE,MAAiC,GACxC,SAAS,CA0BX;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,gBAAgB,EACtB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,MAAiC,GACxC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAiB7D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,mBAAmB,SAAI,EACvB,MAAM,GAAE,mBAAoC,GAC3C,MAAM,CAOR"}
+{"version":3,"file":"ltp.d.ts","sourceRoot":"","sources":["../../src/reinforcement/ltp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,gBAAgB,EACtB,EAAE,EAAE,MAAM,EACV,aAAa,EAAE,MAAM,EACrB,MAAM,GAAE,mBAAoC,EAC5C,MAAM,GAAE,MAAiC,GACxC,SAAS,CA0BX;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,gBAAgB,EACtB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,MAAiC,EACzC,OAAO,GAAE;IACP;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CAC5B,GACL;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CA8B7D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,mBAAmB,SAAI,EACvB,MAAM,GAAE,mBAAoC,GAC3C,MAAM,CAOR"}

package/dist/reinforcement/ltp.js

@@ -63,18 +63,37 @@ export function recordRetrievalSuccess(repo, id, effectiveness, config = DEFAULT
  *
  * 用于 Hebbian 间接强化（邻居得到增益时），
  * 或外部队列触发的批量强化（如 Dreaming 周期）。
+ *
+ * P0-9 修复:Hebbian 邻居联动此前是"幽灵强化" —— 只改 importance,但
+ * effectiveRetrievals / retrievalCount / reinforcementScore 全为 0,且
+ * audit_log 无任何 reinforce 记录。新增 `withStats` 选项让邻居联动也走
+ * 完整统计更新(语义上,邻居被"间接有效检索")。
  */
-export function reinforceEngram(repo, id, amount, nowIso = new Date().toISOString()) {
+export function reinforceEngram(repo, id, amount, nowIso = new Date().toISOString(), options = {}) {
     if (!repo.exists(id)) {
         throw new Error(`Engram not found: ${id}`);
     }
     if (amount < 0) {
         throw new Error(`amount must be >= 0, got ${amount}`);
     }
-    repo.bumpRetrievalStats(id, {
-        importanceDelta: amount,
-        lastEffectiveAt: nowIso,
-    });
+    const withStats = options.withStats ?? false;
+    const effectiveness = options.effectiveness ?? amount;
+    if (withStats) {
+        repo.bumpRetrievalStats(id, {
+            retrievedDelta: 1,
+            effectiveDelta: 1,
+            reinforcementDelta: effectiveness,
+            importanceDelta: amount,
+            lastRetrievedAt: nowIso,
+            lastEffectiveAt: nowIso,
+        });
+    }
+    else {
+        repo.bumpRetrievalStats(id, {
+            importanceDelta: amount,
+            lastEffectiveAt: nowIso,
+        });
+    }
     const updated = repo.readEngram(id);
     return {
         id,

package/dist/reinforcement/ltp.js.map

@@ -1 +1 @@
-{"version":3,"file":"ltp.js","sourceRoot":"","sources":["../../src/reinforcement/ltp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAE,cAAc,EAA4B,MAAM,aAAa,CAAC;AAYvE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAsB,EACtB,EAAU,EACV,aAAqB,EACrB,SAA8B,cAAc,EAC5C,SAAiB,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;IAEzC,IAAI,aAAa,GAAG,CAAC,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,uCAAuC,aAAa,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC;IAC7C,CAAC;IACD,MAAM,eAAe,GAAG,aAAa,GAAG,MAAM,CAAC,OAAO,CAAC;IACvD,IAAI,CAAC,kBAAkB,CAAC,EAAE,EAAE;QAC1B,cAAc,EAAE,CAAC;QACjB,cAAc,EAAE,CAAC;QACjB,kBAAkB,EAAE,aAAa;QACjC,eAAe;QACf,eAAe,EAAE,MAAM;QACvB,eAAe,EAAE,MAAM;KACxB,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACpC,OAAO;QACL,EAAE;QACF,eAAe;QACf,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,cAAc,EAAE,OAAO,CAAC,cAAc;QACtC,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;QAChD,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;QAC9C,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,MAAM;KACnD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAsB,EACtB,EAAU,EACV,MAAc,EACd,SAAiB,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;IAEzC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,IAAI,CAAC,kBAAkB,CAAC,EAAE,EAAE;QAC1B,eAAe,EAAE,MAAM;QACvB,eAAe,EAAE,MAAM;KACxB,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACpC,OAAO;QACL,EAAE;QACF,eAAe,EAAE,MAAM;QACvB,UAAU,EAAE,OAAO,CAAC,UAAU;KAC/B,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAc,EACd,KAAa,EACb,mBAAmB,GAAG,CAAC,EACvB,SAA8B,cAAc;IAE5C,IAAI,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,UAAU,IAAI,mBAAmB,GAAG,MAAM,CAAC,OAAO,CAAC;QACnD,IAAI,UAAU,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;AACjC,CAAC"}
+{"version":3,"file":"ltp.js","sourceRoot":"","sources":["../../src/reinforcement/ltp.ts"],"names":[],"mappings":"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"}

package/dist/reinforcement/related.d.ts

@@ -12,11 +12,20 @@
  *
  * 与 ltp.ts 的关系：
  *   - ltp.recordRetrievalSuccess：直接强化单个 engram
- *   - related.reinforceRelated：触发 ltp 后，对邻居做 reinforceEngram（不更新统计）
+ *   - related.reinforceRelated：触发 ltp 后，对邻居做 reinforceEngram
+ *
+ * P0-9 修复:此前邻居联动是"幽灵强化" —— 邻居 importance 被改但
+ *   (a) effectiveRetrievals/retrievalCount/reinforcementScore 全为 0
+ *   (b) audit_log 无任何 reinforce 记录(查 action:reinforce, engramId:B 永远空)
+ *   (c) 也不知道是哪个 engram 触发的联动
+ * 现在通过 options.auditLog + options.triggeredBy 让联动可观察:
+ *   - reinforceEngram 传 withStats:true 让统计字段同步更新
+ *   - auditLog.append({action:"reinforce", engramId:邻居, metadata:{triggeredBy, sourceImportanceDelta, ...}})
  *
  * @module @co-engram/core/reinforcement
  */
 import type { EngramRepository } from "../storage/repository.js";
+import type { AuditLog } from "../observability/audit-log.js";
 import { type ReinforcementConfig } from "./config.js";
 export interface ReinforceRelatedResult {
     /** 被强化的邻居 id 列表 */
@@ -26,6 +35,25 @@ export interface ReinforceRelatedResult {
     /** 给每个邻居的 importanceDelta */
     readonly importanceDeltaPerNeighbor: number;
 }
+/** reinforceRelated 的可选参数 */
+export interface ReinforceRelatedOptions {
+    /**
+     * 触发此次联动的源 engram id(等于 reinforceRelated 的 engramId 参数)。
+     * 用于 audit metadata,让邻居能追溯"我为什么被强化"。
+     */
+    readonly triggeredBy?: string;
+    /**
+     * 触发此次联动的工具/路径(如 "reinforce" / "close_learning_loop")。
+     * 用于 audit metadata,便于过滤不同来源的联动。
+     */
+    readonly triggerTool?: string;
+    /**
+     * 若提供,对每个被强化的邻居写一条 reinforce audit(解决 P0-9 幽灵强化)。
+     */
+    readonly auditLog?: AuditLog;
+    /** 宿主标识(透传到 audit entry) */
+    readonly host?: "claude-code-mcp" | "openclaw-plugin" | string;
+}
 /**
  * 对邻居执行 Hebbian 强化
  *
@@ -34,6 +62,7 @@ export interface ReinforceRelatedResult {
  * @param baseImportanceDelta - 原始 engram 得到的 importanceDelta
  * @param config - 配置（可选）
  * @param nowIso - 当前时间
+ * @param options - P0-9 修复:可选 auditLog + triggeredBy,让联动可观察
  */
-export declare function reinforceRelated(repo: EngramRepository, engramId: string, baseImportanceDelta: number, config?: ReinforcementConfig, nowIso?: string): ReinforceRelatedResult;
+export declare function reinforceRelated(repo: EngramRepository, engramId: string, baseImportanceDelta: number, config?: ReinforcementConfig, nowIso?: string, options?: ReinforceRelatedOptions): ReinforceRelatedResult;
 //# sourceMappingURL=related.d.ts.map

package/dist/reinforcement/related.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"related.d.ts","sourceRoot":"","sources":["../../src/reinforcement/related.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAQvE,MAAM,WAAW,sBAAsB;IACrC,mBAAmB;IACnB,QAAQ,CAAC,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;IAClD,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6BAA6B;IAC7B,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC;CAC7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,MAAM,EAChB,mBAAmB,EAAE,MAAM,EAC3B,MAAM,GAAE,mBAAoC,EAC5C,MAAM,GAAE,MAAiC,GACxC,sBAAsB,CA4DxB"}
+{"version":3,"file":"related.d.ts","sourceRoot":"","sources":["../../src/reinforcement/related.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAQvE,MAAM,WAAW,sBAAsB;IACrC,mBAAmB;IACnB,QAAQ,CAAC,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;IAClD,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6BAA6B;IAC7B,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC;CAC7C;AAED,6BAA6B;AAC7B,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,MAAM,CAAC;CAChE;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,MAAM,EAChB,mBAAmB,EAAE,MAAM,EAC3B,MAAM,GAAE,mBAAoC,EAC5C,MAAM,GAAE,MAAiC,EACzC,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAwFxB"}