@cursor/july 0.1.40 → 0.1.41

package/dist/kv/memory-kv.js

@@ -0,0 +1,103 @@
+/**
+ * In-memory {@link HostKvCasApi} — the test/dev implementation of the
+ * interface module (`@cursor/july/kv`), exported at
+ * `@cursor/july/kv/memory`.
+ *
+ * The memory KV *is* the dev shim: tests and local runs exercise the
+ * same CAS coordination paths that hosted serving uses, not a mock of an
+ * RPC. Values are deep-copied on both write and
+ * read so callers can never observe (or cause) shared-reference mutation.
+ */
+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());
+    });
+};
+/** Create an empty in-memory CAS-capable KV. */
+export function createMemoryKv() {
+    const entries = new Map();
+    let versionCounter = 0;
+    const nextVersion = () => {
+        versionCounter += 1;
+        return `v${versionCounter}`;
+    };
+    const snapshot = (key) => {
+        const entry = entries.get(key);
+        if (entry === undefined) {
+            return undefined;
+        }
+        return { value: structuredClone(entry.value), version: entry.version };
+    };
+    return {
+        get(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                return (_a = snapshot(key)) === null || _a === void 0 ? void 0 : _a.value;
+            });
+        },
+        put(key, value) {
+            return __awaiter(this, void 0, void 0, function* () {
+                entries.set(key, {
+                    value: structuredClone(value),
+                    version: nextVersion(),
+                });
+            });
+        },
+        delete(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                entries.delete(key);
+            });
+        },
+        getWithVersion(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return snapshot(key);
+            });
+        },
+        putIfAbsent(key, value) {
+            return __awaiter(this, void 0, void 0, function* () {
+                if (entries.has(key)) {
+                    return { ok: false, current: snapshot(key) };
+                }
+                const version = nextVersion();
+                entries.set(key, { value: structuredClone(value), version });
+                return { ok: true, version };
+            });
+        },
+        putIfVersion(key, value, expectedVersion) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const entry = entries.get(key);
+                if (entry === undefined || entry.version !== expectedVersion) {
+                    return { ok: false, current: snapshot(key) };
+                }
+                const version = nextVersion();
+                entries.set(key, { value: structuredClone(value), version });
+                return { ok: true, version };
+            });
+        },
+        listKeys(prefix) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return [...entries.keys()].filter((key) => key.startsWith(prefix)).sort();
+            });
+        },
+    };
+}
+/**
+ * In-memory `cas` group for `defineStorage` — a complete conditional-write
+ * group for sinks whose plain methods are inert or live elsewhere (test
+ * fixtures, an off-hosting no-op sink). Non-durable and process-local by
+ * construction; a real deployment backend should implement CAS against
+ * its own store instead.
+ */
+export function memoryCasTable() {
+    const kv = createMemoryKv();
+    return {
+        getWithVersion: (key) => kv.getWithVersion(key),
+        putIfAbsent: (key, value) => kv.putIfAbsent(key, value),
+        putIfVersion: (key, value, expectedVersion) => kv.putIfVersion(key, value, expectedVersion),
+        listKeys: (prefix) => kv.listKeys(prefix),
+    };
+}

package/dist/kv.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The CAS-capable KV **interface** — `@cursor/july/kv`.
+ *
+ * This module is implementation-free on purpose: it is the contract a
+ * bring-your-own KV implements so coordination protocols (conditional
+ * writes are the substrate for the upcoming session ledger) can run on
+ * it. {@link HostKvCasApi} is the conditional-write superset of the plain
+ * {@link HostKvApi}; {@link supportsKvCas} is the runtime probe for
+ * stores of unknown provenance — a `defineStorage` backend declares CAS
+ * through its `cas` group instead, so it never needs probing.
+ *
+ * Implementations live elsewhere:
+ *
+ * - `@cursor/july/kv/memory` — `createMemoryKv`, the test/dev shim.
+ * - The storage backends implement the same operations as the `cas`
+ *   group on `defineStorage` (see `StorageCasTable` in
+ *   `@cursor/july/storage`): `fileKv` (single-process) and
+ *   `cursorHostedStorage` (control-plane proxy). See `docs/storage.md`.
+ */
+export type { HostKvApi, HostKvCasApi, KvCasResult, KvVersionedEntry, } from "./types.js";
+export { supportsKvCas } from "./types.js";
+//# sourceMappingURL=kv.d.ts.map

package/dist/kv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.d.ts","sourceRoot":"","sources":["../src/kv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,YAAY,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/kv.js

@@ -0,0 +1,20 @@
+/**
+ * The CAS-capable KV **interface** — `@cursor/july/kv`.
+ *
+ * This module is implementation-free on purpose: it is the contract a
+ * bring-your-own KV implements so coordination protocols (conditional
+ * writes are the substrate for the upcoming session ledger) can run on
+ * it. {@link HostKvCasApi} is the conditional-write superset of the plain
+ * {@link HostKvApi}; {@link supportsKvCas} is the runtime probe for
+ * stores of unknown provenance — a `defineStorage` backend declares CAS
+ * through its `cas` group instead, so it never needs probing.
+ *
+ * Implementations live elsewhere:
+ *
+ * - `@cursor/july/kv/memory` — `createMemoryKv`, the test/dev shim.
+ * - The storage backends implement the same operations as the `cas`
+ *   group on `defineStorage` (see `StorageCasTable` in
+ *   `@cursor/july/storage`): `fileKv` (single-process) and
+ *   `cursorHostedStorage` (control-plane proxy). See `docs/storage.md`.
+ */
+export { supportsKvCas } from "./types.js";

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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"}