@cursor/july 0.1.39 → 0.1.41

package/src/ledger/session-ledger.ts

@@ -0,0 +1,535 @@
+/**
+ * Session ledger — coordination only (no inbox).
+ *
+ * Two key families, driven with CAS over 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
+ * ```
+ *
+ * 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.
+ *
+ * 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 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.
+ *
+ * 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;
+
+const DEFAULT_MAX_CAS_ATTEMPTS = 16;
+
+/**
+ * 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.
+ */
+export type SessionLedgerKv = Pick<
+  HostKvCasApi,
+  "getWithVersion" | "putIfAbsent" | "putIfVersion"
+>;
+
+/** 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.getWithVersion === "function" &&
+    typeof candidate.putIfAbsent === "function" &&
+    typeof candidate.putIfVersion === "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, 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.
+ */
+export interface LedgerSnapshot {
+  sessionId: string;
+  head: number;
+  lease: LedgerLease | null;
+  generation: number;
+  lastCommitId: string | null;
+}
+
+export type EnsureSessionResult = {
+  created: boolean;
+  session: SessionIdentity;
+};
+
+export type ClaimResult =
+  | { claimed: true; lease: LedgerLease; head: number }
+  | { claimed: false; reason: "held"; holder: string; expiresAt: number };
+
+export type HeartbeatResult =
+  | { ok: true; expiresAt: number }
+  | { ok: false; reason: "not-found" | "fenced" };
+
+export interface CommitArgs {
+  /** The holder's lease generation (fences zombies). */
+  generation: number;
+  /** `head` observed at claim time (fences concurrent turns). */
+  expectedHead: number;
+  /** Unique per commit attempt; enables ambiguous-outcome recovery. */
+  commitId: string;
+}
+
+export interface CommitResult {
+  head: number;
+  /**
+   * 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.
+   */
+  leaseReleased: boolean;
+}
+
+/**
+ * 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 (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
+  // claim); 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 `session/` and `ledger/` key families over a CAS 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)}`;
+  }
+
+  /**
+   * 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.
+   */
+  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);
+  }
+
+  /**
+   * 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.
+   */
+  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));
+        // 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 };
+      }
+      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 writer, not a lost lease —
+      // the re-read revalidates the generation before trying again.
+      await this.backoff(attempt);
+    }
+    throw new LedgerCasExhaustedError("heartbeat", this.maxCasAttempts);
+  }
+
+  /**
+   * Commit one turn. The single CAS is the commit point: it bumps `head`,
+   * releases the lease, and records `commitId` — atomically.
+   *
+   * 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);
+    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: 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.
+        const stillOurs =
+          ledger.lease !== null &&
+          ledger.lease.holder === this.podId &&
+          ledger.lease.generation === args.generation;
+        return { head: ledger.head, 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 next: LedgerSnapshot = {
+        ...ledger,
+        head: args.expectedHead + 1,
+        lease: null,
+        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, leaseReleased: true };
+      }
+      // Version conflict: a concurrent writer moved the record. 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.
+   */
+  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);
+  }
+}
+
+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,
+    lease: parseLease(lease),
+    generation,
+    lastCommitId: typeof lastCommitId === "string" ? lastCommitId : null,
+  };
+}
+
+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 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;
+}

package/src/ledger.ts

@@ -0,0 +1,29 @@
+/**
+ * Session ledger — coordination only. The protocol library that drives
+ * the `session/` and `ledger/` key families over a CAS-capable KV:
+ * identity creation, lease claim/heartbeat/release, and the fenced
+ * commit sequence. The durable inbox (pending events, mailbox payloads,
+ * append/drain, the janitor) lands in a follow-up; see
+ * `src/ledger/session-ledger.ts` for the trade-off this stage accepts.
+ */
+
+export type {
+  ClaimResult,
+  CommitArgs,
+  CommitResult,
+  EnsureSessionResult,
+  HeartbeatResult,
+  LedgerLease,
+  LedgerSnapshot,
+  SessionIdentity,
+  SessionLedgerKv,
+  SessionLedgerOptions,
+} from "./ledger/session-ledger.js";
+export {
+  HEARTBEAT_INTERVAL_MS,
+  LEASE_TTL_MS,
+  LedgerCasExhaustedError,
+  LedgerFencedError,
+  SessionLedger,
+  supportsSessionLedgerKv,
+} from "./ledger/session-ledger.js";