@visa/cli 4.1.0-rc.21 → 4.1.0-rc.211

package/dist/checkout-engine/index.d.ts

@@ -1,3 +1,9 @@
-export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, } from './cli-engine.js';
+export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, type CliStartMandateInput, type CliMandateFacts, type CliEngineDeps, CheckoutReviewRefusedError, } from './cli-engine.js';
 export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
-export type { CheckoutResult, CheckoutReview, CheckoutOutcome } from './executor.js';
+export type { CheckoutResult, CheckoutReview, CheckoutOutcome, CheckoutFailureCode, } from './executor.js';
+export { readConfirmedMerchants, type ConfirmedMerchant, type ConfirmedCharge, } from './confirmed-merchants.js';
+export { KNOWN_MERCHANT_IDENTITIES, type MerchantIdentity } from './known-merchants.js';
+export { RECEIPT_DIR } from './receipt-dir.js';
+export { HostedApprovalDeclinedError, sanitizeApprovalIntent, APPROVAL_INTENT_MAX_CHARS, } from './hosted-approval.js';
+export { createCardMandate, drawFromMandate, MandateDrawDeclinedError, DEFAULT_MANDATE_MAX_DRAWS, type CreateCardMandateInput, type CreateCardMandateDeps, type CardMandateFacts, type DrawFromMandateInput, type DrawFromMandateDeps, type DrawResult, type CardMandateMerchant, } from './mandate/card-mandate.js';
+export { MandateLedger, remainingMinor, defaultLedgerPath, CARD_MANDATE_LEDGER_VERSION, type CardMandateRecord, type CardMandateLedgerFile, type CardMandateDraw, type CardMandateReservation, } from './mandate/mandate-ledger.js';

package/dist/checkout-engine/index.js

@@ -1,5 +1,11 @@
 // Public API of @visa/checkout-engine. The pay_merchant tool in @visa/cli
 // consumes createCliCheckoutEngine() through a structural seam; the core engine
 // primitives are re-exported for direct/embedded use.
-export { createCliCheckoutEngine, } from './cli-engine.js';
+export { createCliCheckoutEngine, CheckoutReviewRefusedError, } from './cli-engine.js';
 export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
+export { readConfirmedMerchants, } from './confirmed-merchants.js';
+export { KNOWN_MERCHANT_IDENTITIES } from './known-merchants.js';
+export { RECEIPT_DIR } from './receipt-dir.js';
+export { HostedApprovalDeclinedError, sanitizeApprovalIntent, APPROVAL_INTENT_MAX_CHARS, } from './hosted-approval.js';
+export { createCardMandate, drawFromMandate, MandateDrawDeclinedError, DEFAULT_MANDATE_MAX_DRAWS, } from './mandate/card-mandate.js';
+export { MandateLedger, remainingMinor, defaultLedgerPath, CARD_MANDATE_LEDGER_VERSION, } from './mandate/mandate-ledger.js';

package/dist/checkout-engine/instrument.d.ts

@@ -6,6 +6,12 @@ export type CardCredential = {
     cardholderName: string;
     /** Dynamic payment credential expiry, distinct from the card expiration. */
     credentialExpiresAt?: string;
+    /**
+     * Non-sensitive, bounded request-correlation handles returned by the mint
+     * route. These are evidence pointers, not card credential material.
+     */
+    vgsTraceId?: string;
+    networkCorrelationId?: string;
 };
 export type InstrumentContext = {
     merchantHost: string;
@@ -24,6 +30,7 @@ export declare const OFFICIAL_TEST_PANS: {
     readonly visaSlowConfirm: "4000000000000069";
     readonly visaUnknownOutcome: "4000000000000044";
     readonly visaChallenge: "4000000000000010";
+    readonly visaEmailOtp: "4000000000000077";
 };
 export type TestCardOptions = {
     pan?: string;

package/dist/checkout-engine/instrument.js

@@ -22,6 +22,10 @@ export const OFFICIAL_TEST_PANS = {
     // 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();

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

@@ -1,30 +1,10 @@
 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;
-export declare 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 declare function assertLegacyReferenceAllowed(usingReferenceFile: boolean, env?: Record<string, string | undefined>): 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). */
@@ -48,5 +28,10 @@ export declare function isRunSuccess(mode: CheckoutMode, outcome: CheckoutOutcom
  * 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

@@ -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
@@ -96,6 +60,11 @@ export function isRunSuccess(mode, outcome) {
  * 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' ||

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;
+    /** @deprecated Accepted from older callers but deliberately never persisted. */
+    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,226 @@
+// 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,
+        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),
+    };
+}