@cursor/july 0.1.76 → 0.1.78

package/src/ledger/session-ledger.ts

@@ -1,839 +0,0 @@
-/**
- * Session ledger — KV coordination with a durable inbox.
- *
- * 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 + pending + lease — every mutation one CAS
- * mailbox/<sessionId>/<eventId>  immutable payload blobs, plain put
- * ```
- *
- * The keys are deliberately bare: namespacing (per agent, per
- * deployment) is not the ledger's concern. The store handle it is given
- * must already be scoped — the engine applies the namespace exactly once
- * where it constructs the handle (see `durable-session-store.ts`), the
- * same boundary where `host.kv` gets its agent scoping.
- *
- * 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 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
- * deployments accept NTP-synced pods as a documented requirement; a
- * backend-clock primitive can replace the default without touching the
- * protocol code.
- */
-
-import { newSessionId } from "../internal/ids.js";
-import { keySegment } from "../storage.js";
-import type { HostKvCasApi, JsonObject, JsonValue } from "../types.js";
-
-// Lease mechanics: TTL ~30s, heartbeat ~10s, generation increments per
-// 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;
-
-// 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;
-
-/**
- * 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 = 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.listKeys === "function"
-  );
-}
-
-/** `session/<continuationKey>` value. Immutable after creation. */
-export interface SessionIdentity {
-  sessionId: string;
-  sdkSessionRef: string | null;
-  createdAt: number;
-}
-
-export interface LedgerLease {
-  holder: string;
-  generation: number;
-  expiresAt: number;
-}
-
-/**
- * `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; 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 drain time (fences concurrent turns). */
-  expectedHead: number;
-  /** Unique per commit attempt; enables ambiguous-outcome recovery. */
-  commitId: string;
-}
-
-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.
-   */
-  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.
- */
-export class LedgerFencedError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "LedgerFencedError";
-  }
-}
-
-/** A CAS retry loop ran out of attempts (sustained contention or outage). */
-export class LedgerCasExhaustedError extends Error {
-  constructor(operation: string, attempts: number) {
-    super(`${operation}: CAS did not settle after ${attempts} attempts`);
-    this.name = "LedgerCasExhaustedError";
-  }
-}
-
-export interface SessionLedgerOptions {
-  /** Already-scoped store handle; the ledger writes bare keys into it. */
-  kv: SessionLedgerKv;
-  /** Stable identity of this pod/process — the lease `holder`. */
-  podId: string;
-  /** Lease TTL (default {@link LEASE_TTL_MS}). */
-  leaseTtlMs?: number;
-  /** Time source for lease expiry and blob ages (default `Date.now`). */
-  clock?: () => number;
-  /** Max attempts per CAS loop (default 16). */
-  maxCasAttempts?: number;
-  /**
-   * Wait between CAS retries. Default: immediate for the first retries,
-   * then a jittered exponential capped at 250ms.
-   */
-  backoff?: (attempt: number) => Promise<void>;
-  /** Session id mint (default `ses_<24 hex>` like the session engine). */
-  newSessionId?: () => string;
-}
-
-async function defaultBackoff(attempt: number): Promise<void> {
-  // The common case is a single conflicting writer (one heartbeat or one
-  // append); retrying immediately wins the next round. Sleep only when
-  // contention persists.
-  if (attempt < 2) {
-    return;
-  }
-  const cap = Math.min(5 * 2 ** attempt, 250);
-  const waitMs = cap / 2 + Math.random() * (cap / 2);
-  await new Promise((resolve) => setTimeout(resolve, waitMs));
-}
-
-/** Drives the three ledger key families over a CAS-capable KV. */
-export class SessionLedger {
-  private readonly kv: SessionLedgerKv;
-  private readonly podId: string;
-  private readonly leaseTtlMs: number;
-  private readonly clock: () => number;
-  private readonly maxCasAttempts: number;
-  private readonly backoff: (attempt: number) => Promise<void>;
-  private readonly mintSessionId: () => string;
-
-  constructor(options: SessionLedgerOptions) {
-    this.kv = options.kv;
-    this.podId = options.podId;
-    this.leaseTtlMs = options.leaseTtlMs ?? LEASE_TTL_MS;
-    this.clock = options.clock ?? Date.now;
-    this.maxCasAttempts = options.maxCasAttempts ?? DEFAULT_MAX_CAS_ATTEMPTS;
-    this.backoff = options.backoff ?? defaultBackoff;
-    this.mintSessionId = options.newSessionId ?? newSessionId;
-  }
-
-  private sessionKey(continuationKey: string): string {
-    return `session/${keySegment(continuationKey)}`;
-  }
-
-  private ledgerKey(sessionId: string): string {
-    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
-   * and append there.
-   */
-  async ensureSession(
-    continuationKey: string,
-    init?: { sdkSessionRef?: string | null }
-  ): Promise<EnsureSessionResult> {
-    const key = this.sessionKey(continuationKey);
-    for (let attempt = 0; attempt < this.maxCasAttempts; attempt++) {
-      const existing = await this.kv.getWithVersion(key);
-      if (existing !== undefined) {
-        return {
-          created: false,
-          session: parseSessionIdentity(existing.value),
-        };
-      }
-      const session: SessionIdentity = {
-        sessionId: this.mintSessionId(),
-        sdkSessionRef: init?.sdkSessionRef ?? null,
-        createdAt: this.clock(),
-      };
-      const result = await this.kv.putIfAbsent(key, toJson(session));
-      if (result.ok) {
-        return { created: true, session };
-      }
-      if (result.current !== undefined) {
-        return {
-          created: false,
-          session: parseSessionIdentity(result.current.value),
-        };
-      }
-      // Conflict with no current entry (created then deleted underneath
-      // us) — retry from the read.
-      await this.backoff(attempt);
-    }
-    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 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 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);
-        }
-        continue;
-      }
-      const ledger = parseLedgerSnapshot(entry.value);
-      const now = this.clock();
-      if (ledger.lease !== null && ledger.lease.expiresAt > now) {
-        return {
-          claimed: false,
-          reason: "held",
-          holder: ledger.lease.holder,
-          expiresAt: ledger.lease.expiresAt,
-        };
-      }
-      const lease: LedgerLease = {
-        holder: this.podId,
-        generation: ledger.generation + 1,
-        expiresAt: now + this.leaseTtlMs,
-      };
-      const next: LedgerSnapshot = {
-        ...ledger,
-        generation: lease.generation,
-        lease,
-      };
-      const result = await this.kv.putIfVersion(
-        key,
-        toJson(next),
-        entry.version
-      );
-      if (result.ok) {
-        return { claimed: true, lease, head: next.head, pending: next.pending };
-      }
-      await this.backoff(attempt);
-    }
-    throw new LedgerCasExhaustedError("claim", this.maxCasAttempts);
-  }
-
-  /**
-   * Extend the lease. Fails when the generation is no longer ours — the
-   * caller must abort the turn and discard warm state; the session has a
-   * new legitimate holder.
-   */
-  async heartbeat(
-    sessionId: string,
-    generation: number
-  ): Promise<HeartbeatResult> {
-    const key = this.ledgerKey(sessionId);
-    for (let attempt = 0; attempt < this.maxCasAttempts; attempt++) {
-      const entry = await this.kv.getWithVersion(key);
-      if (entry === undefined) {
-        return { ok: false, reason: "not-found" };
-      }
-      const ledger = parseLedgerSnapshot(entry.value);
-      if (
-        ledger.lease === null ||
-        ledger.lease.holder !== this.podId ||
-        ledger.lease.generation !== generation
-      ) {
-        return { ok: false, reason: "fenced" };
-      }
-      const expiresAt = this.clock() + this.leaseTtlMs;
-      const next: LedgerSnapshot = {
-        ...ledger,
-        lease: { ...ledger.lease, expiresAt },
-      };
-      const result = await this.kv.putIfVersion(
-        key,
-        toJson(next),
-        entry.version
-      );
-      if (result.ok) {
-        return { ok: true, expiresAt };
-      }
-      // 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`,
-   * 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
-   * `expectedHead + 1` with our `commitId` ⇒ our write landed, report
-   * success; `head` still at `expectedHead` with our lease ⇒ it did not,
-   * retry against the fresh version; anything else ⇒ fenced.
-   */
-  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) {
-        throw new LedgerFencedError(
-          `commit(${sessionId}): ledger key is missing`
-        );
-      }
-      const ledger = parseLedgerSnapshot(entry.value);
-      if (
-        ledger.head === args.expectedHead + 1 &&
-        ledger.lastCommitId === args.commitId
-      ) {
-        // A previous attempt landed even though its result was lost. The
-        // lease is released *for us* unless the observed lease is exactly
-        // 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,
-          pending: ledger.pending,
-          leaseReleased: !stillOurs,
-        };
-      }
-      if (ledger.head !== args.expectedHead) {
-        throw new LedgerFencedError(
-          `commit(${sessionId}): head is ${ledger.head}, expected ${args.expectedHead}`
-        );
-      }
-      if (
-        ledger.lease === null ||
-        ledger.lease.holder !== this.podId ||
-        ledger.lease.generation !== args.generation
-      ) {
-        throw new LedgerFencedError(
-          `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,
-        pending,
-        lease: leaseReleased ? null : ledger.lease,
-        lastCommitId: args.commitId,
-      };
-      let result: Awaited<ReturnType<SessionLedgerKv["putIfVersion"]>>;
-      try {
-        result = await this.kv.putIfVersion(key, toJson(next), entry.version);
-      } catch {
-        // Unknown outcome — loop back to the re-read, which either finds
-        // our commitId (success) or a fresh version to CAS against.
-        await this.backoff(attempt);
-        continue;
-      }
-      if (result.ok) {
-        return { head: next.head, pending, leaseReleased };
-      }
-      // 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, 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,
-    generation: number
-  ): Promise<{ released: boolean }> {
-    const key = this.ledgerKey(sessionId);
-    for (let attempt = 0; attempt < this.maxCasAttempts; attempt++) {
-      const entry = await this.kv.getWithVersion(key);
-      if (entry === undefined) {
-        return { released: false };
-      }
-      const ledger = parseLedgerSnapshot(entry.value);
-      if (
-        ledger.lease === null ||
-        ledger.lease.holder !== this.podId ||
-        ledger.lease.generation !== generation
-      ) {
-        return { released: false };
-      }
-      const next: LedgerSnapshot = { ...ledger, lease: null };
-      const result = await this.kv.putIfVersion(
-        key,
-        toJson(next),
-        entry.version
-      );
-      if (result.ok) {
-        return { released: true };
-      }
-      await this.backoff(attempt);
-    }
-    throw new LedgerCasExhaustedError("release", this.maxCasAttempts);
-  }
-
-  /** Parsed ledger value for one session, or `undefined` when never created. */
-  async readLedger(sessionId: string): Promise<LedgerSnapshot | undefined> {
-    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 {
-  return value as unknown as JsonValue;
-}
-
-function parseSessionIdentity(value: JsonValue): SessionIdentity {
-  const record = asRecord(value, "session identity");
-  const sessionId = record.sessionId;
-  const createdAt = record.createdAt;
-  if (typeof sessionId !== "string" || typeof createdAt !== "number") {
-    throw new Error("session ledger: malformed session identity value");
-  }
-  const sdkSessionRef = record.sdkSessionRef;
-  return {
-    sessionId,
-    sdkSessionRef: typeof sdkSessionRef === "string" ? sdkSessionRef : null,
-    createdAt,
-  };
-}
-
-function parseLedgerSnapshot(value: JsonValue): LedgerSnapshot {
-  const record = asRecord(value, "ledger");
-  const { sessionId, head, lease, generation, lastCommitId } = record;
-  if (
-    typeof sessionId !== "string" ||
-    typeof head !== "number" ||
-    typeof generation !== "number"
-  ) {
-    throw new Error("session ledger: malformed ledger value");
-  }
-  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;
-  }
-  const record = asRecord(value, "lease");
-  const { holder, generation, expiresAt } = record;
-  if (
-    typeof holder !== "string" ||
-    typeof generation !== "number" ||
-    typeof expiresAt !== "number"
-  ) {
-    throw new Error("session ledger: malformed lease value");
-  }
-  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`);
-  }
-  return value;
-}