otto-intel-mcp 0.1.2 → 0.1.3

package/dist/execution-delegation-cap-store.d.ts

@@ -0,0 +1,369 @@
+/**
+ * execution-delegation-cap-store.ts — the durable, TRANSACTIONAL state machine behind a person's chosen
+ * per-swap cap (Founder word `delegate cap choice`, 2026-09-02; ROUND 5, after four codex NO-GOs).
+ *
+ * ══════════════════════════════════════════════════════════════════════════════════════════════════
+ * 🔴 THE THREAT MODEL THIS ENFORCES (Founder ruling, 2026-09-03, verbatim)
+ * ══════════════════════════════════════════════════════════════════════════════════════════════════
+ * "The per-person delegation cap protects every delegated send that goes through Otto's page
+ * (/app/delegate) and Otto's CLI (otto-execute delegate). A permission a person mints or revokes
+ * directly against Coinbase with their own login, outside Otto's page and CLI, is OUT OF SCOPE: Otto
+ * cannot distinguish it (CDP returns no grant identity, only an expiry) and does not defend against it;
+ * the CDP project-scope $5,000 ceiling remains the hard backstop for every permission. The delegated
+ * agent never holds the person's login."
+ *
+ * Everything below is built to be correct INSIDE that model. Where a defect is only reachable by a
+ * direct-to-Coinbase mint or revoke, the behaviour is stated rather than defended — and every one of
+ * those paths still fails CLOSED here (an unrecorded or unconfirmed grant authorises nothing at all),
+ * so the out-of-scope actor can shorten what Otto may do, never widen it.
+ *
+ * ══════════════════════════════════════════════════════════════════════════════════════════════════
+ * 🔴 WHY THE MACHINE, AND WHY IT IS SQLITE
+ * ══════════════════════════════════════════════════════════════════════════════════════════════════
+ * Round 3 made the expiry unique among ROWS and thought that was enough. The gate's two CRITICALs:
+ *
+ *   "The durable row still authenticates an expiry, not a grant. Enforcement requires only
+ *    (userId, grant.expiresAt); it does not require a successful confirmation, the reservation's
+ *    mintKey, or an active-grant pointer."
+ *   "Confirmation is not an enforcement gate. Reserve writes the complete enforceable capability;
+ *    confirm writes no state at all."
+ *
+ * Both are the same defect: a reserved row was a BEARER CAPABILITY keyed by an instant. Round 4 took the
+ * gate's own minimum safe model —
+ *
+ *      reserved ──confirm──▶ confirmed_active ──┬──▶ superseded   (a later confirm won)
+ *          │                                     ├──▶ revoked      (the person, or a mismatch)
+ *          └──10 min──▶ expired                  └──▶ (expiry passes)
+ *
+ * — and made ONE thing authoritative: `readActive`. A reserved row authorises NOTHING; the send gate
+ * reads the confirmed-active record and requires its expiry to equal the live grant's.
+ *
+ * Round 4 implemented that on filesystem primitives (`open(…,'wx')` + `rename()`), and round 4's gate
+ * retired them: *"`rename()` gives atomic visibility of one pointer, not durability or a multi-file
+ * transaction: there is no file/directory `fsync`, and confirmation performs three writes … There is
+ * also no confirm CAS/serialization. My concurrent-confirm probe returned both calls as `confirmed` and
+ * left both reservation files `confirmed_active`, although only one `active.json` won."* Its prescription
+ * was explicit: *"Use a transactional shared store with unique `(userId, expiry)` and `(userId, mintKey)`
+ * constraints, an active-grant CAS, and atomic confirm/revoke transitions. A database transaction is the
+ * simpler safe implementation."*
+ *
+ * So the primitives are now SQL, on one database file on the mounted Railway volume:
+ *
+ *   · `PRIMARY KEY (user_id, mint_key)` — the mint key is claimed exactly once. Idempotent reserve.
+ *   · `UNIQUE (user_id, expires_at_ms)` — the reservation instant is claimed exactly once, ACROSS
+ *     processes, by the database rather than by a directory entry.
+ *   · `CHECK (state IN …)` — a record can never hold a state this binary does not know.
+ *   · `active_grants` — ONE ROW PER USER, the only pointer enforcement reads, moved by a
+ *     COMPARE-AND-SWAP (`UPDATE … WHERE mint_key = <prior> AND expires_at_ms = <prior>`) inside the
+ *     same transaction that promotes the reservation.
+ *   · Every transition is a CONDITIONAL UPDATE whose `changes` count decides the winner
+ *     (`UPDATE … WHERE state = 'reserved'`), so a concurrent double confirm has exactly one winner and
+ *     the loser is told it was superseded — it is not a race that both sides win.
+ *   · `BEGIN IMMEDIATE` takes the write lock before the first read, so a reserve/confirm/revoke is
+ *     serialized against every other writer on the same file, in this process or another.
+ *   · `journal_mode = WAL`, `synchronous = FULL` — a committed transition survives a crash and a power
+ *     loss, which is the durability `rename()` did not give.
+ *
+ * ⚠️ THE PREMISE, STATED. One database file, reached by every worker: `numReplicas: 1` and one mounted
+ * volume. SQLite's locking is per file, so two volumes would be two independent stores — and two
+ * independent stores can each confirm a different cap for one person, which is the one shape that could
+ * widen a permission from inside the model. Nothing inside a process can check this; the deploy does
+ * (`railway.json`), and the staged first rollout below is what proves it before minting is even possible.
+ *
+ * ══════════════════════════════════════════════════════════════════════════════════════════════════
+ * 🔴 WHY `node:sqlite` AND NOT `better-sqlite3`
+ * ══════════════════════════════════════════════════════════════════════════════════════════════════
+ * `better-sqlite3` installs fine on this image (verified: a prebuilt linux-x64 / Node 22 binary, no
+ * compile). It is not a Railway problem. It is a PUBLISHED-PACKAGE problem: `otto-intel-mcp` ships to npm
+ * and is run as `npx otto-intel-mcp`, and `services/otto-execute` vendors it file-for-file at build time.
+ * A hard native dependency becomes a node-gyp source build wherever no prebuild matches the platform
+ * (musl/Alpine, a newer Node ABI, some ARM builds) and fails the install for every user of the CLI,
+ * including the majority who never touch delegation. `node:sqlite` is in the Node standard library at
+ * this package's own engine floor (`node >= 22`), needs no build step, and gives the identical
+ * primitives: `BEGIN IMMEDIATE` transactions, UNIQUE/CHECK constraints, conditional UPDATE with a
+ * `changes` count, WAL and `synchronous = FULL`.
+ *
+ * It is imported LAZILY and the failure is named: a runtime without `node:sqlite` opens an UNAVAILABLE
+ * store, and every delegated send then refuses by name rather than falling back to anything.
+ *
+ * 🔴 IT FAILS CLOSED, LOUDLY. No durable path configured, a database that cannot be opened, or a record
+ * that cannot be parsed means every delegated send refuses. An unreadable store is NOT an empty one, and
+ * the difference decides whether a person's cap is honoured.
+ *
+ * Nothing here logs a token, an address or a credential. A record is a user id, a mint key, two instants,
+ * a number, a version and a state.
+ */
+/** The explicit path override; otherwise the mounted Railway volume is used. */
+export declare const DELEGATION_CAP_STORE_PATH_ENV: "OTTO_DELEGATION_CAP_STORE_PATH";
+/** The database file inside that directory. The directory is kept so a legacy import can still read it. */
+export declare const CAP_STORE_DB_FILE: "caps.db";
+/**
+ * 🔴 THE STAGED-DEPLOY GATE (gate finding, CRITICAL 2 — the first rolling deployment).
+ *
+ * "The ruleset handshake cannot fence the first rolling deployment. The version refusal exists only in
+ * the new binary … status/reserve/confirm may hit a new worker while prepare/submit hits a still-serving
+ * old worker, which cannot interpret `requiredVersion` and executes anyway."
+ *
+ * The handshake cannot fix that, because the binary that must refuse is the one that has never heard of
+ * it. A DEPLOYMENT SEQUENCE can, and this flag is what makes the sequence possible:
+ *
+ *   1. deploy with `DELEGATION_MINT_ENABLED` unset or false — no new permission can be created at all,
+ *      so there is no cap-bearing grant for an old worker to execute at the ceiling;
+ *   2. confirm exactly one cap-aware worker is serving (`/health` reports `rulesetVersion`);
+ *   3. set the flag true and redeploy.
+ *
+ * DEFAULT FALSE IN CODE. An operator who forgets the variable gets the paused surface, never an
+ * unfenced first rollout. Sends under permissions that are ALREADY confirmed keep working under their
+ * own cap, and REVOKE always works — pausing the creation of authority must never pause its withdrawal.
+ */
+export declare const DELEGATION_MINT_ENABLED_ENV: "DELEGATION_MINT_ENABLED";
+/** True only for an explicit affirmative value. Absent, empty, or anything else is FALSE. */
+export declare function resolveDelegationMintEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** The one sentence every paused surface says. No security narration: it is an update, and it is short. */
+export declare const DELEGATION_MINT_PAUSED_MESSAGE: "Delegation is paused for a few minutes while we update it";
+/**
+ * The shape a mint key must have: what `createDelegation({ idempotencyKey })` accepts, bounded so it
+ * cannot be used as a path or a smuggling channel. A UUID satisfies it.
+ */
+export declare const MINT_KEY_PATTERN: RegExp;
+/** A CDP end-user id, as every schema on this surface bounds it. */
+export declare const END_USER_ID_PATTERN: RegExp;
+/**
+ * How far back the offset ladder may walk, in whole seconds, before it refuses.
+ *
+ * Five minutes of headroom on a grant measured in days: invisible to the reader, far more collisions
+ * than a real person can produce, and bounded so a corrupt or adversarially stuffed table cannot turn a
+ * request into one that never returns.
+ */
+export declare const CAP_EXPIRY_MAX_OFFSET_STEPS: 300;
+/**
+ * 🔴 A RESERVATION THAT IS NEVER CONFIRMED DIES (seat ruling, round 4). Ten minutes is long enough for a
+ * person to finish an OTP sign-in and a mint, and short enough that an abandoned reservation stops being
+ * something a later actor could try to confirm. Its SECOND stays taken — releasing it would let a
+ * different permission land on an instant this one may already have minted at.
+ */
+export declare const CAP_RESERVATION_WINDOW_MS: number;
+/**
+ * The version of the CAP RULESET this binary implements — distinct from the fence policy's version,
+ * which describes what Coinbase enforces.
+ *
+ * 🔴 WHY IT EXISTS (gate finding, HIGH — rolling deploy). "An older worker that accepts the same fence
+ * but lacks per-user cap enforcement can execute a new $10 permission up to the engine ceiling." The
+ * fence is identical on both binaries, so the fence cannot tell them apart. Every record carries the
+ * ruleset version it REQUIRES, a worker refuses a record it is too old to honour, and the page and the
+ * CLI refuse to reserve or mint against a server that reports a version below this one.
+ *
+ * 🔴 AND IT IS DEFENCE IN DEPTH, NOT THE FENCE FOR THE FIRST ROLLOUT — that is
+ * `DELEGATION_MINT_ENABLED` above, because a binary that predates the handshake cannot honour it.
+ */
+/** v2 (fence v2, 2026-09-03): a permission minted under v2 consents to Yield Copilot vault WITHDRAWS as well as swaps/deposits. */
+export declare const MODEL_B_CAP_RULESET_VERSION: 2;
+/** The lifecycle of one permission, as the gate prescribed it, plus the one state a MIGRATION writes. */
+export declare const CAP_RECORD_STATES: readonly ["reserved", "confirmed_active", "superseded", "revoked", "expired", "legacy"];
+export type CapRecordState = (typeof CAP_RECORD_STATES)[number];
+/** One durable record. A row in `reservations`; `active_grants` points at the live one. */
+export interface DelegationCapRecord {
+    readonly userId: string;
+    /** The `idempotencyKey` the permission is minted with. Names the reservation; authorises nothing. */
+    readonly mintKey: string;
+    /** The WHOLE-SECOND instant CDP will echo — the value every enforcement read compares against. */
+    readonly expiresAt: string;
+    /** What goes on the wire: the same second with milliseconds in 1..999, because CDP refuses `.000`. */
+    readonly requestedExpiresAt: string;
+    readonly perSwapCapUsd: number;
+    /** The cap-ruleset version a worker must implement to honour this record. */
+    readonly requiredVersion: number;
+    /**
+     * 🔴 THE REVOKE GENERATION THIS RESERVATION WAS MADE UNDER (gate finding, r4: "Add a durable revoke
+     * generation so Stop cancels already-reserved/in-flight mints without permanently poisoning later
+     * reservations"). Every Stop bumps the person's generation; a confirm whose reservation carries an
+     * older one is CANCELLED rather than promoted. That is how pressing Stop while a mint is in flight
+     * actually stops it — the old design read no grant yet, marked nothing, and the mint landed anyway.
+     *
+     * It poisons nothing: a reservation made AFTER the Stop carries the new generation and confirms
+     * normally, which is exactly what a per-user sticky marker could not do.
+     */
+    readonly revokeGeneration: number;
+    readonly state: CapRecordState;
+    readonly reservedAt: string;
+    readonly confirmedAt?: string;
+    readonly endedAt?: string;
+}
+export interface DelegationCapReservation {
+    readonly outcome: 'reserved' | 'already_reserved';
+    readonly record: DelegationCapRecord;
+}
+export type DelegationCapConfirm = {
+    readonly outcome: 'confirmed';
+    readonly record: DelegationCapRecord;
+}
+/** Already confirmed and still the live one: a retry after a lost response. */
+ | {
+    readonly outcome: 'already_confirmed';
+    readonly record: DelegationCapRecord;
+}
+/** Nothing was reserved for this mint key. */
+ | {
+    readonly outcome: 'unreserved';
+}
+/** The reservation exists but its ten minutes passed, or it was imported, or it was already ended. */
+ | {
+    readonly outcome: 'not_reservable';
+    readonly state: CapRecordState;
+}
+/** It WAS confirmed and a later confirmation replaced it — never revived. */
+ | {
+    readonly outcome: 'superseded';
+}
+/** The person pressed Stop while this permission was being created. Never promoted. */
+ | {
+    readonly outcome: 'cancelled';
+}
+/** The live grant's instant is not the reserved one. */
+ | {
+    readonly outcome: 'expiry_mismatch';
+    readonly record: DelegationCapRecord;
+};
+/** What one official Stop did, durably: the generation now in force and the record it took away. */
+export interface DelegationCapStop {
+    readonly generation: number;
+    /** The instant of the record this Stop moved to `revoked`; absent when nothing was confirmed-active. */
+    readonly revokedExpiresAt?: string;
+}
+export declare class DelegationCapExpiryUnavailableError extends Error {
+    constructor(steps: number);
+}
+export interface DelegationCapStore {
+    /** False when no durable path is configured, or the database could not be opened. Sends refuse while false. */
+    readonly available: boolean;
+    readonly unavailableReason?: string;
+    /**
+     * Reserve the first whole second at or BEFORE `latestExpiresAt` that no reservation for this user
+     * occupies, and record the cap against it. Idempotent per mint key. THROWS when the store cannot be
+     * written; `DelegationCapExpiryUnavailableError` when the ladder is exhausted.
+     */
+    reserve(userId: string, mintKey: string, latestExpiresAt: string, perSwapCapUsd: number, nowMs: number): Promise<DelegationCapReservation>;
+    /** The reservation this mint key holds, with its state as of `nowMs` (the window applied). */
+    readReservation(userId: string, mintKey: string, nowMs: number): Promise<DelegationCapRecord | undefined>;
+    /**
+     * `reserved → confirmed_active`, ONE-SHOT, in a single transaction that also supersedes whatever was
+     * confirmed-active for this user before. A concurrent second confirm loses the conditional UPDATE and
+     * is answered `superseded` or `already_confirmed` — never a second winner.
+     */
+    confirm(userId: string, mintKey: string, grantExpiresAt: string, nowMs: number): Promise<DelegationCapConfirm>;
+    /**
+     * 🔴 THE SEND GATE'S ONLY READ. The confirmed-active record for this user, or undefined. A reserved,
+     * superseded, revoked, expired or legacy record is NEVER returned here — that is what makes a
+     * reservation unable to authorise anything. THROWS when the store cannot be read.
+     */
+    readActive(userId: string, nowMs: number): Promise<DelegationCapRecord | undefined>;
+    /**
+     * Mark the confirmed-active record for this user REVOKED, but only when it is the grant at
+     * `expiresAt`. Per-grant by construction: a revoke aimed at a permission that is no longer the live
+     * one changes nothing, which is what stops a stale tab taking away a permission it never held.
+     *
+     * 🔴 THE REVOKED ROW STAYS, AND ITS SECOND STAYS CONSUMED. That is the "consumed-expiry state" the
+     * gate asked for: after a revoke, no later grant can be minted at that instant through Otto's page or
+     * CLI (the ladder skips it), and one minted there out-of-model matches no confirmed record, so it
+     * authorises nothing.
+     */
+    revoke(userId: string, expiresAt: string, nowMs: number): Promise<boolean>;
+    /**
+     * 🔴 STOP CANCELS WHAT IS ALREADY IN FLIGHT. Bump this person's revoke generation, so any reservation
+     * made before now can never be confirmed. It is not a poison: it is a monotonic counter, and the next
+     * reservation carries the new value. Returns the generation now in force.
+     *
+     * ⚠️ NOT THE OFFICIAL STOP. Every official revoke goes through `stop` below, which does this AND the
+     * record transition in ONE transaction. This stays on the interface for the one-shot cancel case a
+     * test drives directly; nothing in the admin path calls it on its own any more.
+     */
+    bumpRevokeGeneration(userId: string, nowMs: number): Promise<number>;
+    /**
+     * ══════════════════════════════════════════════════════════════════════════════════════════════
+     * 🔴 THE OFFICIAL STOP — ONE TRANSACTION, TWO WRITES, NEVER ONE WITHOUT THE OTHER (gate r5 CRITICAL)
+     * ══════════════════════════════════════════════════════════════════════════════════════════════
+     * "`revokeDelegation` commits the generation bump and then performs the active-record revoke in a
+     *  separate transaction … The process dies or stalls before `capStore.revoke()` … A fresh worker still
+     *  reads the old record as `confirmed_active`; the unchanged live grant matches and a send remains
+     *  admissible."
+     *
+     * So the Stop is one `BEGIN IMMEDIATE` transaction that (1) bumps the revoke generation — cancelling
+     * every reservation taken before now, including a mint already in flight with no grant to find yet —
+     * and (2) moves whatever record is confirmed-active for this person to `revoked`. A crash between the
+     * two is a crash INSIDE the transaction: nothing is committed, the caller is told to retry, and nothing
+     * is revoked at Coinbase either. The revoked row survives and holds its second (the consumed expiry).
+     *
+     * It takes NO expiry, deliberately. A Stop means "Otto acts under nothing for me": the record that is
+     * live goes, whatever tab pressed the button and whatever grant Coinbase happens to hold — exactly what
+     * the CDP-side revoke that follows it does. `revoke` above stays per grant for the mismatch path, where
+     * the thing being taken away IS one specific grant.
+     *
+     * Answers the generation now in force and the instant of the record it revoked, if any.
+     */
+    stop(userId: string, nowMs: number): Promise<DelegationCapStop>;
+    /** Release the database handle. Present on the real store; tests call it, production never needs to. */
+    close?(): void;
+}
+export declare function resolveDelegationCapStorePath(env?: NodeJS.ProcessEnv): string | null;
+/** The instant `ms` floored to a whole second — the only granularity CDP preserves. */
+export declare function wholeSecondMs(ms: number): number;
+/**
+ * The value that goes ON THE WIRE for a reserved second.
+ *
+ * 🔴 CDP REFUSES a `.000` fraction — 401 `unauthorized` "Wallet authentication error", a code that says
+ * nothing about the cause (isolated live on one session, 2026-09-02: `.000Z` refused, `.137Z` accepted
+ * on the very next call, `.000Z` refused again). And it TRUNCATES the fraction when it stores the grant
+ * (`…:46.001Z` → `…:46Z`, `…:45.999Z` → `…:45Z`), so any millisecond in 1..999 lands on the reserved
+ * second and none of them lengthens the permission.
+ */
+export declare const MINT_EXPIRY_FILLER_MS: 1;
+export declare function mintExpiryForSecond(wholeSecondIso: string): string;
+/**
+ * The offset ladder as a pure function: the first whole second at or BEFORE `latestMs` that `taken`
+ * does not hold and that is still in the future, or undefined. It NEVER returns anything later than
+ * `latestMs` — a permission must not outlive the duration the person chose, not even by a second.
+ */
+export declare function firstFreeExpiryMs(latestMs: number, nowMs: number, taken: (candidateMs: number) => boolean, maxSteps?: number): number | undefined;
+/** A record's state as of `nowMs`: a reservation whose window has passed reads as `expired`. */
+export declare function stateAsOf(record: DelegationCapRecord, nowMs: number): CapRecordState;
+/**
+ * The two pragmas the durability claim rests on, read back FROM THE CONNECTION THAT SET THEM.
+ *
+ * 🔴 `synchronous` IS PER CONNECTION. A test that opens its own handle to the same file always reads the
+ * default, so an assertion made that way passes whatever this store did — the mutation that dropped
+ * `synchronous` to OFF survived exactly one run because of it. `journal_mode` is persisted in the file;
+ * this one is not, so the store has to say what it applied.
+ */
+export interface AppliedPragmas {
+    readonly journalMode: string;
+    readonly synchronous: number;
+}
+/**
+ * Everything a pre-SQLite store left in `root`: the round-1/2 append-only JSONL, and the round-4
+ * per-instant JSON files under `u/<userId>/r/`. Read best-effort — a migration that THREW on an
+ * unreadable leftover would stop the store opening at all, and the leftovers authorise nothing either
+ * way.
+ */
+export declare function readLegacyCapRecords(root: string): Promise<DelegationCapRecord[]>;
+/** A store that is present but permanently unavailable — what an unconfigured deploy gets. */
+export declare function unavailableDelegationCapStore(reason: string): DelegationCapStore;
+/**
+ * Open the SQLite store at `root`, importing anything a pre-SQLite store left behind as `legacy`.
+ * Exported so a test can open one on a temp directory without going through the environment.
+ */
+export declare function openDelegationCapStore(root: string): Promise<DelegationCapStore>;
+/**
+ * The store for this process, from the environment. Unconfigured is NOT a silent in-memory fallback: it
+ * is an unavailable store, so the delegated send refuses by name and the ops fix (mount the volume, or
+ * set `OTTO_DELEGATION_CAP_STORE_PATH`) is the thing the refusal asks for.
+ */
+export declare function createDelegationCapStore(env?: NodeJS.ProcessEnv): Promise<DelegationCapStore>;
+/**
+ * An in-memory store — for TESTS and for a local stdio run, where nothing is durable anyway.
+ *
+ * 🔴 IT IMPLEMENTS THE SAME STATE MACHINE, and the suite runs the SAME conformance cases against both,
+ * so a test cannot pass against semantics production does not have. What it cannot model is the
+ * cross-process exclusion and the crash durability SQLite provides — those are asserted against a real
+ * database file, and against two real processes, only.
+ */
+export declare function inMemoryDelegationCapStore(seed?: readonly DelegationCapRecord[]): DelegationCapStore;