@morlay/session-rdb 0.0.14 → 0.0.16-alpha.0

package/src/testing/contract.ts

@@ -1,27 +1,46 @@
 import { describe, expect, it } from "vitest";
-import {
-  SESSION_FORMAT_VERSION,
-  Session,
-  SessionId,
-  SessionLogOffset,
-  SessionSeq,
-  TOOL_NOT_STARTED,
-  TOOL_OUTCOME_UNKNOWN,
-} from "@deepseek-ai/dsh-session";
+import { SESSION_FORMAT_VERSION, Session, SessionId, SessionSeq } from "@deepseek-ai/dsh-session";
 import type {
   SessionEvent,
   SessionHeader,
   SurfaceEventType,
   SurfaceIntent,
 } from "@deepseek-ai/dsh-session";
-import { ToolCallId, MessageId, createMessage, freezeMessage } from "@deepseek-ai/dsh-llm";
-import type { SessionPersistence } from "@deepseek-ai/dsh-session-persistence";
+import { MessageId, freezeMessage } from "@deepseek-ai/dsh-llm";
+import {
+  SessionAlreadyExistsError,
+  SessionAlreadyOwnedError,
+  SessionFormatUnsupportedError,
+  SessionHandleClosedError,
+  SessionPersistenceNotFoundError,
+  SessionReadOnlyError,
+  type SessionHandle,
+  type SessionPersistence,
+} from "@deepseek-ai/dsh-session-persistence";
 
-export interface ContractBackend {
+/** 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,
@@ -32,6 +51,7 @@ 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 } },
@@ -65,6 +85,16 @@ export function oneTurnLog(): SessionEvent[] {
             model: "mock",
           },
         }),
+        stream: [
+          { type: "chunk", time: 3, chunk: { type: "block-start", index: 0, blockType: "text" } },
+          { type: "text-chunks", time0: 3, index: 0, dt: [], texts: ["hello"] },
+          {
+            type: "chunk",
+            time: 4,
+            chunk: { type: "block-end", index: 0, block: { type: "text", text: "hello" } },
+          },
+          { type: "chunk", time: 4, chunk: { type: "finish", reason: { kind: "stop" } } },
+        ],
       },
       surfaceOp: "append",
     },
@@ -78,6 +108,19 @@ 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 } },
+    {
+      type: "turn/end",
+      seq: SessionSeq(startSeq + 1),
+      time: 10,
+      data: { turn: 2, reason: { kind: "completed" } },
+    },
+  ];
+}
+
 export function appendLog(session: Session, events: readonly SessionEvent[]): void {
   for (const e of events) {
     const se = e as SessionEvent<SurfaceEventType>;
@@ -93,467 +136,509 @@ 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 a session: create + append → load returns identical meta and byte-identical events", async () => {
+    it("round-trips through one write handle: append, self-read, offset/length defaults", async () => {
       const { persistence, dispose } = await make();
       try {
-        const m = meta("s1", "/work");
+        const m = meta("round-trip", "/work");
         const log = oneTurnLog();
-        await persistence.create(m);
-        await persistence.append(m.id, log);
-
-        const loaded = await persistence.load(m.id);
-        expect(loaded.meta).toMatchObject({
-          version: SESSION_FORMAT_VERSION,
-          id: m.id,
-          cwd: "/work",
-        });
-        expect(loaded.events).toEqual(log);
+        const handle = await persistence.create(m);
+        expect(handle.access).toBe("write");
+        expect(handle.id).toBe(m.id);
+        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 {
         await dispose();
       }
     });
 
-    it("rejects a fractional creation timestamp without reserving its session id", async () => {
+    it("read rejects negative or fractional offsets and lengths", async () => {
       const { persistence, dispose } = await make();
       try {
-        const m = { ...meta("fractional-created-at"), createdAt: 1.5 };
-        await expect(persistence.create(m)).rejects.toThrow(
-          "session metadata createdAt must be a non-negative safe integer",
-        );
-
-        const valid = meta("fractional-created-at");
-        await persistence.create(valid);
-        await persistence.append(valid.id, oneTurnLog());
-        expect((await persistence.load(valid.id)).meta.createdAt).toBe(valid.createdAt);
+        const handle = await persistence.create(meta("read-args"));
+        await expect(handle.read(-1)).rejects.toThrow(/non-negative safe integer/);
+        await expect(handle.read(1.5)).rejects.toThrow(/non-negative safe integer/);
+        await expect(handle.read(0, -1)).rejects.toThrow(/non-negative safe integer/);
+        await handle.close();
       } finally {
         await dispose();
       }
     });
 
-    it("crash recovery: load preserves an interrupted (unclosed) turn and closes it with turn/end {interrupted}", async () => {
+    it("duplicate create rejects against a live pending session and allows the id after an erasing close", async () => {
       const { persistence, dispose } = await make();
       try {
-        const m = meta("interrupted");
-        await persistence.create(m);
-        await persistence.append(m.id, oneTurnLog()); // turn 1, committed (seqs 0..5)
-        // A second turn that crashed mid-flight: turn/start + step/start were
-        // durably written, but no step/end / turn/end ever arrived.
-        await persistence.append(m.id, [
-          { type: "turn/start", seq: SessionSeq(6), time: 7, data: { turn: 2 } },
-          { type: "step/start", seq: SessionSeq(7), time: 8, data: { turn: 2, step: 1 } },
-        ]);
-        const beforeRepair = (await persistence.listSnapshots()).find(
-          (snapshot) => snapshot.header.id === m.id,
-        )?.revision;
-
-        const inspected = await persistence.inspect(m.id);
-        const afterInspect = (await persistence.listSnapshots()).find(
-          (snapshot) => snapshot.header.id === m.id,
-        )?.revision;
-        expect(afterInspect).toBe(beforeRepair);
-        expect(inspected.events.map((e) => e.type)).toEqual([
-          "turn/start",
-          "user/message",
-          "step/start",
-          "assistant/message",
-          "step/end",
-          "turn/end",
-          "turn/start",
-          "step/start",
-          "step/end",
-          "turn/end",
-        ]);
-
-        // load PRESERVES the interrupted turn's events (a turn can be huge — they
-        // must not be truncated) and closes the orphaned turn with synthetic
-        // boundary events: step/end (the step was open) then turn/end {interrupted}.
-        const loaded = await persistence.load(m.id);
-        const afterRepair = (await persistence.listSnapshots()).find(
-          (snapshot) => snapshot.header.id === m.id,
-        )?.revision;
-        expect(afterRepair).not.toBe(beforeRepair);
-        expect(loaded.events.map((e) => e.type)).toEqual([
-          "turn/start",
-          "user/message",
-          "step/start",
-          "assistant/message",
-          "step/end",
-          "turn/end", // turn 1
-          "turn/start",
-          "step/start",
-          "step/end",
-          "turn/end", // turn 2: real events + synthetic closers
-        ]);
-        expect(loaded.events.map((e) => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
-        const last = loaded.events.at(-1)!;
-        expect(last.type === "turn/end" && last.data.reason).toEqual({ kind: "interrupted" });
-
-        // The closed log is durable and continuable: a fresh append continues at
-        // the balanced length (seq 10), and a reload round-trips identically.
-        await persistence.append(m.id, [
-          { type: "turn/start", seq: SessionSeq(10), time: 9, data: { turn: 3 } },
-          {
-            type: "turn/end",
-            seq: SessionSeq(11),
-            time: 10,
-            data: { turn: 3, reason: { kind: "completed" } },
-          },
-        ]);
-        const reloaded = await persistence.load(m.id);
-        expect(reloaded.events.map((e) => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]);
+        const first = await persistence.create(meta("dup-pending"));
+        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();
       } finally {
         await dispose();
       }
     });
 
-    it("crash recovery: an unstarted assistant tool request gets a retryable synthetic result", async () => {
+    it("concurrent duplicate creates: one wins, the loser rejects SessionAlreadyExistsError", async () => {
       const { persistence, dispose } = await make();
       try {
-        const m = meta("interrupted-toolcall");
-        await persistence.create(m);
-        await persistence.append(m.id, oneTurnLog()); // turn 1, committed (seqs 0..5)
-        // Turn 2 crashed AFTER the assistant message asked for a tool call but
-        // BEFORE the tool/result was written (the loop runs tools after logging
-        // the assistant message — a process killed mid-tool lands exactly here).
-        await persistence.append(m.id, [
-          { type: "turn/start", seq: SessionSeq(6), time: 7, data: { turn: 2 } },
-          { type: "step/start", seq: SessionSeq(7), time: 8, data: { turn: 2, step: 1 } },
-          {
-            type: "assistant/message",
-            seq: SessionSeq(8),
-            time: 9,
-            data: {
-              turn: 2,
-              step: 1,
-              message: createMessage({
-                role: "assistant",
-                content: [
-                  { type: "tool-call", id: ToolCallId("call-x"), name: "bash", arguments: "{}" },
-                ],
-                source: {
-                  kind: "model",
-                  provider: "mock",
-                  model: "mock",
-                },
-              }),
-            },
-            surfaceOp: "append",
-          },
-        ]);
-
-        const loaded = await persistence.load(m.id);
-        // The orphaned call is answered by a synthetic error tool/result BEFORE
-        // step/end + turn/end {interrupted}, so the step (and turn) are balanced
-        // and a resumed session derives a valid transcript (no dangling call).
-        expect(loaded.events.map((e) => e.type)).toEqual([
-          "turn/start",
-          "user/message",
-          "step/start",
-          "assistant/message",
-          "step/end",
-          "turn/end", // turn 1
-          "turn/start",
-          "step/start",
-          "assistant/message",
-          "tool/result",
-          "step/end",
-          "turn/end", // turn 2
-        ]);
-        const synthetic = loaded.events.find((e) => e.type === "tool/result");
-        expect(synthetic?.type === "tool/result" && synthetic.data).toMatchObject({
-          message: {
-            source: { kind: "tool", callId: ToolCallId("call-x") },
-            content: [{ type: "tool-result", toolCallId: ToolCallId("call-x"), isError: true }],
-          },
-          error: { code: TOOL_NOT_STARTED },
-        });
-        // The synthetic result carries the SAME callId as the orphaned tool-call,
-        // so deriveMessages() pairs them — no provider-invalid dangling call.
-        const call = loaded.events.findLast((e) => e.type === "assistant/message");
-        const callId =
-          call?.type === "assistant/message" &&
-          call.data.message.content.find((b) => b.type === "tool-call");
-        expect(callId && callId.type === "tool-call" && callId.id).toBe(ToolCallId("call-x"));
+        const m = meta("dup-race");
+        const results = await Promise.allSettled([persistence.create(m), persistence.create(m)]);
+        const winners = results.filter((r) => r.status === "fulfilled");
+        const losers = results.filter((r) => r.status === "rejected");
+        expect(winners).toHaveLength(1);
+        expect(losers).toHaveLength(1);
+        expect((losers[0] as PromiseRejectedResult).reason).toBeInstanceOf(
+          SessionAlreadyExistsError,
+        );
+        await (winners[0] as PromiseFulfilledResult<SessionHandle>).value.close();
       } finally {
         await dispose();
       }
     });
 
-    it("crash recovery: a recorded tool call with no result tells the model to assess retry risk", async () => {
-      const { persistence, dispose } = await make();
+    it("duplicate create rejects against a materialized artifact seen by a fresh instance", async () => {
+      const backend = await make();
       try {
-        const m = meta("unknown-tool-outcome");
-        await persistence.create(m);
-        await persistence.append(m.id, [
-          { type: "turn/start", seq: SessionSeq(0), time: 1, data: { turn: 1 } },
-          { type: "step/start", seq: SessionSeq(1), time: 2, data: { turn: 1, step: 1 } },
-          {
-            type: "assistant/message",
-            seq: SessionSeq(2),
-            time: 3,
-            data: {
-              turn: 1,
-              step: 1,
-              message: createMessage({
-                role: "assistant",
-                content: [
-                  {
-                    type: "tool-call",
-                    id: ToolCallId("call-risk"),
-                    name: "write",
-                    arguments: "{}",
-                  },
-                ],
-                source: {
-                  kind: "model",
-                  provider: "mock",
-                  model: "mock",
-                },
-              }),
-            },
-            surfaceOp: "append",
-          },
-          {
-            type: "tool/call",
-            seq: SessionSeq(3),
-            time: 4,
-            data: {
-              turn: 1,
-              step: 1,
-              callId: ToolCallId("call-risk"),
-              name: "write",
-              arguments: "{}",
-            },
-          },
-        ]);
-
-        const loaded = await persistence.load(m.id);
-        const synthetic = loaded.events.find((e) => e.type === "tool/result");
-        expect(synthetic?.type === "tool/result" && synthetic.data.error).toEqual({
-          name: "ToolOutcomeUnknownError",
-          code: TOOL_OUTCOME_UNKNOWN,
-        });
-        if (
-          synthetic?.type !== "tool/result" ||
-          synthetic.data.message.content[0].content[0]?.type !== "text"
-        ) {
-          throw new Error("expected a text tool result");
+        if (backend.reopen === undefined) return;
+        const m = meta("dup-stored", "/work");
+        const handle = await backend.persistence.create(m);
+        await handle.append(oneTurnLog());
+        await handle.close();
+
+        const reopened = await backend.reopen();
+        try {
+          await expect(
+            reopened.persistence.create(meta("dup-stored", "/work")),
+          ).rejects.toBeInstanceOf(SessionAlreadyExistsError);
+        } finally {
+          await reopened.dispose();
         }
-        expect(synthetic.data.message.content[0].content[0].text).toContain(
-          "retry only if the operation is read-only or idempotent",
-        );
-        expect(synthetic.data.message.content[0].content[0].text).toContain(
-          "if it may have side effects, first verify external state or ask the user",
+      } finally {
+        await backend.dispose();
+      }
+    });
+
+    it("open of an absent session rejects with SessionPersistenceNotFoundError for both accesses", async () => {
+      const { persistence, dispose } = await make();
+      try {
+        await expect(persistence.open(SessionId("absent"), "read")).rejects.toBeInstanceOf(
+          SessionPersistenceNotFoundError,
         );
-        const resumed = Session.create(
-          m.id,
-          loaded.events,
-          loaded.meta,
-          loaded.inheritedEventCount,
+        await expect(persistence.open(SessionId("absent"), "write")).rejects.toBeInstanceOf(
+          SessionPersistenceNotFoundError,
         );
-        const resumedResult = resumed
-          .deriveMessages()
-          .find((message) => message.content.some((block) => block.type === "tool-result"));
-        expect(resumedResult?.content[0]).toMatchObject({
-          type: "tool-result",
-          toolCallId: ToolCallId("call-risk"),
-          isError: true,
-        });
       } finally {
         await dispose();
       }
     });
 
-    it("list() excludes a created-but-never-appended (zero-event) session", async () => {
+    it("write ownership is single-holder per instance and released by close", async () => {
       const { persistence, dispose } = await make();
       try {
-        await persistence.create(meta("empty"));
-        expect((await persistence.list()).map((m) => m.id)).not.toContain(SessionId("empty"));
-        expect(
-          (await persistence.listSnapshots()).map((snapshot) => snapshot.header.id),
-        ).not.toContain(SessionId("empty"));
+        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,
+        );
+        await creator.append(oneTurnLog());
+        await expect(persistence.open(m.id, "write")).rejects.toBeInstanceOf(
+          SessionAlreadyOwnedError,
+        );
+        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]);
+        await writer.close();
       } finally {
         await dispose();
       }
     });
 
-    it("rejects pre-aborted observation reads with the exact cancellation reason", async () => {
+    it("a read handle refuses append and flush with SessionReadOnlyError", async () => {
       const { persistence, dispose } = await make();
       try {
-        const reason = new Error("persistence observation cancelled");
-        const controller = new AbortController();
-        await expect(persistence.listSnapshots(controller.signal)).resolves.toEqual([]);
-        controller.abort(reason);
+        const m = meta("read-only");
+        const writer = await persistence.create(m);
+        await writer.append(oneTurnLog());
+        await writer.close();
 
-        await expect(persistence.list(controller.signal)).rejects.toBe(reason);
-        await expect(persistence.listSnapshots(controller.signal)).rejects.toBe(reason);
-        await expect(
-          persistence.inspect(SessionId("cancelled-inspect"), controller.signal),
-        ).rejects.toBe(reason);
-        await expect(
-          persistence.readFrom(
-            SessionId("cancelled-read-from"),
-            SessionLogOffset(0),
-            controller.signal,
-          ),
-        ).rejects.toBe(reason);
+        const reader = await persistence.open(m.id, "read");
+        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 {
         await dispose();
       }
     });
 
-    it("readFrom returns exactly the stored suffix from the requested seq, without mutating the log", async () => {
+    it("operations on a closed handle reject; close is idempotent; asyncDispose releases ownership", async () => {
       const { persistence, dispose } = await make();
       try {
-        const m = meta("read-from", "/work");
-        const log = oneTurnLog();
-        await persistence.create(m);
-        await persistence.append(m.id, log);
+        const m = meta("closed");
+        const handle = await persistence.create(m);
+        await handle.append(oneTurnLog());
+        await handle.close();
+        await handle.close();
+        await expect(handle.read()).rejects.toBeInstanceOf(SessionHandleClosedError);
+        await expect(handle.append(secondTurn())).rejects.toBeInstanceOf(SessionHandleClosedError);
+        await expect(handle.flush()).rejects.toBeInstanceOf(SessionHandleClosedError);
 
-        const whole = await persistence.readFrom(m.id, SessionLogOffset(0));
-        expect(whole.meta).toMatchObject({ id: m.id, cwd: "/work" });
-        expect(whole.events).toEqual(log);
+        {
+          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 {
+        await dispose();
+      }
+    });
 
-        const suffix = await persistence.readFrom(m.id, SessionLogOffset(3));
-        expect(suffix.events).toEqual(log.slice(3));
-        expect(suffix.events[0]?.seq).toBe(3);
+    it("service-level flush materializes every active write handle and counts a closing one as flushed", async () => {
+      const backend = await make();
+      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;
 
-        // At/past the stored end: an empty tail, never an error.
-        await expect(
-          persistence.readFrom(m.id, SessionLogOffset(log.length)),
-        ).resolves.toMatchObject({ events: [] });
-        await expect(
-          persistence.readFrom(m.id, SessionLogOffset(log.length + 100)),
-        ).resolves.toMatchObject({
-          events: [],
-        });
-
-        // Non-mutating: an interrupted-turn log is served as stored, no closers.
-        await persistence.append(m.id, [
-          { type: "turn/start", seq: SessionSeq(6), time: 7, data: { turn: 2 } },
-        ]);
-        const tail = await persistence.readFrom(m.id, SessionLogOffset(6));
-        expect(tail.events.map((event) => event.type)).toEqual(["turn/start"]);
+        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();
+          }
+        }
+        await materialized.close();
+      } finally {
+        await backend.dispose();
+      }
+    });
 
-        await expect(
-          persistence.readFrom(SessionId("absent-read-from"), SessionLogOffset(0)),
-        ).rejects.toThrow("not found");
-        await expect(persistence.readFrom(m.id, -1 as never)).rejects.toThrow(
-          "non-negative safe integer",
-        );
-        await expect(persistence.readFrom(m.id, 1.5 as never)).rejects.toThrow(
-          "non-negative safe integer",
-        );
+    it("a created-but-unappended session is visible to this instance and invisible to a fresh one", async () => {
+      const backend = await make();
+      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);
+        expect(snapshot?.header).toMatchObject(m);
+        expect((await backend.persistence.list()).map((s) => s.header.id)).toContain(m.id);
+        const reader = await backend.persistence.open(m.id, "read");
+        expect((await reader.read()).events).toEqual([]);
+        await reader.close();
+
+        if (backend.reopen !== undefined) {
+          const reopened = await backend.reopen();
+          try {
+            expect(await reopened.persistence.stat(m.id)).toBeUndefined();
+            expect((await reopened.persistence.list()).map((s) => s.header.id)).not.toContain(m.id);
+            await expect(reopened.persistence.open(m.id, "read")).rejects.toBeInstanceOf(
+              SessionPersistenceNotFoundError,
+            );
+          } finally {
+            await reopened.dispose();
+          }
+        }
+        await creator.close();
       } finally {
-        await dispose();
+        await backend.dispose();
       }
     });
 
-    it("lists stable lightweight revisions that change after an append", async () => {
+    it("close without an append erases the created session from this instance", async () => {
       const { persistence, dispose } = await make();
       try {
-        const m = meta("s2");
-        await persistence.create(m);
-        await persistence.append(m.id, oneTurnLog());
-        expect((await persistence.list()).map((x) => x.id)).toContain(m.id);
-        const first = (await persistence.listSnapshots()).find(
-          (snapshot) => snapshot.header.id === m.id,
-        );
-        const repeated = (await persistence.listSnapshots()).find(
-          (snapshot) => snapshot.header.id === m.id,
-        );
-        expect(first).toBeDefined();
-        expect(repeated?.revision).toBe(first?.revision);
+        const m = meta("never-was");
+        const creator = await persistence.create(m);
+        await creator.close();
 
-        await persistence.append(m.id, [
-          {
-            type: "turn/start",
-            seq: SessionSeq(6),
-            time: 7,
-            data: { turn: 2 },
-          },
-        ]);
-        const changed = (await persistence.listSnapshots()).find(
-          (snapshot) => snapshot.header.id === m.id,
+        expect(await persistence.stat(m.id)).toBeUndefined();
+        expect((await persistence.list()).map((s) => s.header.id)).not.toContain(m.id);
+        await expect(persistence.open(m.id, "read")).rejects.toBeInstanceOf(
+          SessionPersistenceNotFoundError,
         );
-        expect(changed?.revision).not.toBe(first?.revision);
       } finally {
         await dispose();
       }
     });
 
-    it("append rejects a batch whose first seq does not match the stored next-seq", async () => {
+    it("flush materializes an empty session durably for a fresh instance", async () => {
+      const backend = await make();
+      try {
+        if (backend.reopen === undefined) return;
+        const m = meta("durable-empty", "/work");
+        const creator = await backend.persistence.create(m);
+        await creator.flush();
+        await creator.close();
+
+        const reopened = await backend.reopen();
+        try {
+          expect((await reopened.persistence.list()).map((s) => s.header.id)).toContain(m.id);
+          expect((await reopened.persistence.stat(m.id))?.header).toMatchObject(m);
+          const reader = await reopened.persistence.open(m.id, "read");
+          expect((await reader.read()).events).toEqual([]);
+          await reader.close();
+        } finally {
+          await reopened.dispose();
+        }
+      } finally {
+        await backend.dispose();
+      }
+    });
+
+    it("freshness: reads started after an append resolves observe that prefix on any handle", async () => {
       const { persistence, dispose } = await make();
       try {
-        const m = meta("s3");
-        await persistence.create(m);
-        await persistence.append(m.id, oneTurnLog()); // seqs 0..5, next-seq = 6
-        // A re-append of an already-stored seq must be rejected, not duplicated.
-        const restated = oneTurnLog();
-        await expect(persistence.append(m.id, restated)).rejects.toThrow();
+        const m = meta("fresh");
+        const writer = await persistence.create(m);
+        await writer.append(oneTurnLog());
+
+        const before = await persistence.open(m.id, "read");
+        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]);
+        await before.close();
+        await after.close();
+        await writer.close();
       } finally {
         await dispose();
       }
     });
 
-    it("append rejects a mid-batch seq gap", async () => {
+    it("a fresh instance continues the stored log at the committed next-seq", async () => {
+      const backend = await make();
+      try {
+        if (backend.reopen === undefined) return;
+        const m = meta("continue", "/work");
+        const creator = await backend.persistence.create(m);
+        await creator.append(oneTurnLog());
+        await creator.close();
+
+        const reopened = await backend.reopen();
+        try {
+          const writer = await reopened.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]);
+          await writer.close();
+        } finally {
+          await reopened.dispose();
+        }
+      } finally {
+        await backend.dispose();
+      }
+    });
+
+    it("append rejects a batch that does not contiguously continue the log, naming the expected seq", async () => {
       const { persistence, dispose } = await make();
       try {
-        const m = meta("s4");
-        await persistence.create(m);
+        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 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(0), time: 1, data: { turn: 1 } },
-          { type: "step/start", seq: SessionSeq(2), time: 2, data: { turn: 1, step: 1 } }, // gap: missing seq 1
+          { type: "turn/start", seq: SessionSeq(6), time: 9, data: { turn: 2 } },
+          {
+            type: "turn/end",
+            seq: SessionSeq(8),
+            time: 10,
+            data: { turn: 2, reason: { kind: "completed" } },
+          },
         ];
-        await expect(persistence.append(m.id, gapped)).rejects.toThrow();
+        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 {
         await dispose();
       }
     });
 
-    it("append rejects non-JSON-serializable event data, naming the event type", async () => {
+    it("append rejects non-JSON-serializable event data without storing anything", async () => {
       const { persistence, dispose } = await make();
       try {
-        // Every value `isJsonValue` rejects must be rejected by the backend, not just BigInt —
-        // otherwise a backend could pass this contract while still accepting values that
-        // corrupt the durable round-trip. Each value is carried in a plugin-added field on one
-        // user message so the contract covers the complete JSON-value boundary.
-        const cyclic: Record<string, unknown> = { type: "text", text: "x" };
-        cyclic["self"] = cyclic;
-        const badValues: unknown[] = [
-          1n, // BigInt
-          undefined, // dropped by JSON.stringify
-          Infinity, // → null
-          () => 0, // function
-          Symbol("s"), // symbol
-          new Map(), // exotic object
-          cyclic, // circular ref
-        ];
-        for (const [i, bad] of badValues.entries()) {
-          // A fresh session per value isolates each rejection (a rejected append
-          // must leave no state behind, but isolating keeps the assertion clean).
-          const mi = meta(`s5-${i}`);
-          await persistence.create(mi);
-          const events = [
+        const m = meta("non-json");
+        const handle = await persistence.create(m);
+        const bad = (extra: unknown): SessionEvent[] =>
+          [
             {
-              type: "user/message",
+              type: "turn/start",
               seq: SessionSeq(0),
               time: 1,
-              data: {
-                id: MessageId(`invalid-json-${i}`),
-                role: "user",
-                content: [{ type: "text", text: "x" }],
-                source: { kind: "user" },
-                extra: bad,
-              },
+              data: { turn: 1, extra },
             },
           ] as unknown as SessionEvent[];
-          await expect(persistence.append(mi.id, events)).rejects.toThrow(
-            /losslessly JSON-serializable/,
-          );
+        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();
+      } finally {
+        await dispose();
+      }
+    });
+
+    it("vocabulary fail-closed: an unknown event type refuses append and stored reads", async () => {
+      const { persistence, dispose } = await make();
+      try {
+        const m = meta("foreign-vocabulary");
+        const handle = await persistence.create(m);
+        await handle.append(oneTurnLog());
+        // 写路径 v2 校验：未知类型（非 ignorable）拒绝入库，批次不落库。
+        await expect(
+          handle.append([
+            { type: "mystery/event", seq: SessionSeq(6), time: 7, data: { payload: true } },
+          ] as unknown as SessionEvent[]),
+        ).rejects.toBeInstanceOf(SessionFormatUnsupportedError);
+        await handle.close();
+
+        // 拒绝的批次未落库：log 只有 oneTurnLog，可正常读写。
+        const reader = await persistence.open(m.id, "read");
+        try {
+          const { events } = await reader.read();
+          expect(events).toHaveLength(6);
+        } finally {
+          await reader.close();
+        }
+        const writer = await persistence.open(m.id, "write");
+        try {
+          await writer.append([
+            {
+              type: "turn/end",
+              seq: SessionSeq(6),
+              time: 7,
+              data: { turn: 2, reason: { kind: "completed" } },
+            },
+          ] as unknown as SessionEvent[]);
+        } finally {
+          await writer.close();
+        }
+      } finally {
+        await dispose();
+      }
+    });
+
+    it("a torn physical tail is never served and is durably truncated by the write path", async () => {
+      const backend = await make();
+      try {
+        if (backend.reopen === undefined || backend.corruptTail === undefined) return;
+        const m = meta("torn", "/work");
+        const creator = await backend.persistence.create(m);
+        await creator.append(oneTurnLog());
+        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]);
+          await writer.close();
+        } finally {
+          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");
+          expect((await verify.read()).events.map((e) => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7]);
+          await verify.close();
+        } finally {
+          await verifyInstance.dispose();
+        }
+      } finally {
+        await backend.dispose();
+      }
+    });
+
+    it("stat and list agree on stable revisions that change after an append", async () => {
+      const { persistence, dispose } = await make();
+      try {
+        const m = meta("revisions", "/work");
+        const writer = await persistence.create(m);
+        await writer.append(oneTurnLog());
+
+        const statFirst = await persistence.stat(m.id);
+        const statAgain = await persistence.stat(m.id);
+        const listFirst = (await persistence.list()).find((s) => s.header.id === m.id);
+        expect(statFirst).toBeDefined();
+        expect(statAgain?.revision).toBe(statFirst?.revision);
+        expect(listFirst?.revision).toBe(statFirst?.revision);
+
+        await writer.append(secondTurn());
+        const statChanged = await persistence.stat(m.id);
+        expect(statChanged?.revision).not.toBe(statFirst?.revision);
+        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);
+        expect(statChanged?.header).toMatchObject(m);
+        await reader.close();
+        await writer.close();
+
+        expect(await persistence.stat(SessionId("absent-stat"))).toBeUndefined();
       } finally {
         await dispose();
       }