@x-otto/memory 0.0.1-alpha.2 → 0.0.1-alpha.4

package/dist/index.d.ts

@@ -1,5 +1,42 @@
 import { Message } from "@x-otto/interchange";
 
+//#region src/compaction-truncation.d.ts
+declare function formatMessageForSummary(msg: Message): string;
+/**
+ * RFC-381 M3：压缩阶段 spill 端口（可选）。超大可再生 tool_result 在截断前先全文落盘，
+ * 返回路径字符串；返回 undefined = 无端口/失败（fail-open 退回内存截断）。
+ * 实现侧复用执行时 spill（tool-result-store），与 prune.ts 的 SPILL_MARKER 占位符同格式。
+ */
+type CompactionSpillSink = (toolCallId: string, text: string) => Promise<string | undefined>;
+//#endregion
+//#region src/coverage-governor.d.ts
+/**
+ * coverage-governor.ts —— RFC-324 D3 M3：摘要覆盖率闭环状态（per-session）。
+ *
+ * 从 `compaction.ts` 模块级 Map 迁出（RFC-394 M1）：coverage 递推状态归属实例，
+ * 消除模块级可变全局状态（多实例交叉污染隐患 + 自由函数隐藏状态依赖 + 测试需
+ * 手动清理全局 Map）。M2 将随 CompactionBackend 构造注入。
+ *
+ * 语义（RFC-324 D3 M3）：上次压缩 coverage < warn/error 时，下次压缩调大批次上限
+ * （每批更小源内容 → 提高覆盖率）。**仅递推一次**（consume 后清零），避免持续
+ * 放大导致批次数无界。
+ */
+declare class CoverageGovernor {
+  /** per-session 调大批次数（正常值 0 = 不调整）。 */
+  private readonly boostedBySession;
+  /** 指定 session 的调大批次数（正常值 0 = 不调整）。 */
+  get(sessionId: string): number;
+  /**
+   * 记录本次压缩 coverage，供下次压缩调批次上限（RFC-324 D3 M3）。
+   * coverage < error → 双重调大（x2，下限 16）；error..warn → 调大（+2）；>= warn → 不干预。
+   */
+  record(coverage: number, currentBatches: number, sessionId: string, errorThreshold: number, warnThreshold: number): void;
+  /** 读取并清零（仅递推一次）。delete 而非 set(0)——值归 0 时 key 永久残留（08-12 review W4）。 */
+  consume(sessionId: string): number;
+  /** 会话销毁时清理其条目（MemoryManager.forgetSession 调用）——覆盖「set 后未 consume 即 forget」的残留。 */
+  forget(sessionId: string): void;
+}
+//#endregion
 //#region src/types.d.ts
 /**
  * 触发阈值的三种表达。
@@ -36,10 +73,30 @@ interface PruneConfig {
    * 裁掉=真实信息损失。空列表 = 不裁任何 tool_result。
    */
   regenerableTools: string[];
+  /**
+   * RFC-437 D2：可再生名单的**惰性 getter**（可选）——每次 prune 实时读取，与静态
+   * `regenerableTools` 并集（getter 为工具声明真源，静态名单回退兜底 legacy 名）。
+   * 由装配侧注入 `() => toolRegistry.listRegenerableNames()`：内置 + 插件工具的
+   * `regenerableOutput: true` 声明即时生效（插件晚于 memory 构造装载也能被 prune
+   * 看见）。缺省未提供 = 现状行为逐字节不变。
+   */
+  regenerableToolNames?: () => string[];
   /** 二次保护:即便在 regenerableTools 内,列入此处的工具仍不裁(覆盖)。 */
   protectedTools: string[];
   truncateTools: string[];
   truncateMaxLength: number;
+  /**
+   * RFC review D8：时间基 microcompact（可选，缺省 disabled = 零行为变化）。
+   * 参照 CC `timeBasedMCConfig.ts`：距最后一条 assistant 消息的 gap 超过阈值（默认 60min，
+   * 服务端 1h prompt cache 必过期）→ 下一轮请求前清旧 tool_result，保留最近 keepRecent 条。
+   * 与 token 触发正交（OR 关系）——时间触发不依赖上下文大小，cache 过期窗口内任何旧
+   * 工具输出重写都是纯收益。
+   */
+  timeBased?: {
+    enabled?: boolean; /** gap 阈值（ms）。默认 60min。 */
+    gapThresholdMs?: number; /** 保留最近 N 条 compactable tool_result（更早的全部裁）。缺省 5。 */
+    keepRecent?: number;
+  };
 }
 interface PruneResult {
   messages: Message[];
@@ -79,15 +136,66 @@ interface CompactionConfig {
    */
   coverageErrorThreshold?: number;
   /**
-   * RFC-340 D1：摘要覆盖率**硬下限**。低于此值时 `MemoryManager.process()` 不建立
-   * 压缩边界（视同本轮压缩未发生），阻断"摘要未覆盖的历史被 `capStoredHistory`
-   * 当作死历史物理删除"这条不可逆损失路径。缺省 `MEMORY_COVERAGE_FLOOR_THRESHOLD`（0.3）。
+   * RFC-340 D1：摘要覆盖率**硬下限**。低于此值时摘要正文前置"低保真"标注
+   * （`buildLowCoverageNotice`），如实告知模型这段摘要并不完整——边界照常建立。
+   * （一版设计"低于 floor 即不建边界"已被 RFC-321 M6/C1 回归测试证伪：不建边界 →
+   * escapeValveFailures 累加 → 放行 lossy 裸裁剪，比 6% 覆盖的摘要严格更差。）
+   * 缺省 `MEMORY_COVERAGE_FLOOR_THRESHOLD`（0.3）。
    *
    * 不变式 `floor ≤ error ≤ warn`——floor 是叠加在既有 warn/error 递推之上的**新档位**，
    * 不替换它们（RFC-340 规则 4）。接线层负责钳制，防配置写反导致档位失效。
    */
   coverageFloorThreshold?: number;
   customInstructions?: string;
+  /**
+   * RFC-387 前缀复用开关（2026-08-14 M2b 方案 A 修订）。true 时 compact() 的全部
+   * summarize 调用点携带 `prefix`（单批带 sessionId+messages；map/merge/turn-prefix
+   * 仅 sessionId）——装配方据 sessionId 查 wire 快照、原样重放 system 分段 + tools +
+   * cacheRetention（消息仍在指令文本内）。缺省 false = 现状行为逐字节不变。
+   */
+  prefixReuse?: boolean;
+  /**
+   * RFC-436 G2：压缩请求前缀的 cacheRetention 档位（TTL 决定前缀能否命中 provider
+   * KV 缓存）。**不随正常轮次快照**——压缩是低频大 prefill 操作，正常轮次非交互模式
+   * 用 'short'（5min TTL），压缩距上轮请求通常远超 5 分钟，随快照必然过期（前缀复用
+   * 形同虚设）。缺省 'long'（1h TTL，DEFAULT_COMPACTION_CONFIG 定义）。宿主可按场景
+   * 覆盖（如 provider 对 long 收费异常时临时切 'short'）。
+   */
+  cacheRetention?: CompactionCacheRetention;
+}
+/**
+ * RFC-436 G2：压缩请求前缀 TTL 档位（与 provider 侧 CacheRetention 结构兼容，
+ * memory 是叶包不依赖 provider，本地定义联合类型）。
+ */
+type CompactionCacheRetention = 'none' | 'short' | 'long';
+/**
+ * RFC-387 D1：压缩请求的可缓存前缀（wire 形态快照的子集）。
+ *
+ * - `messages`：待摘要消息原样重放——**不得改写任何消息内容**（RFC-142 R1 强化面）；
+ * - `systemPromptSegments`/`tools`/`modelId`：由调用方（M2b 快照）在装配时合并，
+ *   memory 侧只透传不消费（交接契约：快照的 wire 消息形态与 compact() 切点对齐是
+ *   M2b 的字节门禁）。
+ */
+interface CompactionPrefix {
+  /**
+   * RFC-387 M2b（方案 A）：压缩所属会话 id——装配方据此查 wire 快照
+   * （system 分段 + tools + cacheRetention）。缺省 = 不装配（现状行为）。
+   */
+  sessionId?: string;
+  /**
+   * RFC-387 D5（消息级复用地基，M2b 方案 A 不消费）：待摘要消息原样引用。
+   * 仅单批路径传递；多批各批内容不同，不传。
+   */
+  messages?: readonly Message[];
+  /**
+   * RFC-436 G2：装配方用于压缩请求的 cacheRetention（缺省 'long'）。memory 侧
+   * 从 CompactionConfig.cacheRetention 注入；不随快照（快照是正常轮次的 retention，
+   * 对低频压缩请求 TTL 过短）。
+   */
+  cacheRetention?: CompactionCacheRetention;
+  systemPromptSegments?: readonly unknown[];
+  tools?: readonly unknown[];
+  modelId?: string;
 }
 interface CutPoint {
   firstKeptIndex: number;
@@ -135,6 +243,17 @@ interface ArchiveStorage {
    */
   forgetSession?(sessionId: string): void;
 }
+/**
+ * RFC-381 M1：跨进程 durable 压缩锁端口。
+ * 实现侧（runtime）写 session 树 `compaction-lock` entry（phase start/end + token，
+ * append-only 历史不可变）；本接口是 memory 包与实现之间的薄契约。
+ * - acquire 返回 false = 当前持锁（含孤儿锁未超时）→ 调用方跳过本轮压缩（下轮重试）；
+ * - release 幂等（end 已写/锁已被接管时 no-op 返回）。
+ */
+interface CompactionLockPort {
+  acquire(sessionId: string, token: string): Promise<boolean>;
+  release(sessionId: string, token: string): Promise<void>;
+}
 interface ArchiveEntry {
   path: string;
   timestamp: number;
@@ -172,6 +291,19 @@ interface ContextTokenEstimate {
 }
 interface MemoryManagerConfig {
   sources?: MemorySource[];
+  /**
+   * 确定性时钟端口（M-2）。缺省 = 真实系统时钟（行为不变）；replay/测试注入固定时钟，
+   * 使 prune gap 计算、压缩 token、归档时间戳等 Date.now() 派生路径可确定重放。
+   */
+  clock?: {
+    now(): number;
+  };
+  /**
+   * RFC-382 D1：索引条目文件 mtime 映射（key=`memory/<slug>.md`，与索引行括号内一致）。
+   * 由宿主（coding storage-wiring，有 fs 能力）在组装 sources 时 statSync 采集后注入；
+   * 缺省 undefined = 不折叠（remote/无本地 fs 场景 fail-open，见 buildMemoryInjection）。
+   */
+  entryMtimes?: Map<string, number>;
   memoryStore?: MemoryStore;
   compaction?: Partial<CompactionConfig>;
   prune?: Partial<PruneConfig>;
@@ -191,6 +323,11 @@ interface MemoryManagerConfig {
   summarize: (prompt: string, options?: {
     maxTokens?: number;
     signal?: AbortSignal;
+    /**
+     * RFC-387 D1：可选可缓存前缀。缺省 = 现状（prompt 含全部内容，逐字节等价）；
+     * 传入时实现方须把 `prefix` 原样置于 prompt 之前作为请求前缀（M2b 装配）。
+     */
+    prefix?: CompactionPrefix;
   }) => Promise<string>;
   estimateTokens?: (text: string) => number;
   model?: {
@@ -226,6 +363,20 @@ interface MemoryManagerConfig {
    * 模式对齐同文件的 `getContextWindow`/`getEstimatedBytes`（实现侧注入避免跨包依赖）。
    */
   getMaxContentBytes?: () => number | undefined;
+  /**
+   * RFC-381 M1：跨进程 durable 压缩锁（可选注入）。
+   * 有端口 → process() 压缩前 acquire（false = 他进程/本进程持锁，跳过本轮）、
+   * 压缩结束 finally release；无端口 → 退回进程内 Set（单进程向后兼容）。
+   * 实现侧（runtime）写 session 树 compaction-lock entry（start/end bracket + token），
+   * 崩溃后孤儿 start 可被检测接管。
+   */
+  compactionLock?: CompactionLockPort;
+  /**
+   * RFC-381 M3：压缩阶段 spill 端口（可选）。P3 可再生 tool_result 截断前先全文落盘 +
+   * 占位符（read 可恢复），压缩从有损丢弃升级为无损移出上下文。未注入 → 退回既有
+   * 内存头尾截断（与改动前行为一致）。
+   */
+  compactionSpill?: CompactionSpillSink;
   /**
    * RFC-324 D3：摘要覆盖率阈值的惰性读数。
    *
@@ -244,6 +395,28 @@ interface MemoryManagerConfig {
    * 读取器，跟随活跃会话）。与 `maxContentBytes` 配对注入，缺一不启用字节因子。
    */
   getEstimatedBytes?: () => number | undefined;
+  /**
+   * RFC-390 D2：provider 真实 input token 读数（惰性，跟随最近一轮 usage）。
+   *
+   * 注入后 `needsCompaction` 在 `estimateContextTokens` 的混合口径之外，
+   * 额外参考真实 input tokens——当真实 input（total 口径）已达软触发线 90%
+   * 时提前触发压缩，不等启发式估算追上。解决空响应轮 `record()` 跳过导致
+   * `lastTokenUsage` 滞后的盲区（模型返回空响应时 usage 不更新，估算可能仍判
+   * "不需压缩"，上下文继续膨胀到模型退化）。
+   *
+   * **坐标系（RFC-339 B1 教训）**：返回值是 **total 口径**（含 cache 前缀），
+   * 与 `estimateContextTokens` 的 `total` 同维度。软触发线 `triggerTokens`
+   * 是 bodyAfterPrefix 口径——使用时须换算：`realInput >= triggerTokens * 0.9`
+   * 是保守近似（realInput 含前缀，triggerTokens 不含——保守侧误差，不会误触发）。
+   * 未注入时回退纯估算（向后兼容）。
+   */
+  getRealInputTokens?: () => number | undefined;
+  /**
+   * RFC-394 M1：coverage 闭环状态（可选注入）。缺省 MemoryManager 自建实例。
+   * 注入面供测试读取 per-session boost 值（替代已删除的 `__getCoverageBoostedBatchesForTest`
+   * 测试后门）——测试创建 governor 传入并断言其状态；生产无需注入。
+   */
+  coverageGovernor?: CoverageGovernor;
 }
 interface MemoryDefaults {
   compaction: CompactionConfig;
@@ -254,13 +427,11 @@ interface MemoryDefaults {
 declare class MemoryManager {
   private readonly persistent;
   /**
-   * archive = session 派生视图——loadSessionEntries 就位时走 session 条目的
-   * compaction 边界间重建;未就位(无持久化/V 形态)时回退到 archiveStorage(InMemory)。
+   * RFC-394 M4：归档源——统一接口（替代原 archiveStorage + loadSessionEntries +
+   * messageFromEntry 三字段双路径 try/fallback）。构造期决定用哪个实现
+   * （SessionEntriesArchiveSource / InMemoryArchiveSource），不再运行时分支。
    */
-  private readonly archiveStorage;
-  private readonly loadSessionEntries?;
-  private readonly messageFromEntry?;
-  private readonly summarize;
+  private readonly archiveSource;
   private readonly estimateTokens;
   /** 构造时保留原始配置副本，供 reconfigure 用新窗口重算阈值。 */
   private readonly rawConfig;
@@ -274,9 +445,9 @@ declare class MemoryManager {
   /** RFC-321 M3：生效字节预算惰性读数（跟随 ResidencyGovernor 收紧档位）。 */
   private readonly getMaxContentBytes?;
   private readonly getEstimatedBytes?;
+  /** RFC-390 D2：provider 真实 input token 读数（惰性）。 */
+  private readonly getRealInputTokens?;
   private readonly previousSummaries;
-  /** archive Path 单调发号——每会话内独立(archive:{sessionId}:{1..N})。 */
-  private readonly archiveIdCounter;
   /**
    * 终局架构 review 建议优化项：并发 process() 门闩（per-session）。
    *
@@ -289,6 +460,25 @@ declare class MemoryManager {
    * 延后一轮），finally 保证异常路径也会复位。
    */
   private readonly compactionInFlight;
+  /** RFC-381 M1：跨进程 durable 压缩锁端口（可选；缺省退回进程内 Set）。 */
+  private readonly compactionLock?;
+  /**
+   * RFC-381 M3：压缩阶段 spill 端口（可选；缺省退回既有内存截断）。
+   * **公开只读**——生产链透传回归门（coding m13-storage-wiring.test.ts）断言此字段：
+   * App 组合根注入的 spill 必须真到达 MemoryManager（2026-08-14 曾发生断链：
+   * buildDefaultMemory 解构/传参漏了 compactionSpill，spill 静默失效）。
+   */
+  readonly compactionSpill?: CompactionSpillSink;
+  /** RFC-394 M1：coverage 闭环状态——实例归属（config 可注入供测试读取，缺省自建）。 */
+  private readonly coverageGovernor;
+  /** RFC-394 M2：压缩执行后端（策略与编排分离——本类只编排，执行归 backend）。 */
+  private readonly compactionBackend;
+  /** RFC-394 M3：压缩触发策略列表（OR 合并）。 */
+  private readonly compactionPolicies;
+  /** RFC-394 M3：裁剪触发策略列表（OR 合并）。 */
+  private readonly prunePolicies;
+  /** M-2：确定性时钟端口（缺省真实系统时钟）。 */
+  private readonly clock;
   constructor(config: MemoryManagerConfig);
   /**
    * `/clear`——驱逐本会话的滚动压缩摘要桶（L2 工作记忆）。L1 持久知识(persistent)
@@ -297,7 +487,7 @@ declare class MemoryManager {
   clearSession(sessionId?: string): void;
   /**
    * 审计修复:会话销毁/驱逐时遗忘其全部 per-session 状态——防三个 Map 在长跑进程中无界增长。
-   * 与 clearSession 不同:此处清 archiveIdCounter(会话终态,无再压缩可能)。
+   * 与 clearSession 不同:此处清 archive 会话终态数据(无再压缩可能)。
    */
   forgetSession(sessionId: string): void;
   /**
@@ -313,6 +503,14 @@ declare class MemoryManager {
    * prune/compaction 一切触发线均按此计算,避免构造期 model 未知导致的 200K 默认锁死。
    */
   private effectiveContextWindow;
+  /**
+   * 生效压缩配置——CompactionBackend 经 getConfig 惰性读取。
+   * 装配面：reconfigure 更新 + 生效窗口 + coverage 阈值惰性读（settings 在 App
+   * 构造后才 load，静态快照会永远是 undefined；未注入或字段缺省时回退 memory 侧常量）。
+   * RFC-394 M2：原 compact() 调用处的内联合并逻辑迁入此处，backend 只做
+   * `{ ...DEFAULT, ...getConfig() }` 兜底。
+   */
+  private effectiveCompactionConfig;
   /**
    * 主动检查当前消息量是否超过压缩触发线（基于 reconfigure 后的新窗口）；
    * 超过则 force-compact。用于模型切换时预防下一轮 413。
@@ -335,16 +533,22 @@ declare class MemoryManager {
   private pruneWith;
   needsCompaction(messages: readonly Message[]): boolean;
   /**
-   * 驻留（字节）维度是否已逼近预算——`needsCompaction` 的非 token 触发因子。
-   *
-   * 单独抽出的原因（RFC-321 R10，二轮实证）：字节因子与已删除的条数因子**同型死区**——
-   * 判定为真不代表切得动。`findCutPoint` 要求总 token ≥ keepRecent（窗口×0.1），大窗口下
-   * 「字节超预算但总 token 偏小」的形态（如少量大附件）会让 `prepareCompaction` 返回 null，
-   * 压缩静默不发生（实证：1M 窗口、200 条 × 1000 字符、字节因子触发 → compacted=false、
-   * LLM 调用 0）。故 `process()` 在**由驻留压力驱动**时同样启用 keepRecent 钳制，与
-   * 逃生阀 force 路径共用同一修法。
-   */
-  private residencyPressure;
+   * 驻留（字节）压力是否活跃——供 process() 的 force keepRecent 钳制与日志归因用。
+   * RFC-394 M3：直接用 ResidencyPolicy 判定（策略对象复用，不内联逻辑）。
+   */
+  private isResidencyPressureActive;
+  /**
+   * RFC-394 M3：触发判定上下文装配——一次性读取所有策略所需的状态（estimate /
+   * 生效窗口 / 配置 / 时钟 / realInputTokens / 字节预算 / 字节估算 / timeGapMs），
+   * 供所有策略共用，消除 needsCompaction 与 needsPruneWith 各自读状态的重复。
+   */
+  private buildTriggerContext;
+  /**
+   * RFC review D8 / RFC-394 M3：距最后一条带时间戳消息（user/tool_result/
+   * system_notification——assistant 消息由模型生成无 timestamp）的 gap（ms）。
+   * 单一真源（timeGapTriggered 与 pruneWith 共用，消除重复倒序遍历）。
+   */
+  private computeTimeGapMs;
   isEligibleForManualCompact(messages: readonly Message[]): boolean;
   /**
    * @param options.force RFC-321 R10：强制压缩语义下 keepRecent 钳制到当前总量一半，
@@ -356,9 +560,8 @@ declare class MemoryManager {
   }): CompactionPreparation | null;
   compact(preparation: CompactionPreparation, sessionId?: string, signal?: AbortSignal): Promise<CompactionResult>;
   /**
-   * 压缩归档单源（reused B1 缓存命中 / fresh LLM 压缩两路共用，memory-1 去重）：递增 per-session
-   * 归档序号 → 赋逻辑 `archive:<sessionId>:<idx>` → 仅当无 loadSessionEntries 重建器时落盘
-   * （有重建器则归档按需从会话条目还原，archivePath 只作逻辑引用）。
+   * RFC-394 M4：归档记录委托给 ArchiveSource（SessionEntriesArchiveSource 或
+   * InMemoryArchiveSource）——MemoryManager 不再做形态分支。
    */
   private recordCompactionArchive;
   process(messages: readonly Message[], sessionId?: string, signal?: AbortSignal, options?: {
@@ -379,11 +582,7 @@ declare class MemoryManager {
     };
   }>;
   listArchives(sessionId: string): Promise<ArchiveEntry[]>;
-  /** 从 session entries 的 compaction 节点枚举 ArchiveEntry 列表。 */
-  private listArchivesFromEntries;
   readArchive(archivePath: string): Promise<string>;
-  /** 从 session entries 的 compaction 边界间重建归档全文。 */
-  private readArchiveFromEntries;
   dispose(): void;
 }
 declare function createMemoryManager(config: MemoryManagerConfig): MemoryManager;
@@ -393,9 +592,13 @@ declare const DEFAULT_MEMORY_SOURCES: MemorySource[];
 declare class PersistentMemory {
   private readonly store;
   private readonly sources;
+  /** RFC-382 D1：索引条目 mtime 映射（见 MemoryManagerConfig.entryMtimes）。 */
+  private readonly entryMtimes?;
   private memories;
   private unwatch?;
-  constructor(store: MemoryStore, sources?: MemorySource[]);
+  constructor(store: MemoryStore, sources?: MemorySource[], /** RFC-382 D1：索引条目 mtime 映射（见 MemoryManagerConfig.entryMtimes）。 */
+
+  entryMtimes?: Map<string, number> | undefined);
   load(): Promise<void>;
   reload(): Promise<void>;
   getInjection(): string;
@@ -702,7 +905,8 @@ declare function estimateMessagesTokens(messages: readonly Message[], estimator?
 //#region src/prune.d.ts
 declare function prune(messages: readonly Message[], contextWindow: number, config?: Partial<PruneConfig>, estimator?: typeof estimateTokens, opts?: {
   currentTokens?: number;
-  force?: boolean;
+  force?: boolean; /** RFC review D8：距最后一条 assistant 消息的时间 gap（ms）——时间基 microcompact 触发输入。 */
+  timeGapMs?: number;
 }): PruneResult;
 //#endregion
 //#region src/archive.d.ts
@@ -732,10 +936,56 @@ declare const DEFAULT_COMPACTION_CONFIG: CompactionConfig;
 declare const DEFAULT_PRUNE_CONFIG: PruneConfig;
 declare function resolveContextSize(size: ContextSize, contextWindow: number): number;
 //#endregion
+//#region src/memory-injection.d.ts
+/**
+ * memory-injection.ts —— RFC-394 M6/P1-11：`<agent_memory>` 段注入逻辑。
+ *
+ * 从 `prompts.ts` 拆出——prompts.ts 只留 prompt 模板（摘要/抽取/turn-prefix），
+ * 本文件负责「多源记忆 → 带预算的 `<agent_memory>` 注入文本」：
+ * - token 预算记账（CJK 加权）
+ * - 二分截断到 code-point 边界
+ * - RFC-382 D1 索引行折叠（mtime 窗口）
+ * - `<memory_guidelines>` 尾部追加
+ *
+ * 公开导出不变（barrel re-export，消费方零破坏）。
+ */
+/**
+ * `<agent_memory>` 段的默认总预算（tokens，粗估）。
+ *
+ * 本仓正常场景（AGENTS.md 三源 + AutoMemory 索引）实测 ~3.4k tokens；monorepo
+ * `discoverAgentsSources` 理论上限是 10 文件 × 64KB = 640KB，若真的堆到那个量级会把
+ * system prompt 撑爆。这里的预算不是替代 discoverAgentsSources 的单文件/文件数上限
+ * （那层继续管），而是在全部来源（含它管不到的 writable AGENTS.md / AutoMemory 索引）
+ * 汇总之后再把一道总闸——`buildMemoryInjection` 是唯一收口点，别处管不到的这里管。
+ *
+ * 取 3.4k 实测值的 ~2.3 倍留余量，同时把极端场景压掉 95%+。
+ */
+declare const DEFAULT_MEMORY_INJECTION_BUDGET_TOKENS = 8000;
+declare function buildMemoryInjection(memories: Map<string, string>, budgetTokens?: number, entryMtimes?: Map<string, number>, nowMs?: number): string;
+//#endregion
 //#region src/prompts.d.ts
-declare const SUMMARIZATION_PROMPT = "You are a conversation summarizer for an AI coding assistant. Your task is to create a structured summary of the conversation that preserves all information needed to continue the work.\n\nCreate the summary in the following format:\n\n## Goal\n[What is the user trying to accomplish?]\n\n## Constraints & Preferences\n- [Any constraints, preferences, or requirements the user mentioned]\n\n## All User Requests\n- [List EVERY distinct request/instruction the user made, in order, that is not a tool result. This is the authoritative record of user intent \u2014 quote the user's own wording; do not paraphrase away specifics.]\n\n## Progress\n### Done\n- [x] [Completed work items]\n### In Progress\n- [ ] [Work in progress]\n\n## Key Decisions\n- **[Decision]**: [Brief rationale]\n\n## Next Steps\n1. [Planned next steps. For the immediate next action, include a VERBATIM quote of the most recent user message or your own last stated intent it derives from \u2014 anchors the task, prevents drift.]\n\n## File Operations\n### Read\n- [Files that were read]\n### Modified\n- [Files that were modified]\n\n## Critical Context\n- [Any critical context needed to continue the work]\n\nIMPORTANT:\n- Preserve exact file paths, function names, error messages, and code snippets\n- Keep technical details precise \u2014 do not generalize\n- Include all tool call results that affect the current state\n- Note any pending or failed operations";
+/**
+ * RFC-394 M6/P1-5：SUMMARIZATION_PROMPT 收敛为壳 + SUMMARY_BODY_FORMAT（与其他变体一致，
+ * 消除双模板源的细微措辞漂移风险）。测试断言 `SUMMARIZATION_PROMPT` 含
+ * `'## All User Requests'` / `'EVERY distinct request'` —— SUMMARY_BODY_FORMAT 已含。
+ */
+declare const SUMMARIZATION_PROMPT = "You are a conversation summarizer for an AI coding assistant. Your task is to create a structured summary of the conversation that preserves all information needed to continue the work.\n\nCreate the summary in the following format:\n\n## Goal\n[What is the user trying to accomplish?]\n\n## Constraints & Preferences\n- [Any constraints, preferences, or requirements the user mentioned]\n\n## All User Requests\n- [List EVERY distinct request/instruction the user made, in order, that is not a tool result. This is the authoritative record of user intent \u2014 multi-round compaction must never let an earlier request silently drop. Quote the user's own wording for each; do not paraphrase away specifics.]\n\n## Progress\n### Done\n- [x] [Completed work items]\n### In Progress\n- [ ] [Work in progress]\n\n## Key Decisions\n- **[Decision]**: [Brief rationale]\n\n## Next Steps\n1. [Planned next steps. For the immediate next action, include a VERBATIM quote of the most recent user message or your own last stated intent that it derives from \u2014 this anchors the task and prevents interpretation drift across compactions.]\n\n## File Operations\n### Read\n- [Files that were read]\n### Modified\n- [Files that were modified]\n\n## Critical Context\n- [Any critical context needed to continue the work]\n\nIMPORTANT:\n- Preserve exact file paths, function names, error messages, and code snippets\n- Keep technical details precise \u2014 do not generalize\n- Include all tool call results that affect the current state\n- Note any pending or failed operations";
 declare const UPDATE_SUMMARIZATION_PROMPT = "You are updating an existing conversation summary with new information. The existing summary and new messages are provided below.\n\nProduce a single UPDATED summary that stays BOUNDED \u2014 a summary that grows without limit across rounds eventually gets hard-truncated by the output cap, silently losing whatever fell past the limit. Keep it tight by actively triaging, not by appending.\n\nKeep (never drop):\n- Every distinct user request/instruction (the \"All User Requests\" record is authoritative)\n- Unfinished, in-progress, or blocked work\n- Decisions not yet verified, and anything the user corrected you on\n- Exact file paths, function names, error messages, code snippets still in play\n\nDrop / compress (make room):\n- Work that is both completed AND verified \u2014 collapse to a one-line outcome\n- Superseded intermediate attempts and abandoned approaches\n- Redundant restatements already captured elsewhere in the summary\n\nRules:\n- Move completed \"In Progress\" items to \"Done\", then compress \"Done\" per the above\n- Merge new work items, decisions, and context; do not simply append\n- Keep the same structured format (including \"All User Requests\")\n- If any information conflicts, use the newer version";
 declare const TURN_PREFIX_SUMMARIZATION_PROMPT = "You are summarizing the FIRST PART of an assistant turn that was split during conversation compaction. The remaining part of this turn is still in the conversation.\n\nCreate a brief summary in this format:\n\n## Original Request\n[What did the user ask for in this turn?]\n\n## Early Progress\n- [Key actions completed in the prefix portion]\n\n## Context for Remaining Messages\n- [Information needed to understand the remaining suffix messages]\n\nKeep it concise \u2014 this will be prepended to the remaining messages of this turn.";
+/**
+ * RFC-339 D3：游标感知提示词的三个变体（选择逻辑见 `pickVariant`）。
+ *
+ * 缺陷背景（RFC-339 §1.3 缺陷 D）：`prepareCompaction` 早已算出 `preservedMessages`
+ * （切点之后原样保留、会拼在摘要之后一起送回模型的近期消息），但提示词从不告诉模型
+ * 这个边界的存在。后果：①模型把保留区内容也概括进摘要 → 重复占位、概括版与原文版
+ * 并存易矛盾；②模型无法产出「读懂保留区所需的前置信息」这种面向续作的摘要。
+ *
+ * - FULL：无保留区（全量折叠，罕见）。等价于原 SUMMARIZATION_PROMPT。
+ * - WITH_PRESERVED_TAIL：**主路径**。显式告知其后 N 条原样保留、不要概括它们，
+ *   并要求产出「保留区依赖的前置信息」段。
+ * - SEGMENT：分批（map-reduce）的 map 阶段单段摘要，显式告知「这是第 i/N 段、不是
+ *   全部对话」，禁止输出面向全局的 next-step 判断（那属于 reduce 合并阶段）。
+ */
 declare const WITH_PRESERVED_TAIL_PROMPT = "You are a conversation summarizer for an AI coding assistant. You are summarizing the EARLIER portion of a conversation. The most recent messages are kept verbatim and will follow your summary unchanged \u2014 they are shown to you below in <preserved_tail_context> FOR REFERENCE ONLY.\n\nYour summary and those preserved recent messages together become the assistant's full context going forward.\n\nCreate the summary in the following format:\n\n## Goal\n[What is the user trying to accomplish?]\n\n## Constraints & Preferences\n- [Any constraints, preferences, or requirements the user mentioned]\n\n## All User Requests\n- [List EVERY distinct request/instruction the user made, in order, that is not a tool result. This is the authoritative record of user intent \u2014 multi-round compaction must never let an earlier request silently drop. Quote the user's own wording for each; do not paraphrase away specifics.]\n\n## Progress\n### Done\n- [x] [Completed work items]\n### In Progress\n- [ ] [Work in progress]\n\n## Key Decisions\n- **[Decision]**: [Brief rationale]\n\n## Next Steps\n1. [Planned next steps. For the immediate next action, include a VERBATIM quote of the most recent user message or your own last stated intent that it derives from \u2014 this anchors the task and prevents interpretation drift across compactions.]\n\n## File Operations\n### Read\n- [Files that were read]\n### Modified\n- [Files that were modified]\n\n## Critical Context\n- [Any critical context needed to continue the work]\n\n## Context the Preserved Tail Depends On\n- [Facts a reader MUST know to correctly understand the preserved recent messages shown in <preserved_tail_context>: decisions already made, file paths and their current state, conventions/constraints agreed earlier, mistakes already corrected, and any partially-done work those recent messages continue. Read the preserved tail, then look BACK through the earlier conversation for what it silently relies on. This section is the whole point of this summary \u2014 be specific.]\n\nIMPORTANT:\n- Preserve exact file paths, function names, error messages, and code snippets\n- Keep technical details precise \u2014 do not generalize\n- Include all tool call results that affect the current state\n- Note any pending or failed operations\n- Do NOT summarize the content of <preserved_tail_context> \u2014 it is kept verbatim after your summary and re-describing it wastes your budget. Use it ONLY to work out which parts of the EARLIER conversation it depends on.\n- Summarize ONLY the conversation inside <conversation>.";
 declare const SEGMENT_SUMMARIZATION_PROMPT = "You are summarizing ONE SEGMENT of a longer conversation for an AI coding assistant. This is a partial view \u2014 you are NOT seeing the whole conversation, and other segments are being summarized separately. Your segment summary will later be merged with the others.\n\nCreate a concise summary of THIS SEGMENT in the following format:\n\n## Goal\n[What is the user trying to accomplish?]\n\n## Constraints & Preferences\n- [Any constraints, preferences, or requirements the user mentioned]\n\n## All User Requests\n- [List EVERY distinct request/instruction the user made, in order, that is not a tool result. This is the authoritative record of user intent \u2014 multi-round compaction must never let an earlier request silently drop. Quote the user's own wording for each; do not paraphrase away specifics.]\n\n## Progress\n### Done\n- [x] [Completed work items]\n### In Progress\n- [ ] [Work in progress]\n\n## Key Decisions\n- **[Decision]**: [Brief rationale]\n\n## Next Steps\n1. [Planned next steps. For the immediate next action, include a VERBATIM quote of the most recent user message or your own last stated intent that it derives from \u2014 this anchors the task and prevents interpretation drift across compactions.]\n\n## File Operations\n### Read\n- [Files that were read]\n### Modified\n- [Files that were modified]\n\n## Critical Context\n- [Any critical context needed to continue the work]\n\nIMPORTANT:\n- Preserve exact file paths, function names, error messages, and code snippets\n- Keep technical details precise \u2014 do not generalize\n- Include all tool call results that affect the current state\n- Note any pending or failed operations\n- Do NOT emit conclusions that require seeing the whole conversation (e.g. a single global \"next step\"). Report only what THIS segment establishes; the merge step will reconcile across segments.\n- If <preserved_tail_context> is present, it holds the most recent messages, kept verbatim outside this compaction. Do NOT summarize it \u2014 use it ONLY to judge which parts of THIS segment it depends on, and make sure those parts survive into your summary. Summarize ONLY the content inside <conversation>.";
 declare const SEGMENT_MERGE_PROMPT = "You are merging several segment summaries of one conversation into a single coherent summary for an AI coding assistant. Each input below is a summary of a different (chronological) segment of the same conversation.\n\nReconcile them into one summary in the following format:\n\n## Goal\n[What is the user trying to accomplish?]\n\n## Constraints & Preferences\n- [Any constraints, preferences, or requirements the user mentioned]\n\n## All User Requests\n- [List EVERY distinct request/instruction the user made, in order, that is not a tool result. This is the authoritative record of user intent \u2014 multi-round compaction must never let an earlier request silently drop. Quote the user's own wording for each; do not paraphrase away specifics.]\n\n## Progress\n### Done\n- [x] [Completed work items]\n### In Progress\n- [ ] [Work in progress]\n\n## Key Decisions\n- **[Decision]**: [Brief rationale]\n\n## Next Steps\n1. [Planned next steps. For the immediate next action, include a VERBATIM quote of the most recent user message or your own last stated intent that it derives from \u2014 this anchors the task and prevents interpretation drift across compactions.]\n\n## File Operations\n### Read\n- [Files that were read]\n### Modified\n- [Files that were modified]\n\n## Critical Context\n- [Any critical context needed to continue the work]\n\nIMPORTANT:\n- Preserve exact file paths, function names, error messages, and code snippets\n- Keep technical details precise \u2014 do not generalize\n- Include all tool call results that affect the current state\n- Note any pending or failed operations\n- Resolve conflicts in favour of the LATER segment.\n- Merge duplicate items; do not simply concatenate.";
@@ -764,6 +1014,12 @@ interface SummarizationContext {
    * 缺省/空串 = 不注入标签，提示词与 RFC-358 之前逐字节等价（向后兼容）。
    */
   preservedTailReference?: string;
+  /**
+   * RFC-387 D1：前缀复用模式——对话内容经 `prefix.messages` 原样重放，不进入指令文本。
+   * true 时不追加 `<conversation>` 块（缺省 false = 现状字节等价）。
+   * 注：M1 阶段仅单批路径单测启用；模板内对 `<conversation>` 位置的最小措辞修订属 M2b（D3 方案 a）。
+   */
+  omitConversation?: boolean;
 }
 /**
  * 构造摘要提示词。RFC-339 D3：新增可选 `context` 参数使提示词感知切点/批次形态；
@@ -787,19 +1043,6 @@ declare function buildSummarizationPrompt(messages: string, previousSummary?: st
  */
 declare function buildSegmentMergePrompt(segmentSummaries: string, previousSummary?: string, customInstructions?: string): string;
 declare function buildTurnPrefixPrompt(turnPrefixMessages: string): string;
-/**
- * `<agent_memory>` 段的默认总预算（tokens，粗估）。
- *
- * 本仓正常场景（AGENTS.md 三源 + AutoMemory 索引）实测 ~3.4k tokens；monorepo
- * `discoverAgentsSources` 理论上限是 10 文件 × 64KB = 640KB，若真的堆到那个量级会把
- * system prompt 撑爆。这里的预算不是替代 discoverAgentsSources 的单文件/文件数上限
- * （那层继续管），而是在全部来源（含它管不到的 writable AGENTS.md / AutoMemory 索引）
- * 汇总之后再把一道总闸——`buildMemoryInjection` 是唯一收口点，别处管不到的这里管。
- *
- * 取 3.4k 实测值的 ~2.3 倍留余量，同时把极端场景压掉 95%+。
- */
-declare const DEFAULT_MEMORY_INJECTION_BUDGET_TOKENS = 8000;
-declare function buildMemoryInjection(memories: Map<string, string>, budgetTokens?: number): string;
 /**
  * 跨会话经验抽取提示词。要求模型从一段会话切片里提炼可复用的「经验」
  * （trigger=何时适用 / insight=怎么做 / tags=召回关键词），严格输出 JSON 数组。
@@ -858,13 +1101,12 @@ interface Lesson {
   sourceSessionId: string;
   createdAt: number;
   /**
-   * @deprecated RFC-284 D8：改用 `relevantHitCount`。
-   *
-   * 该字段唯一自增点是 `search()`，而注入路径走 `list()` 且 `search()` 零生产调用方，
-   * 故它在历史数据中结构性恒为 0（详见 RFC-036 §8.9 勘误）。保留仅为向后兼容：
-   * 读取时与 `relevantHitCount` 双向同步，不再作为新的判据来源。
+   * @deprecated RFC-394 M5：改用 `relevantHitCount`。该字段是 v1 遗留——`save()` 不再
+   * 写入它，`search()`/`recordRelevantHits()` 不再同步它。旧数据文件里遗留的值由
+   * `hydrateLesson` 读取时一次性映射到 `relevantHitCount`（读旧写新，无需迁移脚本）。
+   * 类型改为可选——新创建的 lesson 不赋此属性（`JSON.stringify` 不落盘 undefined 键）。
    */
-  appliedCount: number;
+  appliedCount?: number;
   /** 语义类别。缺省视为未归类，由 M4 审计填充。 */
   class?: LessonClass;
   /** 生命周期状态。缺省视为 `active`。 */
@@ -894,6 +1136,15 @@ type LessonInput = Omit<Lesson, 'id' | 'createdAt' | 'appliedCount'>;
 interface LessonFilter {
   tags?: string[];
   query?: string;
+  /**
+   * RFC-284 T7：是否包含已出射（archived/tombstone）的 lesson。缺省 false——
+   * `list()` 的主消费方是 stable prompt 注入（lesson-injection.ts），归档语义
+   * 的全部意义就是「不再进 stable 注入」；审计/维护工具需要全量视图时显式传 true。
+   * 注意 `search()`（相关性召回）刻意**不受**此过滤影响——archived 的经验仍可被
+   * query 相关召回进 volatile hints（出 stable 注入 ≠ 出召回，比 DSH 冻结归档温和，
+   * 适配 lesson「低频但可能突然有用」的数据性质）。
+   */
+  includeArchived?: boolean;
 }
 interface SimilarLesson {
   lesson: Lesson;
@@ -937,6 +1188,12 @@ interface LearningStoreOptions {
    * 两个写盘分支于单点。由 §D1 白名单点 agent-services-setup 从 isShadowModeEnabled 派生。
    */
   ephemeral?: boolean;
+  /**
+   * 确定性时钟端口（RFC-394 M5）。缺省 `() => Date.now()`（向后兼容）；
+   * 注入后 save 的 `createdAt` / search·recordRelevantHits 的 `lastAccessedAt` /
+   * persist 的快照时间戳全部经注入时钟——确定性重放前提（CODE-STYLE §43）。
+   */
+  now?: () => number;
 }
 /** 估算注入 token（CJK≈1/字，ASCII≈4 字符/token）。与 RFC-284 探针脚本同口径。 */
 declare function estimateLessonTokens(lesson: Pick<Lesson, 'tags' | 'trigger' | 'insight'>): number;
@@ -951,6 +1208,11 @@ declare class OperationalLearningStore {
   private lessons;
   private nextId;
   private loaded;
+  /**
+   * RFC-284 T7：本进程是否显式改过治理字段（archiveLessons）。为真时 `persist()` 跳过
+   * 磁盘治理字段合并——否则本进程刚做的归档会被磁盘旧值（active）覆盖回去。
+   */
+  private governanceDirty;
   private readonly snapshotId;
   private readonly persistence;
   /** RFC-164 M164-2 D5：MemoryStore 接入（可选）——提供时优先于 `persistence` 路径。 */
@@ -961,8 +1223,28 @@ declare class OperationalLearningStore {
   private readonly scope;
   /** RFC-345 §D3：影子态——persist() 短路（内存优先架构，写后读经 this.lessons Map 保持）。 */
   private readonly ephemeral;
+  /** RFC-394 M5：确定性时钟端口（缺省 Date.now）。 */
+  private readonly now;
   constructor(options?: LearningStoreOptions);
   save(input: LessonInput): Promise<Lesson>;
+  /**
+   * RFC-284 T7：归档写入通道——把指定 lesson 置为 `archived`（出 stable 注入面，
+   * 数据保留、`search()` 相关性召回不受影响）。这是 archive-plan dry-run（T4a）
+   * 的 apply 执行端。
+   *
+   * 保守语义（RFC-284 endgame-retention-design §4 Layer C）：
+   * - `pinned` / `state==='live'` 的 lesson **拒绝归档**（返回 skipped，不抛错）——
+   *   与 dry-run checker 的保护项判据一致，双层防线（plan 侧 protected + store 侧硬闸）。
+   * - 未知 id 计入 skipped（fail-soft：plan 与 store 可能有漂移，不让单条错拦整批）。
+   * - 幂等：已 archived 的再归档计入 archived（状态不变，不重复写盘副作用）。
+   */
+  archiveLessons(ids: readonly string[]): Promise<{
+    archived: string[];
+    skipped: Array<{
+      id: string;
+      reason: string;
+    }>;
+  }>;
   search(query: string, limit?: number): Promise<Lesson[]>;
   /**
    * RFC-036 M61(R4 去重前置）：在写入前查找与 `(trigger, insight)` 近似重复的既有经验。
@@ -993,6 +1275,23 @@ declare class OperationalLearningStore {
   refresh(): Promise<void>;
   /** RFC-164 M164-2 D5：MemoryStore 路径的加载——store.load 返回原始 JSON 字符串,本地解析。 */
   private loadFromStore;
+  /**
+   * RFC-284 T7 修复（2026-08-15 验收发现的真实缺陷）：写盘前合并磁盘上的**治理字段**。
+   *
+   * 事故：`scripts/rfc284-archive-plan.mjs --apply` 把 60 条 lesson 置为 `archived` 落盘后，
+   * 40 分钟后被长驻 otto 进程整体抹回 `active`——`persist()` 用**进程启动时加载的内存 Map**
+   * 全量覆写，完全不知道外部工具改过磁盘。归档在真机上直接失效（验收脚本抓到）。
+   *
+   * 所有权划分（与 auth-store「读盘-合并-写回」同款纹理）：
+   * - **运行时拥有**：trigger/insight/tags/relevantHitCount/lastAccessedAt 等自身产生的字段；
+   * - **外部治理工具拥有**：`state`/`pinned`/`supersededBy`/`class`（archive-plan/governance-plan
+   *   等脚本写入，运行时只读不产）。
+   *
+   * 合并规则：治理字段以**磁盘为准**（除非本进程显式改过它——`archiveLessons()` 走内存已改，
+   * 此时内存值更新，用 `governanceDirty` 标记豁免）。磁盘读失败一律 fail-open 用内存值写出
+   * （不让合并失败演变成写盘失败——丢新 lesson 比丢归档标记更严重）。
+   */
+  private mergeGovernanceFieldsFromDisk;
   private persist;
 }
 //#endregion
@@ -1063,18 +1362,34 @@ interface MemoryAutoExtractConfig {
   similarityThreshold?: number;
   /** 抽取调用 token 上限,透传 extractLessons。 */
   maxTokens?: number;
+  /**
+   * RFC-327 M3-05:相关召回低水位阈值(显式阈值)。
+   *
+   * 开启 auto-extract 时,若既有 lessons 的最大 relevantHitCount 低于此水位
+   * (召回路径未激活/未被证明有效),跳过本次抽取——防"write-only"噪音积累
+   * (抽取写入了、却从未被相关召回命中)。配合 `readRelevantHits` 端口使用:
+   * 设置了本阈值但未注入读取端口时 fail-closed(不抽取),避免静默绕过配置意图。
+   * 缺省不设(无门,向后兼容)。
+   */
+  minRelevantHits?: number;
 }
 interface MemoryAutoExtractorDeps {
   llm: ExtractLLM;
   store: LessonWriteStore;
   config: MemoryAutoExtractConfig;
+  /**
+   * RFC-327 M3-05:召回信号读取端口——返回既有 lessons 的**最大** relevantHitCount。
+   * 由宿主注入(对齐 `store` 的注入纹理——extractor 不直接持有读取侧 store 依赖)。
+   * 与 `config.minRelevantHits` 配对:设置了阈值但未注入端口时 fail-closed(不抽取)。
+   */
+  readRelevantHits?: () => Promise<number> | number;
   /**
    * R5 不与主 agent 抢:判定某工具调用是否算"记忆写入"——若本批切片里主 agent 已写过记忆,
    * 跳过本次抽取。默认认 `learn` 工具与名字含 `memory` 的工具。
    */
   isMemoryWriteTool?: (toolName: string) => boolean;
 }
-type AutoExtractReason = 'disabled' | 'no-new-messages' | 'throttled' | 'main-agent-wrote' | 'error';
+type AutoExtractReason = 'disabled' | 'no-new-messages' | 'throttled' | 'main-agent-wrote' | 'below-relevant-hits-low-water' | 'error';
 interface AutoExtractOutcome {
   ran: boolean;
   reason?: AutoExtractReason;
@@ -1123,5 +1438,138 @@ declare class FileStateManager {
   private checkRecentFiles;
 }
 //#endregion
-export { type AgentsDiscoveryOptions, type ArchiveEntry, type ArchiveStorage, type AutoExtractOutcome, type AutoExtractReason, AutoMemory, type AutoMemoryEntry, type AutoMemoryOptions, type CompactionConfig, type CompactionPreparation, type CompactionResult, type ContextSize, type ContextTokenEstimate, type CutPoint, DEFAULT_COMPACTION_CONFIG, DEFAULT_MEMORY_INJECTION_BUDGET_TOKENS, DEFAULT_MEMORY_SOURCES, DEFAULT_PRUNE_CONFIG, DEFAULT_SIMILARITY_THRESHOLD, type ExtractLLM, type ExtractionOptions, type FileStateCapture, FileStateManager, type FileStateSnapshot, FileSystemMemoryStore, HttpMemoryStore, IMAGE_BLOCK_TOKEN_ESTIMATE, InMemoryArchiveStorage, InMemoryMemoryStore, LESSON_EXTRACTION_PROMPT, type LearningStoreOptions, type Lesson, type LessonClass, type LessonFilter, type LessonInput, type LessonState, type LessonWriteStore, type MemoryAutoExtractConfig, type MemoryAutoExtractorDeps, type MemoryDefaults, MemoryManager, type MemoryManagerConfig, type MemorySource, type MemoryStore, type MessageFromEntry, type MinimalEntry, OperationalLearningStore, PersistentMemory, type PruneConfig, type PruneResult, SEGMENT_MERGE_PROMPT, SEGMENT_SUMMARIZATION_PROMPT, SUMMARIZATION_PROMPT, type SaveExtractedOptions, type SaveExtractedResult, type SimilarLesson, type StorageType, type SummarizationContext, type SummarizationVariant, TURN_PREFIX_SUMMARIZATION_PROMPT, UPDATE_SUMMARIZATION_PROMPT, WITH_PRESERVED_TAIL_PROMPT, buildArchiveReference, buildExtractionPrompt, buildLowCoverageNotice, buildMemoryInjection, buildSegmentMergePrompt, buildSummarizationPrompt, buildTurnPrefixPrompt, computeLessonContentHash, computeMemoryDefaults, createMemoryAutoExtractor, createMemoryManager, createOverlayMemoryStore, discoverAgentsSources, ensureTokenizer, estimateLessonTokens, estimateMessageTokens, estimateMessagesTokens, estimateTokens, estimateTokensHeuristic, extractLessons, formatArchive, messageToText, prune, resolveContextSize, saveExtractedLessons };
+//#region src/evolution-signal-store.d.ts
+/**
+ * evolution-signal-store.ts —— RFC-327 M3-03：进化观测层的统一信号出口。
+ *
+ * 三回路（RFC-318 skill usage / RFC-287 capability_gap 缺口 / RFC-036 relevantHitCount）
+ * 的进化信号在这里汇聚成 **append-only** 日志，供第③层内化决策与第④层训练语料筛选
+ * 消费（两者均缓议——见 RFC-327 §5 R3'：观测层只收信号不决策）。
+ *
+ * ## 单源裁决（R3'）
+ *
+ * relevantHitCount 的**真源在 memory store**（`OperationalLearningStore.recordRelevantHits`
+ * / `search`），本 store 只做**消费投影**——`appendRelevantHits` 只读 lesson 数据、绝不写回；
+ * 「grep 防第二写入点」升级为模块边界单测（见 evolution-signal-store.test.ts）。
+ *
+ * ## 事件驱动写入（不轮询）
+ *
+ * 所有写入经 `append`（宿主在信号事件发生点调用，如 lesson-relevant-hints hook 在
+ * `recordRelevantHits` 之后投影）；本 store 不提供任何"定时同步/轮询"入口。
+ */
+type EvolutionSignalKind = 'skill.usage' | 'capability.gap' | 'relevant.hits' | 'internalize';
+/** append-only 信号日志中的一条记录。 */
+interface EvolutionSignalRecord {
+  kind: EvolutionSignalKind;
+  /** 信号归属 key（skill 名 / 缺口去重键 / lesson id）。 */
+  key: string;
+  /** 信号值（执行次数 / 上报次数 / 命中次数等）。 */
+  value: number;
+  /** 信号时刻——注入时钟刻度（确定性纪律，本层不直呼 Date.now）。 */
+  at: number;
+  /**
+   * 会话归属（RFC-385 §11 授权扩展，RFC-327 M3 schema 向后兼容）——可选；
+   * 不传 = 该信号无会话归属（旧写入点行为不变，全局聚合照旧）。第④层出口按此字段
+   * 切片做 turn 级质量标注联结（trajectory-capture）。
+   */
+  sessionId?: string;
+  /** 本次事件的增量元数据（如 success/durationMs/deduped）。 */
+  detail?: Record<string, unknown>;
+}
+/** 最小写入端口——消费方（如 lesson-injection）依赖此面，不依赖具体实现。 */
+interface EvolutionSignalSink {
+  append(record: Omit<EvolutionSignalRecord, 'at'>): void;
+  /**
+   * relevantHitCount 消费投影（R3'）——读真源数据派生信号记录并 append。
+   * 实现必须只读、绝不写回 lesson 数据（单源写入点边界，见测试）。
+   */
+  appendRelevantHits(lessons: ReadonlyArray<{
+    id: string;
+    relevantHitCount?: number;
+  }>): void;
+}
+/**
+ * 持久化端口（RFC-388 M1）——宿主注入 SignalLog；可选：不注入 = 纯内存（旧行为不变）。
+ * `append` 返回 Promise（异步落盘）；store 侧 fire-and-forget + .catch 保证无未处理 rejection。
+ */
+interface EvolutionSignalPersistPort {
+  append(record: EvolutionSignalRecord): Promise<unknown>;
+  load(): Promise<EvolutionSignalRecord[]>;
+  close?(): Promise<void>;
+}
+interface EvolutionSignalStoreOptions {
+  /** 时钟端口——信号时刻由注入时钟提供。缺省回退 Date.now（宿主未注入时向后兼容）。 */
+  now?: () => number;
+  /** RFC-388 M1：持久化端口（可选）。不注入 = 纯内存 store，行为与 RFC-327 原版一致。 */
+  persist?: EvolutionSignalPersistPort;
+  /** 落盘/恢复失败的告警端口（可选）。不注入 = 静默（仅吞错，不阻断信号）。 */
+  logWarn?: (msg: string, err?: unknown) => void;
+}
+/** 按 kind:key 聚合的信号计数（快照视图，供进化决策读取）。 */
+interface EvolutionSignalCount {
+  kind: EvolutionSignalKind;
+  key: string;
+  /** 信号值累计（如 total 执行次数 / 上报次数 / 命中次数）。 */
+  total: number;
+  /** 日志条数（事件次数）。 */
+  records: number;
+  /** 最近一次信号时刻。 */
+  lastAt: number;
+}
+declare class EvolutionSignalStore implements EvolutionSignalSink {
+  private readonly records;
+  private readonly now;
+  private readonly persist?;
+  private readonly logWarn?;
+  constructor(options?: EvolutionSignalStoreOptions);
+  /** append-only 写入——事件驱动（宿主在信号事件发生点调用）。 */
+  append(record: Omit<EvolutionSignalRecord, 'at'>): void;
+  /**
+   * 纯投影：从 memory store 数据派生 relevantHitCount 信号记录。
+   *
+   * **只读**——不 append、不改写入参；返回的记录可直接交给 `append` 或消费方检查。
+   * 值来自 memory store 真源（R3'），本方法不提供任何写回 lesson 的路径。
+   */
+  projectRelevantHits(lessons: ReadonlyArray<{
+    id: string;
+    relevantHitCount?: number;
+  }>): Array<Omit<EvolutionSignalRecord, 'at'>>;
+  /** 事件驱动投影写入：读 memory store 的 relevantHitCount，append 信号记录（R3' 消费投影）。 */
+  appendRelevantHits(lessons: ReadonlyArray<{
+    id: string;
+    relevantHitCount?: number;
+  }>): void;
+  /** 全量日志（append-only：无更新/删除入口）。 */
+  list(): readonly EvolutionSignalRecord[];
+  /** 按 kind:key 聚合的快照（信号值累计 + 事件次数）。 */
+  counts(): EvolutionSignalCount[];
+  /**
+   * RFC-388 M1：从持久化日志全量恢复（重放）进内存。append-only 无删改——
+   * 重放后内存 at 序 = 文件 seq 序 = 追加序。宿主启动时调用一次。
+   * fail-soft：文件损坏/读失败时告警并空启动（信号是观测数据可容忍），不抛。
+   * 返回恢复条数（观测 count 用）。
+   *
+   * 时序约束（应用点 B 建议③）：仅在启动早期调用（任何 signal 生产者就绪前）。
+   * 恢复窗口内并发 append 会被 records.length=0 清空抹掉内存快照（该信号已
+   * fire-and-forget 落盘、下次重启可恢复，非数据丢失）——运行期勿调用。
+   */
+  restoreFromLog(): Promise<number>;
+  /** RFC-388 M1：转发 close（flush-on-exit——AppendLog.close() 排空 writeQueue）。 */
+  close(): Promise<void>;
+  get size(): number;
+}
+//#endregion
+//#region src/signal-log.d.ts
+/** 进化信号持久化端口（SignalLog 的最小领域面）。 */
+interface SignalLog {
+  /** 追加一条；FileAppendLog 内部 writeQueue 串行，进程内落盘序 = 调用序。 */
+  append(record: EvolutionSignalRecord): Promise<unknown>;
+  /** 全量重放（seq 升序 = 追加序）。首启无文件 → 空数组，不抛。 */
+  load(): Promise<EvolutionSignalRecord[]>;
+  /** 排空在途写入队列并关闭句柄（flush-on-exit）。 */
+  close(): Promise<void>;
+}
+declare function createSignalLog(dir: string): SignalLog;
+//#endregion
+export { type AgentsDiscoveryOptions, type ArchiveEntry, type ArchiveStorage, type AutoExtractOutcome, type AutoExtractReason, AutoMemory, type AutoMemoryEntry, type AutoMemoryOptions, type CompactionConfig, type CompactionLockPort, type CompactionPrefix, type CompactionPreparation, type CompactionResult, type CompactionSpillSink, type ContextSize, type ContextTokenEstimate, type CutPoint, DEFAULT_COMPACTION_CONFIG, DEFAULT_MEMORY_INJECTION_BUDGET_TOKENS, DEFAULT_MEMORY_SOURCES, DEFAULT_PRUNE_CONFIG, DEFAULT_SIMILARITY_THRESHOLD, type EvolutionSignalCount, type EvolutionSignalKind, type EvolutionSignalPersistPort, type EvolutionSignalRecord, type EvolutionSignalSink, EvolutionSignalStore, type EvolutionSignalStoreOptions, type ExtractLLM, type ExtractionOptions, type FileStateCapture, FileStateManager, type FileStateSnapshot, FileSystemMemoryStore, HttpMemoryStore, IMAGE_BLOCK_TOKEN_ESTIMATE, InMemoryArchiveStorage, InMemoryMemoryStore, LESSON_EXTRACTION_PROMPT, type LearningStoreOptions, type Lesson, type LessonClass, type LessonFilter, type LessonInput, type LessonState, type LessonWriteStore, type MemoryAutoExtractConfig, type MemoryAutoExtractorDeps, type MemoryDefaults, MemoryManager, type MemoryManagerConfig, type MemorySource, type MemoryStore, type MessageFromEntry, type MinimalEntry, OperationalLearningStore, PersistentMemory, type PruneConfig, type PruneResult, SEGMENT_MERGE_PROMPT, SEGMENT_SUMMARIZATION_PROMPT, SUMMARIZATION_PROMPT, type SaveExtractedOptions, type SaveExtractedResult, type SignalLog, type SimilarLesson, type StorageType, type SummarizationContext, type SummarizationVariant, TURN_PREFIX_SUMMARIZATION_PROMPT, UPDATE_SUMMARIZATION_PROMPT, WITH_PRESERVED_TAIL_PROMPT, buildArchiveReference, buildExtractionPrompt, buildLowCoverageNotice, buildMemoryInjection, buildSegmentMergePrompt, buildSummarizationPrompt, buildTurnPrefixPrompt, computeLessonContentHash, computeMemoryDefaults, createMemoryAutoExtractor, createMemoryManager, createOverlayMemoryStore, createSignalLog, discoverAgentsSources, ensureTokenizer, estimateLessonTokens, estimateMessageTokens, estimateMessagesTokens, estimateTokens, estimateTokensHeuristic, extractLessons, formatArchive, formatMessageForSummary, messageToText, prune, resolveContextSize, saveExtractedLessons };
 //# sourceMappingURL=index.d.ts.map