@cursor/july 0.1.39 → 0.1.41

package/dist/ledger/session-ledger.d.ts

@@ -0,0 +1,204 @@
+/**
+ * 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 type { HostKvCasApi } from "../types.js";
+export declare const LEASE_TTL_MS = 30000;
+export declare const HEARTBEAT_INTERVAL_MS = 10000;
+/**
+ * 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 declare function supportsSessionLedgerKv(kv: object): kv is SessionLedgerKv;
+/** `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 declare class LedgerFencedError extends Error {
+    constructor(message: string);
+}
+/** A CAS retry loop ran out of attempts (sustained contention or outage). */
+export declare class LedgerCasExhaustedError extends Error {
+    constructor(operation: string, attempts: number);
+}
+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;
+}
+/** Drives the `session/` and `ledger/` key families over a CAS KV. */
+export declare class SessionLedger {
+    private readonly kv;
+    private readonly podId;
+    private readonly leaseTtlMs;
+    private readonly clock;
+    private readonly maxCasAttempts;
+    private readonly backoff;
+    private readonly mintSessionId;
+    constructor(options: SessionLedgerOptions);
+    private sessionKey;
+    private ledgerKey;
+    /**
+     * 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.
+     */
+    ensureSession(continuationKey: string, init?: {
+        sdkSessionRef?: string | null;
+    }): Promise<EnsureSessionResult>;
+    /**
+     * 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.
+     */
+    claim(sessionId: string): Promise<ClaimResult>;
+    /**
+     * 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.
+     */
+    heartbeat(sessionId: string, generation: number): Promise<HeartbeatResult>;
+    /**
+     * 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.
+     */
+    commit(sessionId: string, args: CommitArgs): Promise<CommitResult>;
+    /**
+     * 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(sessionId: string, generation: number): Promise<{
+        released: boolean;
+    }>;
+    /** Parsed ledger value for one session, or `undefined` when never created. */
+    readLedger(sessionId: string): Promise<LedgerSnapshot | undefined>;
+}
+//# sourceMappingURL=session-ledger.d.ts.map

package/dist/ledger/session-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-ledger.d.ts","sourceRoot":"","sources":["../../src/ledger/session-ledger.ts"],"names":[],"mappings":"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"}

package/dist/ledger/session-ledger.js

@@ -0,0 +1,382 @@
+/**
+ * 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.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { newSessionId } from "../internal/ids.js";
+import { keySegment } from "../storage.js";
+// Lease mechanics: TTL ~30s, heartbeat ~10s, generation increments per
+// acquisition.
+export const LEASE_TTL_MS = 30000;
+export const HEARTBEAT_INTERVAL_MS = 10000;
+const DEFAULT_MAX_CAS_ATTEMPTS = 16;
+/** Runtime probe for {@link SessionLedgerKv} on stores of unknown shape. */
+export function supportsSessionLedgerKv(kv) {
+    const candidate = kv;
+    return (typeof candidate.getWithVersion === "function" &&
+        typeof candidate.putIfAbsent === "function" &&
+        typeof candidate.putIfVersion === "function");
+}
+/**
+ * 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) {
+        super(message);
+        this.name = "LedgerFencedError";
+    }
+}
+/** A CAS retry loop ran out of attempts (sustained contention or outage). */
+export class LedgerCasExhaustedError extends Error {
+    constructor(operation, attempts) {
+        super(`${operation}: CAS did not settle after ${attempts} attempts`);
+        this.name = "LedgerCasExhaustedError";
+    }
+}
+function defaultBackoff(attempt) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // 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 * Math.pow(2, attempt), 250);
+        const waitMs = cap / 2 + Math.random() * (cap / 2);
+        yield new Promise((resolve) => setTimeout(resolve, waitMs));
+    });
+}
+/** Drives the `session/` and `ledger/` key families over a CAS KV. */
+export class SessionLedger {
+    constructor(options) {
+        var _a, _b, _c, _d, _e;
+        this.kv = options.kv;
+        this.podId = options.podId;
+        this.leaseTtlMs = (_a = options.leaseTtlMs) !== null && _a !== void 0 ? _a : LEASE_TTL_MS;
+        this.clock = (_b = options.clock) !== null && _b !== void 0 ? _b : Date.now;
+        this.maxCasAttempts = (_c = options.maxCasAttempts) !== null && _c !== void 0 ? _c : DEFAULT_MAX_CAS_ATTEMPTS;
+        this.backoff = (_d = options.backoff) !== null && _d !== void 0 ? _d : defaultBackoff;
+        this.mintSessionId = (_e = options.newSessionId) !== null && _e !== void 0 ? _e : newSessionId;
+    }
+    sessionKey(continuationKey) {
+        return `session/${keySegment(continuationKey)}`;
+    }
+    ledgerKey(sessionId) {
+        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.
+     */
+    ensureSession(continuationKey, init) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const key = this.sessionKey(continuationKey);
+            for (let attempt = 0; attempt < this.maxCasAttempts; attempt++) {
+                const existing = yield this.kv.getWithVersion(key);
+                if (existing !== undefined) {
+                    return {
+                        created: false,
+                        session: parseSessionIdentity(existing.value),
+                    };
+                }
+                const session = {
+                    sessionId: this.mintSessionId(),
+                    sdkSessionRef: (_a = init === null || init === void 0 ? void 0 : init.sdkSessionRef) !== null && _a !== void 0 ? _a : null,
+                    createdAt: this.clock(),
+                };
+                const result = yield 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.
+                yield 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.
+     */
+    claim(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const key = this.ledgerKey(sessionId);
+            for (let attempt = 0; attempt < this.maxCasAttempts; attempt++) {
+                const entry = yield this.kv.getWithVersion(key);
+                if (entry === undefined) {
+                    const initial = {
+                        sessionId,
+                        head: 0,
+                        lease: null,
+                        generation: 0,
+                        lastCommitId: null,
+                    };
+                    const result = yield this.kv.putIfAbsent(key, toJson(initial));
+                    // Won or lost, the record now exists — loop back and claim it.
+                    if (!result.ok) {
+                        yield 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 = {
+                    holder: this.podId,
+                    generation: ledger.generation + 1,
+                    expiresAt: now + this.leaseTtlMs,
+                };
+                const next = Object.assign(Object.assign({}, ledger), { generation: lease.generation, lease });
+                const result = yield this.kv.putIfVersion(key, toJson(next), entry.version);
+                if (result.ok) {
+                    return { claimed: true, lease, head: next.head };
+                }
+                yield 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.
+     */
+    heartbeat(sessionId, generation) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const key = this.ledgerKey(sessionId);
+            for (let attempt = 0; attempt < this.maxCasAttempts; attempt++) {
+                const entry = yield 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 = Object.assign(Object.assign({}, ledger), { lease: Object.assign(Object.assign({}, ledger.lease), { expiresAt }) });
+                const result = yield 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.
+                yield 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.
+     */
+    commit(sessionId, args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const key = this.ledgerKey(sessionId);
+            for (let attempt = 0; attempt < this.maxCasAttempts; attempt++) {
+                const entry = yield 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 = Object.assign(Object.assign({}, ledger), { head: args.expectedHead + 1, lease: null, lastCommitId: args.commitId });
+                let result;
+                try {
+                    result = yield this.kv.putIfVersion(key, toJson(next), entry.version);
+                }
+                catch (_a) {
+                    // Unknown outcome — loop back to the re-read, which either finds
+                    // our commitId (success) or a fresh version to CAS against.
+                    yield 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.
+                yield 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(sessionId, generation) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const key = this.ledgerKey(sessionId);
+            for (let attempt = 0; attempt < this.maxCasAttempts; attempt++) {
+                const entry = yield 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 = Object.assign(Object.assign({}, ledger), { lease: null });
+                const result = yield this.kv.putIfVersion(key, toJson(next), entry.version);
+                if (result.ok) {
+                    return { released: true };
+                }
+                yield this.backoff(attempt);
+            }
+            throw new LedgerCasExhaustedError("release", this.maxCasAttempts);
+        });
+    }
+    /** Parsed ledger value for one session, or `undefined` when never created. */
+    readLedger(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const entry = yield this.kv.getWithVersion(this.ledgerKey(sessionId));
+            return entry === undefined ? undefined : parseLedgerSnapshot(entry.value);
+        });
+    }
+}
+function toJson(value) {
+    return value;
+}
+function parseSessionIdentity(value) {
+    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) {
+    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) {
+    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, what) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`session ledger: ${what} value is not an object`);
+    }
+    return value;
+}

package/dist/ledger.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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";
+//# sourceMappingURL=ledger.d.ts.map

package/dist/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,YAAY,EACV,WAAW,EACX,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,WAAW,EACX,cAAc,EACd,eAAe,EACf,eAAe,EACf,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,qBAAqB,EACrB,YAAY,EACZ,uBAAuB,EACvB,iBAAiB,EACjB,aAAa,EACb,uBAAuB,GACxB,MAAM,4BAA4B,CAAC"}

package/dist/ledger.js

@@ -0,0 +1,9 @@
+/**
+ * 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 { HEARTBEAT_INTERVAL_MS, LEASE_TTL_MS, LedgerCasExhaustedError, LedgerFencedError, SessionLedger, supportsSessionLedgerKv, } from "./ledger/session-ledger.js";