@cursor/july 0.1.45 → 0.1.46

package/src/ledger/session-ledger.ts

@@ -1,12 +1,13 @@
 /**
- * Session ledger — coordination only (no inbox).
+ * Session ledger — KV coordination with a durable inbox.
  *
- * Two key families, driven with CAS over a {@link SessionLedgerKv};
- * agents never touch these keys directly:
+ * Three key families, all driven with `get` + CAS on a
+ * {@link SessionLedgerKv}; agents never touch these keys directly:
  *
  * ```
- * session/<continuationKey>   identity, created with put-if-absent
- * ledger/<sessionId>          head + lease — every mutation one CAS
+ * session/<continuationKey>      identity, created with put-if-absent
+ * ledger/<sessionId>             head + pending + lease — every mutation one CAS
+ * mailbox/<sessionId>/<eventId>  immutable payload blobs, plain put
  * ```
  *
  * The keys are deliberately bare: namespacing (per agent, per
@@ -15,21 +16,21 @@
  * where it constructs the handle (see `durable-session-store.ts`), the
  * same boundary where `host.kv` gets its agent scoping.
  *
- * This is a coordination ledger: session identity, one writer per
- * session (leases with generation fencing), and a fenced,
- * ambiguity-safe commit sequence (`head`). It deliberately has **no
- * durable inbox** — no pending list, no payload blobs, no append/drain,
- * no janitor. An event that arrives while the lease is held waits
- * *in-process* on the delivering pod; a crash loses that in-flight
- * event exactly as resident serving does. What ledger mode adds over
- * resident is cross-pod mutual exclusion, zombie fencing, and the
- * committed head sequence. A dead pod needs no janitor: its lease
- * simply expires (~30s) and the next delivery claims at generation+1.
+ * The guarantee: **exactly-once ledger apply, at-least-once actuation.**
+ * A commit is one CAS carrying the read version, the expected `head`, and
+ * the holder's `generation` — one committed transition per turn, atomic by
+ * construction. What the CAS cannot fence (a zombie's plain `host.kv`
+ * writes, external tool calls) is a stated bound, not this module's job.
  *
- * The commit is one CAS carrying the read version, the expected `head`,
- * and the holder's `generation` — one committed transition per turn,
- * atomic by construction. Commit always releases the lease: with no
- * pending list there is nothing to keep it for.
+ * The inbox makes events durable before their turn runs: `appendEvent`
+ * writes the payload blob, then one CAS indexes the eventId into
+ * `pending` — that CAS is the ack point. A delivery that finds the lease
+ * held walks away; the holder's commit sees the appended id in the same
+ * CAS value, keeps the lease, and drains again. Sessions whose holder
+ * died with events pending are recovered by the janitor
+ * (`./janitor.js`), which is also why the store must implement
+ * `listKeys`: the inbox brings the prefix scans (janitor + orphan
+ * sweep) that the coordination-only ledger did not need.
  *
  * Clocks: lease expiry compares `expiresAt` against {@link
  * SessionLedgerOptions.clock} (default `Date.now`). Self-hosted N-pod
@@ -46,26 +47,36 @@ import type { HostKvCasApi, JsonObject, JsonValue } from "../types.js";
 // acquisition.
 export const LEASE_TTL_MS = 30_000;
 export const HEARTBEAT_INTERVAL_MS = 10_000;
+/** Unreferenced mailbox blobs older than this are sweepable. */
+export const DEFAULT_ORPHAN_TTL_MS: number = 60 * 60_000;
 
-const DEFAULT_MAX_CAS_ATTEMPTS = 16;
+// Sized against the two-pod simulation running at this default (no
+// override): 64 exhausts appendEvent under a hot session's worst-case
+// interleaving, 128 passes with margin. Exhaustion mid-lease stalls the
+// session for a lease TTL, so the budget errs generous — the backoff
+// keeps late attempts cheap.
+const DEFAULT_MAX_CAS_ATTEMPTS = 128;
 
 /**
- * Exactly the KV surface the coordination-only ledger uses. `listKeys`
- * is deliberately absent: nothing here scans, so a store must not be
- * rejected for lacking it.
+ * The KV surface the ledger uses — the full CAS-capable contract. The
+ * coordination half needs only `getWithVersion` / `putIfAbsent` /
+ * `putIfVersion`; the inbox adds plain `get`/`put`/`delete` for mailbox
+ * payload blobs and `listKeys` for the janitor scan and the orphan
+ * sweep.
  */
-export type SessionLedgerKv = Pick<
-  HostKvCasApi,
-  "getWithVersion" | "putIfAbsent" | "putIfVersion"
->;
+export type SessionLedgerKv = HostKvCasApi;
 
 /** Runtime probe for {@link SessionLedgerKv} on stores of unknown shape. */
 export function supportsSessionLedgerKv(kv: object): kv is SessionLedgerKv {
   const candidate = kv as Partial<SessionLedgerKv>;
   return (
+    typeof candidate.get === "function" &&
+    typeof candidate.put === "function" &&
+    typeof candidate.delete === "function" &&
     typeof candidate.getWithVersion === "function" &&
     typeof candidate.putIfAbsent === "function" &&
-    typeof candidate.putIfVersion === "function"
+    typeof candidate.putIfVersion === "function" &&
+    typeof candidate.listKeys === "function"
   );
 }
 
@@ -83,38 +94,68 @@ export interface LedgerLease {
 }
 
 /**
- * `ledger/<sessionId>` value: `{ sessionId, head, lease, generation,
- * lastCommitId }`. `sessionId` lets a future scan address sessions
- * without inverting digested key segments; `generation` is a monotonic
- * acquisition counter that must survive lease release, or a zombie of a
- * cleanly released lease could reuse its generation; `lastCommitId` is
- * the ambiguous-commit recovery token.
+ * `ledger/<sessionId>` value: `{ sessionId, head, pending, lease,
+ * generation, lastCommitId }`. `sessionId` lets the janitor's prefix
+ * scan address sessions without inverting digested key segments;
+ * `generation` is a monotonic acquisition counter that must survive
+ * lease release, or a zombie of a cleanly released lease could reuse
+ * its generation; `lastCommitId` is the ambiguous-commit recovery
+ * token.
  */
 export interface LedgerSnapshot {
   sessionId: string;
   head: number;
+  pending: string[];
   lease: LedgerLease | null;
   generation: number;
   lastCommitId: string | null;
 }
 
+/** One event handed to {@link SessionLedger.appendEvent}. */
+export interface LedgerEventInput {
+  eventId: string;
+  envelope: JsonValue;
+  hookContext?: JsonValue;
+  /** Source-assigned timestamp used for drain ordering. */
+  sourceTs: number;
+}
+
+/** One drained mailbox event. */
+export interface LedgerEvent {
+  eventId: string;
+  envelope: JsonValue;
+  hookContext: JsonValue | null;
+  sourceTs: number;
+  /** Pod-clock write time; drives the orphan sweep TTL. */
+  storedAt: number;
+}
+
 export type EnsureSessionResult = {
   created: boolean;
   session: SessionIdentity;
 };
 
 export type ClaimResult =
-  | { claimed: true; lease: LedgerLease; head: number }
+  | { claimed: true; lease: LedgerLease; head: number; pending: string[] }
   | { claimed: false; reason: "held"; holder: string; expiresAt: number };
 
 export type HeartbeatResult =
   | { ok: true; expiresAt: number }
   | { ok: false; reason: "not-found" | "fenced" };
 
+export interface DrainResult {
+  /** `head` at read time — pass as `expectedHead` to the matching commit. */
+  head: number;
+  /** Pending events sorted by `sourceTs`, then `eventId`. */
+  events: LedgerEvent[];
+}
+
 export interface CommitArgs {
+  /** Event ids this turn actually consumed. Only these leave `pending`. */
+  drainedEventIds: string[];
   /** The holder's lease generation (fences zombies). */
   generation: number;
-  /** `head` observed at claim time (fences concurrent turns). */
+  /** `head` observed at drain time (fences concurrent turns). */
   expectedHead: number;
   /** Unique per commit attempt; enables ambiguous-outcome recovery. */
   commitId: string;
@@ -122,18 +163,30 @@ export interface CommitArgs {
 
 export interface CommitResult {
   head: number;
+  /** Events that arrived mid-turn; non-empty ⇒ the lease was kept. */
+  pending: string[];
   /**
    * Whether this holder's lease is gone — for the caller's purposes, not
    * the record's: `true` also when the re-read of an ambiguous commit
    * finds a *new claimant's* lease, since we no longer hold the session
    * either way and continuing the turn loop would duplicate the new
-   * holder's work. On this coordination-only stage every commit
-   * releases, so this is always `true`; it exists so callers already
-   * branch on it before the inbox makes keep-the-lease outcomes real.
+   * holder's work.
    */
   leaseReleased: boolean;
 }
 
+export interface SweepOrphansArgs {
+  /** Limit the sweep to one session (default: all mailbox blobs). */
+  sessionId?: string;
+  /** Age gate (default {@link DEFAULT_ORPHAN_TTL_MS}). */
+  olderThanMs?: number;
+}
+
+export interface SweepOrphansResult {
+  /** Deleted blob ids as `<sessionId>/<eventId>`. */
+  deleted: string[];
+}
+
 /**
  * The turn was fenced: a stale generation, a moved head, or a missing
  * ledger. The caller must abort the turn and discard warm state.
@@ -160,7 +213,7 @@ export interface SessionLedgerOptions {
   podId: string;
   /** Lease TTL (default {@link LEASE_TTL_MS}). */
   leaseTtlMs?: number;
-  /** Time source for lease expiry (default `Date.now`). */
+  /** Time source for lease expiry and blob ages (default `Date.now`). */
   clock?: () => number;
   /** Max attempts per CAS loop (default 16). */
   maxCasAttempts?: number;
@@ -175,7 +228,7 @@ export interface SessionLedgerOptions {
 
 async function defaultBackoff(attempt: number): Promise<void> {
   // The common case is a single conflicting writer (one heartbeat or one
-  // claim); retrying immediately wins the next round. Sleep only when
+  // append); retrying immediately wins the next round. Sleep only when
   // contention persists.
   if (attempt < 2) {
     return;
@@ -185,7 +238,7 @@ async function defaultBackoff(attempt: number): Promise<void> {
   await new Promise((resolve) => setTimeout(resolve, waitMs));
 }
 
-/** Drives the `session/` and `ledger/` key families over a CAS KV. */
+/** Drives the three ledger key families over a CAS-capable KV. */
 export class SessionLedger {
   private readonly kv: SessionLedgerKv;
   private readonly podId: string;
@@ -213,9 +266,29 @@ export class SessionLedger {
     return `ledger/${keySegment(sessionId)}`;
   }
 
+  private mailboxKey(sessionId: string, eventId: string): string {
+    return `${this.mailboxPrefix(sessionId)}${keySegment(eventId)}`;
+  }
+
+  private mailboxPrefix(sessionId: string): string {
+    return `mailbox/${keySegment(sessionId)}/`;
+  }
+
+  private emptyLedger(sessionId: string): LedgerSnapshot {
+    return {
+      sessionId,
+      head: 0,
+      pending: [],
+      lease: null,
+      generation: 0,
+      lastCommitId: null,
+    };
+  }
+
   /**
    * Create-or-read the session identity for a continuation key. The create
-   * race has one winner (put-if-absent); losers read the winner's identity.
+   * race has one winner (put-if-absent); losers read the winner's identity
+   * and append there.
    */
   async ensureSession(
     continuationKey: string,
@@ -252,25 +325,82 @@ export class SessionLedger {
     throw new LedgerCasExhaustedError("ensureSession", this.maxCasAttempts);
   }
 
+  /**
+   * Make one event durable: payload blob first, then one CAS indexing its
+   * id into `pending`. The blob must land before the index — a pending id
+   * with no payload would break drain, while the reverse (blob without
+   * index, i.e. a crash between the two writes) is a sweepable orphan.
+   * Idempotent by `eventId`: `pending` is a set, so redelivery re-runs are
+   * no-ops. The CAS in step two is the ack point — callers ack the source
+   * only after this resolves.
+   */
+  async appendEvent(
+    sessionId: string,
+    event: LedgerEventInput
+  ): Promise<{ appended: boolean }> {
+    const blob: JsonObject = {
+      sessionId,
+      eventId: event.eventId,
+      envelope: event.envelope,
+      hookContext: event.hookContext ?? null,
+      sourceTs: event.sourceTs,
+      storedAt: this.clock(),
+    };
+    await this.kv.put(this.mailboxKey(sessionId, event.eventId), blob);
+
+    const key = this.ledgerKey(sessionId);
+    for (let attempt = 0; attempt < this.maxCasAttempts; attempt++) {
+      const entry = await this.kv.getWithVersion(key);
+      if (entry === undefined) {
+        const initial: LedgerSnapshot = {
+          ...this.emptyLedger(sessionId),
+          pending: [event.eventId],
+        };
+        const result = await this.kv.putIfAbsent(key, toJson(initial));
+        if (result.ok) {
+          return { appended: true };
+        }
+        await this.backoff(attempt);
+        continue;
+      }
+      const ledger = parseLedgerSnapshot(entry.value);
+      if (ledger.pending.includes(event.eventId)) {
+        return { appended: false };
+      }
+      const next: LedgerSnapshot = {
+        ...ledger,
+        pending: [...ledger.pending, event.eventId],
+      };
+      const result = await this.kv.putIfVersion(
+        key,
+        toJson(next),
+        entry.version
+      );
+      if (result.ok) {
+        return { appended: true };
+      }
+      await this.backoff(attempt);
+    }
+    throw new LedgerCasExhaustedError("appendEvent", this.maxCasAttempts);
+  }
+
   /**
    * Try to take the session lease, creating the ledger record on first
    * contact. Succeeds only when the lease is null or expired; the CAS
    * bumps the acquisition generation, fencing every prior holder. A
-   * losing caller gets `reason: "held"` and decides whether to wait.
+   * losing caller walks away — the holder's commit sees any appended
+   * events in the same CAS value, and the janitor recovers sessions
+   * whose holder died.
    */
   async claim(sessionId: string): Promise<ClaimResult> {
     const key = this.ledgerKey(sessionId);
     for (let attempt = 0; attempt < this.maxCasAttempts; attempt++) {
       const entry = await this.kv.getWithVersion(key);
       if (entry === undefined) {
-        const initial: LedgerSnapshot = {
-          sessionId,
-          head: 0,
-          lease: null,
-          generation: 0,
-          lastCommitId: null,
-        };
-        const result = await this.kv.putIfAbsent(key, toJson(initial));
+        const result = await this.kv.putIfAbsent(
+          key,
+          toJson(this.emptyLedger(sessionId))
+        );
         // Won or lost, the record now exists — loop back and claim it.
         if (!result.ok) {
           await this.backoff(attempt);
@@ -303,7 +433,7 @@ export class SessionLedger {
         entry.version
       );
       if (result.ok) {
-        return { claimed: true, lease, head: next.head };
+        return { claimed: true, lease, head: next.head, pending: next.pending };
       }
       await this.backoff(attempt);
     }
@@ -346,16 +476,47 @@ export class SessionLedger {
       if (result.ok) {
         return { ok: true, expiresAt };
       }
-      // Version conflict here is a concurrent writer, not a lost lease —
+      // Version conflict here is a concurrent append, not a lost lease —
       // the re-read revalidates the generation before trying again.
       await this.backoff(attempt);
     }
     throw new LedgerCasExhaustedError("heartbeat", this.maxCasAttempts);
   }
 
+  /**
+   * Read the pending mailbox: fetch each indexed payload blob and return
+   * them sorted by `sourceTs`, then `eventId` (mailbox order ≠ source
+   * order is a stated non-guarantee; this is the drain order). The
+   * returned `head` is the `expectedHead` for the matching commit.
+   */
+  async drain(sessionId: string): Promise<DrainResult> {
+    const entry = await this.kv.getWithVersion(this.ledgerKey(sessionId));
+    if (entry === undefined) {
+      return { head: 0, events: [] };
+    }
+    const ledger = parseLedgerSnapshot(entry.value);
+    const events: LedgerEvent[] = [];
+    for (const eventId of ledger.pending) {
+      const blob = await this.kv.get(this.mailboxKey(sessionId, eventId));
+      // Append order (blob before index) makes a missing blob impossible;
+      // skip defensively rather than wedge the session on corruption.
+      if (blob === undefined) {
+        continue;
+      }
+      events.push(parseLedgerEvent(blob));
+    }
+    events.sort(
+      (a, b) => a.sourceTs - b.sourceTs || compareStrings(a.eventId, b.eventId)
+    );
+    return { head: ledger.head, events };
+  }
+
   /**
    * Commit one turn. The single CAS is the commit point: it bumps `head`,
-   * releases the lease, and records `commitId` — atomically.
+   * removes ONLY the drained ids from `pending`, releases the lease iff
+   * nothing is left pending, and records `commitId` — atomically. A
+   * non-empty result `pending` means events landed mid-turn: the lease was
+   * kept and the caller drains again.
    *
    * Ambiguous outcomes (the KV threw and we never saw the CAS result) are
    * resolved by re-reading, never by blind-retrying: `head` advanced to
@@ -365,6 +526,7 @@ export class SessionLedger {
    */
   async commit(sessionId: string, args: CommitArgs): Promise<CommitResult> {
     const key = this.ledgerKey(sessionId);
+    const drained = new Set(args.drainedEventIds);
     for (let attempt = 0; attempt < this.maxCasAttempts; attempt++) {
       const entry = await this.kv.getWithVersion(key);
       if (entry === undefined) {
@@ -379,15 +541,19 @@ export class SessionLedger {
       ) {
         // A previous attempt landed even though its result was lost. The
         // lease is released *for us* unless the observed lease is exactly
-        // ours: a non-null lease here belongs to a claimant who took the
-        // session after our releasing write, and reporting it as "still
-        // held" would keep the caller's turn loop alive alongside the new
-        // holder's.
+        // ours (our commit kept it for a non-empty pending): any other
+        // non-null lease belongs to a claimant who took the session after
+        // our releasing write, and reporting it as "still held" would
+        // keep the caller's turn loop alive alongside the new holder's.
         const stillOurs =
           ledger.lease !== null &&
           ledger.lease.holder === this.podId &&
           ledger.lease.generation === args.generation;
-        return { head: ledger.head, leaseReleased: !stillOurs };
+        return {
+          head: ledger.head,
+          pending: ledger.pending,
+          leaseReleased: !stillOurs,
+        };
       }
       if (ledger.head !== args.expectedHead) {
         throw new LedgerFencedError(
@@ -403,10 +569,13 @@ export class SessionLedger {
           `commit(${sessionId}): lease generation ${args.generation} is stale`
         );
       }
+      const pending = ledger.pending.filter((id) => !drained.has(id));
+      const leaseReleased = pending.length === 0;
       const next: LedgerSnapshot = {
         ...ledger,
         head: args.expectedHead + 1,
-        lease: null,
+        pending,
+        lease: leaseReleased ? null : ledger.lease,
         lastCommitId: args.commitId,
       };
       let result: Awaited<ReturnType<SessionLedgerKv["putIfVersion"]>>;
@@ -419,20 +588,21 @@ export class SessionLedger {
         continue;
       }
       if (result.ok) {
-        return { head: next.head, leaseReleased: true };
+        return { head: next.head, pending, leaseReleased };
       }
-      // Version conflict: a concurrent writer moved the record. Re-read
-      // and retry — the fencing predicates re-run against the fresh value.
+      // Version conflict: a concurrent append. Re-read and retry — the
+      // fencing predicates re-run against the fresh value.
       await this.backoff(attempt);
     }
     throw new LedgerCasExhaustedError("commit", this.maxCasAttempts);
   }
 
   /**
-   * Release a held lease without committing — graceful shutdown, or a
-   * turn that failed before its commit. Fenced by generation: a stale
-   * holder's release is a no-op (the session has moved on). `head` and
-   * the acquisition counter are untouched, so prior holders stay fenced.
+   * Release a held lease without committing — graceful shutdown, a turn
+   * that failed before its commit, or a claim that found nothing to
+   * drain. Fenced by generation: a stale holder's release is a no-op
+   * (the session has moved on). `head` and the acquisition counter are
+   * untouched, so prior holders stay fenced.
    */
   async release(
     sessionId: string,
@@ -471,6 +641,92 @@ export class SessionLedger {
     const entry = await this.kv.getWithVersion(this.ledgerKey(sessionId));
     return entry === undefined ? undefined : parseLedgerSnapshot(entry.value);
   }
+
+  /**
+   * All ledgers under this prefix (the janitor's scan). An unparseable
+   * record is skipped — reported through `onSkip` — never thrown: one
+   * corrupt value must degrade that one session, not abort the scan and
+   * kill the whole agent's recovery pass.
+   */
+  async listLedgers(
+    onSkip?: (key: string, error: unknown) => void
+  ): Promise<LedgerSnapshot[]> {
+    const keys = await this.kv.listKeys("ledger/");
+    const ledgers: LedgerSnapshot[] = [];
+    for (const key of keys) {
+      const entry = await this.kv.getWithVersion(key);
+      if (entry === undefined) {
+        continue;
+      }
+      try {
+        ledgers.push(parseLedgerSnapshot(entry.value));
+      } catch (error) {
+        onSkip?.(key, error);
+      }
+    }
+    return ledgers;
+  }
+
+  /**
+   * Delete mailbox blobs that are (a) not referenced by their session's
+   * `pending` and (b) older than the TTL. Covers both true orphans (a
+   * crash between the payload put and the ledger CAS) and consumed blobs
+   * whose ids a commit already removed. Membership is checked against a
+   * ledger read taken *after* listing the blobs, so a blob whose append
+   * CAS is in flight is never swept: its id is either already in
+   * `pending`, or the blob is younger than any sane TTL.
+   */
+  async sweepOrphans(args?: SweepOrphansArgs): Promise<SweepOrphansResult> {
+    const olderThanMs = args?.olderThanMs ?? DEFAULT_ORPHAN_TTL_MS;
+    const prefix =
+      args?.sessionId === undefined
+        ? "mailbox/"
+        : this.mailboxPrefix(args.sessionId);
+    const keys = await this.kv.listKeys(prefix);
+    const now = this.clock();
+
+    // Blob contents carry sessionId/eventId (key segments may be digested
+    // and are not invertible), so group by reading each blob.
+    const bySession = new Map<
+      string,
+      Array<{ key: string; event: LedgerEvent }>
+    >();
+    for (const key of keys) {
+      const value = await this.kv.get(key);
+      if (value === undefined) {
+        continue;
+      }
+      const event = parseLedgerEvent(value);
+      const sessionId = readBlobSessionId(value);
+      const group = bySession.get(sessionId) ?? [];
+      group.push({ key, event });
+      bySession.set(sessionId, group);
+    }
+
+    const deleted: string[] = [];
+    for (const [sessionId, blobs] of bySession) {
+      const ledger = await this.readLedger(sessionId);
+      const pending = new Set(ledger?.pending ?? []);
+      for (const { key, event } of blobs) {
+        if (pending.has(event.eventId)) {
+          continue;
+        }
+        if (event.storedAt + olderThanMs > now) {
+          continue;
+        }
+        await this.kv.delete(key);
+        deleted.push(`${sessionId}/${event.eventId}`);
+      }
+    }
+    return { deleted };
+  }
+}
+
+function compareStrings(a: string, b: string): number {
+  if (a < b) {
+    return -1;
+  }
+  return a > b ? 1 : 0;
 }
 
 function toJson(value: SessionIdentity | LedgerSnapshot): JsonValue {
@@ -505,12 +761,32 @@ function parseLedgerSnapshot(value: JsonValue): LedgerSnapshot {
   return {
     sessionId,
     head,
+    pending: parsePending(record.pending),
     lease: parseLease(lease),
     generation,
     lastCommitId: typeof lastCommitId === "string" ? lastCommitId : null,
   };
 }
 
+/**
+ * Records written by the pre-inbox ledger have no `pending` field; read
+ * them as an empty inbox instead of rejecting them — one legacy record
+ * must not brick `claim`/`readLedger` (or a whole `listLedgers` scan)
+ * after an upgrade. Every write from the inbox on includes the field.
+ */
+function parsePending(value: JsonValue | undefined): string[] {
+  if (value === undefined) {
+    return [];
+  }
+  if (
+    !Array.isArray(value) ||
+    !value.every((id): id is string => typeof id === "string")
+  ) {
+    throw new Error("session ledger: malformed ledger value");
+  }
+  return value;
+}
+
 function parseLease(value: JsonValue | undefined): LedgerLease | null {
   if (value === null || value === undefined) {
     return null;
@@ -527,6 +803,34 @@ function parseLease(value: JsonValue | undefined): LedgerLease | null {
   return { holder, generation, expiresAt };
 }
 
+function parseLedgerEvent(value: JsonValue): LedgerEvent {
+  const record = asRecord(value, "mailbox blob");
+  const { eventId, sourceTs, storedAt } = record;
+  if (
+    typeof eventId !== "string" ||
+    typeof sourceTs !== "number" ||
+    typeof storedAt !== "number"
+  ) {
+    throw new Error("session ledger: malformed mailbox blob");
+  }
+  return {
+    eventId,
+    envelope: record.envelope ?? null,
+    hookContext: record.hookContext ?? null,
+    sourceTs,
+    storedAt,
+  };
+}
+
+function readBlobSessionId(value: JsonValue): string {
+  const record = asRecord(value, "mailbox blob");
+  const sessionId = record.sessionId;
+  if (typeof sessionId !== "string") {
+    throw new Error("session ledger: mailbox blob is missing sessionId");
+  }
+  return sessionId;
+}
+
 function asRecord(value: JsonValue, what: string): JsonObject {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     throw new Error(`session ledger: ${what} value is not an object`);