@visa/cli 4.1.0-rc.261 → 4.1.0-rc.262

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

@@ -2,7 +2,7 @@ import { type Browser } from 'playwright-core';
 import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, type CheckoutMode, type CheckoutOutcome, type CheckoutFailureCode, type CheckoutResult, type PreparedCheckoutSessionStore } from './executor.js';
 import { claimMandatePickup as realClaimMandatePickup, runHostedApproval as realRunHostedApproval } from './hosted-approval.js';
 import { type VgsCheckoutTarget } from './vgs-live-instrument.js';
-import { serverFetchCryptogram, serverPostConfirmation } from './vgs-gateway/server-mint-client.js';
+import { ServerIntentError, serverFetchCryptogram, serverPostConfirmation } from './vgs-gateway/server-mint-client.js';
 import { type CardMandateFacts } from './mandate/card-mandate.js';
 import { MandateLedger } from './mandate/mandate-ledger.js';
 import { writeReceipt as realWriteReceipt } from './receipt.js';
@@ -194,6 +194,43 @@ export type CliMandateFacts = CardMandateFacts & {
      */
     registerFailureReason?: string;
 };
+/**
+ * The owner approved a budget but the intent bootstrap did not complete
+ * (#8470). `resumable` means the same approval can be resumed without a second
+ * passkey ceremony: the server's bootstrap state is at-most-once per signed
+ * token, so a resume can only recover an intent that already exists or
+ * dispatch once when nothing was ever dispatched — never create a sibling.
+ */
+export type CardMandateActivationFacts = {
+    phase: 'intent';
+    /** `uncertain`: the provider may have created the intent. `not_created`: proven not. */
+    outcome: 'uncertain' | 'not_created';
+    resumable: boolean;
+    status: number | null;
+    errorCode: string | null;
+    requestId: string | null;
+    bootstrapState: string;
+    /** Opaque, process-bound handle for {@link CliCheckoutEngine.resumeCardMandate}. */
+    resumeToken?: string;
+    /** When the approval's bootstrap credential stops being usable. */
+    resumeExpiresAt?: string;
+};
+export declare class CardMandateActivationError extends Error {
+    readonly facts: CardMandateActivationFacts;
+    readonly code = "CARD_MANDATE_ACTIVATION_INCOMPLETE";
+    constructor(message: string, facts: CardMandateActivationFacts);
+}
+export type CliResumeMandateInput = {
+    resumeToken: string;
+};
+/**
+ * Sort a budget-intent route failure into resume semantics. Exported for the
+ * regression net; the truth table is the product contract of #8470.
+ */
+export declare function classifyServerIntentFailure(err: ServerIntentError): {
+    outcome: 'uncertain' | 'not_created';
+    resumable: boolean;
+};
 type Session = {
     browser: Browser;
     /** Exact caller URL repeated at pay time; may contain a UCP capability. */
@@ -353,6 +390,7 @@ export type ReceiptWriteObservation = {
 };
 export declare function createCliCheckoutEngine(deps?: CliEngineDeps): {
     startCardMandate(input: CliStartMandateInput): Promise<CliMandateFacts>;
+    resumeCardMandate(input: CliResumeMandateInput): Promise<CliMandateFacts>;
     claimCardMandate(input: CliClaimMandateInput): Promise<CliMandateFacts>;
     review(input: CliReviewInput): Promise<CliReviewFacts>;
     /**

package/dist/checkout-engine/cli-engine.js

@@ -11,13 +11,13 @@
 // Every browser/network primitive is injectable (CliEngineDeps) so the session/
 // timer/store lifecycle is unit-testable without launching Chromium.
 import { readFile } from 'node:fs/promises';
-import { randomUUID } from 'node:crypto';
+import { randomBytes, randomUUID } from 'node:crypto';
 import { launchCheckoutBrowser } from './browser-launch.js';
 import { RECEIPT_DIR } from './receipt-dir.js';
 import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
 import { claimMandatePickup as realClaimMandatePickup, runHostedApproval as realRunHostedApproval, } from './hosted-approval.js';
 import { VgsLiveInstrument, decimalToMinor, minorToDecimal, } from './vgs-live-instrument.js';
-import { serverCreateIntent, serverFetchCryptogram, serverPostConfirmation, } from './vgs-gateway/server-mint-client.js';
+import { serverCreateIntent, serverReadIntentBootstrap, ServerIntentError, serverFetchCryptogram, serverPostConfirmation, } from './vgs-gateway/server-mint-client.js';
 import { createCardMandate, DEFAULT_MANDATE_MAX_DRAWS, drawFromMandate, MandateDrawDeclinedError, } from './mandate/card-mandate.js';
 import { MandateLedger } from './mandate/mandate-ledger.js';
 import { buildReceipt, writeReceipt as realWriteReceipt, } from './receipt.js';
@@ -207,6 +207,62 @@ function failedPay(detail) {
         credentialDisclosed: false,
     };
 }
+export class CardMandateActivationError extends Error {
+    facts;
+    code = 'CARD_MANDATE_ACTIVATION_INCOMPLETE';
+    constructor(message, facts) {
+        super(message);
+        this.facts = facts;
+        this.name = 'CardMandateActivationError';
+    }
+}
+/**
+ * Sort a budget-intent route failure into resume semantics. Exported for the
+ * regression net; the truth table is the product contract of #8470.
+ */
+export function classifyServerIntentFailure(err) {
+    const { status, errorCode, retryable, bootstrapState, outcome } = err.facts;
+    if (bootstrapState === 'created')
+        return { outcome: 'not_created', resumable: true };
+    if (bootstrapState === 'ambiguous' || errorCode === 'budget_intent_creation_ambiguous') {
+        return { outcome: 'uncertain', resumable: true };
+    }
+    if (bootstrapState === 'pending' || errorCode === 'budget_intent_creation_pending') {
+        return { outcome: 'uncertain', resumable: true };
+    }
+    // An explicit uncertain or unknown outcome wins over retry advice: a
+    // retryable failure of the STATUS read says nothing about whether the
+    // original dispatch created the intent, so it must not read as not_created.
+    // A terminal refusal of the read itself (the approval credential is no
+    // longer accepted, or is not a budget token) is still uncertain about the
+    // intent but cannot be resumed under that credential.
+    if (outcome === 'uncertain' || outcome === 'unknown') {
+        const terminalRead = status === 401 || status === 403 || status === 404;
+        return { outcome: 'uncertain', resumable: !terminalRead };
+    }
+    if (retryable)
+        return { outcome: 'not_created', resumable: true };
+    if (status === 0 || status >= 500) {
+        return { outcome: 'uncertain', resumable: true };
+    }
+    // A completed 4xx refusal (claims, binding, conflict, already registered)
+    // proves no intent exists and no resume can change the answer.
+    return { outcome: 'not_created', resumable: false };
+}
+function mintTokenExpiryMs(mintToken, fallbackMs) {
+    try {
+        const payload = mintToken.split('.')[1];
+        if (!payload)
+            return fallbackMs;
+        const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+        return typeof claims.exp === 'number' && Number.isFinite(claims.exp)
+            ? claims.exp * 1000
+            : fallbackMs;
+    }
+    catch {
+        return fallbackMs;
+    }
+}
 function boundedReceiptWriteErrorCode(reason) {
     return reason.match(/\b(?:EACCES|EEXIST|ENOSPC|ENOTDIR|EPERM|EROFS)\b/)?.[0] ?? 'UNKNOWN';
 }
@@ -222,6 +278,45 @@ export function createCliCheckoutEngine(deps = {}) {
     const sessions = deps.sessions ?? defaultSessions;
     const payAttempts = deps.payAttempts ?? defaultPayAttempts;
     const ttlMs = deps.ttlMs ?? PREPARED_TTL_MS;
+    // #8470: process-bound resume handles for a budget whose intent bootstrap
+    // did not complete after owner approval. Holds the one-use bootstrap
+    // credential in memory only, for at most its own lifetime.
+    const pendingActivations = new Map();
+    function dropActivation(token) {
+        const pending = pendingActivations.get(token);
+        if (!pending)
+            return;
+        clearTimeout(pending.cleanupTimer);
+        pendingActivations.delete(token);
+    }
+    function parkActivation(pending) {
+        const token = `act_${randomBytes(18).toString('base64url')}`;
+        const cleanupTimer = setTimeout(() => dropActivation(token), Math.max(0, pending.expiresAtMs - now().getTime()));
+        cleanupTimer.unref?.();
+        pendingActivations.set(token, { ...pending, cleanupTimer });
+        return token;
+    }
+    function activationFailure(err, pending, existingToken) {
+        if (!(err instanceof ServerIntentError))
+            throw err;
+        const classified = classifyServerIntentFailure(err);
+        const resumeToken = classified.resumable
+            ? (existingToken ?? parkActivation(pending))
+            : undefined;
+        if (!classified.resumable && existingToken)
+            dropActivation(existingToken);
+        throw new CardMandateActivationError(err.message, {
+            phase: 'intent',
+            outcome: classified.outcome,
+            resumable: classified.resumable,
+            status: err.facts.status,
+            errorCode: err.facts.errorCode,
+            requestId: err.facts.requestId,
+            bootstrapState: err.facts.bootstrapState,
+            ...(resumeToken ? { resumeToken } : {}),
+            ...(resumeToken ? { resumeExpiresAt: new Date(pending.expiresAtMs).toISOString() } : {}),
+        });
+    }
     const launchBrowser = deps.launchBrowser ?? (() => launchCheckoutBrowser());
     const prepareCheckout = deps.prepareCheckout ?? realPrepareCheckout;
     const submitApprovedCheckout = deps.submitApprovedCheckout ?? realSubmitApprovedCheckout;
@@ -394,6 +489,45 @@ export function createCliCheckoutEngine(deps = {}) {
             ...(reg.reason !== undefined ? { registerFailureReason: reg.reason } : {}),
         };
     }
+    // Shared by mandate-start and resume: mint (or adopt) the ceiling intent,
+    // persist the owner-only ledger entry, and register server-side.
+    async function activateBudget(pending, createIntent) {
+        const facts = await createCardMandate({
+            agentJkt: pending.registerCap.agentJkt,
+            tokenId: pending.tokenId,
+            assuranceData: pending.assuranceData,
+            ceilingMinor: pending.ceilingMinor,
+            merchant: pending.merchant,
+            currencyCode: pending.currency,
+            expiresAt: pending.expiresAt,
+            maxDraws: DEFAULT_MANDATE_MAX_DRAWS,
+            crossMerchant: true,
+        }, {
+            createIntent,
+            ledger,
+            approvalBaseUrl: pending.approvalBaseUrl,
+            now,
+        });
+        // Seed the one server-authoritative cumulative store keyed by the VGS
+        // intent ID. A later draw requires its PoP verdict; the budget token never
+        // falls back as payable authority.
+        const registered = await registerMandateOrDisable({
+            registerCap: pending.registerCap,
+            mandateId: facts.mandateId,
+            mintToken: pending.mintToken,
+            ceiling: pending.ceiling,
+            currency: pending.currency,
+        });
+        return {
+            ...facts,
+            ...approvedCeilingFacts(facts, registered.approvedCeilingMinor),
+            merchantHost: new URL(pending.merchant.url).hostname,
+            registerFailed: registered.registerFailed,
+            ...(registered.registerFailureReason !== undefined
+                ? { registerFailureReason: registered.registerFailureReason }
+                : {}),
+        };
+    }
     return {
         // BUDGET step: one passkey approves a CEILING; a VGS intent is minted with
         // that ceiling as its decline threshold and the owner-only ledger records
@@ -469,41 +603,86 @@ export function createCliCheckoutEngine(deps = {}) {
                 throw new Error('the approval server issued no valid budget expiry');
             }
             const expiresAt = new Date(assurance.validUntil * 1000).toISOString();
-            const facts = await createCardMandate({
-                agentJkt: registerCap.agentJkt,
-                tokenId: credential.tokenId,
+            const pending = {
+                mintToken,
                 assuranceData: assurance.assuranceData,
+                ceiling: input.ceiling,
                 ceilingMinor,
+                currency: input.currency,
                 merchant,
-                currencyCode: input.currency,
                 expiresAt,
-                maxDraws: DEFAULT_MANDATE_MAX_DRAWS,
-                crossMerchant: true,
-            }, {
-                createIntent: (i) => serverCreateIntent(input.approvalBaseUrl, mintToken, i),
-                ledger,
+                tokenId: credential.tokenId,
                 approvalBaseUrl: input.approvalBaseUrl,
-                now,
-            });
-            // Seed the one server-authoritative cumulative store keyed by the VGS
-            // intent ID. A later draw requires its PoP verdict; the budget token never
-            // falls back as payable authority.
-            const registered = await registerMandateOrDisable({
                 registerCap,
-                mandateId: facts.mandateId,
-                mintToken,
-                ceiling: input.ceiling,
-                currency: input.currency,
-            });
-            return {
-                ...facts,
-                ...approvedCeilingFacts(facts, registered.approvedCeilingMinor),
-                merchantHost: new URL(merchant.url).hostname,
-                registerFailed: registered.registerFailed,
-                ...(registered.registerFailureReason !== undefined
-                    ? { registerFailureReason: registered.registerFailureReason }
-                    : {}),
+                expiresAtMs: mintTokenExpiryMs(mintToken, now().getTime() + 10 * 60 * 1000),
             };
+            return activateBudget(pending, (i) => serverCreateIntent(input.approvalBaseUrl, mintToken, i)).catch((err) => activationFailure(err, pending));
+        },
+        // RESUME leg (#8470): the owner already approved, but the intent bootstrap
+        // did not complete. Read the server's durable state under the SAME one-use
+        // credential: a created intent is registered as-is, nothing-dispatched is
+        // dispatched once, pending/ambiguous stays uncertain. No approval page, no
+        // passkey, and never a sibling intent.
+        async resumeCardMandate(input) {
+            const pending = pendingActivations.get(input.resumeToken);
+            if (!pending || pending.expiresAtMs <= now().getTime()) {
+                if (pending)
+                    dropActivation(input.resumeToken);
+                throw new CardMandateActivationError('no resumable budget activation for this operation — its approval credential expired; start a fresh approval', {
+                    phase: 'intent',
+                    outcome: 'not_created',
+                    resumable: false,
+                    status: null,
+                    errorCode: 'activation_resume_expired',
+                    requestId: null,
+                    bootstrapState: 'unknown',
+                });
+            }
+            let read;
+            try {
+                read = await serverReadIntentBootstrap(pending.approvalBaseUrl, pending.mintToken);
+            }
+            catch (err) {
+                return activationFailure(err, pending, input.resumeToken);
+            }
+            if (read.state === 'created' && read.intentId) {
+                const intentId = read.intentId;
+                const facts = await activateBudget(pending, async () => ({
+                    intentId,
+                    status: read.intentStatus,
+                }));
+                dropActivation(input.resumeToken);
+                return facts;
+            }
+            if (read.state === 'none') {
+                return activateBudget(pending, (i) => serverCreateIntent(pending.approvalBaseUrl, pending.mintToken, i))
+                    .then((facts) => {
+                    dropActivation(input.resumeToken);
+                    return facts;
+                })
+                    .catch((err) => activationFailure(err, pending, input.resumeToken));
+            }
+            throw new CardMandateActivationError(read.state === 'ambiguous'
+                ? 'the card network never confirmed this budget intent and its outcome cannot be verified; this approval cannot be reused'
+                : read.state === 'pending'
+                    ? 'this budget intent is still being created; check again shortly'
+                    : 'the budget activation state could not be read; check again shortly', {
+                phase: 'intent',
+                outcome: 'uncertain',
+                // Stays parked and queryable: a further resume only re-reads state
+                // and can never redispatch under this token.
+                resumable: true,
+                status: null,
+                errorCode: read.state === 'ambiguous'
+                    ? 'budget_intent_creation_ambiguous'
+                    : read.state === 'pending'
+                        ? 'budget_intent_creation_pending'
+                        : 'budget_intent_state_unavailable',
+                requestId: read.requestId,
+                bootstrapState: read.state,
+                resumeToken: input.resumeToken,
+                resumeExpiresAt: new Date(pending.expiresAtMs).toISOString(),
+            });
         },
         // PICKUP leg: the owner already approved the ceiling in the account panel
         // and handed this runtime a single-use pickup code. Claim it, verify it was

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

@@ -1,4 +1,4 @@
-export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, type CliStartMandateInput, type CliMandateFacts, type CliEngineDeps, type ReceiptWriteObservation, CheckoutReviewRefusedError, } from './cli-engine.js';
+export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, type CliStartMandateInput, type CliMandateFacts, type CliEngineDeps, type ReceiptWriteObservation, CheckoutReviewRefusedError, CardMandateActivationError, classifyServerIntentFailure, type CardMandateActivationFacts, type CliResumeMandateInput, } from './cli-engine.js';
 export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
 export type { CheckoutResult, CheckoutReview, CheckoutOutcome, CheckoutFailureCode, CheckoutRoute, } from './executor.js';
 export { readConfirmedMerchants, type ConfirmedMerchant, type ConfirmedCharge, } from './confirmed-merchants.js';

package/dist/checkout-engine/index.js

@@ -1,7 +1,7 @@
 // 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, CheckoutReviewRefusedError, } from './cli-engine.js';
+export { createCliCheckoutEngine, CheckoutReviewRefusedError, CardMandateActivationError, classifyServerIntentFailure, } 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';

package/dist/checkout-engine/vgs-gateway/server-mint-client.d.ts

@@ -36,6 +36,31 @@ export declare class ServerCryptogramRefusedError extends Error {
     readonly terminal: true;
     constructor(status: number, detail: string);
 }
+export type ServerIntentBootstrapState = 'none' | 'pending' | 'created' | 'ambiguous' | 'conflict' | 'unknown';
+/**
+ * The budget-intent route's failure, kept structured (#8470). `status` 0 means
+ * the request never produced an HTTP response (network failure or abort), which
+ * is outcome-uncertain exactly like a 5xx: the server may have dispatched.
+ */
+export declare class ServerIntentError extends Error {
+    readonly facts: {
+        status: number;
+        errorCode: string | null;
+        retryable: boolean;
+        requestId: string | null;
+        bootstrapState: ServerIntentBootstrapState;
+        outcome: 'uncertain' | 'not_created' | 'unknown';
+    };
+    readonly code = "SERVER_INTENT_FAILED";
+    constructor(message: string, facts: {
+        status: number;
+        errorCode: string | null;
+        retryable: boolean;
+        requestId: string | null;
+        bootstrapState: ServerIntentBootstrapState;
+        outcome: 'uncertain' | 'not_created' | 'unknown';
+    });
+}
 /**
  * Optional mandate override for serverCreateIntent. Absent → the default
  * intent shape (cap = ceil(amount)+10 min 25, quantity 1, 30-day window).
@@ -71,6 +96,18 @@ export declare function serverCreateIntent(base: string, mintToken: string, inpu
     intentId: string;
     status: string | null;
 }>;
+/**
+ * Read the durable budget-bootstrap state for a budget mint token via
+ * GET {base}/api/vgs/intent (#8470). A `created` answer carries the intent the
+ * server already minted under this token, so the runner registers it instead
+ * of dispatching again; `pending` and `ambiguous` are never redispatched.
+ */
+export declare function serverReadIntentBootstrap(base: string, mintToken: string, deps?: ServerMintDeps): Promise<{
+    state: ServerIntentBootstrapState;
+    intentId: string | null;
+    intentStatus: string | null;
+    requestId: string | null;
+}>;
 /**
  * Mint the FULL payment credential via POST {base}/api/vgs/payment-cryptogram.
  * The server's route does a SINGLE gateway call and 502s on a not-COMPLETED

package/dist/checkout-engine/vgs-gateway/server-mint-client.js

@@ -63,9 +63,10 @@ export class ServerCryptogramRefusedError extends Error {
         this.status = status;
     }
 }
-/** Read a stable, non-secret error message from a route's JSON body. */
-async function routeError(res) {
-    const doc = (await res.json().catch(() => null));
+async function readRouteErrorDoc(res) {
+    return (await res.json().catch(() => null));
+}
+function routeErrorMessage(res, doc) {
     const base = doc?.error || doc?.error_code || `HTTP ${res.status}`;
     // Carry the provider's own status and rejected-attribute identifiers into the
     // message when the route reflected them. Without this the operator sees only
@@ -79,6 +80,61 @@ async function routeError(res) {
     }
     return parts.length > 0 ? `${base} [${parts.join(' ')}]` : base;
 }
+async function routeError(res) {
+    return routeErrorMessage(res, await readRouteErrorDoc(res));
+}
+const BOOTSTRAP_STATES = new Set([
+    'none',
+    'pending',
+    'created',
+    'ambiguous',
+    'conflict',
+    'unknown',
+]);
+function bootstrapStateOf(value) {
+    return typeof value === 'string' && BOOTSTRAP_STATES.has(value)
+        ? value
+        : 'unknown';
+}
+const SAFE_REQUEST_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+function requestIdOf(res, doc) {
+    const candidate = res?.headers.get('x-request-id') ?? doc?.request_id ?? null;
+    return typeof candidate === 'string' && SAFE_REQUEST_ID.test(candidate) ? candidate : null;
+}
+/**
+ * The budget-intent route's failure, kept structured (#8470). `status` 0 means
+ * the request never produced an HTTP response (network failure or abort), which
+ * is outcome-uncertain exactly like a 5xx: the server may have dispatched.
+ */
+export class ServerIntentError extends Error {
+    facts;
+    code = 'SERVER_INTENT_FAILED';
+    constructor(message, facts) {
+        super(message);
+        this.facts = facts;
+        this.name = 'ServerIntentError';
+    }
+}
+function serverIntentErrorFrom(res, doc) {
+    const errorCode = typeof doc?.error_code === 'string'
+        ? doc.error_code
+        : typeof doc?.error === 'string' && /^[a-z0-9_]{1,64}$/.test(doc.error)
+            ? doc.error
+            : null;
+    const outcome = doc?.outcome === 'uncertain' || doc?.outcome === 'not_created'
+        ? doc.outcome
+        : res.status >= 500 || res.status === 0
+            ? 'uncertain'
+            : 'not_created';
+    return new ServerIntentError(`server intent failed (${res.status}): ${routeErrorMessage(res, doc)}`, {
+        status: res.status,
+        errorCode,
+        retryable: doc?.retryable === true,
+        requestId: requestIdOf(res, doc),
+        bootstrapState: bootstrapStateOf(doc?.bootstrap_state),
+        outcome,
+    });
+}
 function bearer(mintToken) {
     return { 'content-type': 'application/json', authorization: `Bearer ${mintToken}` };
 }
@@ -99,34 +155,92 @@ export async function serverCreateIntent(base, mintToken, input, deps = {}) {
     const effectiveUntil = override.effectiveUntil ?? new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString();
     const consumerPrompt = override.consumerPrompt ??
         `Buy an item from ${t.merchantName} for ${t.transactionCurrencyCode.toUpperCase()} ${t.transactionAmount}`;
-    const res = await fetchImpl(`${stripTrailingSlashes(base)}/api/vgs/intent`, {
-        method: 'POST',
-        headers: bearer(mintToken),
-        body: JSON.stringify({
-            tokenId,
-            consumerPrompt,
-            assuranceData,
-            mandates: [
-                {
-                    description: `Purchase at ${t.merchantName}`,
-                    declineThresholdAmount,
-                    declineThresholdCurrencyCode: t.transactionCurrencyCode.toUpperCase(),
-                    effectiveUntil,
-                    merchantCategory: 'Retail',
-                    merchantCategoryCode: '5999',
-                    preferredMerchantName: t.merchantName,
-                    quantity,
-                },
-            ],
-        }),
-    });
+    let res;
+    try {
+        res = await fetchImpl(`${stripTrailingSlashes(base)}/api/vgs/intent`, {
+            method: 'POST',
+            headers: bearer(mintToken),
+            body: JSON.stringify({
+                tokenId,
+                consumerPrompt,
+                assuranceData,
+                mandates: [
+                    {
+                        description: `Purchase at ${t.merchantName}`,
+                        declineThresholdAmount,
+                        declineThresholdCurrencyCode: t.transactionCurrencyCode.toUpperCase(),
+                        effectiveUntil,
+                        merchantCategory: 'Retail',
+                        merchantCategoryCode: '5999',
+                        preferredMerchantName: t.merchantName,
+                        quantity,
+                    },
+                ],
+            }),
+        });
+    }
+    catch (err) {
+        // No HTTP response at all: the request may or may not have reached the
+        // server, so this is outcome-uncertain, never a proven non-creation.
+        throw new ServerIntentError(`server intent failed (0): ${err instanceof Error ? err.message : String(err)}`, {
+            status: 0,
+            errorCode: null,
+            retryable: false,
+            requestId: null,
+            bootstrapState: 'unknown',
+            outcome: 'uncertain',
+        });
+    }
     if (!res.ok)
-        throw new Error(`server intent failed (${res.status}): ${await routeError(res)}`);
+        throw serverIntentErrorFrom(res, await readRouteErrorDoc(res));
     const doc = (await res.json().catch(() => null));
     if (!doc?.intentId)
         throw new Error('server intent response missing intentId');
     return { intentId: doc.intentId, status: typeof doc.status === 'string' ? doc.status : null };
 }
+/**
+ * Read the durable budget-bootstrap state for a budget mint token via
+ * GET {base}/api/vgs/intent (#8470). A `created` answer carries the intent the
+ * server already minted under this token, so the runner registers it instead
+ * of dispatching again; `pending` and `ambiguous` are never redispatched.
+ */
+export async function serverReadIntentBootstrap(base, mintToken, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    let res;
+    try {
+        res = await fetchImpl(`${stripTrailingSlashes(base)}/api/vgs/intent`, {
+            method: 'GET',
+            headers: bearer(mintToken),
+        });
+    }
+    catch (err) {
+        throw new ServerIntentError(`server intent status failed (0): ${err instanceof Error ? err.message : String(err)}`, {
+            status: 0,
+            errorCode: null,
+            retryable: true,
+            requestId: null,
+            bootstrapState: 'unknown',
+            outcome: 'unknown',
+        });
+    }
+    const doc = (await res.json().catch(() => null));
+    if (!res.ok) {
+        const error = serverIntentErrorFrom(res, doc);
+        throw new ServerIntentError(error.message.replace('server intent failed', 'server intent status failed'), {
+            ...error.facts,
+            retryable: error.facts.retryable || res.status === 503,
+            outcome: 'unknown',
+        });
+    }
+    const state = bootstrapStateOf(doc?.bootstrap_state);
+    const intentId = typeof doc?.intent?.intentId === 'string' && doc.intent.intentId ? doc.intent.intentId : null;
+    return {
+        state: state === 'created' && !intentId ? 'unknown' : state,
+        intentId,
+        intentStatus: typeof doc?.intent?.status === 'string' ? doc.intent.status : null,
+        requestId: requestIdOf(res, doc),
+    };
+}
 /**
  * Mint the FULL payment credential via POST {base}/api/vgs/payment-cryptogram.
  * The server's route does a SINGLE gateway call and 502s on a not-COMPLETED