@cursor/july 0.1.76 → 0.1.78

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

@@ -1,293 +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 type { HostKvCasApi, JsonValue } from "../types.js";
-export declare const LEASE_TTL_MS = 30000;
-export declare const HEARTBEAT_INTERVAL_MS = 10000;
-/** Unreferenced mailbox blobs older than this are sweepable. */
-export declare const DEFAULT_ORPHAN_TTL_MS: number;
-/**
- * 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 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, 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 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 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;
-}
-/** Drives the three ledger key families over a CAS-capable 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;
-    private mailboxKey;
-    private mailboxPrefix;
-    private emptyLedger;
-    /**
-     * 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.
-     */
-    ensureSession(continuationKey: string, init?: {
-        sdkSessionRef?: string | null;
-    }): Promise<EnsureSessionResult>;
-    /**
-     * 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: string, event: LedgerEventInput): Promise<{
-        appended: boolean;
-    }>;
-    /**
-     * 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.
-     */
-    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>;
-    /**
-     * 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: string): Promise<DrainResult>;
-    /**
-     * 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.
-     */
-    commit(sessionId: string, args: CommitArgs): Promise<CommitResult>;
-    /**
-     * 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: string, generation: number): Promise<{
-        released: boolean;
-    }>;
-    /** Parsed ledger value for one session, or `undefined` when never created. */
-    readLedger(sessionId: string): Promise<LedgerSnapshot | undefined>;
-    /**
-     * 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?: (key: string, error: unknown) => void): Promise<LedgerSnapshot[]>;
-    /**
-     * 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?: SweepOrphansArgs): Promise<SweepOrphansResult>;
-}
-//# sourceMappingURL=session-ledger.d.ts.map

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

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