@morlay/session-rdb 0.0.19 → 0.0.21-alpha.0

package/src/storage-takeover/storage-backend.ts

@@ -1,37 +1,20 @@
-/**
- * storages 接管：注册在 storage hub 上的 `rdb` KV 后端。它把 workspace 域
- * （上游 single 布局：一张 `workspaces` 表 + global 单例）映射到 session-rdb
- * 的语义专用表，与事件日志同库同连接；域层（`ctx.storageDomain`）通过
- * `routes` 把 `workspace` 域路由到本后端。
- *
- * 本后端只服务已知域的专用表：未知 unit 名 fail loud，而不是静默落到通用
- * 存储——表结构是显式维护的（见 docs/schema.md）。
- */
-
 import { StorageError } from "@deepseek-ai/dsh-storage";
 import type { SessionId } from "@deepseek-ai/dsh-session";
 import type { WorkspaceId } from "@deepseek-ai/dsh-workspace";
 import type { KvFacet, KvUnit, KvUnitDescriptor, StorageBackend } from "@deepseek-ai/dsh-storage";
 import type { StorageRepository, WorkspaceRecord, WorkspaceDomainState } from "./types.ts";
 
-/** 注册到 storage hub 的后端名（storage-domain 的 routes 引用它）。 */
 export const RDB_STORAGE_BACKEND = "rdb";
 
-/** 本后端唯一服务的域：上游 `workspaceDomainSpec`（v2，single 布局）。 */
 const WORKSPACE_UNIT = "workspace";
 const WORKSPACE_TABLE = "workspaces";
 
-/** 只服务 workspace 域的 KV 后端。 */
 export class RdbStorageBackend implements StorageBackend {
   readonly kv: KvFacet = { open: (descriptor) => this.openUnit(descriptor) };
 
-  /** 已打开（或打开中）的 unit；重复 open 是调用方 bug。 */
   private readonly open = new Map<string, WorkspaceKvUnit>();
   private closed = false;
 
-  /**
-   * @param repository - storages 接管表访问层（与事件日志同介质）。
-   */
   constructor(private readonly repository: StorageRepository) {}
 
   private async openUnit(descriptor: KvUnitDescriptor): Promise<KvUnit> {
@@ -47,8 +30,7 @@ export class RdbStorageBackend implements StorageBackend {
           `(table '${WORKSPACE_TABLE}' plus a global slot)`,
       );
     }
-    // 本后端是 single 布局的专用表实现：per-record 布局（及其 compatibleVersions
-    // 读语义）无法表达，宁可 fail loud 也不静默按 single 读。
+
     if (descriptor.layout !== undefined && descriptor.layout !== "single") {
       throw new Error(
         `rdb storage backend serves only the 'single' layout (domain '${descriptor.name}' ` +
@@ -58,7 +40,7 @@ export class RdbStorageBackend implements StorageBackend {
     if (this.open.has(descriptor.name)) {
       throw new Error(`kv unit '${descriptor.name}' is already open (double-open is a caller bug)`);
     }
-    // 名字在同步段预留：并发第二个 open 必须在任何 await 之前被拒。
+
     const unit = new WorkspaceKvUnit(this.repository, descriptor);
     this.open.set(descriptor.name, unit);
     try {
@@ -82,13 +64,6 @@ export class RdbStorageBackend implements StorageBackend {
     return unit;
   }
 
-  /**
-   * Release the backend. New writes are rejected immediately; already-queued
-   * unit writes drain first (upstream backend contract). The medium (the
-   * session database) belongs to the owning session-rdb plugin, so closing
-   * open units here does not close it.
-   * @returns resolution after every open unit drained.
-   */
   async close(): Promise<void> {
     this.closed = true;
     const units = [...this.open.values()];
@@ -97,10 +72,9 @@ export class RdbStorageBackend implements StorageBackend {
   }
 }
 
-/** workspace 域的 KV unit：每个原语一条 SQL 语句，值形状与上游记录一致。 */
 class WorkspaceKvUnit implements KvUnit {
   private closed = false;
-  /** 在途写操作：close 先拒绝新写，再 drain 它们（不丢已受理的写）。 */
+
   private readonly inflight = new Set<Promise<void>>();
   private onClosed: (() => void) | undefined;
 
@@ -109,7 +83,6 @@ class WorkspaceKvUnit implements KvUnit {
     private readonly descriptor: KvUnitDescriptor,
   ) {}
 
-  /** Install the name-release callback after the backend registered this unit. */
   onClose(release: () => void): void {
     this.onClosed = release;
   }
@@ -150,7 +123,6 @@ class WorkspaceKvUnit implements KvUnit {
     this.onClosed?.();
   }
 
-  /** Register one accepted write so close can drain it. */
   private async track(operation: Promise<unknown>): Promise<void> {
     const settled = operation.then(
       () => undefined,
@@ -177,7 +149,6 @@ class WorkspaceKvUnit implements KvUnit {
   }
 }
 
-/** Narrow one opaque KV record to the workspace record the domain shipped. */
 function workspaceRecordOf(value: unknown): WorkspaceRecord {
   const record = value as Partial<WorkspaceRecord> | null;
   if (
@@ -200,7 +171,6 @@ function workspaceRecordOf(value: unknown): WorkspaceRecord {
   };
 }
 
-/** Narrow one opaque KV global to the workspace registry state the domain shipped. */
 function workspaceStateOf(value: unknown): WorkspaceDomainState {
   const state = value as Partial<WorkspaceDomainState> | null;
   if (

package/src/storage-takeover/types.ts

@@ -1,14 +1,3 @@
-/**
- * storages 接管的类型：**能复用上游契约的一律复用**——记录形状来自上游
- * domain/projection 的 `z.infer` 产物（`WorkspaceRecord` / `WorkspaceDomainState`
- * / `CheckpointIdentity` / `ProjectionCheckpoint`），本文件只声明存储层的访问
- * 接口与"上游类型 + 会话键"的组合。上游 spec 变化时这里直接编译报错，不会
- * 静默偏移。
- *
- * 这些 import 全是类型导入（无运行时依赖）：rdb 是通用插件，不能硬依赖
- * web 层的 workspace 包或已被替换的 projcache 包。
- */
-
 import type { SessionId } from "@deepseek-ai/dsh-session";
 import type { CheckpointIdentity } from "@deepseek-ai/dsh-session-projection-cache";
 import type {
@@ -25,66 +14,35 @@ export type {
   WorkspaceRecord,
 };
 
-/**
- * 一个会话的完整 checkpoint：上游 `CheckpointIdentity`（日志身份，唯一权威定义
- * 在被替换的 projcache spec 里）+ 上游 `ProjectionCheckpoint`（逐 key 行）+ 会话键。
- */
 export interface StoredProjcacheEntry {
   sessionId: SessionId;
   identity: CheckpointIdentity;
   rows: ProjectionCheckpoint;
 }
 
-/**
- * storages 接管表的方言无关访问层：SQLite 与 PostgreSQL 两个 Backend 各提供
- * 同一实现，调用方（KV 后端与投影缓存服务）不感知介质差异。读方法返回持久
- * 值的语义视图，workspace 的写入在介质事务内整体替换。
- */
 export interface StorageRepository {
-  /** 读一个域的版本戳；域从未打开时 undefined。 */
   readUnitVersion(name: string): Promise<number | undefined>;
-  /** 写入域的首次版本戳；已存在时保持原值。 */
+
   insertUnitVersion(name: string, version: number): Promise<void>;
-  /** 读全部 workspace 记录（按 workspace id）。 */
+
   listWorkspaces(): Promise<Array<{ id: string; record: WorkspaceRecord }>>;
-  /** 覆盖写一条 workspace 记录（含归属行）。 */
+
   putWorkspace(id: string, record: WorkspaceRecord): Promise<void>;
-  /** 删除一条 workspace 记录（缺失为 no-op）。 */
+
   deleteWorkspace(id: string): Promise<void>;
-  /** 读 workspace 单例；从未写入时 null。 */
+
   readWorkspaceState(): Promise<WorkspaceDomainState | null>;
-  /** 覆盖写 workspace 单例（显示顺序与归档集一并整体替换）。 */
+
   writeWorkspaceState(state: WorkspaceDomainState): Promise<void>;
-  /** 读全部投影 checkpoint（含逐 key 行）。 */
+
   loadProjcache(): Promise<StoredProjcacheEntry[]>;
-  /**
-   * 同步读一个会话的 checkpoint：只有同步驱动（SQLite）提供，读路径直接落到
-   * 介质；异步驱动（PostgreSQL）缺席，调用方退化为写穿镜像。上游的
-   * `cachedSnapshot` 系列是同步签名，这里的存在性就是"能否直读库"的开关。
-   * @param sessionId - 会话 id。
-   * @returns 该会话的 checkpoint，缺失时 `undefined`。
-   */
-  readProjcacheSync?(sessionId: string): StoredProjcacheEntry | undefined;
-  /**
-   * 同步读一个会话的标题列（`t_sessions.f_title` / `f_title_seq`，rdb 写路径与
-   * rewind 维护）：只有同步驱动提供，列表消费直接取会话数据，不依赖 checkpoint
-   * 行是否存在。
-   * @param sessionId - 会话 id。
-   * @returns 标题与其事件 seq，未写过标题时 `undefined`。
-   */
-  readSessionTitleSync?(sessionId: string): { title: string; seq: number } | undefined;
-  /**
-   * 覆盖写一个会话的 checkpoint 行（先清旧行再写新行，同一事务）。记录头
-   * 不在这里：它与 `t_sessions` 行 1:1，identity 直接复用该行的列。
-   * @param sessionId - 会话 id。
-   * @param rows - 每个投影 key 一行。
-   */
+
+  /** 不经 await、直接读的路径（供同步的 `cachedSnapshot` 消费）；宿主提供不了则缺省。 */
+  readProjcacheDirect?(sessionId: string): StoredProjcacheEntry | undefined;
+
+  readSessionTitleDirect?(sessionId: string): { title: string; seq: number } | undefined;
+
   putProjcache(sessionId: string, rows: ProjectionCheckpoint): Promise<void>;
-  /**
-   * 清理陈旧 checkpoint 行：水位为负却已有事件的会话（旧版写入路径的产物，
-   * 会把有对话的会话误判为空白）。缓存是派生数据，删除只让该会话回到
-   * 「未知即可见」并等待下一次强制点重写。
-   * @returns 删除的行数。
-   */
+
   pruneStaleProjcache(): Promise<number>;
 }

package/src/storage.ts

@@ -1,5 +1,3 @@
-// 存储引擎层：schema 常量/表定义、sqlite 后端（openDatabase / SqliteBackend）与
-// 并发写保护（WriteGuard）。文件物理分开，经本入口聚合导出。
 export * from "./schema.ts";
 export * from "./sqlite.ts";
 export * from "./write-guard.ts";

package/src/testing/contract.ts

@@ -18,29 +18,17 @@ import {
   type SessionPersistence,
 } from "@deepseek-ai/dsh-session-persistence";
 
-/** One backend service instance under test plus its teardown. */
 interface ContractBackendInstance {
   persistence: SessionPersistence;
   dispose: () => Promise<void>;
 }
 
-/** A backend under test: the primary instance plus optional storage-level capabilities. */
 export interface ContractBackend extends ContractBackendInstance {
-  /**
-   * Open a FRESH backend instance over the SAME storage, as another process
-   * would after this one exits. Enables the cross-instance visibility and
-   * reopen-continuation tests; a backend without shared storage omits it and
-   * those tests self-skip.
-   */
   reopen?: () => Promise<ContractBackendInstance>;
-  /**
-   * Inject a torn physical tail after the committed log of one stored session,
-   * simulating a crash mid-write. Enables the torn-tail tests.
-   */
+
   corruptTail?: (id: SessionId, cwd: string | undefined) => Promise<void>;
 }
 
-/** Build a minimal {@link SessionHeader} for a session id. */
 export function meta(id: string, cwd?: string): SessionHeader {
   return {
     version: SESSION_FORMAT_VERSION,
@@ -51,7 +39,6 @@ export function meta(id: string, cwd?: string): SessionHeader {
   };
 }
 
-/** A well-formed one-turn event log (contiguous seqs from 0). */
 export function oneTurnLog(): SessionEvent[] {
   return [
     { type: "turn/start", seq: SessionSeq(0), time: 1, data: { turn: 1 } },
@@ -108,7 +95,6 @@ export function oneTurnLog(): SessionEvent[] {
   ];
 }
 
-/** A contiguous second-turn batch continuing {@link oneTurnLog}. */
 function secondTurn(startSeq = 6): SessionEvent[] {
   return [
     { type: "turn/start", seq: SessionSeq(startSeq), time: 9, data: { turn: 2 } },
@@ -136,12 +122,6 @@ export function appendLog(session: Session, events: readonly SessionEvent[]): vo
   }
 }
 
-/**
- * Run the backend-agnostic handle contract suite. `make()` MUST return a
- * fresh backend over fresh, empty storage each call.
- * @param name - suite label, e.g. `jsonl-none` / `sqlite`.
- * @param make - factory producing one fresh {@link ContractBackend} per test.
- */
 export function runPersistenceContract(name: string, make: () => Promise<ContractBackend>): void {
   describe(`SessionPersistence contract: ${name}`, () => {
     it("round-trips through one write handle: append, self-read, offset/length defaults", async () => {
@@ -155,18 +135,18 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         expect(handle.header).toMatchObject(m);
 
         await handle.append(log);
-        // An empty batch is a no-op, not an error.
+
         await handle.append([]);
-        // A write handle reads its own successful appends.
+
         const full = await handle.read();
         expect(full.events).toEqual(log);
         expect((await handle.read(3)).events).toEqual(log.slice(3));
         expect((await handle.read(0, 2)).events).toEqual(log.slice(0, 2));
         expect((await handle.read(1, 3)).events).toEqual(log.slice(1, 4));
-        // At/past the stored end: an empty list, never an error.
+
         expect((await handle.read(log.length)).events).toEqual([]);
         expect((await handle.read(log.length + 100)).events).toEqual([]);
-        // flush after a durable append is a satisfied barrier, not an error.
+
         await handle.flush();
         await handle.close();
       } finally {
@@ -194,8 +174,7 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         await expect(persistence.create(meta("dup-pending"))).rejects.toBeInstanceOf(
           SessionAlreadyExistsError,
         );
-        // Closing the creator without ever appending erases the session, so
-        // the id is free again.
+
         await first.close();
         const second = await persistence.create(meta("dup-pending"));
         await second.close();
@@ -263,7 +242,7 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
       try {
         const m = meta("owned");
         const creator = await persistence.create(m);
-        // The creator holds ownership even before materialization.
+
         await expect(persistence.open(m.id, "write")).rejects.toBeInstanceOf(
           SessionAlreadyOwnedError,
         );
@@ -273,7 +252,6 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         );
         await creator.close();
 
-        // After close, a new write handle continues at the stored next-seq.
         const writer = await persistence.open(m.id, "write");
         await writer.append(secondTurn());
         expect((await writer.read()).events.map((e) => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7]);
@@ -295,7 +273,7 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         expect(reader.access).toBe("read");
         await expect(reader.append(secondTurn())).rejects.toBeInstanceOf(SessionReadOnlyError);
         await expect(reader.flush()).rejects.toBeInstanceOf(SessionReadOnlyError);
-        // The refusals mutated nothing.
+
         expect((await reader.read()).events).toEqual(oneTurnLog());
         await reader.close();
       } finally {
@@ -319,7 +297,7 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
           await using writer = await persistence.open(m.id, "write");
           await writer.append(secondTurn());
         }
-        // Leaving the block disposed the handle, so ownership is free again.
+
         const reopened = await persistence.open(m.id, "write");
         await reopened.close();
       } finally {
@@ -332,8 +310,7 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
       try {
         const materialized = await backend.persistence.create(meta("flush-all"));
         const abandoned = await backend.persistence.create(meta("flush-all-closing"));
-        // Close starts before the barrier: the swept handle refuses its flush,
-        // which counts as flushed — close itself drained durably.
+
         const closing = abandoned.close();
         await backend.persistence.flush();
         await closing;
@@ -341,9 +318,8 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         if (backend.reopen !== undefined) {
           const reopened = await backend.reopen();
           try {
-            // The barrier materialized the empty session durably...
             expect(await reopened.persistence.stat(SessionId("flush-all"))).toBeDefined();
-            // ...while the one that closed unappended never existed.
+
             expect(await reopened.persistence.stat(SessionId("flush-all-closing"))).toBeUndefined();
           } finally {
             await reopened.dispose();
@@ -360,7 +336,7 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
       try {
         const m = meta("lazy", "/work");
         const creator = await backend.persistence.create(m);
-        // The creator's own reads see the empty log before materialization.
+
         expect((await creator.read()).events).toEqual([]);
 
         const snapshot = await backend.persistence.stat(m.id);
@@ -440,8 +416,7 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         expect((await before.read()).events).toEqual(oneTurnLog());
 
         await writer.append(secondTurn());
-        // Both a pre-existing read handle and a freshly opened one observe the
-        // append once it has resolved.
+
         expect((await before.read()).events.map((e) => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7]);
         const after = await persistence.open(m.id, "read");
         expect((await after.read()).events.map((e) => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7]);
@@ -481,10 +456,10 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
       try {
         const m = meta("contiguity");
         const handle = await persistence.create(m);
-        await handle.append(oneTurnLog()); // seqs 0..5, next-seq = 6
-        // A re-append of an already-stored seq is rejected, not duplicated.
+        await handle.append(oneTurnLog());
+
         await expect(handle.append(oneTurnLog())).rejects.toThrow(/expected 6/);
-        // A mid-batch gap is rejected as a whole.
+
         const gapped: SessionEvent[] = [
           { type: "turn/start", seq: SessionSeq(6), time: 9, data: { turn: 2 } },
           {
@@ -495,7 +470,7 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
           },
         ];
         await expect(handle.append(gapped)).rejects.toThrow(/expected 7/);
-        // Neither rejection changed the stored log.
+
         expect((await handle.read()).events.map((e) => e.seq)).toEqual([0, 1, 2, 3, 4, 5]);
         await handle.close();
       } finally {
@@ -520,7 +495,7 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         await expect(handle.append(bad(1n))).rejects.toThrow(TypeError);
         await expect(handle.append(bad(1n))).rejects.toThrow(/losslessly JSON-serializable/);
         await expect(handle.append(bad(undefined))).rejects.toThrow(/losslessly JSON-serializable/);
-        // The rejected batches left no events behind: seq 0 is still free.
+
         await handle.append(oneTurnLog());
         expect((await handle.read()).events).toEqual(oneTurnLog());
         await handle.close();
@@ -535,7 +510,7 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         const m = meta("foreign-vocabulary");
         const handle = await persistence.create(m);
         await handle.append(oneTurnLog());
-        // 写路径当前格式校验：未知类型（非 ignorable）拒绝入库，批次不落库。
+
         await expect(
           handle.append([
             { type: "mystery/event", seq: SessionSeq(6), time: 7, data: { payload: true } },
@@ -543,7 +518,6 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         ).rejects.toBeInstanceOf(SessionFormatUnsupportedError);
         await handle.close();
 
-        // 拒绝的批次未落库：log 只有 oneTurnLog，可正常读写。
         const reader = await persistence.open(m.id, "read");
         try {
           const { events } = await reader.read();
@@ -579,15 +553,12 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         await creator.close();
         await backend.corruptTail(m.id, m.cwd);
 
-        // A reader over the corrupted artifact serves only the committed prefix.
         const readerInstance = await backend.reopen();
         try {
           const reader = await readerInstance.persistence.open(m.id, "read");
           expect((await reader.read()).events).toEqual(oneTurnLog());
           await reader.close();
 
-          // A write open + first append durably truncates the torn tail and
-          // continues at the committed next-seq.
           const writer = await readerInstance.persistence.open(m.id, "write");
           await writer.append(secondTurn());
           expect((await writer.read()).events.map((e) => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7]);
@@ -596,7 +567,6 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
           await readerInstance.dispose();
         }
 
-        // The repaired log is intact for the next instance.
         const verifyInstance = await backend.reopen();
         try {
           const verify = await verifyInstance.persistence.open(m.id, "read");
@@ -630,7 +600,6 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         const listChanged = (await persistence.list()).find((s) => s.header.id === m.id);
         expect(listChanged?.revision).toBe(statChanged?.revision);
 
-        // Snapshot headers carry the stored header, identically everywhere.
         const reader = await persistence.open(m.id, "read");
         expect(statChanged?.header).toEqual(reader.header);
         expect(listChanged?.header).toEqual(reader.header);

package/src/testing/coordinator-contract.ts

@@ -25,11 +25,6 @@ function send(session: Session, events: readonly SessionEvent[]): void {
   appendLog(session, events);
 }
 
-/**
- * RDB 特有行为契约：live 会话驱动持久化、seed 边界、fork/resume、HMR
- * dispose drain、冲突拒绝、torn-tail。coordinator 内部状态（ownerless /
- * per-id chain / legacy 迁移）已由新版 handle 模型承担，不再单独测试。
- */
 export function runCoordinatorContract(
   name: string,
   makeFixture: () => Promise<CoordinatorFixture>,
@@ -169,15 +164,14 @@ export function runCoordinatorContract(
       const { ctx, fiber } = await freshCtx(fix);
       try {
         const seed = oneTurnLog();
-        // A fork: a brand-new id whose seed came from elsewhere.
+
         const forked = ctx.sessions.create(SessionId("forked"), { seed, meta: { cwd: WORK } });
-        await ctx.sessions.flush(forked); // onCreated persisted the seed
+        await ctx.sessions.flush(forked);
         const loaded = await readAll(ctx, SessionId("forked"));
-        // Fork is where the marker earns its keep: the inherited prefix may
-        // carry a bracket the still-running parent owns.
+
         expect(loaded.events.slice(0, seed.length)).toEqual(seed);
         expect(loaded.events.at(-1)).toMatchObject({ type: "session/end-seed", seq: seed.length });
-        // A flush with no NEW events must not double-write.
+
         await ctx.sessions.flush(forked);
         const reloaded = await readAll(ctx, SessionId("forked"));
         expect(reloaded.events).toEqual(loaded.events);
@@ -205,13 +199,13 @@ export function runCoordinatorContract(
           seed: loaded.events,
           meta: { cwd: WORK },
         });
-        await second.ctx.sessions.flush(s2); // let onCreated adopt
+        await second.ctx.sessions.flush(s2);
         s2.append("turn/start", { turn: 2 });
         s2.append("turn/end", { turn: 2, reason: { kind: "completed" } });
         await second.ctx.sessions.flush(s2);
 
         const reloaded = await readAll(second.ctx, SessionId("resumed"));
-        // 0-5 the resumed seed, 6 end-seed, 7-8 the new turn.
+
         expect(reloaded.events.map((e) => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8]);
         expect(reloaded.events[6]).toMatchObject({ type: "session/end-seed" });
       } finally {
@@ -224,7 +218,7 @@ export function runCoordinatorContract(
       const fix = await makeFixture();
       const ctx = new Context();
       await ctx.plugin(SessionStore);
-      // A session exists BEFORE the persistence plugin is applied.
+
       const session = ctx.sessions.create(SessionId("pre-existing"), { meta: { cwd: WORK } });
       session.append("turn/start", { turn: 1 });
       session.append(
@@ -239,7 +233,6 @@ export function runCoordinatorContract(
 
       const fiber = await fix.mount(ctx);
       try {
-        // The plugin seeded it on apply; a subsequent flush persists its events.
         await ctx.sessions.flush(session);
         const loaded = await readAll(ctx, SessionId("pre-existing"));
         expect(loaded.events.length).toBeGreaterThanOrEqual(2);
@@ -265,10 +258,9 @@ export function runCoordinatorContract(
         { surfaceOp: "append" },
       );
       session.append("turn/end", { turn: 1, reason: { kind: "completed" } });
-      // No explicit flush — dispose must drain.
+
       await fiber.dispose();
 
-      // A fresh backend instance reads what the disposed one drained.
       const second = await freshCtx(fix);
       try {
         const loaded = await readAll(second.ctx, SessionId("drain"));
@@ -283,7 +275,6 @@ export function runCoordinatorContract(
       const fix = await makeFixture();
       const { ctx, fiber } = await freshCtx(fix);
       try {
-        // Persist a session with cwd WORK.
         let first!: Session;
         const firstFiber = await ctx.plugin(
           Object.assign(
@@ -297,7 +288,6 @@ export function runCoordinatorContract(
         await ctx.sessions.flush(first);
         await firstFiber.dispose();
 
-        // A NEW live session with the same id but a DIFFERENT cwd must be rejected.
         let second!: Session;
         await ctx.plugin(
           Object.assign(
@@ -318,8 +308,6 @@ export function runCoordinatorContract(
       const fix = await makeFixture();
       const { ctx, fiber } = await freshCtx(fix);
       try {
-        // A live session created then disposed BEFORE its first append: never
-        // materialized. A new live session reusing the id must reclaim it.
         let firstSession!: Session;
         const firstFiber = await ctx.plugin(
           Object.assign(
@@ -329,8 +317,8 @@ export function runCoordinatorContract(
             { inject: ["sessions"] },
           ),
         );
-        await ctx.sessions.flush(firstSession); // register the lazy state
-        await firstFiber.dispose(); // disposed before any append → never materialized
+        await ctx.sessions.flush(firstSession);
+        await firstFiber.dispose();
 
         let reuse!: Session;
         await ctx.plugin(
@@ -362,7 +350,6 @@ export function runCoordinatorContract(
         await handle.append(oneTurnLog());
         await handle.close();
 
-        // A fresh backend instance appends through a write handle.
         const writer = await ctx.sessionPersistence.open(SessionId("storage-only"), "write");
         await writer.append([
           { type: "turn/start", seq: SessionSeq(6), time: 7, data: { turn: 2 } },
@@ -430,12 +417,10 @@ export function runCoordinatorContract(
         await creator.close();
         await fix.corruptTail(SessionId("torn"), WORK);
 
-        // A reader serves only the committed prefix.
         const reader = await ctx.sessionPersistence.open(SessionId("torn"), "read");
         expect((await reader.read()).events).toEqual(oneTurnLog());
         await reader.close();
 
-        // A write open + first append durably truncates the torn tail.
         const writer = await ctx.sessionPersistence.open(SessionId("torn"), "write");
         await writer.append([
           { type: "turn/start", seq: SessionSeq(6), time: 7, data: { turn: 2 } },

package/src/testing.ts

@@ -1,7 +1,7 @@
-// 测试支撑（跨包测试共享）：helpers / contract / coordinator-contract。
-// 仅供 vitest 测试引用；不进入运行时 bundle。
 export { EmptySettings } from "./testing/helpers.ts";
 export type { ContractBackend } from "./testing/contract.ts";
 export { appendLog, meta, oneTurnLog, runPersistenceContract } from "./testing/contract.ts";
 export type { CoordinatorFixture } from "./testing/coordinator-contract.ts";
 export { runCoordinatorContract } from "./testing/coordinator-contract.ts";
+
+export { truncateLiveSession } from "./branch.ts";