@visa/cli 4.1.0-rc.2 → 4.1.0-rc.200

package/dist/checkout-engine/instrument.js

@@ -0,0 +1,87 @@
+// Instrument abstraction: the checkout engine is deliberately blind to WHERE
+// card credentials come from. Official test PANs, callback-backed agentic
+// credentials, and owner-only VIC harness files are enabled; VGS aliases stay
+// stubbed until a reveal seam exists. The executor remains unchanged across
+// every instrument.
+// Official public test PANs only. These are the sanctioned Visa/network test
+// numbers used against local fixtures; they carry no funds and pass Luhn.
+export const OFFICIAL_TEST_PANS = {
+    visa: '4242424242424242',
+    visaAlt: '4111111111111111',
+    // PAN whose last four are 0002 is treated as a forced decline by the
+    // fixture acquirer, for exercising the declined outcome path.
+    visaDecline: '4000000000000002',
+    // Ending 0069: the fixture acquirer shows a processing interstitial, then
+    // JS-redirects to a Shopify-style thank-you URL with no confirmation text —
+    // exercises the outcome observer's late, URL-signal confirmation path.
+    visaSlowConfirm: '4000000000000069',
+    // Ending 0044: the fixture acquirer returns a neutral page with neither a
+    // confirmation nor a decline signal — exercises the unknown-outcome deadline.
+    visaUnknownOutcome: '4000000000000044',
+    // Ending 0010: the fixture acquirer answers with a 3DS-style verification
+    // page embedding an ACS challenge iframe that never completes — exercises
+    // the observer's action-required (issuer challenge) path.
+    visaChallenge: '4000000000000010',
+    // Ending 0077: the fixture acquirer emails a one-time code to the agent
+    // inbox and shows a 'check your email for a code' page with a one-time-code
+    // field — exercises the executor's agent-resolvable email-OTP subroutine.
+    visaEmailOtp: '4000000000000077',
+};
+function futureExpiry() {
+    const now = new Date();
+    return { expMonth: 12, expYear: now.getFullYear() + 3 };
+}
+export class TestCardInstrument {
+    kind = 'test-card';
+    credential;
+    constructor(opts = {}) {
+        const exp = futureExpiry();
+        this.credential = {
+            pan: opts.pan ?? OFFICIAL_TEST_PANS.visa,
+            expMonth: opts.expMonth ?? exp.expMonth,
+            expYear: opts.expYear ?? exp.expYear,
+            cvc: opts.cvc ?? '123',
+            cardholderName: opts.cardholderName ?? 'Test Agent',
+        };
+    }
+    async getCredential(_ctx) {
+        return this.credential;
+    }
+}
+const NOT_ENABLED = 'not enabled: pending VGS alias reveal support';
+// Stub. Once VGS enablement lands, this resolves a network token / alias into a
+// fillable credential (a virtual PAN plus its verification value).
+export class VgsAliasInstrument {
+    _alias;
+    kind = 'vgs-alias';
+    constructor(_alias) {
+        this._alias = _alias;
+    }
+    async getCredential(_ctx) {
+        throw new Error(`${NOT_ENABLED}. VgsAliasInstrument cannot resolve alias "${this._alias}" ` +
+            'to a fillable PAN until VGS exposes the reveal seam for this spike.');
+    }
+}
+// A server-side provider mints the transaction-bound credential whose pan
+// carries the DPAN and whose cvc carries the short DAVV. Omitting the provider
+// preserves a clear fail-closed result for callers that have only a token ref.
+export class AgenticTokenInstrument {
+    tokenRef;
+    mintCredential;
+    kind = 'agentic-token';
+    used = false;
+    constructor(tokenRef, mintCredential) {
+        this.tokenRef = tokenRef;
+        this.mintCredential = mintCredential;
+    }
+    async getCredential(ctx) {
+        if (!this.mintCredential) {
+            throw new Error('not enabled: no agentic credential provider configured. ' +
+                `Token ${this.tokenRef} needs a server-side VGS credential provider.`);
+        }
+        if (this.used)
+            throw new Error('agentic credential instrument is single-use');
+        this.used = true;
+        return this.mintCredential(ctx);
+    }
+}

package/dist/checkout-engine/known-merchants.d.ts

@@ -0,0 +1,10 @@
+export type MerchantIdentity = {
+    /** Human-recognizable merchant name. */
+    name: string;
+    /** What the merchant is, e.g. "charity (animal rescue)". */
+    category: string;
+    /** The merchant's own site, when known — not the checkout URL. */
+    website?: string;
+};
+/** Checkout URL → who is actually behind it. Confirmed live 2026-07/2026-08. */
+export declare const KNOWN_MERCHANT_IDENTITIES: Readonly<Record<string, MerchantIdentity>>;

package/dist/checkout-engine/known-merchants.js

@@ -0,0 +1,38 @@
+// Curated identities for checkout URLs the registry cannot name on its own.
+//
+// Hosted payment links are anonymous by construction: the page host is the
+// PSP's (donate.stripe.com, buy.stripe.com), the path is an opaque token, and
+// the receipt records nothing else. So a registry row for a completed payment
+// link answers "where can I use my card?" with a string no human recognizes.
+// This map carries the once-per-link human identification, keyed by the exact
+// checkout URL the receipts group on.
+//
+// Curation rule: an entry is added only after a checkout at that URL completed
+// for real (engine outcome 'confirmed' + VIC APPROVED — the same admission rule
+// confirmed-merchants.ts enforces) and the merchant behind the link was
+// identified by a person. The map never creates registry rows; it only names
+// rows the device's own receipts already earned. A URL missing here still
+// lists — it just shows as its host.
+/** Checkout URL → who is actually behind it. Confirmed live 2026-07/2026-08. */
+export const KNOWN_MERCHANT_IDENTITIES = {
+    'https://donate.stripe.com/3cscPcaqY20H8ta4gh': {
+        name: 'NC Seaside Animal Rescue',
+        category: 'charity (animal rescue, NC nonprofit)',
+        website: 'https://www.ncseasideanimalrescue.org/make-a-donation',
+    },
+    'https://donate.stripe.com/14k3ei9TYgwFclq145': {
+        name: 'FreeCAD',
+        category: 'open-source project donation (CAD software)',
+        website: 'https://www.freecad.org',
+    },
+    'https://buy.stripe.com/dR6eWGaK41MX2YgaEF': {
+        name: 'scribepod',
+        category: 'indie creator tip jar (AI podcast project)',
+        website: 'https://github.com/yacineMTB/scribepod',
+    },
+    'https://donate.stripe.com/7sIcNj9Gs4WO6d29AA': {
+        name: 'n0bleKing GRAFFITI',
+        category: 'indie creator tip jar (pixel art and fonts)',
+        website: 'https://nobleking-graffiti.itch.io',
+    },
+};

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

@@ -0,0 +1,37 @@
+import type { CheckoutMode, CheckoutOutcome, CheckoutResult } from './executor.js';
+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;
+/** 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.
+ *
+ * The executor now NAMES this state in the outcome itself ('unverified'), so
+ * the two agree by construction. This predicate stays the broader guard: it
+ * also catches a post-click throw or any future outcome that leaves the same
+ * question open, and it is what the receipt's reconciliation list reads.
+ */
+export declare function submitClickedWithoutConfirmation(result: CheckoutResult): boolean;

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

@@ -0,0 +1,76 @@
+// Deliberate-enablement seam for run-live-fill's submit mode. A real submit
+// moves real money, so it requires:
+//   1. the invocation opts in (--mode submit, or the CHECKOUT_AGENT_MODE
+//      environment default for operators who always run one mode),
+//   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 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
+ * 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)})`);
+}
+/** Distinct phrases per mode so dry-run muscle memory can never authorize a payment. */
+export function approvalPhrase(mode, 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) {
+    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 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' : 'reviewed-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.
+ *
+ * The executor now NAMES this state in the outcome itself ('unverified'), so
+ * the two agree by construction. This predicate stays the broader guard: it
+ * also catches a post-click throw or any future outcome that leaves the same
+ * question open, and it is what the receipt's reconciliation list reads.
+ */
+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,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 surfaces the no-covering refusal (#7348) — 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; a v4 card grant then requires a new mandate before another checkout';
+/**
+ * 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),
+    };
+}