@x-otto/session 0.0.1-alpha.4 → 0.0.1-alpha.6

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { DiskPersistence, MemoryPersistenceBase, Migration, PaginatedResult, PersistenceShape, RemotePersistence, RemotePersistenceError, RemoteSnapshotConflictError } from "@x-otto/persistence";
+import { MemoryPersistenceBase, Migration, PaginatedResult, PersistenceShape, RemotePersistence, RemotePersistenceError, RemoteSnapshotConflictError } from "@x-otto/persistence";
 
 //#region src/types.d.ts
 type SessionEntry<T = unknown> = {
@@ -40,6 +40,22 @@ type SessionEntry<T = unknown> = {
   id: string;
   parentId?: string;
   timestamp: number;
+}
+/**
+ * RFC-381 M1：压缩锁 bracket（跨进程 durable 锁）。
+ * 压缩开始写 phase:'start'、结束写 phase:'end'（同 token）；崩溃后 start 无配对 end
+ * 即为孤儿锁（可超时/takeover 接管）。
+ * **三类边界**：锁 entry 非消息（buildContext/messages/visibleMessages 均不可见）、
+ * 不计 messageCount、不 bump lastActiveAt（派生记账非真实活动）。
+ * **additive optional variant——不升 SESSION_SNAPSHOT_VERSION**（旧快照无此条目即无锁）。
+ */
+| {
+  type: 'compaction-lock';
+  id: string;
+  parentId?: string; /** 'start' = 持锁；'end' = 释放。 */
+  phase: 'start' | 'end'; /** 持锁进程 token（pid + 随机后缀）——end 必须匹配同 token；孤儿判定依据。 */
+  token: string;
+  timestamp: number;
 };
 interface SessionContext<T = unknown> {
   summary?: string;
@@ -246,6 +262,17 @@ interface Session<T = unknown> {
   clearContext(options?: {
     purge?: boolean;
   }): void;
+  /**
+   * RFC-381 M1/M2：压缩锁 bracket 写日志（compaction-lock entry，start/end + token）。
+   * 可选——旧实现/轻量替身无此能力时 lock 端口应拒绝接线（见 session-compaction-lock）。
+   */
+  appendCompactionLock?(phase: 'start' | 'end', token: string): void;
+  /** RFC-381 M1/M2：当前压缩锁状态（最近一个 compaction-lock entry；无则 undefined）。 */
+  compactionLockState?(): {
+    phase: 'start' | 'end';
+    token: string;
+    timestamp: number;
+  } | undefined;
   /**
    * RFC-194 D3：物理释放最后一个 clear 边界之前的内存驻留（message 条目 splice 移除 +
    * 非活跃 compaction 的 replacement 剥离；DB append-forever 不动）。幂等；无边界 no-op。
@@ -284,6 +311,25 @@ interface Session<T = unknown> {
    * （不保留旧分组，防止"未置顶但残留分组名"的僵尸状态，见 RFC-158 §4）。
    */
   setPinned(pinned: boolean, group?: string): void;
+  /** 绝对回合总数（resume 末尾对齐派生 turnBoundaries）。领域记账，非 UI 面板态。 */
+  getTurnCount(): number | undefined;
+  setTurnCount(n: number): void;
+}
+/**
+ * UI 面板态持久化接口——todoList/editedFiles/subagents/drafts/turnSummaries 五个
+ * TUI 面板 + 已废弃的输入历史迁移读取。
+ *
+ * 终局 review 2026-08-14：从 `Session` 拆出（原 Session 接口 40 方法中 14 个是面板
+ * get/set，领域接口被 UI 演进绑架——每加一个新面板都要改领域接口、聚合根与快照格式
+ * 三处）。拆分后消费方按需收窄类型：领域读者用 `Session`，面板读者用
+ * `SessionPanelState`，两者都要用 `Session & SessionPanelState`。
+ *
+ * **终局方向（投影化）**：面板态是 entry 事件流上的 UI 投影（读模型），理想形态是从
+ * seq watermark 折叠出面板视图并独立落库（投影缓存，机制参照 deepseek-harness
+ * session-projection-cache），而不是聚合根的附属存储。本接口是迁移的中途形态：先做
+ * 接口层分离（零行为变化），投影化存储变更作为专项另行推进。
+ */
+interface SessionPanelState {
   /**
    * 持久化 config 字段存取器（取代 cli 侧 `as unknown as {...}` 裸 cast，给持久化契约真类型）。
    * RFC-108 D3：todoList/editedFiles/subagents/drafts 四个 UI 面板字段从 PersistedSessionConfig
@@ -306,9 +352,6 @@ interface Session<T = unknown> {
   /** 子代理面板持久化（stat-only）。RFC-108 D3：存储迁至 panelState 独立字段。 */
   getSubagents(): SubagentEntry[] | undefined;
   setSubagents(entries: SubagentEntry[], options?: PanelWriteOptions): void;
-  /** 绝对回合总数（resume 末尾对齐派生 turnBoundaries）。 */
-  getTurnCount(): number | undefined;
-  setTurnCount(n: number): void;
   /** 草稿面板持久化（DraftPane 的 Ctrl+S 保存/加载）。RFC-108 D3：存储迁至 panelState 独立字段。 */
   getDrafts(): DraftEntry[] | undefined;
   setDrafts(entries: DraftEntry[], options?: PanelWriteOptions): void;
@@ -364,6 +407,9 @@ interface SessionPersistence<T = unknown> extends PersistenceShape<SessionSnapsh
   /**
    * RFC-325 M4：DB 冷归档能力（optional，只有 relational SQLite 后端实现）。
    * 将 entries 复制到外部 .jsonl.gz + 标 archived=1，**不删除 DB 行**（RFC-159 红线）。
+   *
+   * **能力探测**：消费方应使用 {@link supportsArchive} 类型守卫，而非 `typeof` 检查或 `as` cast
+   *（RFC-393 M2：三态收拢为统一能力接口模式）。
    */
   archiveSession?: (sessionId: string) => Promise<string>;
   /** 从外部归档恢复（幂等 append，不删除既有条目）。 */
@@ -377,10 +423,21 @@ interface PaginationOptions {
 }
 //#endregion
 //#region src/in-memory-session.d.ts
-declare class InMemorySession<T = unknown> implements Session<T> {
+/** 注入端口形状（结构类型，与 @x-otto/agent 的 ClockPort/IdPort 兼容）。 */
+interface InMemorySessionPorts {
+  clock?: {
+    now(): number;
+  };
+  idGen?: {
+    uuid(): string;
+  };
+}
+declare class InMemorySession<T = unknown> implements Session<T>, SessionPanelState {
   readonly id: string;
   private readonly sessionEntries;
   private readonly entryMap;
+  private readonly clock;
+  private readonly idGen;
   /**
    * RFC-178 D2：会话消息内容字节估算（增量维护，避免每回合 O(n) 重算——lesson_54）。
    * 覆盖全部变更路径：append 累加 / cap splice 递减 / clearContext purge 递减 /
@@ -404,6 +461,8 @@ declare class InMemorySession<T = unknown> implements Session<T> {
    * 时机静默错位。本方法给测试（每个 mutation 路径测试的收尾断言）与 debug 排查提供
    * 唯一真源比对点。O(n) 全量遍历，**勿在热路径调用**（lesson_54）。
    *
+   * RFC-393 M3：实现委托给 {@link ResidencyPolicy}（计数器 owner 仍为本类）。
+   *
    * @returns 漂移量（`recomputed - counter`；0 = 无漂移）
    */
   verifyEstimatedContentBytes(): {
@@ -419,7 +478,16 @@ declare class InMemorySession<T = unknown> implements Session<T> {
    * 无需修改。turnSummaries 是后续新增字段（回合完成摘要行持久化，见 TurnSummaryEntry）。
    */
   private readonly panelState;
-  constructor(id: string, parentSessionId?: string, forkPoint?: number);
+  /**
+   * RFC-393 M3：驻留治理策略（capStoredHistory / capStoredHistoryByBytes / wouldTrim* /
+   * verifyEstimatedContentBytes / removeOldestMessages）从聚合根抽离。
+   * 计数器唯一 owner 仍是本类（`_estimatedContentBytes` / `meta.messageCount`）——
+   * policy 经下方闭包 host 读写，不持有可变状态。
+   */
+  private readonly residencyPolicy;
+  constructor(id: string, parentSessionId?: string, forkPoint?: number, ports?: InMemorySessionPorts);
+  /** RFC-393 M3：policy 访问内部状态的窄接口（闭包捕获私有字段，不暴露 public 方法）。 */
+  private createResidencyHost;
   private _leafId;
   get leafId(): string | undefined;
   /**
@@ -492,6 +560,27 @@ declare class InMemorySession<T = unknown> implements Session<T> {
   clearContext(options?: {
     purge?: boolean;
   }): void;
+  /**
+   * RFC-381 M1：压缩锁 bracket 写日志（append-only，历史不可变）。
+   * 写入 `compaction-lock` 结构 entry（phase start/end + token）。
+   * **三类边界**：不 bump messageCount、不 markActivity（派生记账非真实活动）、
+   * buildContext/messages/visibleMessages 均不可见（非 message 类型天然被过滤）。
+   * 落库由持久化层照常走（type+data 通用行，零序列化改动）。
+   */
+  appendCompactionLock(phase: 'start' | 'end', token: string): void;
+  /**
+   * RFC-381 M1：当前压缩锁状态（最近一个 compaction-lock entry）。
+   * - undefined：无锁（从未加锁或已 end）；
+   * - phase 'end'：已释放；
+   * - phase 'start'：持锁中（token 是持有者；跨进程据此判定孤儿——start 长时间无
+   *   配对 end 即崩溃残留，可超时/takeover）。
+   * 只读当前 leaf 分支（walkBranch），不触碰完整转录。
+   */
+  compactionLockState(): {
+    phase: 'start' | 'end';
+    token: string;
+    timestamp: number;
+  } | undefined;
   /**
    * RFC-194 D3：物理释放最后一个 clear 边界之前的内存驻留（DB append-forever 不动）。
    * 供持久化层在「clear 边界确认落盘成功后」调用（顺序保证见 RFC-194 D2——先 save
@@ -622,7 +711,7 @@ declare class InMemorySession<T = unknown> implements Session<T> {
    * 操作零 UI 反馈，用户长会话（>2000 条）resume 后发现前段历史消失却毫无线索。**本方法只
    * 操作内存**——持久层是否也删除取决于调用方使用的 persistence 实现：RFC-159 起默认的
    * `RelationalSessionPersistence`（SQLite）是 append-forever，被本方法裁掉的条目仍完整
-   * 保留在 DB；仅已废弃的 `OTTO_SESSION_BLOB=1` 逃生口后端会因整份快照覆写而真实丢失。
+   * 保留在 DB（RFC-393 P2 已删除 OTTO_SESSION_BLOB=1 blob 逃生口，不再有整份快照覆写丢失）。
    * 返回 `{capped:false}` 时未发生任何裁剪（正常场景，消息数未超上限）。
    *
    * **RFC-321 R5——返回语义是"尽力裁"而非"裁到 maxMessages"**：裁剪永不跨越活跃
@@ -633,6 +722,8 @@ declare class InMemorySession<T = unknown> implements Session<T> {
    * @returns `capped`/`removedCount` 同前；`boundaryLimited` = 因边界保护提前停止；
    * `activeOversized` = 边界前死历史已裁尽、**活跃区自身仍超限**（RFC-321 D1-a′ 逃生阀
    * 信号，供上层请求强制压缩；M1 只产出信号，消费方接线属 M2/T320-08b）。
+   *
+   * RFC-393 M3：实现委托给 {@link ResidencyPolicy}（计数器 owner 仍为本类）。
    */
   capStoredHistory(maxMessages: number, canStartHistory?: (msg: T) => boolean): {
     capped: boolean;
@@ -651,9 +742,11 @@ declare class InMemorySession<T = unknown> implements Session<T> {
    *
    * 判据：活跃边界之前的 message 条目数 < 需要移除的条数。无活跃边界时，边界前死历史
    * 视为 0——即任何裁剪都会触及活跃上下文，恒返回 true（这正是最该先压缩的场景）。
+   *
+   * RFC-393 M3：实现委托给 {@link ResidencyPolicy}。
    */
   wouldTrimTouchActiveContext(targetMessages: number): boolean;
-  /** 同上，字节口径（供 `capStoredHistoryByBytes` 的前置判定）。 */
+  /** 同上，字节口径（供 `capStoredHistoryByBytes` 的前置判定）。RFC-393 M3：委托给 policy。 */
   wouldByteTrimTouchActiveContext(targetBytes: number): boolean;
   /**
    * RFC-178 D3 硬段：把存储的会话历史按**字节估算**收紧到 maxBytes 以内（从最早的消息条目
@@ -665,6 +758,8 @@ declare class InMemorySession<T = unknown> implements Session<T> {
    *
    * **RFC-321 R4/R5**：同样受活跃 compaction 边界保护、同样是"尽力裁"语义，返回字段与
    * `capStoredHistory` 同构（`activeOversized` 此处按字节口径判定：裁后估算字节仍超预算）。
+   *
+   * RFC-393 M3：实现委托给 {@link ResidencyPolicy}。
    */
   capStoredHistoryByBytes(maxBytes: number, canStartHistory?: (msg: T) => boolean): {
     capped: boolean;
@@ -672,28 +767,6 @@ declare class InMemorySession<T = unknown> implements Session<T> {
     boundaryLimited: boolean;
     activeOversized: boolean;
   };
-  /**
-   * 共享裁剪循环（条数/字节两模式复用）：从 sessionEntries 头部移除 removeCount 条 message
-   * 条目，随后按 canStartHistory 谓词继续移除至工具边界对齐（保留区第一条非孤儿
-   * tool_result）。每次移除同步递减字节估算（RFC-178 D2 路径 2）。
-   *
-   * **RFC-321 R4（边界即止，不可削弱）**：裁剪**永不跨越活跃 compaction 边界**——遇到
-   * 该边界即停止，宁可少裁（`removed < removeCount`）也不破坏 branch 链完整性。
-   *
-   * 修复前的缺陷（RFC-321 P1-a，实证）：本循环只按 `type === 'message'` 从头部 splice，
-   * 既不感知 compaction 边界、也不修复被删条目后继的 `parentId`。一旦裁剪深度超过边界前的
-   * 死历史条数，边界条目的 `parentId` 就会指向已删 id → `walkBranch` 回溯撞空提前截断 →
-   * 边界不在 branch 上 → `buildContext` 走 `lastBoundaryIndex === -1` 分支 → **summary 静默
-   * 丢失**（模型上下文降级，用户与日志均无信号）。主要可达面是 `ResidencyGovernor` 的
-   * critical 档（cap 除以 4，`residency-governor.ts`）——内存压力下恰恰最可能触发。
-   *
-   * 边界之前的条目全是"已被摘要替换的死历史"，边界之后是模型仍在用的活跃上下文；以边界
-   * 为界即把"裁剪只能裁死历史"从时序假设变成**结构不变式**（不再依赖上游触发器配合）。
-   *
-   * @returns `removed` 实际移除条数（可能 < removeCount）；`boundaryLimited` 是否因边界
-   * 保护提前停止（诊断用，非错误）。
-   */
-  private removeOldestMessages;
   setTags(tags: string[]): void;
   addTag(tag: string): void;
   restoreEntries(entries: SessionEntry<T>[], meta: SessionMetadata, restoredLeafId?: string): void;
@@ -713,6 +786,96 @@ declare class InMemorySession<T = unknown> implements Session<T> {
   private lastBoundaryIndex;
 }
 //#endregion
+//#region src/residency-policy.d.ts
+/**
+ * ResidencyPolicy 访问 InMemorySession 内部状态的窄接口。
+ * 由 session 以闭包实现（捕获私有字段），不暴露为 public 方法。
+ */
+interface ResidencyPolicyHost<T> {
+  /** 活 entry 数组（policy 就地 splice 裁剪）。 */
+  getEntries(): SessionEntry<T>[];
+  /** entry id → entry 索引（policy 删除条目时同步清理）。 */
+  getEntryMap(): Map<string, SessionEntry<T>>;
+  /** 当前字节估算计数器（唯一 owner = session）。 */
+  getEstimatedBytes(): number;
+  setEstimatedBytes(n: number): void;
+  /** 当前消息条数计数器（唯一 owner = session）。 */
+  getMessageCount(): number;
+  setMessageCount(n: number): void;
+  /** 当前 leaf parent 链上最近的 compaction 边界 id（无则 undefined；clear 截断）。 */
+  getActiveCompactionId(): string | undefined;
+}
+interface ResidencyTrimResult {
+  capped: boolean;
+  removedCount: number;
+  boundaryLimited: boolean;
+  activeOversized: boolean;
+}
+declare class ResidencyPolicy<T> {
+  private readonly host;
+  constructor(host: ResidencyPolicyHost<T>);
+  /**
+   * 把存储的会话历史封顶到最近 maxMessages 条（删最早的消息条目，compaction/clear 边界
+   * 不参与计数、不被裁）。调用后 messageCount 重新派生。
+   *
+   * **RFC-321 R5——返回语义是"尽力裁"而非"裁到 maxMessages"**：裁剪永不跨越活跃
+   * compaction 边界（R4，见 removeOldestMessages），故 removedCount 可能小于所需，裁后
+   * 条数可能仍 > maxMessages。
+   */
+  capStoredHistory(maxMessages: number, canStartHistory?: (msg: T) => boolean): ResidencyTrimResult;
+  /**
+   * RFC-321 R12（M5 压缩前置）：**只读预判**——把历史裁到 `targetMessages` 条是否会
+   * 触及活跃上下文（即边界前的死历史不够裁）。不做任何修改。
+   *
+   * 判据：活跃边界之前的 message 条目数 < 需要移除的条数。无活跃边界时，边界前死历史
+   * 视为 0——即任何裁剪都会触及活跃上下文，恒返回 true（这正是最该先压缩的场景）。
+   */
+  wouldTrimTouchActiveContext(targetMessages: number): boolean;
+  /** 同上，字节口径（供 capStoredHistoryByBytes 的前置判定）。 */
+  wouldByteTrimTouchActiveContext(targetBytes: number): boolean;
+  /**
+   * RFC-178 D3 硬段：把存储的会话历史按**字节估算**收紧到 maxBytes 以内（从最早的消息
+   * 条目开始裁，compaction/clear 边界不裁）。与 capStoredHistory（条数模式）共享同一裁剪
+   * 循环与工具边界对齐谓词。同为**纯内存防御**，DB append-forever 不受影响（RFC-159）。
+   *
+   * 保底护栏：无论多超限，保留区至少留 1 条消息（避免字节预算配置过小时清空整个会话视图）。
+   */
+  capStoredHistoryByBytes(maxBytes: number, canStartHistory?: (msg: T) => boolean): ResidencyTrimResult;
+  /**
+   * 计数器漂移校验：从 entries 全量重算字节估算，与增量计数器比对。
+   * O(n) 全量遍历，**勿在热路径调用**（lesson_54）。
+   *
+   * @returns 漂移量（`recomputed - counter`；0 = 无漂移）
+   */
+  verifyEstimatedContentBytes(): {
+    counter: number;
+    recomputed: number;
+    drift: number;
+  };
+  /**
+   * 共享裁剪循环（条数/字节两模式复用）：从 entries 头部移除 removeCount 条 message
+   * 条目，随后按 canStartHistory 谓词继续移除至工具边界对齐（保留区第一条非孤儿
+   * tool_result）。每次移除同步递减字节估算（RFC-178 D2 路径 2）。
+   *
+   * **RFC-321 R4（边界即止，不可削弱）**：裁剪**永不跨越活跃 compaction 边界**——遇到
+   * 该边界即停止，宁可少裁（removed < removeCount）也不破坏 branch 链完整性。
+   *
+   * 修复前的缺陷（RFC-321 P1-a，实证）：本循环只按 type === 'message' 从头部 splice，
+   * 既不感知 compaction 边界、也不修复被删条目后继的 parentId。一旦裁剪深度超过边界前的
+   * 死历史条数，边界条目的 parentId 就会指向已删 id → walkBranch 回溯撞空提前截断 →
+   * 边界不在 branch 上 → buildContext 走 lastBoundaryIndex === -1 分支 → **summary 静默
+   * 丢失**（模型上下文降级，用户与日志均无信号）。主要可达面是 ResidencyGovernor 的
+   * critical 档（cap 除以 4，residency-governor.ts）——内存压力下恰恰最可能触发。
+   *
+   * 边界之前的条目全是"已被摘要替换的死历史"，边界之后是模型仍在用的活跃上下文；以边界
+   * 为界即把"裁剪只能裁死历史"从时序假设变成**结构不变式**（不再依赖上游触发器配合）。
+   *
+   * @returns `removed` 实际移除条数（可能 < removeCount）；`boundaryLimited` 是否因边界
+   * 保护提前停止（诊断用，非错误）。
+   */
+  private removeOldestMessages;
+}
+//#endregion
 //#region src/message-bytes.d.ts
 /**
  * message-bytes.ts — RFC-178 D2：消息内容字节估算（会话驻留治理的字节维度口径）。
@@ -734,8 +897,18 @@ declare class InMemorySession<T = unknown> implements Session<T> {
 declare function estimateMessageContentBytes(message: unknown): number;
 //#endregion
 //#region src/store.d.ts
+/**
+ * 内存会话容器（活 Session 持有者）。注意与 {@link InMemorySessionPersistence} 区分：
+ * 本类是 `SessionStore` 实现——持有 InMemorySession 实例、提供 create/get/list/delete/fork；
+ * InMemorySessionPersistence 是 `SessionPersistence` 实现——存取 SessionSnapshot 信封。
+ * 两者都叫 "InMemory" 但服务不同契约（活对象 vs 快照存取）。
+ */
 declare class InMemorySessionStore<T = unknown> implements SessionStore<T> {
   private readonly sessions;
+  private readonly ports?;
+  constructor(ports?: InMemorySessionPorts);
+  /** 会话 id 生成走注入端口（M-2 确定性），缺省 fallback 安全随机（与 InMemorySession 同纪律）。 */
+  private newId;
   createSession(id?: string): Promise<Session<T>>;
   getSession(id: string): Session<T> | undefined;
   listSessions(): ReadonlyArray<Session<T>>;
@@ -743,11 +916,15 @@ declare class InMemorySessionStore<T = unknown> implements SessionStore<T> {
   deleteSession(id: string): Promise<boolean>;
   forkSession(sourceId: string, newId?: string): Promise<Session<T> | undefined>;
 }
-declare function createInMemorySessionStore<T = unknown>(): SessionStore<T>;
+declare function createInMemorySessionStore<T = unknown>(ports?: InMemorySessionPorts): SessionStore<T>;
 //#endregion
 //#region src/memory-persistence.d.ts
 /**
- * 内存态会话持久化。复用内核抽象基类 {@link MemoryPersistenceBase}，仅声明 `extractId` +
+ * 内存态会话持久化（SessionSnapshot 存取）。注意与 {@link InMemorySessionStore} 区分：
+ * 本类是 `SessionPersistence` 实现——存取 SessionSnapshot 信封（save/load/delete/list）；
+ * InMemorySessionStore 是 `SessionStore` 实现——持有活 InMemorySession 实例。
+ * 两者都叫 "InMemory" 但服务不同契约（快照存取 vs 活对象容器）。
+ * 复用内核抽象基类 {@link MemoryPersistenceBase}，仅声明 `extractId` +
  * 按 `SessionMetadata`（lastActiveAt/createdAt）取排序值——与 File/Remote 同款薄子类模式。
  * 内核已统一 save/load/delete/list/listPaginated 实现（M2-02，路径 A）。
  */
@@ -759,34 +936,6 @@ declare class InMemorySessionPersistence<T = unknown> extends MemoryPersistenceB
   listRecentMeta(limit: number): Promise<string[]>;
 }
 //#endregion
-//#region src/file-persistence.d.ts
-interface FileSessionPersistenceOptions {
-  baseDir: string;
-}
-/**
- * @deprecated blob session persistence replaced by RelationalSessionPersistence。
- * 仅保留为 OTTO_SESSION_BLOB=1 逃生口；关系路径线上跑稳后删除。
- */
-declare class FileSessionPersistence<T = unknown> extends DiskPersistence<SessionSnapshot<T>> implements SessionPersistence<T> {
-  /**
-   * RFC-305 M3：文件后端整份快照覆写（非游标增量）→ 'snapshot'。该后端仅为
-   * OTTO_SESSION_BLOB=1 逃生口（M63 已废弃，跑稳后删除），节流语义与 remote 一致。
-   */
-  readonly turnFlush: "snapshot";
-  private readonly sessionBaseDir;
-  private readonly sessionExtension;
-  constructor(options: FileSessionPersistenceOptions);
-  protected extractId(snapshot: SessionSnapshot<T>): string;
-  /**
-   * RFC-154 D1（blob 逃生口实现）：单文件即整个 snapshot（entries+metadata 打包），无法像
-   * SQLite 那样只读元数据列——只能先按 mtime（lastActiveAt 代理值）排序，再逐个 load() 直到
-   * 凑够 limit 个非归档会话。比"全量 load 后排序"仍更省：mtime 排序在前，命中 limit 后即
-   * 停止读取，不会读到排序靠后但从不会被选中的文件。该路径 M63 起标记弃用，不追求极致优化
-   * （RFC-154 §3 D1）。
-   */
-  listRecentMeta(limit: number): Promise<string[]>;
-}
-//#endregion
 //#region src/session-repository.d.ts
 /**
  * SessionRepository — 会话关系化仓储(row 级,结构类型)。
@@ -797,13 +946,6 @@ declare class FileSessionPersistence<T = unknown> extends DiskPersistence<Sessio
  * 本层仍只认结构化行(workspaces / sessions / session_entries)，**不依赖 SessionSnapshot 领域形状**
  * （snapshot↔rows 桥在 relational-bridge）。change_log(entry 级)属后续阶段C(gated)，本层不建。
  */
-interface WorkspaceRow {
-  readonly id: string;
-  readonly name: string;
-  readonly ownerId?: string;
-  readonly orgId?: string;
-  readonly createdAt: number;
-}
 interface SessionRow {
   readonly id: string;
   /** 分区第一维(= ws_<id>);默认 'default'。 */
@@ -837,7 +979,7 @@ interface SessionRow {
   /** 置顶分组名（RFC-158）。仅 pinned=true 时生效；缺省落入默认组。 */
   readonly pinGroup?: string;
 }
-type SessionEntryType = 'message' | 'compaction' | 'clear';
+type SessionEntryType = 'message' | 'compaction' | 'clear' | 'compaction-lock';
 /** 追加输入:seq 由仓储发号,调用方只给 entryId(幂等键)+ 内容。 */
 interface EntryInput {
   /** 客户端生成(规则0/1 幂等键);(sessionId, entryId) 唯一。 */
@@ -853,21 +995,34 @@ interface EntryRow extends EntryInput {
   /** 会话内插入序(规则0:≠ change_log 游标)。 */
   readonly seq: number;
 }
+/**
+ * touchSession 的 options 对象（RFC-393 M1：从 9 位置参数收拢）。
+ *
+ * COALESCE 语义保持不变：缺省（undefined）的字段不覆盖既有值。
+ * leaf_id 悬空防护独立于 COALESCE——校验通过才写，否则走 leafPersisted=false 分支。
+ */
+interface TouchSessionOptions {
+  id: string;
+  leafId?: string;
+  lastActiveAt: number;
+  title?: string;
+  titleSource?: 'custom' | 'ai' | 'derived';
+  config?: unknown;
+  archived?: boolean;
+  pinned?: boolean;
+  pinGroup?: string;
+}
+/**
+ * 仓储层归档能力接口（RFC-393 M2：统一能力接口模式，范式 = ReplacementHydrationCapable）。
+ * 只有 SQLite 后端实现（SqliteSessionRepository）。消费方用 {@link supportsArchive} 探测。
+ */
+interface ArchiveCapable {
+  archiveSession(sessionId: string): Promise<string>;
+  restoreArchivedSession(sessionId: string): Promise<number>;
+}
+/** 能力探测（类型守卫）。 */
+declare function supportsArchive(repo: unknown): repo is ArchiveCapable;
 interface SessionRepository {
-  /**
-   * ⚠️ **DORMANT（resume/workspace 关联审计，2026-07-11 核实）**：`workspaces` 表 + 本三方法
-   * 当前**零生产调用方**（仅 `sqlite-session-repository.test.ts` 覆盖）——对应 RFC-034 M57
-   * 里程碑设计的"web-ui workspaces CRUD"（`POST/GET/DELETE /workspaces`），但该 HTTP 路由
-   * 从未实现，只落地了本层 SQLite 原语。当前 local workspace 身份完全靠 `.otto/workspace.json`
-   * marker（`@x-otto/workspace` 包）+ `sessions.workspace_key` 列分区，不依赖本表。
-   * 参考 RFC-067 M115-04（workspace 相关代码"现实修正：不强删活包"的既有判定）与
-   * M115-02（remote-persistence-server 删除前需产品确认）先例——**接它前先把 web-ui
-   * workspaces CRUD 路由一并接上**，删它前先问是否已确认 web-ui 落地路线放弃该设计。
-   * 勿孤立增删本三方法。
-   */
-  upsertWorkspace(ws: WorkspaceRow): Promise<void>;
-  getWorkspace(id: string): Promise<WorkspaceRow | null>;
-  listWorkspaces(): Promise<WorkspaceRow[]>;
   createSession(row: SessionRow): Promise<void>;
   /**
    * 轻量排序 id 列表（RFC-154 D1）——只读 sessions 表的 `id`/`last_active_at`/`archived` 列，
@@ -902,7 +1057,7 @@ interface SessionRepository {
    * sqlite-session-repository.ts 实现注释的完整事故分析）。
    * @returns `leafPersisted` — 本次传入的 `leafId` 是否真的被采纳写入（false = 悬空，已拒绝覆盖）。
    */
-  touchSession(id: string, leafId: string | undefined, lastActiveAt: number, title?: string, titleSource?: 'custom' | 'ai' | 'derived', config?: unknown, archived?: boolean, pinned?: boolean, pinGroup?: string): Promise<{
+  touchSession(options: TouchSessionOptions): Promise<{
     leafPersisted: boolean;
   }>;
   getSession(id: string): Promise<SessionRow | null>;
@@ -1042,6 +1197,13 @@ interface SessionWriteLeaseOptions {
   renewEveryMs?: number;
   /** 是否注册 process exit 钩子同步释放(默认 true;测试注入 false 避免跨用例泄漏)。 */
   installExitHook?: boolean;
+  /**
+   * 确定性 token 生成端口（M-2）。**token 随机性是安全特性（防伪造）**，生产缺省仍走
+   * `crypto.randomUUID()`；此注入仅在测试 / 确定性重放场景使用，不得在生产路径关闭随机性。
+   */
+  idGen?: {
+    uuid(): string;
+  };
 }
 declare function createSessionWriteLeaseManager(options: SessionWriteLeaseOptions): SessionWriteLeaseManager;
 /**
@@ -1172,6 +1334,8 @@ declare class RelationalSessionPersistence<T = unknown> implements SessionPersis
 declare function sessionRowFromSnapshot<T>(snapshot: SessionSnapshot<T>, workspaceKey: string): SessionRow;
 /** 一条 SessionEntry → 仓储输入(id/parentId/type/timestamp 进列,其余进 data)。 */
 declare function entryToInput<T>(e: SessionEntry<T>): EntryInput;
+/** 一行 → SessionEntry(列还原 + data 展开)。 */
+declare function rowToEntry<T>(r: EntryRow): SessionEntry<T>;
 /** 炸开 snapshot 到仓储行(createSession + 逐条 appendEntry,保序 + parentId/leaf/config)。 */
 declare function explodeSnapshot<T>(snapshot: SessionSnapshot<T>, workspaceKey: string, repo: SessionRepository): Promise<void>;
 /** RFC-159 D4:尾窗口加载选项。 */
@@ -1251,6 +1415,26 @@ declare const SESSION_IDLE_TIMEOUT_MS: number;
 declare const SESSION_MAX: number;
 declare const SESSION_PAGE_SIZE: number;
 declare const SESSION_SNAPSHOT_VERSION: number;
+/**
+ * session_entries.type 白名单（RFC-393 P2 收尾：entry 类型注册表最小落地）。
+ * 写侧（appendEntry）校验白名单，防 bug/外部导入写入垃圾 type 行；
+ * 读侧（rowToEntry）未知 type 自然被消费方过滤（无害，无需拒绝）。
+ * 未来新增 entry 类型时必须同时加到此白名单（防漂移规则：新增类型 = 白名单 + 序列化双改动）。
+ */
+declare const SESSION_ENTRY_TYPES: readonly ["message", "compaction", "clear", "compaction-lock"];
+/** 类型守卫：entry type 是否在白名单内。 */
+declare function isKnownSessionEntryType(type: string): boolean;
+/**
+ * 面板态持久化上限（RFC-393 M1：从 in-memory-session.ts 硬编码收拢为常量）。
+ * 防止面板态无界增长；超出截断（最新在前或最新在末尾取决于面板语义）。
+ */
+declare const PANEL_STATE_LIMITS: {
+  /** 编辑文件面板：最新在前，max 50 条。 */readonly editedFiles: 50; /** 子代理面板：stat-only，max 100 条。 */
+  readonly subagents: 100; /** 回合摘要面板：最新在末尾，max 200 条。 */
+  readonly turnSummaries: 200; /** 草稿面板：max 50 条。 */
+  readonly drafts: 50; /** 输入历史（@deprecated RFC-088 M4b）：最近在末尾，max 100 条。 */
+  readonly inputHistory: 100;
+};
 //#endregion
 //#region src/sqlite-session-repository.d.ts
 /**
@@ -1271,24 +1455,18 @@ interface SqliteSessionRepositoryOptions {
  */
 declare class SqliteSessionRepository implements SessionRepository {
   private readonly db;
-  private readonly archiveDir;
+  /** RFC-393 P1-4：归档格式编排下沉独立类（gzip/jsonl/目录 + 幂等 append），本类只组合委托。 */
+  private readonly archiveStore;
   /** RFC-345：内存会话（dbPath=':memory:'）——归档不落盘（磁盘零写；:memory: 无跨重启需求）。 */
   private readonly ephemeral;
   constructor(options: SqliteSessionRepositoryOptions);
   close(): void;
-  /** RFC-324 D4 M4：归档——把会话的全部 entries 读出，逐行写入 .jsonl.gz（gzip 压缩）。
-   * 不删除 entries 行（RFC-159 R4 红线），只标记 archived=1 + 复制到外部文件。
-   * 返回值：归档文件路径。 */
+  /** RFC-324 D4 M4：归档——委托 {@link SessionArchiveStore}（RFC-393 P1-4 下沉）。 */
   archiveSession(sessionId: string): Promise<string>;
-  /** RFC-324 D4 M4：恢复——从 .jsonl.gz 读回并重建 entries（RFC-159 append-forever）
-   * 已有的 entries 不删（幂等 append 可能产生重复，appendEntry 幂等去重可容忍），
-   * 仅当 DB 中的条目数 < 归档条目数时追加缺失部分。 */
+  /** RFC-324 D4 M4：恢复——委托 {@link SessionArchiveStore}（RFC-393 P1-4 下沉）。 */
   restoreArchivedSession(sessionId: string): Promise<number>;
-  upsertWorkspace(ws: WorkspaceRow): Promise<void>;
-  getWorkspace(id: string): Promise<WorkspaceRow | null>;
-  listWorkspaces(): Promise<WorkspaceRow[]>;
   createSession(row: SessionRow): Promise<void>;
-  touchSession(id: string, leafId: string | undefined, lastActiveAt: number, title?: string, titleSource?: 'custom' | 'ai' | 'derived', config?: unknown, archived?: boolean, pinned?: boolean, pinGroup?: string): Promise<{
+  touchSession(options: TouchSessionOptions): Promise<{
     leafPersisted: boolean;
   }>;
   getSession(id: string): Promise<SessionRow | null>;
@@ -1332,6 +1510,37 @@ declare class SqliteSessionRepository implements SessionRepository {
   private batchInQuery;
 }
 //#endregion
+//#region src/session-archive-store.d.ts
+interface SessionArchiveStoreDeps {
+  /** 归档目录（与 dbPath 同级的 archives/ 子目录）。 */
+  archiveDir: string;
+  /** 内存会话（:memory:）——归档不落盘（磁盘零写；:memory: 无跨重启需求）。 */
+  ephemeral?: boolean;
+  loadEntries(sessionId: string): Promise<EntryRow[]>;
+  appendEntry(sessionId: string, entry: EntryInput): Promise<number>;
+  /** 标记/清除 archived 标志（只改 archived 列，不动 lastActiveAt——管理动作非活动，RFC-159 判据）。 */
+  setArchived(sessionId: string, archived: boolean): void;
+}
+/**
+ * 会话冷归档：entries 复制到外部 .jsonl.gz + 标 archived=1（不删除 DB 行，RFC-159 R4）。
+ * 恢复：从 .jsonl.gz 读回并幂等 append 缺失部分（appendEntry 幂等去重可容忍重复）。
+ */
+declare class SessionArchiveStore {
+  private readonly archiveDir;
+  private readonly ephemeral;
+  private readonly deps;
+  constructor(options: SessionArchiveStoreDeps);
+  private archivePath;
+  /** RFC-324 D4 M4：归档——把会话的全部 entries 读出，逐行写入 .jsonl.gz（gzip 压缩）。
+   * 不删除 entries 行（RFC-159 R4 红线），只标记 archived=1 + 复制到外部文件。
+   * 返回值：归档文件路径。 */
+  archiveSession(sessionId: string): Promise<string>;
+  /** RFC-324 D4 M4：恢复——从 .jsonl.gz 读回并重建 entries（RFC-159 append-forever）
+   * 已有的 entries 不删（幂等 append 可能产生重复，appendEntry 幂等去重可容忍），
+   * 仅当 DB 中的条目数 < 归档条目数时追加缺失部分。 */
+  restoreArchivedSession(sessionId: string): Promise<number>;
+}
+//#endregion
 //#region src/remote-persistence.d.ts
 interface RemoteSessionPersistenceOptions {
   baseUrl: string;
@@ -1375,5 +1584,5 @@ declare class RemoteSessionPersistence<T = unknown> extends RemotePersistence<Se
   listRecentMeta(limit: number): Promise<string[]>;
 }
 //#endregion
-export { type DraftEntry, type EditedFile, type EntryInput, type EntryRow, FileSessionPersistence, type FileSessionPersistenceOptions, InMemorySession, InMemorySessionPersistence, InMemorySessionStore, type LeaseInspection, type PaginationOptions, type PanelWriteOptions, type PersistedSessionConfig, type ReassembleOptions, RelationalSessionPersistence, RemotePersistenceError, RemoteSessionPersistence, type RemoteSessionPersistenceOptions, RemoteSnapshotConflictError, type ReplacementHydrationCapable, SESSION_IDLE_TIMEOUT_MS, SESSION_MAX, SESSION_MIGRATIONS, SESSION_PAGE_SIZE, SESSION_SNAPSHOT_VERSION, type Session, type SessionContext, type SessionEntry, type SessionEntryType, type SessionMetadata, type SessionPersistence, type SessionRepository, type SessionRow, type SessionSnapshot, type SessionStore, SessionWriteLeaseDeniedError, type SessionWriteLeaseManager, type SessionWriteLeaseOptions, SqliteSessionRepository, type SqliteSessionRepositoryOptions, type SubagentEntry, type TodoItem, type TurnSummaryEntry, type WorkspaceRow, createInMemorySessionStore, createNoopSessionWriteLeaseManager, createSessionWriteLeaseManager, decodeReplacementFromBlobs, encodeReplacementToBlobs, entryToInput, estimateMessageContentBytes, explodeSnapshot, hasStrippedReplacements, hashMessageContent, hydrateStrippedReplacements, reassembleSnapshot, sessionRowFromSnapshot, supportsReplacementHydration };
+export { type ArchiveCapable, type DraftEntry, type EditedFile, type EntryInput, type EntryRow, InMemorySession, InMemorySessionPersistence, InMemorySessionStore, type LeaseInspection, PANEL_STATE_LIMITS, type PaginationOptions, type PanelWriteOptions, type PersistedSessionConfig, type ReassembleOptions, RelationalSessionPersistence, RemotePersistenceError, RemoteSessionPersistence, type RemoteSessionPersistenceOptions, RemoteSnapshotConflictError, type ReplacementHydrationCapable, ResidencyPolicy, type ResidencyPolicyHost, type ResidencyTrimResult, SESSION_ENTRY_TYPES, SESSION_IDLE_TIMEOUT_MS, SESSION_MAX, SESSION_MIGRATIONS, SESSION_PAGE_SIZE, SESSION_SNAPSHOT_VERSION, type Session, SessionArchiveStore, type SessionArchiveStoreDeps, type SessionContext, type SessionEntry, type SessionEntryType, type SessionMetadata, type SessionPanelState, type SessionPersistence, type SessionRepository, type SessionRow, type SessionSnapshot, type SessionStore, SessionWriteLeaseDeniedError, type SessionWriteLeaseManager, type SessionWriteLeaseOptions, SqliteSessionRepository, type SqliteSessionRepositoryOptions, type SubagentEntry, type TodoItem, type TouchSessionOptions, type TurnSummaryEntry, createInMemorySessionStore, createNoopSessionWriteLeaseManager, createSessionWriteLeaseManager, decodeReplacementFromBlobs, encodeReplacementToBlobs, entryToInput, estimateMessageContentBytes, explodeSnapshot, hasStrippedReplacements, hashMessageContent, hydrateStrippedReplacements, isKnownSessionEntryType, reassembleSnapshot, rowToEntry, sessionRowFromSnapshot, supportsArchive, supportsReplacementHydration };
 //# sourceMappingURL=index.d.ts.map