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

package/dist/checkout-engine/adapters/shopify.d.ts

@@ -2,7 +2,7 @@ import type { Page } from 'playwright-core';
 import { type PageAmountRead } from '../amount.js';
 import { type DetectResult, type FieldMap } from '../detect.js';
 import type { CardCredential } from '../instrument.js';
-import type { Contact, FillResult, FilledField } from '../types.js';
+import type { Contact, FillResult, FilledField, PostalAddress } from '../types.js';
 import { type CheckoutAdapter } from './generic.js';
 type ShopifySummary = {
     subtotalMinor: number | null;
@@ -12,10 +12,27 @@ type ShopifySummary = {
     totalMinor: number | null;
     currency: string | null;
     verified: boolean;
+    /**
+     * Component rows that never rendered and were counted as zero to reconcile
+     * the total (#8669). A summary that leans on an implied row is weaker than a
+     * fully rendered one: the row may simply not have been painted yet.
+     */
+    impliedZeroRows: Array<'tax' | 'shipping'>;
 };
 export declare function parseShopifySummary(text: string): ShopifySummary;
 export declare function readShopifyAmount(page: Page, requireVerified: boolean): Promise<PageAmountRead>;
-export declare function readStableShopifyAmount(page: Page, timeoutMs?: number): Promise<PageAmountRead>;
+/** Consecutive identical reads (200 ms apart) an implied-zero summary must hold. */
+export declare const IMPLIED_ZERO_STABLE_READS = 8;
+export type StableShopifyAmountOptions = {
+    /**
+     * A merchant-authoritative total (minor units) the page must equal before an
+     * implied-zero summary is trusted: for a trusted UCP handoff this is the
+     * server-settled checkout total. Without it, the page must hold the same
+     * implied-zero summary for {@link IMPLIED_ZERO_STABLE_READS} reads.
+     */
+    expectedMinor?: number | null;
+};
+export declare function readStableShopifyAmount(page: Page, timeoutMs?: number, options?: StableShopifyAmountOptions): Promise<PageAmountRead>;
 export declare function isShopifyCheckoutPage(page: Page): Promise<boolean>;
 export type ShopifyCheckoutSurface = {
     signal: string;
@@ -56,6 +73,7 @@ export declare function assertShopifyGuestCheckout(page: Page): Promise<ShopifyG
  * presentation-only: swapping it keeps the same checkout session and token.
  */
 export declare function shopifyEnglishCheckoutUrl(current: string): string | null;
+export declare function requiredAddressRoles(address: PostalAddress, prefix?: string): string[];
 export declare function missingContactRoles(filled: FilledField[], expected: string[]): string[];
 /**
  * The contact surface to prefill. Shipping fields when the checkout has them —

package/dist/checkout-engine/adapters/shopify.js

@@ -6,10 +6,22 @@ import { minorFromDecimal, pageCurrency } from '../amount.js';
 import { detectFields, } from '../detect.js';
 import { fillContactFieldMap, fillFieldMap } from './generic.js';
 const SUMMARY_LABELS = /^(Subtotal|Shipping|Estimated taxes|Taxes|Tax|Discounts?|Total)(?:\s*:?\s+((?:[A-Z]{3}\s+)?-?[$€£]?\s*\d[\d.,]*|Free))?$/i;
+// A row whose value has not been computed yet. Shopify phrases it several
+// ways; every one of them means "not a number", never "zero".
+const PENDING_VALUE = /calculated at (?:the )?next step|enter (?:a |your )?shipping address|calculating|getting rates|pending/i;
 function valueAfterLabel(lines, index, inline) {
     if (inline)
         return inline;
-    return lines.slice(index + 1, index + 4).find((line) => /\d|free/i.test(line)) ?? '';
+    for (const line of lines.slice(index + 1, index + 4)) {
+        // Never borrow a later row's number: the scan stops at the next label and
+        // a pending phrase ends it with no value (#8669: "Shipping / Calculated at
+        // next step / Total / $1.50" used to read shipping as $1.50).
+        if (SUMMARY_LABELS.test(line) || PENDING_VALUE.test(line))
+            return '';
+        if (/\d|free/i.test(line))
+            return line;
+    }
+    return '';
 }
 export function parseShopifySummary(text) {
     const lines = text
@@ -53,12 +65,33 @@ export function parseShopifySummary(text) {
     // checkout, value or not, and discount already defaults to 0 — only the
     // additive components force reconciliation.
     const componentLabelPresent = [...values.keys()].some((key) => key !== 'total' && key !== 'discount' && key !== 'discounts');
+    // Shopify omits a component row entirely when its value is zero: a tax-free
+    // destination renders no "Taxes" line and a free-shipping order can render no
+    // "Shipping" line (observed live 2026-09-02, #8669: a settled Colorado
+    // checkout showed Subtotal + Shipping = Total with no tax row and refused as
+    // unreadable). A row that is absent may only ever count as zero when the
+    // rows that ARE present reconcile exactly to the total; a pending
+    // "Calculated at next step" still parses as null and still refuses.
+    const rowAbsent = (...keys) => keys.every((key) => !values.has(key));
+    const taxAbsent = rowAbsent('estimated taxes', 'taxes', 'tax');
+    const shippingAbsent = rowAbsent('shipping');
+    const reconciles = (shipping, tax) => subtotalMinor != null &&
+        shipping != null &&
+        tax != null &&
+        totalMinor != null &&
+        subtotalMinor + shipping + tax - discountMinor === totalMinor;
+    // A row that rendered with a pending or unreadable value is present-and-null
+    // and always refuses; only a row that never rendered at all may imply zero.
+    const fullyReconciled = reconciles(shippingMinor, taxMinor);
+    const impliedZeroRows = [];
+    if (componentLabelPresent && !fullyReconciled) {
+        if (taxAbsent && reconciles(shippingMinor, 0))
+            impliedZeroRows.push('tax');
+        else if (shippingAbsent && reconciles(0, taxMinor))
+            impliedZeroRows.push('shipping');
+    }
     const verified = componentLabelPresent
-        ? subtotalMinor != null &&
-            shippingMinor != null &&
-            taxMinor != null &&
-            totalMinor != null &&
-            subtotalMinor + shippingMinor + taxMinor - discountMinor === totalMinor
+        ? fullyReconciled || impliedZeroRows.length > 0
         : totalMinor != null;
     return {
         subtotalMinor,
@@ -68,6 +101,7 @@ export function parseShopifySummary(text) {
         totalMinor,
         currency: pageCurrency(totalText ?? ''),
         verified,
+        impliedZeroRows,
     };
 }
 export async function readShopifyAmount(page, requireVerified) {
@@ -89,24 +123,46 @@ export async function readShopifyAmount(page, requireVerified) {
         amountMinor: summary.totalMinor,
         currency: summary.currency,
         source: 'shopify-summary',
+        ...(summary.impliedZeroRows.length > 0 ? { impliedZeroRows: summary.impliedZeroRows } : {}),
     };
 }
-export async function readStableShopifyAmount(page, timeoutMs = 6_000) {
+/** Consecutive identical reads (200 ms apart) an implied-zero summary must hold. */
+export const IMPLIED_ZERO_STABLE_READS = 8;
+export async function readStableShopifyAmount(page, timeoutMs = 6_000, options = {}) {
     const startedAt = Date.now();
     let previous = '';
     let stableReads = 0;
+    let sawImpliedZeroMismatch = false;
     while (Date.now() - startedAt < timeoutMs) {
         const latest = await readShopifyAmount(page, true);
         const fingerprint = JSON.stringify(latest);
         stableReads = fingerprint === previous ? stableReads + 1 : 0;
-        if (latest.kind === 'ok' && stableReads >= 1)
-            return latest;
+        if (latest.kind === 'ok') {
+            const implied = (latest.impliedZeroRows?.length ?? 0) > 0;
+            if (!implied) {
+                if (stableReads >= 1)
+                    return latest;
+            }
+            else if (options.expectedMinor != null) {
+                // A missing tax or shipping row may be a pre-tax render (#8669). The
+                // merchant-authoritative total is the settle signal: accept the implied
+                // summary only once the page total equals it.
+                if (latest.amountMinor === options.expectedMinor && stableReads >= 1)
+                    return latest;
+                sawImpliedZeroMismatch = true;
+            }
+            else if (stableReads >= IMPLIED_ZERO_STABLE_READS) {
+                return latest;
+            }
+        }
         previous = fingerprint;
         await page.waitForTimeout(200);
     }
     return {
         kind: 'unreadable',
-        reason: 'Shopify tax and total did not settle before the review deadline',
+        reason: sawImpliedZeroMismatch
+            ? 'Shopify summary omitted a tax or shipping row and its total never matched the merchant-settled total'
+            : 'Shopify tax and total did not settle before the review deadline',
     };
 }
 export async function isShopifyCheckoutPage(page) {
@@ -565,7 +621,7 @@ function labelBillingEvidence(filled) {
         role: BILLING_ROLE_NAMES[field.role] ?? `billing:${field.role}`,
     }));
 }
-function requiredAddressRoles(address, prefix = '') {
+export function requiredAddressRoles(address, prefix = '') {
     const role = (name) => `${prefix}${prefix ? name[0].toUpperCase() + name.slice(1) : name}`;
     const regionRequired = ['US', 'CA', 'AU'].includes(address.country?.toUpperCase() ?? '');
     return [

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

@@ -11,5 +11,7 @@ export type PageAmountRead = {
     amountMinor: number;
     currency: string | null;
     source: 'page-attr' | 'page-text' | 'shopify-summary';
+    /** Shopify rows counted as zero because they never rendered (#8669). */
+    impliedZeroRows?: Array<'tax' | 'shipping'>;
 };
 export declare function readGenericPageAmount(page: Page): Promise<PageAmountRead>;

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

@@ -1,8 +1,9 @@
 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 type { MandateRefusalCode } from './mandate.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';
@@ -74,6 +75,8 @@ export declare class CheckoutReviewRefusedError extends Error {
     readonly code = "CHECKOUT_REVIEW_REFUSED";
     readonly checkoutOutcome: CheckoutOutcome;
     readonly failureCode?: CheckoutFailureCode;
+    /** Bounded mandate/trusted-identity reason (#8669); absent for other outcomes. */
+    readonly refusalCode?: MandateRefusalCode;
     readonly requiresAdapter: string[];
     readonly detectedRoles: string[];
     readonly receiptWrite: ReceiptWriteObservation;
@@ -194,6 +197,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 +393,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';
@@ -161,6 +161,8 @@ export class CheckoutReviewRefusedError extends Error {
     code = 'CHECKOUT_REVIEW_REFUSED';
     checkoutOutcome;
     failureCode;
+    /** Bounded mandate/trusted-identity reason (#8669); absent for other outcomes. */
+    refusalCode;
     requiresAdapter;
     detectedRoles;
     receiptWrite;
@@ -172,6 +174,7 @@ export class CheckoutReviewRefusedError extends Error {
         this.name = 'CheckoutReviewRefusedError';
         this.checkoutOutcome = result.outcome;
         this.failureCode = result.failureCode;
+        this.refusalCode = result.refusalCode;
         this.requiresAdapter = [...result.requiresAdapter];
         this.detectedRoles = Object.keys(result.fields);
         this.receiptWrite = receiptWrite;
@@ -207,6 +210,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 +281,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 +492,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 +606,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/executor.d.ts

@@ -1,11 +1,12 @@
 import type { Browser, BrowserContext, Page } from 'playwright-core';
 import { type FieldMap } from './detect.js';
-import { type Mandate } from './mandate.js';
+import { type Mandate, type MandateRefusalCode } from './mandate.js';
 import type { Instrument } from './instrument.js';
 import type { Contact, OtpResolver } from './types.js';
 import { EvidenceLog } from './evidence.js';
 import { type ObservedOutcome } from './outcome.js';
 import { type WebBotAuthConfig } from './web-bot-auth.js';
+import { type NavigationRedirectEvidence } from './shopify-primary-domain.js';
 export { minorFromDecimal, pageCurrency } from './amount.js';
 export type CheckoutMode = 'dry-run' | 'submit';
 export type CheckoutRoute = 'guest-card';
@@ -53,6 +54,8 @@ export type CheckoutResult = {
     credentialLifecycle: CredentialLifecycle;
     credentialTiming: CredentialTiming;
     failureCode?: CheckoutFailureCode;
+    /** Bounded reason behind a `blocked-by-mandate` outcome; absent otherwise. */
+    refusalCode?: MandateRefusalCode;
     detail?: string;
 };
 export type PrepareCheckoutOptions = {
@@ -190,7 +193,34 @@ export declare class InMemoryPreparedCheckoutStore implements PreparedCheckoutSe
     private scheduleReaper;
     private closeState;
 }
+export type TrustedOriginVerdict = Readonly<{
+    code: MandateRefusalCode;
+    reason: string;
+}>;
+export declare function trustedMerchantOriginVerdict(options: PrepareCheckoutOptions, pageUrl: string, expectedOrigin?: string): TrustedOriginVerdict | null;
 export declare function trustedMerchantOriginRefusal(options: PrepareCheckoutOptions, pageUrl: string, expectedOrigin?: string): string | null;
+/**
+ * Bind the storefront a trusted UCP continuation actually lands on (#8669).
+ *
+ * The merchant published its UCP business profile at its own business origin
+ * and declared the permanent `*.myshopify.com` service that issued the
+ * continuation; the CLI verified both before minting the handoff. That is
+ * independently verified merchant provenance, so the review may bind the final
+ * page origin when, and only when: the navigation started on that declared
+ * myshopify origin, the final origin is plain HTTPS, and its host is the
+ * declared business host modulo a leading `www.` label. The redirect chain in
+ * between (Shopify's primary-domain hop, its shop.app bounce, #8496) carries no
+ * authority either way: a redirect cannot land on the merchant's own business
+ * domain unless the merchant controls it, and any other final host stays an
+ * undeclared origin. Shopify's `primary_domain_redirection` proof is recorded
+ * as evidence when present but is not required.
+ */
+export declare function trustedShopifyAliasOrigin(args: {
+    allowedOrigins: readonly string[];
+    initialUrl: string;
+    finalUrl: string;
+    redirects: readonly NavigationRedirectEvidence[];
+}): string | null;
 export declare function reconcileHeldOutcome(original: ObservedOutcome, held: ObservedOutcome): ObservedOutcome;
 export declare function debugShotMaskPlan(fields: FieldMap): {
     skipReason: string | null;