@visa/cli 4.1.0-rc.3 → 4.1.0-rc.31

package/dist/checkout-engine/live-fill-approval.d.ts

@@ -0,0 +1,43 @@
+import type { CheckoutMode, CheckoutOutcome, CheckoutResult } from './executor.js';
+export declare const SUBMIT_ENV_FLAG = "CHECKOUT_AGENT_ALLOW_SUBMIT";
+export declare const MODE_ENV_FLAG = "CHECKOUT_AGENT_MODE";
+/**
+ * `--mode` values map 1:1 onto CheckoutMode; an absent flag falls back to the
+ * CHECKOUT_AGENT_MODE environment default, then to the safe dry-run default.
+ */
+export declare function parseCheckoutMode(value: string | undefined, env?: Record<string, string | undefined>): CheckoutMode;
+/**
+ * Fail fast (before any file read or browser launch) when submit lacks an
+ * enablement. The env arm exists to stop AUTOMATION from reaching a live
+ * charge by accident — so it is required only when stdin is not a real TTY
+ * (scripts, agents, pipes). An interactive human needs no standing config:
+ * their per-run consent is the typed PAY phrase plus the passkey tap, both of
+ * which a non-interactive caller cannot fake (the phrase names the exact
+ * review id; the passkey is a FIDO ceremony on the verify site).
+ */
+export declare function assertSubmitAllowed(mode: CheckoutMode, env?: Record<string, string | undefined>, isInteractive?: boolean): void;
+/** Distinct phrases per mode so dry-run muscle memory can never authorize a payment. */
+export declare function approvalPhrase(mode: CheckoutMode, reviewId: string): string;
+/** Integer-only minor→display formatting (two-decimal currencies, the same assumption as decimalToMinor). */
+export declare function formatAmountMinor(amountMinor: number, currency: string): string;
+/** The operator question. In submit mode it names the exact charge — amount and merchant. */
+export declare function approvalQuestion(mode: CheckoutMode, review: {
+    merchantHost: string;
+    amountMinor: number;
+    currency: string;
+}, phrase: string): string;
+/** The one outcome each mode may exit 0 with. */
+export declare function isRunSuccess(mode: CheckoutMode, outcome: CheckoutOutcome): boolean;
+/**
+ * True when the pay control was actually clicked but the run ended with an
+ * UNKNOWN outcome — neither 'confirmed' nor 'declined' (e.g. a slow redirect
+ * or confirmation copy the heuristics don't recognize). The charge may still
+ * have gone through; the operator must verify with the merchant before any
+ * retry, because a blind rerun risks a double charge. A 'declined' outcome is
+ * a definitive negative from the merchant, so it does not warn. Neither does
+ * 'action-required': a 3-D Secure challenge intercepts BEFORE authorization,
+ * so no charge can exist until it is completed — the double-charge warning
+ * would misdirect the operator, and the runner prints the challenge-specific
+ * notice instead.
+ */
+export declare function submitClickedWithoutConfirmation(result: CheckoutResult): boolean;

package/dist/checkout-engine/live-fill-approval.js

@@ -0,0 +1,90 @@
+// Deliberate-enablement seam for run-live-fill's submit mode. A real submit
+// moves real money, so it requires:
+//   1. an interactive human at a real TTY — or, for scripted/agent runs,
+//      the explicit CHECKOUT_AGENT_ALLOW_SUBMIT=1 environment arm,
+//   2. the invocation opts in (--mode submit, or the CHECKOUT_AGENT_MODE
+//      environment default for operators who always run one mode),
+//   3. the operator types the PAY phrase against the exact review id (and a
+//      hosted run additionally requires the passkey tap on the verify site).
+// The env arm is an anti-automation gate, not a human ritual: a TTY human's
+// consent is act 3 — the PAY phrase differs from dry-run's FILL phrase, so a
+// muscle-memory rerun of the dry-run procedure still cannot drift into
+// charging a card — while a non-interactive caller (script, agent, pipe) can
+// fake neither the phrase's review id nor the FIDO ceremony and must also be
+// explicitly armed. Fresh checkouts therefore need ZERO persisted config.
+export const SUBMIT_ENV_FLAG = 'CHECKOUT_AGENT_ALLOW_SUBMIT';
+export const MODE_ENV_FLAG = 'CHECKOUT_AGENT_MODE';
+/**
+ * `--mode` values map 1:1 onto CheckoutMode; an absent flag falls back to the
+ * CHECKOUT_AGENT_MODE environment default, then to the safe dry-run default.
+ */
+export function parseCheckoutMode(value, env = process.env) {
+    const effective = value ?? env[MODE_ENV_FLAG];
+    if (effective === undefined || effective === 'dry-run')
+        return 'dry-run';
+    if (effective === 'submit')
+        return 'submit';
+    throw new Error(`--mode (or ${MODE_ENV_FLAG}) must be dry-run or submit (got ${JSON.stringify(effective)})`);
+}
+/**
+ * Fail fast (before any file read or browser launch) when submit lacks an
+ * enablement. The env arm exists to stop AUTOMATION from reaching a live
+ * charge by accident — so it is required only when stdin is not a real TTY
+ * (scripts, agents, pipes). An interactive human needs no standing config:
+ * their per-run consent is the typed PAY phrase plus the passkey tap, both of
+ * which a non-interactive caller cannot fake (the phrase names the exact
+ * review id; the passkey is a FIDO ceremony on the verify site).
+ */
+export function assertSubmitAllowed(mode, env = process.env, isInteractive = process.stdin.isTTY === true) {
+    if (mode !== 'submit')
+        return;
+    if (env[SUBMIT_ENV_FLAG] === '1')
+        return;
+    if (isInteractive)
+        return;
+    throw new Error(`--mode submit refused: this is not an interactive terminal, and scripted submits ` +
+        `require ${SUBMIT_ENV_FLAG}=1. The gate is default-off so automation cannot ` +
+        'reach a live charge by accident.');
+}
+/** Distinct phrases per mode so dry-run muscle memory can never authorize a payment. */
+export function approvalPhrase(mode, reviewId) {
+    return `${mode === 'submit' ? 'PAY' : 'FILL'} ${reviewId}`;
+}
+/** Integer-only minor→display formatting (two-decimal currencies, the same assumption as decimalToMinor). */
+export function formatAmountMinor(amountMinor, currency) {
+    return `${Math.floor(amountMinor / 100)}.${String(amountMinor % 100).padStart(2, '0')} ${currency}`;
+}
+/** The operator question. In submit mode it names the exact charge — amount and merchant. */
+export function approvalQuestion(mode, review, phrase) {
+    if (mode === 'submit') {
+        return (`Inspect the visible checkout. This WILL charge ` +
+            `${formatAmountMinor(review.amountMinor, review.currency)} at ${review.merchantHost}. ` +
+            `Type ${JSON.stringify(phrase)} to disclose the credential AND submit the order: `);
+    }
+    return (`Inspect the visible checkout. Type ${JSON.stringify(phrase)} ` +
+        `to disclose the credential to this page without submitting: `);
+}
+/** The one outcome each mode may exit 0 with. */
+export function isRunSuccess(mode, outcome) {
+    return outcome === (mode === 'submit' ? 'confirmed' : 'filled-dry-run');
+}
+/**
+ * True when the pay control was actually clicked but the run ended with an
+ * UNKNOWN outcome — neither 'confirmed' nor 'declined' (e.g. a slow redirect
+ * or confirmation copy the heuristics don't recognize). The charge may still
+ * have gone through; the operator must verify with the merchant before any
+ * retry, because a blind rerun risks a double charge. A 'declined' outcome is
+ * a definitive negative from the merchant, so it does not warn. Neither does
+ * 'action-required': a 3-D Secure challenge intercepts BEFORE authorization,
+ * so no charge can exist until it is completed — the double-charge warning
+ * would misdirect the operator, and the runner prints the challenge-specific
+ * notice instead.
+ */
+export function submitClickedWithoutConfirmation(result) {
+    if (result.outcome === 'confirmed' ||
+        result.outcome === 'declined' ||
+        result.outcome === 'action-required') {
+        return false;
+    }
+    return result.evidence.getSteps().some((s) => s.type === 'submit' && s.data.clicked === true);
+}

package/dist/checkout-engine/mandate/card-mandate.d.ts

@@ -0,0 +1,117 @@
+import { type VgsCheckoutTarget, type VgsPaymentCredential } from '../vgs-live-instrument.js';
+import { MandateLedger } from './mandate-ledger.js';
+/**
+ * Default number of draws a ceiling intent may fulfil (VGS mandate quantity).
+ * This is a purchase-COUNT cap, NOT the exposure bound: VGS enforces the
+ * declineThreshold as a CUMULATIVE cap across draws (live-verified 2026-07-23),
+ * so the total the network will authorize is the ceiling REGARDLESS of how many
+ * draws it is spread across — maxDraws only limits the number of separate
+ * purchases, it does not multiply the exposure. Kept SMALL as a sensible default
+ * purchase count (the owner-side client ledger also caps cumulative spend at ONE
+ * ceiling). This is the single default; callers that don't set maxDraws inherit
+ * it (do not re-duplicate it upstream).
+ */
+export declare const DEFAULT_MANDATE_MAX_DRAWS = 3;
+export type CardMandateMerchant = {
+    name: string;
+    url: string;
+    countryCode: string;
+};
+export type CreateCardMandateInput = {
+    tokenId: string;
+    assuranceData: unknown;
+    ceilingMinor: number;
+    merchant: CardMandateMerchant;
+    currencyCode: string;
+    expiresAt: string;
+    /** Max draws the ceiling intent may fulfil; defaults to DEFAULT_MANDATE_MAX_DRAWS. */
+    maxDraws?: number;
+    /** BUDGET mandate — spendable at any merchant (see CardMandateRecord.crossMerchant). */
+    crossMerchant?: boolean;
+};
+export type CreateIntentFn = (input: {
+    tokenId: string;
+    assuranceData: unknown;
+    transaction: VgsCheckoutTarget;
+    mandate: {
+        declineThresholdAmount: string;
+        quantity: number;
+        effectiveUntil: string;
+        consumerPrompt: string;
+    };
+}) => Promise<{
+    intentId: string;
+    status: string | null;
+}>;
+export type CreateCardMandateDeps = {
+    /** Mint the ceiling intent — wire serverCreateIntent(base, mintToken, …). */
+    createIntent: CreateIntentFn;
+    ledger: MandateLedger;
+    /** verify-web origin the intent is minted against (persisted for later draws). */
+    approvalBaseUrl: string;
+    /** Scoped mint token to persist for tap-free draws. */
+    mintToken?: string;
+    now?: () => Date;
+};
+export type CardMandateFacts = {
+    mandateId: string;
+    ceilingMinor: number;
+    remainingMinor: number;
+    currencyCode: string;
+    merchant: CardMandateMerchant;
+    expiresAt: string;
+};
+/**
+ * Create a card mandate: approve a spend CEILING once (the passkey assurance
+ * passed here was scoped to the ceiling + merchant), mint one VGS intent with
+ * that ceiling as its decline threshold, and record the cumulative-budget
+ * ledger entry. Integer minor units only.
+ */
+export declare function createCardMandate(input: CreateCardMandateInput, deps: CreateCardMandateDeps): Promise<CardMandateFacts>;
+export type FetchCryptogramFn = (input: {
+    tokenId: string;
+    intentId: string;
+    transaction: VgsCheckoutTarget;
+}) => Promise<VgsPaymentCredential>;
+export type DrawFromMandateInput = {
+    mandateId: string;
+    amountMinor: number;
+    /** The exact per-draw checkout target (merchant + amount + currency). */
+    transaction: VgsCheckoutTarget;
+};
+export type DrawFromMandateDeps = {
+    /** Draw a cryptogram against the mandate intent — wire serverFetchCryptogram. */
+    fetchCryptogram: FetchCryptogramFn;
+    ledger: MandateLedger;
+    /** Override the payable-credential gate (default validateCredential). */
+    validate?: (credential: VgsPaymentCredential) => void;
+    now?: () => Date;
+};
+export type DrawResult = {
+    payment: VgsPaymentCredential;
+    intentId: string;
+    remainingMinor: number;
+};
+/**
+ * Thrown ONLY for the post-reservation network/validation rejection class — the
+ * cryptogram fetch failed or returned a non-payable credential (the DRAW_REMEDY
+ * path). This is the sole draw failure that should DISABLE the mandate: it means
+ * the acquirer would not honor a ceiling-scoped assurance for a sub-amount draw.
+ *
+ * Pre-network failures — a fail-closed `reserve()` (concurrent over-budget race
+ * or expiry) or a `commit()` file-I/O error — throw a plain Error instead, so
+ * the caller (cli-engine) can rethrow them WITHOUT marking a HEALTHY mandate
+ * unhonored. Discriminating on this type is what keeps a transient race from
+ * permanently disabling a good mandate (michaelyang1 M1).
+ */
+export declare class MandateDrawDeclinedError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Draw a cryptogram against an existing card mandate with NO fresh tap. The
+ * reservation is atomic and the budget is decremented ONLY after a payable
+ * cryptogram returns; any rejection releases the reservation so remaining is
+ * unchanged. Validates merchant + currency + amount against the mandate first.
+ */
+export declare function drawFromMandate(input: DrawFromMandateInput, deps: DrawFromMandateDeps): Promise<DrawResult>;

package/dist/checkout-engine/mandate/card-mandate.js

@@ -0,0 +1,221 @@
+// Card mandate (budget) layer — the split the north-star card flow needs:
+//
+//   BUDGET  = start_card_mandate: approve a CEILING once with the passkey. This
+//             mints ONE VGS intent whose decline threshold is the ceiling (not
+//             amount+10) and whose quantity permits many draws. The passkey
+//             assurance is scoped to the ceiling + merchant, not one charge.
+//   DRAW    = pay_merchant (tap-free): pull a cryptogram against that intent for
+//             an in-budget purchase, WITHOUT a fresh tap, and decrement the
+//             cumulative budget in the owner-only ledger.
+//
+// This mirrors x402's start_session -> wallet_pay shape on the card rail.
+//
+// PROVEN (live probe 2026-07-23): VGS honors a ceiling-scoped assurance across
+// multiple sub-amount cryptogram draws against one intent, AND enforces the
+// decline threshold as a CUMULATIVE cap — draws summing to the ceiling are
+// payable, the next draw over the cumulative ceiling is declined. So the total
+// the network authorizes is the ceiling, not maxDraws × ceiling. drawFromMandate
+// stays FAIL-CLEAN as defense-in-depth: the budget is decremented only after a
+// payable cryptogram returns; a network rejection leaves the budget untouched.
+// The caller (cli-engine) then marks the mandate unhonored so the NEXT
+// pay_merchant skips it and takes a fresh per-purchase tap — the same call is
+// not retried in-flight. Never fail-open.
+import { decimalToMinor, minorToDecimal, validateCredential, } from '../vgs-live-instrument.js';
+import { CARD_MANDATE_LEDGER_VERSION, remainingMinor, } from './mandate-ledger.js';
+/**
+ * Default number of draws a ceiling intent may fulfil (VGS mandate quantity).
+ * This is a purchase-COUNT cap, NOT the exposure bound: VGS enforces the
+ * declineThreshold as a CUMULATIVE cap across draws (live-verified 2026-07-23),
+ * so the total the network will authorize is the ceiling REGARDLESS of how many
+ * draws it is spread across — maxDraws only limits the number of separate
+ * purchases, it does not multiply the exposure. Kept SMALL as a sensible default
+ * purchase count (the owner-side client ledger also caps cumulative spend at ONE
+ * ceiling). This is the single default; callers that don't set maxDraws inherit
+ * it (do not re-duplicate it upstream).
+ */
+export const DEFAULT_MANDATE_MAX_DRAWS = 3;
+function assertPositiveInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`${label} must be a positive integer (minor units)`);
+    }
+}
+function merchantHost(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        throw new Error(`mandate merchant URL is invalid: ${url}`);
+    }
+}
+/**
+ * Create a card mandate: approve a spend CEILING once (the passkey assurance
+ * passed here was scoped to the ceiling + merchant), mint one VGS intent with
+ * that ceiling as its decline threshold, and record the cumulative-budget
+ * ledger entry. Integer minor units only.
+ */
+export async function createCardMandate(input, deps) {
+    assertPositiveInteger(input.ceilingMinor, 'mandate ceiling');
+    const currencyCode = String(input.currencyCode).toUpperCase();
+    if (!/^[A-Z]{3}$/.test(currencyCode)) {
+        throw new Error('mandate currency must be a 3-letter ISO 4217 code');
+    }
+    if (!input.tokenId?.trim())
+        throw new Error('mandate requires a tokenId');
+    const now = (deps.now ?? (() => new Date()))();
+    const expiryMs = Date.parse(input.expiresAt);
+    if (!Number.isFinite(expiryMs))
+        throw new Error('mandate expiresAt must be ISO 8601');
+    if (expiryMs <= now.getTime())
+        throw new Error('mandate expiresAt is already in the past');
+    const host = merchantHost(input.merchant.url);
+    const maxDraws = input.maxDraws ?? DEFAULT_MANDATE_MAX_DRAWS;
+    if (!Number.isSafeInteger(maxDraws) || maxDraws < 1) {
+        throw new Error('mandate maxDraws must be a positive integer');
+    }
+    // Pass the currency so a non-2-decimal currency is REFUSED here rather than
+    // silently rendered with a wrong wire amount (minorToDecimal assumes /100).
+    const ceilingDecimal = minorToDecimal(input.ceilingMinor, currencyCode);
+    // The passkey prompt must state the REAL grant. VGS enforces the
+    // declineThreshold as a CUMULATIVE cap across draws (live-verified 2026-07-23),
+    // so the total this single approval can authorize is the CEILING — not
+    // maxDraws × ceiling. maxDraws only caps how many separate purchases the intent
+    // may fulfil. The prompt therefore names the ceiling as the total and maxDraws
+    // as the purchase-count limit (H1: consent must match the true grant).
+    // The intent transaction is scoped to the CEILING itself: the decline
+    // threshold IS the ceiling (not the historical ceil(amount)+10), and quantity
+    // permits multiple draws.
+    const ceilingTarget = {
+        merchantName: input.merchant.name,
+        merchantUrl: input.merchant.url,
+        merchantCountryCode: input.merchant.countryCode.toUpperCase(),
+        transactionAmount: ceilingDecimal,
+        transactionCurrencyCode: currencyCode,
+    };
+    const { intentId } = await deps.createIntent({
+        tokenId: input.tokenId,
+        assuranceData: input.assuranceData,
+        transaction: ceilingTarget,
+        mandate: {
+            declineThresholdAmount: ceilingDecimal,
+            quantity: maxDraws,
+            effectiveUntil: new Date(expiryMs).toISOString(),
+            consumerPrompt: `Approve up to ${ceilingDecimal} ${currencyCode} total (across up to ` +
+                `${maxDraws} purchase${maxDraws === 1 ? '' : 's'}) at ${input.merchant.name} ` +
+                `for my Visa agent`,
+        },
+    });
+    if (!intentId?.trim())
+        throw new Error('mandate intent creation returned no intentId');
+    const record = {
+        version: CARD_MANDATE_LEDGER_VERSION,
+        mandateId: intentId,
+        tokenId: input.tokenId,
+        ceilingMinor: input.ceilingMinor,
+        spentMinor: 0,
+        reservations: [],
+        currencyCode,
+        merchantName: input.merchant.name,
+        merchantUrl: input.merchant.url,
+        merchantHost: host,
+        merchantCountryCode: input.merchant.countryCode.toUpperCase(),
+        approvalBaseUrl: deps.approvalBaseUrl,
+        ...(deps.mintToken ? { mintToken: deps.mintToken } : {}),
+        expiresAt: new Date(expiryMs).toISOString(),
+        createdAt: now.toISOString(),
+        draws: [],
+        ...(input.crossMerchant ? { crossMerchant: true } : {}),
+    };
+    await deps.ledger.create(record);
+    return {
+        mandateId: record.mandateId,
+        ceilingMinor: record.ceilingMinor,
+        remainingMinor: remainingMinor(record),
+        currencyCode,
+        merchant: input.merchant,
+        expiresAt: record.expiresAt,
+    };
+}
+const DRAW_REMEDY = 'the card-mandate draw did not complete — a ceiling-scoped assurance may not be honored ' +
+    'for this sub-amount draw. The budget is untouched. If this was a transient network error ' +
+    '(gateway 5xx / try again), retry — the mandate stays active; a persistent decline disables ' +
+    'the mandate and your next pay_merchant uses a fresh per-purchase tap';
+/**
+ * Thrown ONLY for the post-reservation network/validation rejection class — the
+ * cryptogram fetch failed or returned a non-payable credential (the DRAW_REMEDY
+ * path). This is the sole draw failure that should DISABLE the mandate: it means
+ * the acquirer would not honor a ceiling-scoped assurance for a sub-amount draw.
+ *
+ * Pre-network failures — a fail-closed `reserve()` (concurrent over-budget race
+ * or expiry) or a `commit()` file-I/O error — throw a plain Error instead, so
+ * the caller (cli-engine) can rethrow them WITHOUT marking a HEALTHY mandate
+ * unhonored. Discriminating on this type is what keeps a transient race from
+ * permanently disabling a good mandate (michaelyang1 M1).
+ */
+export class MandateDrawDeclinedError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = 'MandateDrawDeclinedError';
+        this.cause = cause;
+    }
+}
+/**
+ * Draw a cryptogram against an existing card mandate with NO fresh tap. The
+ * reservation is atomic and the budget is decremented ONLY after a payable
+ * cryptogram returns; any rejection releases the reservation so remaining is
+ * unchanged. Validates merchant + currency + amount against the mandate first.
+ */
+export async function drawFromMandate(input, deps) {
+    assertPositiveInteger(input.amountMinor, 'draw amount');
+    const validate = deps.validate ?? validateCredential;
+    const now = (deps.now ?? (() => new Date()))();
+    const record = await deps.ledger.get(input.mandateId);
+    if (!record)
+        throw new Error(`no such mandate ${input.mandateId}`);
+    // The wire amount and the accounting amount MUST agree — a mismatch would
+    // draw one figure while reserving another. Fail before any reservation.
+    const wireMinor = decimalToMinor(input.transaction.transactionAmount);
+    if (wireMinor === null || wireMinor !== input.amountMinor) {
+        throw new Error(`draw amount ${input.amountMinor} disagrees with transaction amount ` +
+            `${JSON.stringify(input.transaction.transactionAmount)} (minor units)`);
+    }
+    // Currency must always match; merchant must match UNLESS this is a budget
+    // (crossMerchant) mandate the owner approved for any merchant. The network
+    // honors a ceiling-scoped cryptogram cross-merchant, so a budget mandate is
+    // deliberately not host-restricted — the ceiling + per-transaction limit still
+    // bound it.
+    const targetHost = merchantHost(input.transaction.merchantUrl);
+    if (!record.crossMerchant && targetHost !== record.merchantHost) {
+        throw new Error(`draw merchant ${targetHost} does not match mandate merchant ${record.merchantHost}`);
+    }
+    if (String(input.transaction.transactionCurrencyCode).toUpperCase() !==
+        record.currencyCode.toUpperCase()) {
+        throw new Error(`draw currency ${input.transaction.transactionCurrencyCode} does not match mandate ` +
+            `currency ${record.currencyCode}`);
+    }
+    // Atomic reserve — throws (fail-closed) if expired or over remaining budget.
+    const reservationId = await deps.ledger.reserve(input.mandateId, input.amountMinor, now);
+    let payment;
+    try {
+        payment = await deps.fetchCryptogram({
+            tokenId: record.tokenId,
+            intentId: record.mandateId,
+            transaction: input.transaction,
+        });
+        // A 2xx that is not actually a payable DAVV must NOT decrement the budget.
+        validate(payment);
+    }
+    catch (err) {
+        await deps.ledger.release(input.mandateId, reservationId, now);
+        // Typed so the caller disables the mandate ONLY for this post-reservation
+        // network/validation decline — never for a pre-network reserve()/commit()
+        // failure, which throws a plain Error above/below this try.
+        throw new MandateDrawDeclinedError(`${DRAW_REMEDY}: ${err.message}`, err);
+    }
+    const committed = await deps.ledger.commit(input.mandateId, reservationId, { intentId: record.mandateId }, now);
+    return {
+        payment,
+        intentId: record.mandateId,
+        remainingMinor: remainingMinor(committed),
+    };
+}

package/dist/checkout-engine/mandate/mandate-ledger.d.ts

@@ -0,0 +1,135 @@
+export declare const CARD_MANDATE_LEDGER_VERSION: 1;
+export type CardMandateReservation = {
+    reservationId: string;
+    amountMinor: number;
+    reservedAt: string;
+};
+export type CardMandateDraw = {
+    drawId: string;
+    reservationId: string;
+    amountMinor: number;
+    intentId: string;
+    status: 'committed' | 'released';
+    at: string;
+};
+export type CardMandateRecord = {
+    version: typeof CARD_MANDATE_LEDGER_VERSION;
+    /** == the VGS intentId the ceiling approval created. */
+    mandateId: string;
+    tokenId: string;
+    ceilingMinor: number;
+    /** Permanently committed (drawn) spend, integer minor units. */
+    spentMinor: number;
+    /** In-flight reservations (reserved but not yet committed/released). */
+    reservations: CardMandateReservation[];
+    currencyCode: string;
+    merchantName: string;
+    merchantUrl: string;
+    merchantHost: string;
+    merchantCountryCode: string;
+    /** verify-web origin the ceiling intent was minted against. */
+    approvalBaseUrl: string;
+    /**
+     * Scoped mint token released by the ceiling approval, reused to draw
+     * cryptograms tap-free. Owner-only (0600) like the rest of the file; whether
+     * it stays valid across multiple draws is part of the unproven spike.
+     */
+    mintToken?: string;
+    expiresAt: string;
+    createdAt: string;
+    draws: CardMandateDraw[];
+    /**
+     * Set when the network DECLINED a tap-free draw against this mandate (a
+     * ceiling-scoped assurance the acquirer would not honor for a sub-amount
+     * draw). Distinct from a reservation `status`: it disables the whole mandate.
+     * Once set, findCovering() SKIPS this mandate so the caller's next
+     * pay_merchant falls through to a fresh per-purchase tap instead of
+     * re-selecting the same failing mandate forever. ISO 8601.
+     */
+    unhonoredAt?: string;
+    /**
+     * Set when the delegated-draw register handshake FAILED at mandate-start (the
+     * server-side `card_mandate_spend` row was never created), so a later
+     * delegated (verdict-signed) draw would 404 `no_mandate`. Like `unhonoredAt`,
+     * findCovering() SKIPS a register-failed mandate so the next checkout falls
+     * through to a fresh per-purchase tap instead of surfacing a confusing
+     * `no_mandate`. Only set when a delegated binding was present and register was
+     * attempted; a bare bearer mandate (no binding) never carries it. ISO 8601.
+     */
+    registerFailedAt?: string;
+    /**
+     * A BUDGET mandate: spendable at ANY merchant, not scoped to `merchantHost`.
+     * The card network honors a ceiling-scoped cryptogram cross-merchant (the
+     * mandate's merchant is only an advisory hint on the intent), so this is a
+     * deliberate product mode — the owner approved a spend budget usable anywhere,
+     * bounded by the same ceiling + per-transaction limit. When set, findCovering
+     * matches this mandate for any merchant and drawFromMandate skips the
+     * merchant-match guard. Absent/false = the default merchant-scoped mandate.
+     */
+    crossMerchant?: boolean;
+};
+export type CardMandateLedgerFile = {
+    version: typeof CARD_MANDATE_LEDGER_VERSION;
+    mandates: CardMandateRecord[];
+};
+export type CoverQuery = {
+    merchantHost: string;
+    currencyCode: string;
+    amountMinor: number;
+    now?: Date;
+};
+/** Available headroom = ceiling - committed - reserved. Integer minor units. */
+export declare function remainingMinor(record: CardMandateRecord): number;
+/**
+ * The persisted card-mandate ledger. All mutating operations are serialized on
+ * an in-process promise chain so two concurrent draws cannot both observe the
+ * same remaining balance (the read-modify-write is atomic within the process).
+ */
+export declare class MandateLedger {
+    private readonly path;
+    private chain;
+    constructor(path?: string);
+    /** Serialize a read-modify-write so concurrent draws can't race the file. */
+    private run;
+    private load;
+    private save;
+    /** Append a freshly-created mandate record. */
+    create(record: CardMandateRecord): Promise<CardMandateRecord>;
+    /** Read a single mandate (no lock — a snapshot copy). */
+    get(mandateId: string): Promise<CardMandateRecord | null>;
+    /**
+     * First ACTIVE mandate (not expired) whose merchant + currency match and whose
+     * remaining headroom covers amountMinor. Used by pay_merchant to decide the
+     * tap-free draw path vs a fresh per-purchase tap.
+     */
+    findCovering(query: CoverQuery): Promise<CardMandateRecord | null>;
+    /**
+     * Mark a mandate as unhonored — the network declined a ceiling-scoped draw
+     * against it, so it must never be selected again. Atomic, owner-only write on
+     * the same serialized chain as every other mutation. Idempotent: a second
+     * call keeps the first timestamp. Throws only if the mandate is unknown.
+     */
+    markUnhonored(mandateId: string, now?: Date): Promise<CardMandateRecord>;
+    /**
+     * Mark a mandate as register-failed — the delegated-draw register handshake
+     * did not create the server row at mandate-start, so it must never be selected
+     * for a (delegated) draw. Atomic, owner-only write on the same serialized chain
+     * as every other mutation. Idempotent: a second call keeps the first timestamp.
+     * Throws only if the mandate is unknown.
+     */
+    markRegisterFailed(mandateId: string, now?: Date): Promise<CardMandateRecord>;
+    /**
+     * Atomically reserve headroom for a draw. Fail-closed: refuses when the
+     * mandate is unknown, expired, or the amount exceeds remaining headroom. The
+     * reservation counts against availability immediately, closing the window in
+     * which two concurrent draws both see the same remaining balance.
+     */
+    reserve(mandateId: string, amountMinor: number, now?: Date): Promise<string>;
+    /** Commit a reservation to permanent spend and record the payable draw. */
+    commit(mandateId: string, reservationId: string, meta: {
+        intentId: string;
+    }, now?: Date): Promise<CardMandateRecord>;
+    /** Release a reservation back to availability (draw failed / not payable). */
+    release(mandateId: string, reservationId: string, now?: Date): Promise<CardMandateRecord>;
+}
+export declare function defaultLedgerPath(): string;