@visa/cli 4.1.0-rc.13 → 4.1.0-rc.131

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

@@ -1,18 +1,19 @@
 // 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
+//   1. 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
+//   2. 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';
+// The PAY phrase differs from dry-run's FILL phrase and names the exact review
+// id, so a muscle-memory rerun of the dry-run procedure cannot drift into
+// charging a card. Fresh checkouts need ZERO persisted config.
+//
+// There was a third requirement — a CHECKOUT_AGENT_ALLOW_SUBMIT=1 environment
+// arm, exempted for interactive TTYs — meant to stop AUTOMATION reaching a live
+// charge. It never ran: nothing in the product ever called `assertSubmitAllowed`.
+// The same flag DID gate `pay_merchant`, where being default-off with no
+// in-product way to set it meant a real install could not complete a purchase at
+// all. Both are gone; the phrase and the mandate caps are the gates.
 export const MODE_ENV_FLAG = 'CHECKOUT_AGENT_MODE';
 /**
  * `--mode` values map 1:1 onto CheckoutMode; an absent flag falls back to the
@@ -26,46 +27,9 @@ export function parseCheckoutMode(value, env = process.env) {
         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.');
-}
-export const LEGACY_REFERENCE_ENV_FLAG = 'CHECKOUT_AGENT_ALLOW_LEGACY_REFERENCE';
-/**
- * The legacy --reference-file path replays a PRE-CREATED intent, so the
- * purchase-assurance gate (#5709) cannot vet the ceremony that backed it —
- * scope/freshness problems surface only as the opaque cryptogram failure the
- * gate exists to prevent. Default-off escape hatch, same shape as the submit
- * gate: fail fast before any file is read.
- */
-export function assertLegacyReferenceAllowed(usingReferenceFile, env = process.env) {
-    if (!usingReferenceFile)
-        return;
-    if (env[LEGACY_REFERENCE_ENV_FLAG] !== '1') {
-        throw new Error(`--reference-file refused: this legacy path bypasses purchase-assurance validation ` +
-            `(#5709) — prefer --checkout-file with --purchase-assurance-file. Set ` +
-            `${LEGACY_REFERENCE_ENV_FLAG}=1 to proceed anyway.`);
-    }
-}
 /** 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}`;
+    return `${mode === 'submit' ? 'PAY' : 'CHECK'} ${reviewId}`;
 }
 /** Integer-only minor→display formatting (two-decimal currencies, the same assumption as decimalToMinor). */
 export function formatAmountMinor(amountMinor, currency) {
@@ -79,11 +43,11 @@ export function approvalQuestion(mode, review, phrase) {
             `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: `);
+        `to validate the reviewed page without minting, filling, or submitting a credential: `);
 }
 /** The one outcome each mode may exit 0 with. */
 export function isRunSuccess(mode, outcome) {
-    return outcome === (mode === 'submit' ? 'confirmed' : 'filled-dry-run');
+    return outcome === (mode === 'submit' ? 'confirmed' : 'reviewed-dry-run');
 }
 /**
  * True when the pay control was actually clicked but the run ended with an

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

@@ -0,0 +1,121 @@
+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 = {
+    /** Exact current runtime request key selected before human approval. */
+    agentJkt: string;
+    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;
+    /** Cross-host retail budget; network category eligibility still applies. */
+    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;
+    /** Network-enforced maximum purchase count disclosed at approval. */
+    maxDraws: number;
+};
+/**
+ * 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,227 @@
+// 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');
+    if (!/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/.test(input.agentJkt)) {
+        throw new Error('mandate requires a canonical agent request-key JKT');
+    }
+    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,
+        agentJkt: input.agentJkt,
+        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(),
+        maxDraws,
+        createdAt: now.toISOString(),
+        draws: [],
+        ...(input.crossMerchant ? { crossMerchant: true } : {}),
+    };
+    await deps.ledger.create(record, now);
+    return {
+        mandateId: record.mandateId,
+        ceilingMinor: record.ceilingMinor,
+        remainingMinor: remainingMinor(record),
+        currencyCode,
+        merchant: input.merchant,
+        expiresAt: record.expiresAt,
+        maxDraws,
+    };
+}
+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 eligible retail merchants. 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,165 @@
+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;
+    /** Exact runtime request key this budget was issued to. Absent on legacy rows. */
+    agentJkt?: 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 token released by the ceiling approval. It bootstraps the one intent
+     * + register ceremony only. Each cryptogram AND its outcome confirmation use
+     * the exact per-draw verdict instead. Owner-only (0600).
+     */
+    mintToken?: string;
+    expiresAt: string;
+    /** Network purchase-count cap disclosed at approval. Absent on legacy rows. */
+    maxDraws?: number;
+    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`. Mandate-start requires delegated card authority, so every
+     * created record attempted registration. ISO 8601.
+     */
+    registerFailedAt?: string;
+    /**
+     * A cross-host retail budget, not scoped to one `merchantHost`. The local
+     * selector may attempt it at any host, while the provider/network still
+     * applies the approved Retail/5999 category plus amount/count/time controls.
+     * `crossMerchant` is retained as the version-1 persisted field name.
+     */
+    crossMerchant?: boolean;
+};
+export type CardMandateLedgerFile = {
+    version: typeof CARD_MANDATE_LEDGER_VERSION;
+    mandates: CardMandateRecord[];
+};
+export type CoverQuery = {
+    merchantHost: string;
+    currencyCode: string;
+    amountMinor: number;
+    /** Exact selected request key; omitted means legacy unbound mandates only. */
+    agentJkt?: string;
+    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. `now` drives the expired-mandate
+     * prune below; it defaults to the wall clock but is injectable so callers (and
+     * tests) can pin it — every other mutating method takes the same clock, and a
+     * real `new Date()` here would otherwise make the prune non-deterministic
+     * against fixtures dated relative to a fixed reference time.
+     */
+    create(record: CardMandateRecord, now?: Date): 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>;
+    /**
+     * ONE SPENDING LIMIT: adopt the ceiling the SERVER actually approved.
+     *
+     * The requested ceiling is only a request. At register, auth clamps it to the
+     * owner's live card-grant cap (`min(requested, grant daily limit)`) and writes
+     * that. The local record used to keep the requested figure, so a runtime whose
+     * request exceeded the grant reported — and selected against — a budget the
+     * owner never approved. The draw still failed closed at auth's verdict, so it
+     * was never over-spend; it was the runtime lying about its own headroom and
+     * then hitting a decline it could not explain.
+     *
+     * LOWERS ONLY. A value at or above the current ceiling is ignored, not
+     * written: the server clamps downward, so a higher number means an unexpected
+     * response, and honouring it would let a client-observed value hand a runtime
+     * headroom no human approved. Cap authority stays server-side either way —
+     * this only stops the local copy from overstating it.
+     *
+     * Atomic and idempotent on the same serialized chain as every other mutation.
+     * Throws only if the mandate is unknown.
+     */
+    applyApprovedCeiling(mandateId: string, approvedCeilingMinor: number): 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;