@nanobpm/agentic 0.1.0 → 0.5.0

package/src/session/adapter.ts

@@ -0,0 +1,159 @@
+/**
+ * The `@nanobpm/agentic/session` adapter contract — ADR 0062, slice 1.
+ *
+ * The three-method interface every session backend implements. It is the *mind*
+ * side of a durable agent activation: the authoritative log of what the agent
+ * thought/did ({@link SessionAdapter.emit}, the "mind tap"), the mind/world join
+ * points at a push boundary ({@link SessionAdapter.checkpoint}), and the seed a
+ * re-leased incarnation replays to resume ({@link SessionAdapter.restore}).
+ *
+ * Publishing this interface + the {@link SessionEvent} types first is the whole
+ * point of slice 1: the ACP client (slice 2), the stream-json/native normalisers
+ * (slice 3) and the nano-workforce world-restore (slice 4) all code against this
+ * stable contract in parallel. Keep it small and additive.
+ */
+import type { AppendedSessionEvent, SessionEvent } from "./events.ts";
+
+/**
+ * Identifies one **activation** — a single leased run of a BPMN element. This is
+ * the log's identity for fencing and replay: every incarnation of the same
+ * `(processInstanceKey, elementId)` shares one causal log and one fence, so a
+ * re-lease resumes the same session rather than starting a new one.
+ *
+ * The authoritative log is keyed `(processInstanceKey, elementId)` (ADR 0062):
+ * this pair identifies the activation and shares one fence. The current
+ * `incarnation` is stored as the fence token, and each appended event carries an
+ * `incarnation` stamp recording which generation wrote that row.
+ */
+export interface ActivationKey {
+  readonly processInstanceKey: string;
+  readonly elementId: string;
+}
+
+/** Render an {@link ActivationKey} as an opaque, collision-free string key. */
+export function activationKeyString(key: ActivationKey): string {
+  // NUL separates the two components so no pair of distinct (pik, elementId)
+  // values can collide by concatenation (NUL cannot appear in either).
+  return `${key.processInstanceKey}\u0000${key.elementId}`;
+}
+
+/**
+ * One recorded side effect at a checkpoint's push boundary. The *shape* of an
+ * effect (its `kind` vocabulary, how it is replayed/fenced) is owned by slice 4
+ * (nano-workforce world-restore); slice 1 stores the ledger opaquely so the
+ * contract is stable before that lands. `detail` is an opaque JSON value.
+ */
+export interface EffectEntry {
+  readonly id: string;
+  readonly kind: string;
+  readonly detail?: unknown;
+}
+
+/**
+ * The world-side effects committed at a checkpoint. Stored verbatim (JSON) and
+ * handed back unchanged at {@link SessionAdapter.restore}; slice 1 never
+ * interprets it.
+ */
+export type EffectLedger = readonly EffectEntry[];
+
+/**
+ * A mind/world join recorded at a push boundary: the agent's mind is at log
+ * `offset`, the world is at git `commitSha`, and `effectLedger` lists the effects
+ * that boundary committed. On re-lease the newest checkpoint's seed is replayed.
+ */
+export interface SessionCheckpoint {
+  /** Unique checkpoint id (producer- or backend-assigned). */
+  readonly id: string;
+  /**
+   * The log offset the checkpoint pins: exactly the log's `nextOffset` at the
+   * moment it was taken, so the seed is events `[0, offset)`.
+   */
+  readonly offset: number;
+  /** The world (git) commit the mind is joined to at this boundary. */
+  readonly commitSha: string;
+  /** The effects committed at this boundary (opaque to slice 1). */
+  readonly effectLedger: EffectLedger;
+  /** The incarnation that took the checkpoint. */
+  readonly incarnation: number;
+  /** When the checkpoint was taken, ISO-8601. */
+  readonly at: string;
+}
+
+/**
+ * The mind seed handed back on re-lease: everything a resumed incarnation needs
+ * to reconstruct the agent's mind up to a checkpoint and continue from there.
+ */
+export interface SessionSeed {
+  /**
+   * The checkpoint the seed restores from, or `null` when the session has no
+   * checkpoint yet (a fresh start — `events` is empty and `nextOffset` is 0).
+   */
+  readonly checkpoint: SessionCheckpoint | null;
+  /**
+   * The authoritative log replayed up to (and excluding) the checkpoint offset,
+   * in offset order — the events the resumed agent replays to rebuild its mind.
+   */
+  readonly events: readonly AppendedSessionEvent[];
+  /**
+   * The offset the resumed incarnation continues appending at — the checkpoint
+   * offset (0 when there is no checkpoint). Any events a dead incarnation wrote
+   * *past* the checkpoint are uncommitted and are not part of the seed.
+   */
+  readonly nextOffset: number;
+}
+
+/**
+ * The three-method session adapter. An instance is bound to one
+ * {@link ActivationKey} and one `incarnation`; a re-lease constructs a new
+ * adapter at a higher incarnation over the same authoritative log.
+ */
+export interface SessionAdapter {
+  /** The activation this adapter writes to. */
+  readonly key: ActivationKey;
+  /** The generation of this writer (the fencing token). */
+  readonly incarnation: number;
+
+  /**
+   * The **mind tap**: append `event` to the authoritative session log at the
+   * current offset, returning it stamped with its assigned `offset` and this
+   * writer's `incarnation`. Fenced — a call from an incarnation that a newer one
+   * has superseded throws {@link StaleIncarnationError} and writes nothing.
+   */
+  emit(event: SessionEvent): AppendedSessionEvent;
+
+  /**
+   * Mark a mind/world join at a push boundary: record a checkpoint pinning the
+   * current log offset to `commitSha` and `effectLedger`. Fenced like
+   * {@link emit}. Returns the recorded checkpoint.
+   */
+  checkpoint(commitSha: string, effectLedger: EffectLedger): SessionCheckpoint;
+
+  /**
+   * Hand back the mind seed to resume from. With no argument (or an unknown id)
+   * it resolves the **latest** checkpoint; given a checkpoint id it restores that
+   * specific one. Returns a {@link SessionSeed} of the log up to the checkpoint
+   * offset. Read-only — it does not mutate the log or the fence.
+   */
+  restore(fromCheckpoint?: string): SessionSeed;
+}
+
+/**
+ * Raised when a write (emit/checkpoint) is attempted by an incarnation that a
+ * newer one has already superseded — the fence rejected it. The stale writer's
+ * call has no effect; the log stays owned by the current incarnation.
+ */
+export class StaleIncarnationError extends Error {
+  readonly key: ActivationKey;
+  readonly incarnation: number;
+  readonly current: number;
+  constructor(key: ActivationKey, incarnation: number, current: number) {
+    super(
+      `incarnation ${incarnation} is fenced for activation ` +
+        `${key.processInstanceKey}/${key.elementId}: a newer incarnation ${current} has taken over`,
+    );
+    this.name = "StaleIncarnationError";
+    this.key = key;
+    this.incarnation = incarnation;
+    this.current = current;
+  }
+}

package/src/session/backend.test.ts

@@ -0,0 +1,198 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type { TestContext } from "node:test";
+import { type ActivationKey, StaleIncarnationError } from "./adapter.ts";
+import type { SessionEvent } from "./events.ts";
+import { InMemorySessionLog, type SessionLog, SqliteSessionLog } from "./log.ts";
+import { SessionBackend } from "./backend.ts";
+import { openTestDb } from "./test-db.ts";
+
+const KEY: ActivationKey = { processInstanceKey: "pik-1", elementId: "implement-task" };
+const LEDGER = [{ id: "eff-1", kind: "git-push", detail: { ref: "feat/x" } }];
+
+function seqIds(prefix: string): () => string {
+  let n = 0;
+  return () => `${prefix}-${n++}`;
+}
+
+function msg(id: string, parentId: string | null, text: string): SessionEvent {
+  return { type: "assistant", id, parentId, text };
+}
+
+interface Harness {
+  readonly name: string;
+  /**
+   * A fresh shared log (persists across incarnations of the same activation).
+   * Pass the test context so any backing SQLite DB is closed on test teardown.
+   */
+  makeLog(t: TestContext): SessionLog;
+}
+
+const HARNESSES: readonly Harness[] = [
+  { name: "in-memory", makeLog: (_t: TestContext) => new InMemorySessionLog() },
+  {
+    name: "sqlite",
+    makeLog: (t: TestContext) => {
+      const log = new SqliteSessionLog(openTestDb(t));
+      log.ensureSchema();
+      return log;
+    },
+  },
+];
+
+for (const h of HARNESSES) {
+  test(`[${h.name}] emit* → checkpoint → restore reproduces the seed at the checkpoint offset`, (t) => {
+    const log = h.makeLog(t);
+    const backend = new SessionBackend(log, KEY, 1, { newCheckpointId: seqIds("cp") });
+
+    const e0 = backend.emit(msg("e0", null, "a"));
+    const e1 = backend.emit(msg("e1", "e0", "b"));
+    const e2 = backend.emit(msg("e2", "e1", "c"));
+    assert.deepEqual([e0.offset, e1.offset, e2.offset], [0, 1, 2]);
+
+    const cp = backend.checkpoint("sha-abc", LEDGER);
+    assert.equal(cp.offset, 3, "checkpoint pins the current next offset");
+    assert.equal(cp.incarnation, 1);
+    assert.deepEqual(cp.effectLedger, LEDGER);
+
+    // A dead-tail event emitted after the checkpoint must NOT appear in the seed.
+    backend.emit(msg("e3", "e2", "d"));
+
+    const seed = backend.restore();
+    assert.deepEqual(seed.checkpoint, cp);
+    assert.equal(seed.nextOffset, 3);
+    assert.deepEqual(seed.events, [e0, e1, e2], "seed is exactly the log up to the checkpoint offset");
+  });
+
+  test(`[${h.name}] restore repositions the cursor so a resume overwrites the uncommitted tail`, (t) => {
+    const log = h.makeLog(t);
+    const backend = new SessionBackend(log, KEY, 1, { newCheckpointId: seqIds("cp") });
+    backend.emit(msg("e0", null, "a"));
+    backend.emit(msg("e1", "e0", "b"));
+    backend.checkpoint("sha", LEDGER); // offset 2
+    backend.emit(msg("e2-dead", "e1", "dead")); // uncommitted tail at offset 2
+
+    backend.restore(); // cursor back to 2
+    const replacement = backend.emit(msg("e2-live", "e1", "live"));
+    assert.equal(replacement.offset, 2);
+
+    // The authoritative log now holds the live event, not the dead one.
+    const all = log.replay(KEY, 0);
+    assert.deepEqual(all.map((e) => e.id), ["e0", "e1", "e2-live"]);
+    assert.equal(log.nextOffset(KEY), 3);
+  });
+
+  test(`[${h.name}] restore of a session with no checkpoint yields a fresh seed`, (t) => {
+    const log = h.makeLog(t);
+    const backend = new SessionBackend(log, KEY, 1);
+    backend.emit(msg("e0", null, "a"));
+    const seed = backend.restore();
+    assert.deepEqual(seed, { checkpoint: null, events: [], nextOffset: 0 });
+  });
+
+  test(`[${h.name}] restore(id) resolves a specific earlier checkpoint`, (t) => {
+    const log = h.makeLog(t);
+    const backend = new SessionBackend(log, KEY, 1, { newCheckpointId: seqIds("cp") });
+    backend.emit(msg("e0", null, "a"));
+    const cp0 = backend.checkpoint("sha0", LEDGER); // offset 1
+    backend.emit(msg("e1", "e0", "b"));
+    const cp1 = backend.checkpoint("sha1", LEDGER); // offset 2
+
+    assert.deepEqual(backend.restore().checkpoint, cp1, "no arg → latest");
+    assert.deepEqual(backend.restore(cp0.id).checkpoint, cp0, "id → that checkpoint");
+    assert.equal(backend.restore(cp0.id).events.length, 1);
+  });
+
+  test(`[${h.name}] resuming from an earlier checkpoint prunes now-dangling later checkpoints`, (t) => {
+    const log = h.makeLog(t);
+    const backend = new SessionBackend(log, KEY, 1, { newCheckpointId: seqIds("cp") });
+    backend.emit(msg("e0", null, "a"));
+    const cp0 = backend.checkpoint("sha0", LEDGER); // offset 1
+    backend.emit(msg("e1", "e0", "b"));
+    backend.emit(msg("e2", "e1", "c"));
+    const cpLate = backend.checkpoint("sha-late", LEDGER); // offset 3
+
+    // Rewind to the earlier checkpoint and rewrite the tail from there. This
+    // truncates events [1, 3), so cpLate (offset 3) now points past the head.
+    backend.restore(cp0.id);
+    backend.emit(msg("e1b", "e0", "b2")); // offset 1
+
+    // The now-dangling later checkpoint must be pruned, and the surviving
+    // earlier checkpoint (whose offset is still backed by real events) kept.
+    assert.equal(log.getCheckpoint(KEY, cpLate.id), undefined, "dangling later checkpoint is pruned");
+    assert.deepEqual(log.latestCheckpoint(KEY), cp0, "latest is the surviving earlier checkpoint");
+    assert.ok(log.nextOffset(KEY) <= cpLate.offset, "head did not advance past the rewritten tail");
+
+    // A subsequent restore() must not reposition the cursor past the head, so
+    // the next emit continues gap-free instead of throwing a gap RangeError.
+    const seed = backend.restore();
+    assert.equal(seed.nextOffset, cp0.offset, "restore resumes at the surviving checkpoint, not a dangling one");
+    assert.doesNotThrow(() => backend.emit(msg("e-next", "e0", "n")), "resume after prune does not gap");
+  });
+
+  test(`[${h.name}] restore(unknown id) falls back to the latest checkpoint`, (t) => {
+    const log = h.makeLog(t);
+    const backend = new SessionBackend(log, KEY, 1, { newCheckpointId: seqIds("cp") });
+    backend.emit(msg("e0", null, "a"));
+    backend.checkpoint("sha0", LEDGER); // offset 1
+    backend.emit(msg("e1", "e0", "b"));
+    const latest = backend.checkpoint("sha1", LEDGER); // offset 2
+
+    // The contract: an unknown id resolves the latest checkpoint, not a fresh seed.
+    assert.deepEqual(backend.restore("does-not-exist").checkpoint, latest);
+    assert.equal(backend.restore("does-not-exist").nextOffset, latest.offset);
+  });
+
+  test(`[${h.name}] the incarnation fence rejects a stale writer`, (t) => {
+    const log = h.makeLog(t);
+    const inc1 = new SessionBackend(log, KEY, 1);
+    inc1.emit(msg("e0", null, "a"));
+
+    // A re-lease at a higher incarnation fences the prior one.
+    const inc2 = new SessionBackend(log, KEY, 2);
+    assert.throws(() => inc1.emit(msg("stale", "e0", "x")), StaleIncarnationError);
+    assert.throws(() => inc1.checkpoint("sha", LEDGER), StaleIncarnationError);
+
+    // The current incarnation still writes fine.
+    const ok = inc2.emit(msg("e1", "e0", "b"));
+    assert.equal(ok.incarnation, 2);
+  });
+
+  test(`[${h.name}] constructing a stale incarnation throws at lease time`, (t) => {
+    const log = h.makeLog(t);
+    void new SessionBackend(log, KEY, 5);
+    assert.throws(() => new SessionBackend(log, KEY, 3), StaleIncarnationError);
+  });
+}
+
+test("[sqlite] the fence high-water is durable across a fresh store (restart)", (t) => {
+  const db = openTestDb(t);
+  const first = new SqliteSessionLog(db);
+  first.ensureSchema();
+  const inc1 = new SessionBackend(first, KEY, 1);
+  inc1.emit(msg("e0", null, "a"));
+
+  // A brand-new store over the same DB (a process restart) leases at inc 2.
+  const revived = new SqliteSessionLog(db);
+  const inc2 = new SessionBackend(revived, KEY, 2);
+  inc2.emit(msg("e1", "e0", "b"));
+
+  // The original in-process writer is now fenced by the persisted high-water.
+  assert.throws(() => inc1.emit(msg("zombie", "e0", "z")), StaleIncarnationError);
+});
+
+test("[sqlite] a resumed incarnation replays the durable seed across a restart", (t) => {
+  const db = openTestDb(t);
+  const first = new SqliteSessionLog(db);
+  first.ensureSchema();
+  const inc1 = new SessionBackend(first, KEY, 1, { newCheckpointId: seqIds("cp") });
+  const a = inc1.emit(msg("e0", null, "a"));
+  const b = inc1.emit(msg("e1", "e0", "b"));
+  inc1.checkpoint("sha", LEDGER); // offset 2
+
+  const revived = new SqliteSessionLog(db);
+  const inc2 = new SessionBackend(revived, KEY, 2);
+  const seed = inc2.restore();
+  assert.deepEqual(seed.events, [a, b]);
+  assert.equal(seed.nextOffset, 2);
+});

package/src/session/backend.ts

@@ -0,0 +1,128 @@
+/**
+ * {@link SessionBackend} — the canonical {@link SessionAdapter} implementation,
+ * ADR 0062 slice 1.
+ *
+ * There is exactly **one** adapter implementation (derivation over duplication):
+ * it is bound to a {@link SessionLog} port, so the *same* emit/checkpoint/restore
+ * semantics run over either the in-memory reference log ({@link InMemorySessionLog}
+ * — the stub slices 2–5 code against) or the durable SQLite log
+ * ({@link SqliteSessionLog}). The backend owns the append cursor and the fencing
+ * token; the log owns storage and the fence high-water.
+ */
+import { randomUUID } from "node:crypto";
+import {
+  type ActivationKey,
+  type EffectLedger,
+  type SessionAdapter,
+  type SessionCheckpoint,
+  type SessionSeed,
+} from "./adapter.ts";
+import type { AppendedSessionEvent, SessionEvent } from "./events.ts";
+import { type Clock, InMemorySessionLog, type SessionLog, type SqliteDb, SqliteSessionLog, systemClock } from "./log.ts";
+
+export interface SessionBackendOptions {
+  /** Injectable clock for deterministic checkpoint timestamps. Default {@link systemClock}. */
+  clock?: Clock;
+  /** Injectable checkpoint-id generator (deterministic tests). Default `crypto.randomUUID`. */
+  newCheckpointId?: () => string;
+}
+
+/**
+ * A session adapter bound to one activation and one incarnation. Constructing it
+ * takes the lease at `incarnation` (advancing the fence), so a re-lease at a
+ * higher incarnation immediately fences every prior one — a subsequent `emit`
+ * from an older adapter throws {@link StaleIncarnationError}.
+ */
+export class SessionBackend implements SessionAdapter {
+  readonly key: ActivationKey;
+  readonly incarnation: number;
+  readonly #log: SessionLog;
+  readonly #clock: Clock;
+  readonly #newCheckpointId: () => string;
+  /** The offset the next `emit` writes at. Advanced by `emit`, repositioned by `restore`. */
+  #cursor: number;
+
+  constructor(log: SessionLog, key: ActivationKey, incarnation: number, options: SessionBackendOptions = {}) {
+    log.lease(key, incarnation);
+    this.#log = log;
+    this.key = key;
+    this.incarnation = incarnation;
+    this.#clock = options.clock ?? systemClock;
+    this.#newCheckpointId = options.newCheckpointId ?? randomUUID;
+    // Default to appending after whatever is already committed; `restore`
+    // repositions the cursor to a checkpoint boundary when resuming.
+    this.#cursor = log.nextOffset(key);
+  }
+
+  /** The offset the next `emit` will assign. */
+  get nextOffset(): number {
+    return this.#cursor;
+  }
+
+  emit(event: SessionEvent): AppendedSessionEvent {
+    const appended = this.#log.append(this.key, this.incarnation, this.#cursor, event);
+    this.#cursor = appended.offset + 1;
+    return appended;
+  }
+
+  checkpoint(commitSha: string, effectLedger: EffectLedger): SessionCheckpoint {
+    const checkpoint: SessionCheckpoint = {
+      id: this.#newCheckpointId(),
+      offset: this.#cursor,
+      commitSha,
+      effectLedger,
+      incarnation: this.incarnation,
+      at: new Date(this.#clock.now()).toISOString(),
+    };
+    return this.#log.putCheckpoint(this.key, this.incarnation, checkpoint);
+  }
+
+  restore(fromCheckpoint?: string): SessionSeed {
+    // Contract: no argument OR an unknown id resolves the latest checkpoint; a
+    // known id restores exactly that checkpoint.
+    const checkpoint =
+      fromCheckpoint === undefined
+        ? this.#log.latestCheckpoint(this.key)
+        : (this.#log.getCheckpoint(this.key, fromCheckpoint) ?? this.#log.latestCheckpoint(this.key));
+    if (checkpoint === undefined) {
+      // No checkpoint to resume from: start the mind fresh at offset 0. The next
+      // emit at offset 0 discards any uncommitted events a dead incarnation left.
+      this.#cursor = 0;
+      return { checkpoint: null, events: [], nextOffset: 0 };
+    }
+    const events = this.#log.replay(this.key, 0, checkpoint.offset);
+    // Reposition the write cursor to the checkpoint boundary: the resumed
+    // incarnation continues from there, overwriting any uncommitted tail.
+    this.#cursor = checkpoint.offset;
+    return { checkpoint, events, nextOffset: checkpoint.offset };
+  }
+}
+
+/**
+ * Open a session adapter over an in-memory reference log. Pass a shared
+ * {@link InMemorySessionLog} across incarnations of the same activation so the
+ * fence and events persist across a re-lease (the reference resume scenario);
+ * omit it for a throwaway single-incarnation log.
+ */
+export function openInMemorySession(
+  key: ActivationKey,
+  incarnation: number,
+  options: SessionBackendOptions & { log?: InMemorySessionLog } = {},
+): { backend: SessionBackend; log: InMemorySessionLog } {
+  const log = options.log ?? new InMemorySessionLog();
+  const backend = new SessionBackend(log, key, incarnation, options);
+  return { backend, log };
+}
+
+/** Open a session adapter over the durable SQLite log. Applies the schema idempotently. */
+export function openSqliteSession(
+  db: SqliteDb,
+  key: ActivationKey,
+  incarnation: number,
+  options: SessionBackendOptions = {},
+): { backend: SessionBackend; log: SqliteSessionLog } {
+  const log = new SqliteSessionLog(db, { clock: options.clock });
+  log.ensureSchema();
+  const backend = new SessionBackend(log, key, incarnation, options);
+  return { backend, log };
+}

package/src/session/events.test.ts

@@ -0,0 +1,168 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  parseSessionEvent,
+  SESSION_EVENT_TYPES,
+  type SessionEvent,
+  SessionEventShapeError,
+} from "./events.ts";
+
+/** Build a runtime value from untyped JSON (never an `as`-cast — see AGENTS.md). */
+function fromJson(json: string): unknown {
+  return JSON.parse(json);
+}
+
+const sample: readonly SessionEvent[] = [
+  { type: "system", id: "s0", parentId: null, text: "you are nano" },
+  { type: "user", id: "u1", parentId: "s0", text: "hi" },
+  { type: "assistant", id: "a2", parentId: "u1", text: "hello" },
+  { type: "reasoning", id: "r3", parentId: "u1", text: "thinking", providerContinuation: "OPAQUE==" },
+  { type: "reasoning", id: "r3b", parentId: "u1" },
+  { type: "tool-call", id: "tc4", parentId: "a2", callId: "c1", name: "read", args: { path: "/x" } },
+  { type: "tool-result", id: "tr5", parentId: "tc4", callId: "c1", ok: true, result: { bytes: 12 } },
+  { type: "tool-result", id: "tr5b", parentId: "tc4", callId: "c2", ok: false, result: "boom" },
+  { type: "compaction", id: "cp6", parentId: "a2", reason: "compaction", replacesFrom: 0, replacesTo: 3, summary: "…" },
+  { type: "compaction", id: "cp6b", parentId: "a2", reason: "truncation", replacesFrom: 4, replacesTo: 6 },
+  { type: "usage", id: "us7", parentId: "a2", inputTokens: 100, outputTokens: 42, model: "opus" },
+  { type: "usage", id: "us7b", parentId: "a2", inputTokens: 1, outputTokens: 2 },
+  { type: "turn-start", id: "ts8", parentId: null, turn: 1 },
+  { type: "turn-end", id: "te9", parentId: "ts8", turn: 1 },
+];
+
+test("every SessionEvent variant round-trips through JSON + parseSessionEvent unchanged", () => {
+  for (const event of sample) {
+    const restored = parseSessionEvent(fromJson(JSON.stringify(event)));
+    assert.deepEqual(restored, event, `variant ${event.type} (${event.id}) must round-trip`);
+  }
+});
+
+test("the sample corpus covers every declared SessionEventType", () => {
+  const covered = new Set(sample.map((e) => e.type));
+  for (const type of SESSION_EVENT_TYPES) {
+    assert.ok(covered.has(type), `missing round-trip coverage for event type "${type}"`);
+  }
+});
+
+test("parseSessionEvent rejects an unknown event type", () => {
+  assert.throws(() => parseSessionEvent(fromJson('{"type":"bogus","id":"x","parentId":null}')), SessionEventShapeError);
+});
+
+test("parseSessionEvent rejects a missing required field", () => {
+  assert.throws(() => parseSessionEvent(fromJson('{"type":"user","id":"u","parentId":null}')), SessionEventShapeError);
+});
+
+test("parseSessionEvent rejects a malformed parentId", () => {
+  assert.throws(
+    () => parseSessionEvent(fromJson('{"type":"system","id":"s","parentId":7,"text":"x"}')),
+    SessionEventShapeError,
+  );
+});
+
+test("parseSessionEvent rejects a compaction with an invalid reason", () => {
+  assert.throws(
+    () =>
+      parseSessionEvent(
+        fromJson('{"type":"compaction","id":"c","parentId":null,"reason":"nope","replacesFrom":0,"replacesTo":1}'),
+      ),
+    SessionEventShapeError,
+  );
+});
+
+test("parseSessionEvent rejects a non-object", () => {
+  assert.throws(() => parseSessionEvent(fromJson("42")), SessionEventShapeError);
+});
+
+test("parseSessionEvent normalises an omitted opaque tool-call `args` to null (JSON-stable)", () => {
+  // A dialect that omits args (e.g. `obj.arguments ?? obj.args`, both absent)
+  // yields `undefined`, which `JSON.stringify` drops from the object — the
+  // persisted event would then no longer round-trip to the same shape on replay.
+  // The boundary must coerce the absence to the JSON "no value" (`null`).
+  const event = parseSessionEvent({
+    type: "tool-call",
+    id: "tc",
+    parentId: null,
+    callId: "c1",
+    name: "read",
+    args: undefined,
+  });
+  assert.equal(event.type, "tool-call");
+  if (event.type !== "tool-call") return;
+  assert.equal(event.args, null);
+  assert.deepEqual(parseSessionEvent(fromJson(JSON.stringify(event))), event, "must survive a JSON round-trip unchanged");
+});
+
+test("parseSessionEvent normalises an omitted opaque tool-result `result` to null (JSON-stable)", () => {
+  const event = parseSessionEvent({
+    type: "tool-result",
+    id: "tr",
+    parentId: null,
+    callId: "c1",
+    ok: false,
+    result: undefined,
+  });
+  assert.equal(event.type, "tool-result");
+  if (event.type !== "tool-result") return;
+  assert.equal(event.result, null);
+  assert.deepEqual(parseSessionEvent(fromJson(JSON.stringify(event))), event, "must survive a JSON round-trip unchanged");
+});
+
+test("parseSessionEvent preserves a falsy-but-present opaque payload (0 / false / null are not undefined)", () => {
+  for (const payload of [0, false, null, ""]) {
+    const call = parseSessionEvent({ type: "tool-call", id: "tc", parentId: null, callId: "c", name: "n", args: payload });
+    assert.equal(call.type, "tool-call");
+    if (call.type !== "tool-call") return;
+    assert.equal(call.args, payload, `present args ${JSON.stringify(payload)} must be preserved, not coerced`);
+  }
+});
+
+test("parseSessionEvent rejects a negative or non-integer turn index", () => {
+  assert.throws(
+    () => parseSessionEvent(fromJson('{"type":"turn-start","id":"t","parentId":null,"turn":-1}')),
+    SessionEventShapeError,
+  );
+  assert.throws(
+    () => parseSessionEvent(fromJson('{"type":"turn-end","id":"t","parentId":null,"turn":1.5}')),
+    SessionEventShapeError,
+  );
+});
+
+test("parseSessionEvent rejects negative or fractional token counts", () => {
+  assert.throws(
+    () =>
+      parseSessionEvent(
+        fromJson('{"type":"usage","id":"u","parentId":null,"inputTokens":-1,"outputTokens":2}'),
+      ),
+    SessionEventShapeError,
+  );
+  assert.throws(
+    () =>
+      parseSessionEvent(
+        fromJson('{"type":"usage","id":"u","parentId":null,"inputTokens":1,"outputTokens":2.5}'),
+      ),
+    SessionEventShapeError,
+  );
+});
+
+test("parseSessionEvent rejects a compaction with a negative or inverted offset range", () => {
+  assert.throws(
+    () =>
+      parseSessionEvent(
+        fromJson('{"type":"compaction","id":"c","parentId":null,"reason":"compaction","replacesFrom":-1,"replacesTo":3}'),
+      ),
+    SessionEventShapeError,
+  );
+  assert.throws(
+    () =>
+      parseSessionEvent(
+        fromJson('{"type":"compaction","id":"c","parentId":null,"reason":"compaction","replacesFrom":5,"replacesTo":3}'),
+      ),
+    SessionEventShapeError,
+  );
+  assert.throws(
+    () =>
+      parseSessionEvent(
+        fromJson('{"type":"compaction","id":"c","parentId":null,"reason":"compaction","replacesFrom":0,"replacesTo":2.5}'),
+      ),
+    SessionEventShapeError,
+  );
+});