@cursor/july 0.1.45 → 0.1.46

package/dist/ledger/session-ledger.js

@@ -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
@@ -52,13 +53,24 @@ import { keySegment } from "../storage.js";
 // acquisition.
 export const LEASE_TTL_MS = 30000;
 export const HEARTBEAT_INTERVAL_MS = 10000;
-const DEFAULT_MAX_CAS_ATTEMPTS = 16;
+/** Unreferenced mailbox blobs older than this are sweepable. */
+export const DEFAULT_ORPHAN_TTL_MS = 60 * 60000;
+// 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;
 /** Runtime probe for {@link SessionLedgerKv} on stores of unknown shape. */
 export function supportsSessionLedgerKv(kv) {
     const candidate = kv;
-    return (typeof candidate.getWithVersion === "function" &&
+    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");
 }
 /**
  * The turn was fenced: a stale generation, a moved head, or a missing
@@ -80,7 +92,7 @@ export class LedgerCasExhaustedError extends Error {
 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
+        // append); retrying immediately wins the next round. Sleep only when
         // contention persists.
         if (attempt < 2) {
             return;
@@ -90,7 +102,7 @@ function defaultBackoff(attempt) {
         yield 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 {
     constructor(options) {
         var _a, _b, _c, _d, _e;
@@ -108,9 +120,26 @@ export class SessionLedger {
     ledgerKey(sessionId) {
         return `ledger/${keySegment(sessionId)}`;
     }
+    mailboxKey(sessionId, eventId) {
+        return `${this.mailboxPrefix(sessionId)}${keySegment(eventId)}`;
+    }
+    mailboxPrefix(sessionId) {
+        return `mailbox/${keySegment(sessionId)}/`;
+    }
+    emptyLedger(sessionId) {
+        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.
      */
     ensureSession(continuationKey, init) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -146,11 +175,60 @@ 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.
+     */
+    appendEvent(sessionId, event) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const blob = {
+                sessionId,
+                eventId: event.eventId,
+                envelope: event.envelope,
+                hookContext: (_a = event.hookContext) !== null && _a !== void 0 ? _a : null,
+                sourceTs: event.sourceTs,
+                storedAt: this.clock(),
+            };
+            yield this.kv.put(this.mailboxKey(sessionId, event.eventId), blob);
+            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 = Object.assign(Object.assign({}, this.emptyLedger(sessionId)), { pending: [event.eventId] });
+                    const result = yield this.kv.putIfAbsent(key, toJson(initial));
+                    if (result.ok) {
+                        return { appended: true };
+                    }
+                    yield this.backoff(attempt);
+                    continue;
+                }
+                const ledger = parseLedgerSnapshot(entry.value);
+                if (ledger.pending.includes(event.eventId)) {
+                    return { appended: false };
+                }
+                const next = Object.assign(Object.assign({}, ledger), { pending: [...ledger.pending, event.eventId] });
+                const result = yield this.kv.putIfVersion(key, toJson(next), entry.version);
+                if (result.ok) {
+                    return { appended: true };
+                }
+                yield 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.
      */
     claim(sessionId) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -158,14 +236,7 @@ export class SessionLedger {
             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));
+                    const result = yield this.kv.putIfAbsent(key, toJson(this.emptyLedger(sessionId)));
                     // Won or lost, the record now exists — loop back and claim it.
                     if (!result.ok) {
                         yield this.backoff(attempt);
@@ -190,7 +261,7 @@ export class SessionLedger {
                 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 };
+                    return { claimed: true, lease, head: next.head, pending: next.pending };
                 }
                 yield this.backoff(attempt);
             }
@@ -222,16 +293,46 @@ 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.
                 yield 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.
+     */
+    drain(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const entry = yield this.kv.getWithVersion(this.ledgerKey(sessionId));
+            if (entry === undefined) {
+                return { head: 0, events: [] };
+            }
+            const ledger = parseLedgerSnapshot(entry.value);
+            const events = [];
+            for (const eventId of ledger.pending) {
+                const blob = yield 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
@@ -242,6 +343,7 @@ export class SessionLedger {
     commit(sessionId, args) {
         return __awaiter(this, void 0, void 0, function* () {
             const key = this.ledgerKey(sessionId);
+            const drained = new Set(args.drainedEventIds);
             for (let attempt = 0; attempt < this.maxCasAttempts; attempt++) {
                 const entry = yield this.kv.getWithVersion(key);
                 if (entry === undefined) {
@@ -252,14 +354,18 @@ export class SessionLedger {
                     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.
+                    // 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(`commit(${sessionId}): head is ${ledger.head}, expected ${args.expectedHead}`);
@@ -269,7 +375,9 @@ export class SessionLedger {
                     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 });
+                const pending = ledger.pending.filter((id) => !drained.has(id));
+                const leaseReleased = pending.length === 0;
+                const next = Object.assign(Object.assign({}, ledger), { head: args.expectedHead + 1, pending, lease: leaseReleased ? null : ledger.lease, lastCommitId: args.commitId });
                 let result;
                 try {
                     result = yield this.kv.putIfVersion(key, toJson(next), entry.version);
@@ -281,20 +389,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.
                 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 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.
      */
     release(sessionId, generation) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -327,6 +436,87 @@ export class SessionLedger {
             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.
+     */
+    listLedgers(onSkip) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const keys = yield this.kv.listKeys("ledger/");
+            const ledgers = [];
+            for (const key of keys) {
+                const entry = yield this.kv.getWithVersion(key);
+                if (entry === undefined) {
+                    continue;
+                }
+                try {
+                    ledgers.push(parseLedgerSnapshot(entry.value));
+                }
+                catch (error) {
+                    onSkip === null || onSkip === void 0 ? void 0 : 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.
+     */
+    sweepOrphans(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            const olderThanMs = (_a = args === null || args === void 0 ? void 0 : args.olderThanMs) !== null && _a !== void 0 ? _a : DEFAULT_ORPHAN_TTL_MS;
+            const prefix = (args === null || args === void 0 ? void 0 : args.sessionId) === undefined
+                ? "mailbox/"
+                : this.mailboxPrefix(args.sessionId);
+            const keys = yield 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();
+            for (const key of keys) {
+                const value = yield this.kv.get(key);
+                if (value === undefined) {
+                    continue;
+                }
+                const event = parseLedgerEvent(value);
+                const sessionId = readBlobSessionId(value);
+                const group = (_b = bySession.get(sessionId)) !== null && _b !== void 0 ? _b : [];
+                group.push({ key, event });
+                bySession.set(sessionId, group);
+            }
+            const deleted = [];
+            for (const [sessionId, blobs] of bySession) {
+                const ledger = yield this.readLedger(sessionId);
+                const pending = new Set((_c = ledger === null || ledger === void 0 ? void 0 : ledger.pending) !== null && _c !== void 0 ? _c : []);
+                for (const { key, event } of blobs) {
+                    if (pending.has(event.eventId)) {
+                        continue;
+                    }
+                    if (event.storedAt + olderThanMs > now) {
+                        continue;
+                    }
+                    yield this.kv.delete(key);
+                    deleted.push(`${sessionId}/${event.eventId}`);
+                }
+            }
+            return { deleted };
+        });
+    }
+}
+function compareStrings(a, b) {
+    if (a < b) {
+        return -1;
+    }
+    return a > b ? 1 : 0;
 }
 function toJson(value) {
     return value;
@@ -356,11 +546,28 @@ function parseLedgerSnapshot(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) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value) ||
+        !value.every((id) => typeof id === "string")) {
+        throw new Error("session ledger: malformed ledger value");
+    }
+    return value;
+}
 function parseLease(value) {
     if (value === null || value === undefined) {
         return null;
@@ -374,6 +581,31 @@ function parseLease(value) {
     }
     return { holder, generation, expiresAt };
 }
+function parseLedgerEvent(value) {
+    var _a, _b;
+    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: (_a = record.envelope) !== null && _a !== void 0 ? _a : null,
+        hookContext: (_b = record.hookContext) !== null && _b !== void 0 ? _b : null,
+        sourceTs,
+        storedAt,
+    };
+}
+function readBlobSessionId(value) {
+    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, what) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         throw new Error(`session ledger: ${what} value is not an object`);

package/dist/ledger.d.ts

@@ -1,11 +1,12 @@
 /**
- * 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.
+ * Session ledger — KV coordination with a durable inbox. The protocol
+ * library that drives the `session/`, `ledger/`, and `mailbox/` key
+ * families over a CAS-capable KV: identity creation, event append,
+ * lease claim/heartbeat/release, fenced commit, drain, the janitor
+ * loop, and the orphan sweep.
  */
-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";
+export type { JanitorClaimedSession, JanitorRunResult, LedgerJanitor, LedgerJanitorOptions, } from "./ledger/janitor.js";
+export { createLedgerJanitor, DEFAULT_JANITOR_INTERVAL_MS, } from "./ledger/janitor.js";
+export type { ClaimResult, CommitArgs, CommitResult, DrainResult, EnsureSessionResult, HeartbeatResult, LedgerEvent, LedgerEventInput, LedgerLease, LedgerSnapshot, SessionIdentity, SessionLedgerKv, SessionLedgerOptions, SweepOrphansArgs, SweepOrphansResult, } from "./ledger/session-ledger.js";
+export { DEFAULT_ORPHAN_TTL_MS, 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

@@ -1 +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"}
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EACb,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,mBAAmB,EACnB,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,WAAW,EACX,UAAU,EACV,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,YAAY,EACZ,uBAAuB,EACvB,iBAAiB,EACjB,aAAa,EACb,uBAAuB,GACxB,MAAM,4BAA4B,CAAC"}

package/dist/ledger.js

@@ -1,9 +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.
+ * Session ledger — KV coordination with a durable inbox. The protocol
+ * library that drives the `session/`, `ledger/`, and `mailbox/` key
+ * families over a CAS-capable KV: identity creation, event append,
+ * lease claim/heartbeat/release, fenced commit, drain, the janitor
+ * loop, and the orphan sweep.
  */
-export { HEARTBEAT_INTERVAL_MS, LEASE_TTL_MS, LedgerCasExhaustedError, LedgerFencedError, SessionLedger, supportsSessionLedgerKv, } from "./ledger/session-ledger.js";
+export { createLedgerJanitor, DEFAULT_JANITOR_INTERVAL_MS, } from "./ledger/janitor.js";
+export { DEFAULT_ORPHAN_TTL_MS, HEARTBEAT_INTERVAL_MS, LEASE_TTL_MS, LedgerCasExhaustedError, LedgerFencedError, SessionLedger, supportsSessionLedgerKv, } from "./ledger/session-ledger.js";