@visa/cli 4.1.0-rc.298 → 4.1.0-rc.299

package/dist/checkout-engine/executor.js

@@ -1,1837 +0,0 @@
-// Executor. The explicit confirmation path is split into two phases:
-//   prepareCheckout(): navigate -> stabilize -> mandate gate -> resolve the
-//   review facts. No credential is requested or filled in this phase.
-//   submitApprovedCheckout(): verify the approval is bound to that review ->
-//   revalidate -> in dry-run stop without requesting a credential; in submit
-//   mode mint -> fill -> revalidate -> submit.
-//
-// runCheckout() remains the one-shot, auto-approved compatibility wrapper.
-//
-// Two-phase mandate gate:
-//   - The PRE-FILL gate (structure, expiry, merchant host, asserted currency)
-//     runs before instrument.getCredential(). No credential is minted and no
-//     field is filled on a page the mandate does not cover.
-//   - The PRE-SUBMIT gate re-runs the full check with the resolved amount and
-//     currency. No submit ever happens without it passing. Dry-run requests no
-//     credential and neither fills fields nor clicks submit.
-import { randomUUID } from 'node:crypto';
-import { mkdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { detectFields } from './detect.js';
-import { checkMandate, checkMandatePreFill, } from './mandate.js';
-import { EvidenceLog, maskOtp } from './evidence.js';
-import { observeOutcome } from './outcome.js';
-import { selectAdapter } from './adapters/index.js';
-import { summarizeFillFailure } from './adapters/generic.js';
-import { traceHandleFields } from './trace-handles.js';
-import { readGenericPageAmount } from './amount.js';
-import { webBotAuthHeadersOrNone } from './web-bot-auth.js';
-import { assertShopifyGuestCheckout, ensureShopifyGuestCheckout, isShopifyCheckoutPage, readShopifyAmount, readStableShopifyAmount, shopifyEnglishCheckoutUrl, } from './adapters/shopify.js';
-import { navigationRedirectEvidence, shopifyPrimaryDomainAlias, } from './shopify-primary-domain.js';
-export { minorFromDecimal, pageCurrency } from './amount.js';
-const SUBMIT_TEXT = /pay|place order|complete|buy|submit|checkout/i;
-const REVEAL_TEXT = /continue|next|proceed|review|go to payment/i;
-// Post-submit confirmed/declined/challenge signals live in outcome.ts
-// (classifyOutcomePage).
-async function waitForStableDom(page) {
-    await page.waitForLoadState('domcontentloaded').catch(() => { });
-    // networkidle is best-effort and bounded: a keep-alive socket or a slow PSP
-    // asset can keep it from ever firing, so we never block on it.
-    await page.waitForLoadState('networkidle', { timeout: 2000 }).catch(() => { });
-}
-async function settle(page) {
-    await page.waitForTimeout(200);
-    await page.waitForLoadState('networkidle', { timeout: 1500 }).catch(() => { });
-}
-async function tryReveal(page, evidence, clicked) {
-    // 1) A payment-method radio for card/credit/debit (accordion layouts).
-    const radios = page.locator('input[type="radio"]');
-    const rn = await radios.count().catch(() => 0);
-    for (let i = 0; i < rn; i++) {
-        const r = radios.nth(i);
-        const value = ((await r.getAttribute('value').catch(() => '')) || '').toLowerCase();
-        const id = (await r.getAttribute('id').catch(() => '')) || '';
-        let labelText = '';
-        if (id) {
-            labelText = ((await page
-                .locator(`label[for="${id}"]`)
-                .first()
-                .textContent()
-                .catch(() => '')) || '').toLowerCase();
-        }
-        if (/card|credit|debit/.test(`${value} ${labelText}`)) {
-            const key = `radio:${i}`;
-            if (!clicked.has(key)) {
-                await r.check().catch(() => { });
-                clicked.add(key);
-                evidence.step('reveal', { action: 'select-card-payment-method', index: i });
-                return true;
-            }
-        }
-    }
-    // 2) A continue/next/proceed control (multi-step layouts).
-    const btn = page.getByRole('button', { name: REVEAL_TEXT }).first();
-    const hasBtn = (await btn.count().catch(() => 0)) > 0;
-    if (hasBtn) {
-        const label = ((await btn.textContent().catch(() => '')) || '').trim();
-        // Never reveal-click an effective submit control: a bare <button>Continue
-        // inside a <form> is an implicit type="submit" (findSubmit only matches
-        // explicit [type=submit] + SUBMIT_TEXT, so it is never fingerprinted as
-        // the submit target), and clicking it would POST the form — bypassing the
-        // pre-submit mandate gate and the dry-run never-submits contract. Unknown
-        // (evaluate failed) is treated as would-submit: fail closed, don't click.
-        const wouldSubmit = await btn
-            .evaluate((el) => {
-            const control = el;
-            const type = (control.type || '').toLowerCase();
-            return Boolean(control.form) && (type === 'submit' || type === '');
-        })
-            .catch(() => true);
-        if (wouldSubmit) {
-            evidence.step('reveal', { action: 'skip-submit-control', label });
-            return false;
-        }
-        const key = `reveal-btn:${label}`;
-        if (!clicked.has(key)) {
-            await btn.click().catch(() => { });
-            clicked.add(key);
-            evidence.step('reveal', { action: 'advance-step', label });
-            return true;
-        }
-    }
-    return false;
-}
-async function fingerprintSubmitTarget(locator, kind, fallbackLabel) {
-    return locator.evaluate((element, { targetKind, targetFallbackLabel }) => {
-        const control = element;
-        const form = control.form ?? null;
-        const label = (control.textContent ?? '').trim() ||
-            (control.value ?? '').trim() ||
-            (control.getAttribute('aria-label') ?? '').trim() ||
-            targetFallbackLabel;
-        const formAction = control.getAttribute('formaction') || form?.action || null;
-        const formMethod = control.getAttribute('formmethod') || form?.method || null;
-        const formTarget = control.getAttribute('formtarget') || form?.target || null;
-        return {
-            kind: targetKind,
-            label,
-            elementTag: control.tagName.toLowerCase(),
-            elementId: control.id || null,
-            elementName: control.getAttribute('name') || null,
-            elementType: control.getAttribute('type')?.toLowerCase() || null,
-            formAction,
-            formMethod: formMethod?.toUpperCase() || null,
-            formTarget: formTarget || null,
-        };
-    }, { targetKind: kind, targetFallbackLabel: fallbackLabel });
-}
-// Shopify checkouts keep INERT duplicates of the pay control in the DOM —
-// aria-hidden="true", tabindex="-1", and/or zero-size. Playwright still reports
-// those as "visible, enabled and stable", so a bare `.first()` resolves to one
-// and then every click is swallowed by whatever paints on top of it
-// (observed live: `<h3 id="billingAddress"> intercepts pointer events`, retried
-// until the 6s timeout, deterministically, on casper.com). Rank the real
-// controls ahead of the inert ones and prefer a pay-labelled control.
-export function preferredSubmitIndex(cands, opts = {}) {
-    const indexed = cands.map((c, i) => ({ c, i }));
-    const usable = indexed.filter(({ c }) => c.visible && !c.ariaHidden && c.tabIndex !== -1 && c.area > 0);
-    const usablePayLike = usable.find(({ c }) => PAY_LABEL.test(c.label));
-    if (usablePayLike)
-        return usablePayLike.i;
-    if (!opts.allowDeferred)
-        return usable[0]?.i ?? -1;
-    // A genuine multi-step checkout can keep its final submit control inside a
-    // hidden payment section until a safe, non-submit Continue button advances
-    // the page. The human still needs that exact control bound into the review
-    // before approval. Accept it for fingerprinting only when it is not marked
-    // inert; the pre-click lookup remains strict and will refuse unless the same
-    // control becomes visible and has non-zero area after reveal.
-    const deferred = indexed.filter(({ c }) => !c.ariaHidden && c.tabIndex !== -1);
-    if (deferred.length === 0)
-        return -1;
-    const deferredPayLike = deferred.find(({ c }) => PAY_LABEL.test(c.label));
-    return (deferredPayLike ?? usable[0] ?? deferred[0]).i;
-}
-const PAY_LABEL = /pay|place order|complete order|submit order|buy now/i;
-async function findSubmit(page, opts = {}) {
-    const controls = page.locator('button[type="submit"], input[type="submit"]');
-    const handles = await controls.all().catch(() => []);
-    if (handles.length > 0) {
-        const metas = await Promise.all(handles.map(async (h) => {
-            const text = ((await h.textContent().catch(() => '')) || '').trim();
-            const value = text || (await h.getAttribute('value').catch(() => '')) || '';
-            const ariaHidden = await h.getAttribute('aria-hidden').catch(() => null);
-            const tabIndexRaw = await h.getAttribute('tabindex').catch(() => null);
-            const visible = await h.isVisible().catch(() => false);
-            const box = await h.boundingBox().catch(() => null);
-            return {
-                label: value,
-                ariaHidden: ariaHidden === 'true',
-                tabIndex: tabIndexRaw === null ? null : Number(tabIndexRaw),
-                visible,
-                area: box ? box.width * box.height : 0,
-            };
-        }));
-        const idx = preferredSubmitIndex(metas, opts);
-        if (idx >= 0) {
-            const chosen = handles[idx];
-            const label = metas[idx].label || 'submit';
-            return {
-                desc: `submit button ("${label}")`,
-                fingerprint: await fingerprintSubmitTarget(chosen, 'submit-control', 'submit'),
-                click: () => chosen.click(),
-            };
-        }
-    }
-    const byText = page.getByRole('button', { name: SUBMIT_TEXT }).first();
-    if ((await byText.count().catch(() => 0)) > 0) {
-        const label = ((await byText.textContent().catch(() => '')) || '').trim();
-        return {
-            desc: `text button ("${label}")`,
-            fingerprint: await fingerprintSubmitTarget(byText, 'text-button', 'button'),
-            click: () => byText.click(),
-        };
-    }
-    return null;
-}
-// The diagnostic snapshot records the page ORIGIN only, never the full URL: a
-// payment-session path/query (e.g. a live Stripe `cs_live_...` checkout-session
-// id) must not be retained in the local receipt, which elsewhere promises
-// "hostname only" (#7101). Falls back to the raw value only if it does not parse
-// as a URL (never a real page.url()).
-export function snapshotOrigin(rawUrl) {
-    try {
-        return new URL(rawUrl).origin;
-    }
-    catch {
-        return '';
-    }
-}
-async function snapshotSummary(page) {
-    const info = await page
-        .evaluate(() => {
-        const heading = document.querySelector('h1, h2, [role="heading"]');
-        const body = (document.body?.innerText || '').replace(/\s+/g, ' ').trim().slice(0, 240);
-        return { title: document.title, heading: heading?.textContent?.trim() || '', body };
-    })
-        .catch(() => ({ title: '', heading: '', body: '' }));
-    return `url=${snapshotOrigin(page.url())} title="${info.title}" heading="${info.heading}" body="${info.body}"`;
-}
-async function readConfirmationRef(page) {
-    const ref = await page
-        .locator('#order-ref, [data-order-ref]')
-        .first()
-        .textContent()
-        .catch(() => null);
-    if (ref && ref.trim())
-        return ref.trim();
-    const body = (await page.textContent('body').catch(() => '')) || '';
-    // "Order #…" is the classic phrasing; Shopify-style thank-you pages say
-    // "Confirmation #…" instead.
-    const m = body.match(/(?:order|confirmation)\s*#\s*([A-Za-z0-9-]+)/i);
-    return m ? m[1] : undefined;
-}
-export const DEFAULT_PREPARED_CHECKOUT_TTL_MS = 5 * 60 * 1000;
-export const DEFAULT_PREPARED_CHECKOUT_CLEANUP_RETRY_MS = 5_000;
-// M0 keeps live Playwright handles in one process, but keys them by the public
-// review ID so the prepare and approval calls do not depend on object identity.
-// The interface is injectable; a control-plane implementation can replace this
-// store without changing submit/cancel call signatures.
-export class InMemoryPreparedCheckoutStore {
-    entries = new Map();
-    cleanupPending = new Map();
-    ttlMs;
-    cleanupRetryMs;
-    now;
-    reaper = null;
-    constructor(options = {}) {
-        this.ttlMs = options.ttlMs ?? DEFAULT_PREPARED_CHECKOUT_TTL_MS;
-        this.cleanupRetryMs = options.cleanupRetryMs ?? DEFAULT_PREPARED_CHECKOUT_CLEANUP_RETRY_MS;
-        this.now = options.now ?? Date.now;
-        if (!Number.isFinite(this.ttlMs) || this.ttlMs <= 0) {
-            throw new Error('prepared checkout ttlMs must be a positive finite number');
-        }
-        if (!Number.isFinite(this.cleanupRetryMs) || this.cleanupRetryMs <= 0) {
-            throw new Error('prepared checkout cleanupRetryMs must be a positive finite number');
-        }
-    }
-    put(reviewId, state) {
-        if (reviewId !== state.checkout.review.id) {
-            throw new Error('prepared checkout store key must match its review ID');
-        }
-        if (this.entries.has(reviewId) || this.cleanupPending.has(reviewId)) {
-            throw new Error(`prepared checkout already exists for review ${reviewId}`);
-        }
-        this.entries.set(reviewId, { state, expiresAtMs: this.now() + this.ttlMs });
-        this.scheduleReaper();
-    }
-    take(reviewId) {
-        const entry = this.entries.get(reviewId);
-        if (!entry)
-            return undefined;
-        this.entries.delete(reviewId);
-        this.scheduleReaper();
-        if (entry.expiresAtMs <= this.now()) {
-            this.queueCleanup(reviewId, entry.state, 'prepared checkout expired before it was consumed', this.now());
-            void this.reapExpired();
-            return undefined;
-        }
-        return entry.state;
-    }
-    // Intended for diagnostics and deterministic tests. Production submission
-    // still consumes through take(), preserving single-use behavior.
-    peek(reviewId) {
-        return this.entries.get(reviewId)?.state;
-    }
-    pendingCleanupReviewIds() {
-        return [...this.cleanupPending.keys()];
-    }
-    async reapExpired(nowMs = this.now()) {
-        let expiredCount = 0;
-        for (const [reviewId, entry] of this.entries) {
-            if (entry.expiresAtMs > nowMs)
-                continue;
-            this.entries.delete(reviewId);
-            this.queueCleanup(reviewId, entry.state, 'prepared checkout expired before approval or cancellation', nowMs);
-            expiredCount += 1;
-        }
-        const due = [...this.cleanupPending.entries()].filter(([, entry]) => entry.retryAtMs <= nowMs);
-        await Promise.all(due.map(async ([reviewId, entry]) => {
-            // Prevent a concurrent reap from starting a second close attempt.
-            entry.retryAtMs = Number.POSITIVE_INFINITY;
-            const recordApproval = !entry.approvalRecorded;
-            entry.approvalRecorded = true;
-            const closed = await this.closeState(entry.state, entry.reason, recordApproval);
-            if (closed) {
-                this.cleanupPending.delete(reviewId);
-            }
-            else if (this.cleanupPending.get(reviewId) === entry) {
-                entry.retryAtMs = nowMs + this.cleanupRetryMs;
-            }
-        }));
-        this.scheduleReaper();
-        return expiredCount;
-    }
-    async dispose() {
-        if (this.reaper)
-            clearTimeout(this.reaper);
-        this.reaper = null;
-        const states = [
-            ...[...this.entries.values()].map((entry) => ({
-                state: entry.state,
-                reason: 'prepared checkout store disposed',
-            })),
-            ...[...this.cleanupPending.values()].map((entry) => ({
-                state: entry.state,
-                reason: entry.reason,
-            })),
-        ];
-        this.entries.clear();
-        this.cleanupPending.clear();
-        await Promise.all(states.map(({ state, reason }) => this.closeState(state, reason, true)));
-    }
-    queueCleanup(reviewId, state, reason, retryAtMs) {
-        if (this.cleanupPending.has(reviewId))
-            return;
-        this.cleanupPending.set(reviewId, {
-            state,
-            reason,
-            retryAtMs,
-            approvalRecorded: false,
-        });
-    }
-    scheduleReaper() {
-        if (this.reaper)
-            clearTimeout(this.reaper);
-        this.reaper = null;
-        let nextExpiry = Number.POSITIVE_INFINITY;
-        for (const entry of this.entries.values()) {
-            nextExpiry = Math.min(nextExpiry, entry.expiresAtMs);
-        }
-        for (const entry of this.cleanupPending.values()) {
-            nextExpiry = Math.min(nextExpiry, entry.retryAtMs);
-        }
-        if (!Number.isFinite(nextExpiry))
-            return;
-        const delay = Math.max(0, Math.min(nextExpiry - this.now(), 2_147_483_647));
-        this.reaper = setTimeout(() => {
-            this.reaper = null;
-            void this.reapExpired();
-        }, delay);
-        this.reaper.unref();
-    }
-    async closeState(state, reason, recordApproval) {
-        if (recordApproval) {
-            state.evidence.step('approval', {
-                approved: false,
-                reviewId: state.checkout.review.id,
-                reason,
-            });
-        }
-        try {
-            await state.context.close();
-            return true;
-        }
-        catch (error) {
-            state.evidence.step('note', {
-                phase: 'prepared-session-cleanup',
-                reviewId: state.checkout.review.id,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            return false;
-        }
-    }
-}
-const defaultPreparedCheckoutStore = new InMemoryPreparedCheckoutStore();
-function unknownPreparedCheckoutResult(reviewId) {
-    const evidence = new EvidenceLog();
-    const detail = 'prepared checkout is unknown, expired, or already consumed';
-    evidence.step('approval', { approved: false, reviewId, reason: detail });
-    return makeResult('failed', {}, evidence, [], detail);
-}
-function makeResult(outcome, fields, evidence, requiresAdapter, detail, confirmationRef, failureCode, refusalCode) {
-    const steps = evidence.getSteps();
-    const approved = steps.find((step) => step.type === 'approval' && step.data.approved === true);
-    const minted = steps.find((step) => step.type === 'credential-minted');
-    const completed = steps.find((step) => step.type === 'fill-complete');
-    const filledRoles = new Set(steps
-        .filter((step) => step.type === 'field-fill' && step.data.ok === true)
-        .map((step) => String(step.data.role)));
-    const fullyFilled = filledRoles.has('number') &&
-        filledRoles.has('cvc') &&
-        (filledRoles.has('expCombined') || (filledRoles.has('expMonth') && filledRoles.has('expYear')));
-    const credentialLifecycle = !minted
-        ? 'not-requested'
-        : fullyFilled
-            ? 'fully-filled'
-            : filledRoles.has('number') || filledRoles.has('cvc')
-                ? 'partially-exposed'
-                : 'minted-not-exposed';
-    const terminalFailureCode = failureCode ??
-        (outcome === 'action-required'
-            ? 'human-action-required'
-            : outcome === 'blocked-by-mandate'
-                ? 'mandate-blocked'
-                : undefined);
-    return {
-        outcome,
-        fields,
-        evidence,
-        requiresAdapter: [...requiresAdapter],
-        credentialLifecycle,
-        credentialTiming: {
-            ...(approved ? { approvedAt: approved.ts } : {}),
-            ...(minted ? { credentialMintedAt: minted.ts } : {}),
-            ...(typeof minted?.data.credentialExpiresAt === 'string'
-                ? { credentialExpiresAt: minted.data.credentialExpiresAt }
-                : {}),
-            ...(completed ? { fillCompletedAt: completed.ts } : {}),
-        },
-        ...(terminalFailureCode ? { failureCode: terminalFailureCode } : {}),
-        ...(refusalCode ? { refusalCode } : {}),
-        ...(detail ? { detail } : {}),
-        ...(confirmationRef ? { confirmationRef } : {}),
-    };
-}
-// Shopify computes shipping and tax asynchronously after the delivery address
-// lands; a settled, reconciled summary can take well over the default 6s on a
-// cold checkout. Review is free and safe to wait on; approval and pre-submit
-// keep the strict short window because they only confirm an already-settled page.
-const SHOPIFY_REVIEW_SETTLE_MS = 20_000;
-async function readTransactionFacts(page, opts, phase) {
-    const shopify = await isShopifyCheckoutPage(page);
-    const amountRead = shopify
-        ? phase === 'review'
-            ? await readStableShopifyAmount(page, SHOPIFY_REVIEW_SETTLE_MS, {
-                // A trusted UCP handoff carries the merchant-settled total; a page
-                // that omits a tax row must match it before the review trusts it.
-                expectedMinor: opts.trustedMerchantIdentity ? (opts.amountMinor ?? null) : null,
-            })
-            : await readShopifyAmount(page, true)
-        : await readGenericPageAmount(page);
-    const pageAmount = shopify && amountRead.kind === 'none'
-        ? {
-            kind: 'unreadable',
-            reason: 'Shopify final tax and total summary is not available',
-        }
-        : amountRead;
-    const amountMinor = pageAmount.kind === 'ok'
-        ? pageAmount.amountMinor
-        : pageAmount.kind === 'none'
-            ? (opts.amountMinor ?? null)
-            : null;
-    // A page-derived amount gates in the currency the page states or the
-    // caller asserts — never the mandate's by default. A caller-supplied
-    // amount is the caller's (amount, currency) pair, defaulting to the
-    // mandate currency as documented on PrepareCheckoutOptions.
-    const currency = pageAmount.kind === 'ok'
-        ? (pageAmount.currency ?? opts.currency ?? null)
-        : opts.amountMinor != null
-            ? (opts.currency ?? opts.mandate.currency)
-            : null;
-    const source = pageAmount.kind === 'ok'
-        ? pageAmount.source
-        : pageAmount.kind === 'unreadable'
-            ? 'page-unreadable'
-            : opts.amountMinor != null
-                ? 'caller'
-                : 'unknown';
-    if (amountMinor == null) {
-        return {
-            ok: false,
-            amountMinor,
-            currency,
-            source,
-            code: 'amount_unreadable',
-            reason: pageAmount.kind === 'unreadable'
-                ? (pageAmount.reason ?? 'page total is displayed but cannot be parsed unambiguously')
-                : 'transaction amount could not be determined',
-            detail: pageAmount.kind === 'unreadable'
-                ? `transaction amount could not be determined (${pageAmount.reason ?? 'page total present but ambiguous'}); refusing fail-closed`
-                : 'transaction amount could not be determined (no readable page total, no amountMinor provided); refusing fail-closed',
-        };
-    }
-    if (currency == null) {
-        return {
-            ok: false,
-            amountMinor,
-            currency,
-            source,
-            code: 'currency_unreadable',
-            reason: 'transaction currency could not be determined',
-            detail: 'transaction currency could not be determined (page total does not state one unambiguously, no currency asserted by the caller); refusing fail-closed',
-        };
-    }
-    return { ok: true, amountMinor, currency, source };
-}
-function recordTransactionFacts(evidence, phase, facts) {
-    evidence.step('note', {
-        phase,
-        amountSource: facts.source,
-        amountMinor: facts.amountMinor,
-        currency: facts.currency,
-    });
-}
-function reviewChangeReason(review, merchantHost, facts, merchantOrigin) {
-    if (review.merchantOrigin && merchantOrigin !== review.merchantOrigin) {
-        return `merchant origin changed after review: ${review.merchantOrigin} -> ${merchantOrigin ?? 'invalid'}`;
-    }
-    if (merchantHost !== review.merchantHost) {
-        return `merchant changed after review: ${review.merchantHost} -> ${merchantHost}`;
-    }
-    if (facts.amountMinor !== review.amountMinor) {
-        return `amount changed after review: ${review.amountMinor} -> ${facts.amountMinor} (minor units)`;
-    }
-    if (facts.currency.toUpperCase() !== review.currency.toUpperCase()) {
-        return `currency changed after review: ${review.currency} -> ${facts.currency}`;
-    }
-    return null;
-}
-function exactOrigin(value) {
-    try {
-        const url = new URL(value);
-        if (url.protocol !== 'https:' || url.username || url.password)
-            return null;
-        return url.origin.toLowerCase();
-    }
-    catch {
-        return null;
-    }
-}
-export function trustedMerchantOriginVerdict(options, pageUrl, expectedOrigin) {
-    const identity = options.trustedMerchantIdentity;
-    if (!identity)
-        return null;
-    if (Date.parse(identity.expiresAt) <= Date.now()) {
-        return { code: 'trusted_handoff_expired', reason: 'trusted UCP checkout handoff expired' };
-    }
-    const origin = exactOrigin(pageUrl);
-    if (!origin) {
-        return {
-            code: 'trusted_origin_insecure',
-            reason: 'trusted UCP checkout reached a non-HTTPS or credentialed origin',
-        };
-    }
-    if (expectedOrigin) {
-        return origin === expectedOrigin
-            ? null
-            : {
-                code: 'trusted_origin_changed',
-                reason: `merchant origin changed after review: ${expectedOrigin} -> ${origin}`,
-            };
-    }
-    return identity.allowedOrigins.includes(origin)
-        ? null
-        : {
-            code: 'trusted_origin_undeclared',
-            reason: `trusted UCP checkout reached undeclared origin ${origin}`,
-        };
-}
-export function trustedMerchantOriginRefusal(options, pageUrl, expectedOrigin) {
-    return trustedMerchantOriginVerdict(options, pageUrl, expectedOrigin)?.reason ?? null;
-}
-function wwwNormalizedHost(host) {
-    return host.toLowerCase().replace(/^www\./, '');
-}
-const MYSHOPIFY_SERVICE_HOST = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.myshopify\.com$/;
-/**
- * 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 function trustedShopifyAliasOrigin(args) {
-    let initial;
-    let final;
-    try {
-        initial = new URL(args.initialUrl);
-        final = new URL(args.finalUrl);
-    }
-    catch {
-        return null;
-    }
-    if (initial.protocol !== 'https:' || final.protocol !== 'https:')
-        return null;
-    if (final.username || final.password || final.port)
-        return null;
-    const initialHost = initial.hostname.toLowerCase();
-    const finalHost = final.hostname.toLowerCase();
-    if (!MYSHOPIFY_SERVICE_HOST.test(initialHost) || initialHost === finalHost)
-        return null;
-    // A declared origin is held to the same standard as the final one: plain
-    // HTTPS, default port, no credentials. Anything else never contributes a
-    // host, so the identity stays an origin set rather than widening to a host.
-    const declared = args.allowedOrigins.flatMap((candidate) => {
-        try {
-            const url = new URL(candidate);
-            return url.protocol === 'https:' && !url.username && !url.password && !url.port
-                ? [url.hostname.toLowerCase()]
-                : [];
-        }
-        catch {
-            return [];
-        }
-    });
-    if (!declared.includes(initialHost))
-        return null;
-    const declaredBusiness = declared.some((host) => host !== initialHost &&
-        !MYSHOPIFY_SERVICE_HOST.test(host) &&
-        wwwNormalizedHost(host) === wwwNormalizedHost(finalHost));
-    return declaredBusiness ? final.origin.toLowerCase() : null;
-}
-function mandateForPage(options, pageUrl) {
-    if (!options.trustedMerchantIdentity)
-        return options.mandate;
-    return { ...options.mandate, merchantHost: new URL(pageUrl).hostname };
-}
-function submitTargetChangeReason(review, current) {
-    const reviewed = review.submitTargetFingerprint;
-    if (!reviewed && !current)
-        return null;
-    if (!reviewed && current) {
-        return `submit target appeared after review: ${current.desc}`;
-    }
-    if (reviewed && !current) {
-        return `submit target disappeared after review: ${review.submitTarget ?? 'reviewed control'}`;
-    }
-    const currentFingerprint = current?.fingerprint;
-    const fingerprintChanged = reviewed?.kind !== currentFingerprint?.kind ||
-        reviewed?.label !== currentFingerprint?.label ||
-        reviewed?.elementTag !== currentFingerprint?.elementTag ||
-        reviewed?.elementId !== currentFingerprint?.elementId ||
-        reviewed?.elementName !== currentFingerprint?.elementName ||
-        reviewed?.elementType !== currentFingerprint?.elementType ||
-        reviewed?.formAction !== currentFingerprint?.formAction ||
-        reviewed?.formMethod !== currentFingerprint?.formMethod ||
-        reviewed?.formTarget !== currentFingerprint?.formTarget;
-    if (fingerprintChanged) {
-        return `submit target changed after review: ${review.submitTarget ?? 'reviewed control'} -> ${current?.desc ?? 'none'}`;
-    }
-    return null;
-}
-// Belt-and-braces static mask: generic autocomplete roles + the concrete
-// Stripe payment-link input names. This is NOT sufficient on its own — the fill
-// is heuristic and can touch inputs (e.g. `<input id="card_num" maxlength="16">`
-// detected by attr-heuristic, no autocomplete) that match none of these. The
-// authoritative mask is built per-run from the detected field entries below.
-const CREDENTIAL_MASK_SELECTOR = [
-    'input[autocomplete="cc-number"]',
-    'input[autocomplete="cc-csc"]',
-    'input[autocomplete="cc-exp"]',
-    'input[name="cardNumber"]',
-    'input[name="cardCvc"]',
-    'input[name="cardExpiry"]',
-    'input[name="cardnumber"]',
-    'input[name="cvc"]',
-    'input[name="exp-date"]',
-].join(', ');
-// Roles whose value is the credential and must NEVER reach disk.
-const CREDENTIAL_ROLES = ['number', 'cvc', 'expCombined', 'expMonth', 'expYear'];
-// Reconcile a challenge-hold's second observation with the original challenge
-// verdict. If the hold expired still-unresolved (`unknown` + last-seen
-// `action-required`), keep the ORIGINAL action-required — reporting `unknown`
-// would throw away a state we understand precisely (the exact misreport the
-// challenge hold exists to prevent). Any resolved verdict (confirmed/declined),
-// or an `unknown` whose last-seen was `processing` (challenge gone, still
-// settling), is the newer truth and wins.
-export function reconcileHeldOutcome(original, held) {
-    if (held.status === 'unknown' && held.lastSeen === 'action-required')
-        return original;
-    return held;
-}
-// Plan the screenshot mask from what detection actually resolved — the same
-// entries fillFieldMap fills — so a heuristically-detected card input is masked
-// even though it matches no static selector. Fail closed: a credential field
-// hosted inside a frame cannot be guaranteed reachable by the page-level mask,
-// so the shot is skipped entirely rather than risk writing a PAN/CVC.
-export function debugShotMaskPlan(fields) {
-    const credentialEntries = CREDENTIAL_ROLES.map((r) => fields[r]).filter((e) => Boolean(e));
-    if (credentialEntries.some((e) => e.frame)) {
-        return {
-            skipReason: 'credential field is frame-hosted — cannot guarantee mask coverage',
-            maskLocators: [],
-            maskFrames: [],
-        };
-    }
-    // Mask every detected field the agent could fill (credential AND contact —
-    // receipts are redaction-first, #5708), not only the credential roles.
-    const maskLocators = [];
-    const maskFrames = [];
-    for (const entry of Object.values(fields)) {
-        if (!entry)
-            continue;
-        if (entry.frame)
-            maskFrames.push({ frame: entry.frame, locator: entry.locator });
-        else
-            maskLocators.push(entry.locator);
-    }
-    return { skipReason: null, maskLocators, maskFrames };
-}
-// Best-effort debug screenshot — a capture failure must never affect the run.
-async function captureDebugShot(page, dir, reviewId, label, evidence, fields) {
-    try {
-        const plan = debugShotMaskPlan(fields);
-        if (plan.skipReason) {
-            evidence.step('note', { debugShot: label, skipped: plan.skipReason });
-            return;
-        }
-        await mkdir(dir, { recursive: true });
-        const path = join(dir, `${reviewId}-${label}.png`);
-        const mask = [
-            page.locator(CREDENTIAL_MASK_SELECTOR),
-            ...plan.maskLocators.map((l) => page.locator(l)),
-            ...plan.maskFrames.map((f) => page.frameLocator(f.frame).locator(f.locator)),
-        ];
-        await page.screenshot({ path, mask, maskColor: '#000000' });
-        evidence.step('note', { debugShot: label, path });
-    }
-    catch {
-        // never break a checkout for a screenshot
-    }
-}
-// Stripe Link (the wallet that pops "Confirm it's you" for an enrolled email)
-// decides to show its modal by calling the consumer-session lookup when the
-// email is entered; the follow-up start_verification is what texts the OTP.
-// Aborting the lookup suppresses the modal AND prevents the OTP from ever being
-// sent — proven by live probe on donate.stripe.com. We ALWAYS suppress Link:
-// this agent pays with the freshly minted VIC credential via the guest card
-// fields and must never route to a Link-saved card. The matched hosts are
-// Link-consumer endpoints ONLY — never the PaymentIntent confirm
-// (/v1/payment_intents/…), so the charge path is untouched.
-export function isStripeLinkConsumerRequest(url) {
-    return /(?:^|\/\/)([a-z0-9.-]*\.)?stripe\.com\/v1\/consumers\/sessions\/(?:lookup|start_verification)\b/i.test(url);
-}
-// Keyed by Page so the tracker installed at prepare time is reachable from the
-// approved-submit leg without threading through the session store types.
-const linkSuppressionByPage = new WeakMap();
-// Exported for the link-quiet unit tests (a fake Page captures the route
-// handler); production callers stay inside this module.
-export async function suppressStripeLink(page, evidence) {
-    const state = { suppressed: 0, waiters: [] };
-    linkSuppressionByPage.set(page, state);
-    await page.route((u) => isStripeLinkConsumerRequest(typeof u === 'string' ? u : u.href), (route) => {
-        state.suppressed += 1;
-        if (state.suppressed === 1) {
-            // origin + pathname only — never the full URL. The lookup carries the
-            // email in the POST body today, but keep an operator email out of the
-            // evidence log even if Stripe moves a param to the query string (#5708).
-            const u = route.request().url();
-            let safe = u;
-            try {
-                const parsed = new URL(u);
-                safe = parsed.origin + parsed.pathname;
-            }
-            catch {
-                /* keep raw if unparseable */
-            }
-            evidence.step('note', { linkSuppressed: safe });
-        }
-        for (const wake of state.waiters.splice(0))
-            wake();
-        return route.abort();
-    });
-}
-/**
- * Wait for the suppressed Stripe Link lookup to fire and settle BEFORE the
- * submit click. Stripe debounces its consumer-session lookup ~300ms after the
- * email input changes; our fill→click gap is single-digit ms, so the (aborted)
- * lookup used to land INSIDE Stripe's in-flight submit chain and kill it
- * silently — the click looked accepted but tokenization never ran and the page
- * sat on the form until the outcome deadline (#5879: three identical live
- * stalls at donate.stripe.com). Verified live A/B on that page: instant click →
- * dead submit, no /v1/payment_methods; lookup settled first → tokenization and
- * the confirm step both reached.
- *
- * If the lookup already fired, only the short settle applies (lets Stripe's
- * abort handling unwind). If it never fires — non-Link page variants, no email
- * field — the bound expires and the click proceeds as before.
- */
-export async function waitForLinkLookupQuiet(page, opts = {}) {
-    const boundMs = opts.boundMs ?? 1500;
-    const settleMs = opts.settleMs ?? 250;
-    const delay = opts.delay ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-    const state = linkSuppressionByPage.get(page);
-    if (!state)
-        return { fired: false, waitedMs: 0 };
-    const started = Date.now();
-    if (state.suppressed === 0) {
-        await Promise.race([
-            new Promise((resolve) => state.waiters.push(resolve)),
-            delay(boundMs),
-        ]);
-    }
-    const fired = state.suppressed > 0;
-    if (fired)
-        await delay(settleMs);
-    return { fired, waitedMs: Date.now() - started };
-}
-// Payer-chosen amount inputs. Deliberately payment-link-specific (Stripe's
-// customUnitAmount): on an ordinary checkout the total is merchant-controlled
-// and typing into anything price-like must never happen.
-const PAYER_AMOUNT_SELECTORS = ['input#customUnitAmount', 'input[name="customUnitAmount"]'];
-async function fillPayerChosenAmount(page, amountMinor) {
-    // money-boundary: ALLOW_BOUNDARY — the merchant's payer-facing amount input requires a decimal string
-    const amount = (amountMinor / 100).toFixed(2);
-    for (const selector of PAYER_AMOUNT_SELECTORS) {
-        const loc = page.locator(selector).first();
-        if ((await loc.count().catch(() => 0)) === 0)
-            continue;
-        try {
-            await loc.click({ timeout: 2000 });
-            await loc.fill('');
-            await loc.pressSequentially(amount, { delay: 20 });
-            await loc.blur().catch(() => { });
-            // The page reformats ("5.00" → "$5.00"); accept any readback that
-            // parses to the same minor units.
-            const readback = (await loc.inputValue().catch(() => '')) || '';
-            const parsed = Number(readback.replace(/[^0-9.]/g, ''));
-            return { present: true, filled: Math.round(parsed * 100) === amountMinor, selector, readback };
-        }
-        catch {
-            return { present: true, filled: false, selector };
-        }
-    }
-    return { present: false, filled: false };
-}
-export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore) {
-    // Snapshot the authorization inputs. The caller may retain and mutate its
-    // objects while a human is reviewing; resume must keep enforcing the exact
-    // mandate and fallback facts that produced the review.
-    const options = {
-        ...opts,
-        mandate: { ...opts.mandate },
-        ...(opts.trustedMerchantIdentity
-            ? {
-                trustedMerchantIdentity: Object.freeze({
-                    ...opts.trustedMerchantIdentity,
-                    allowedOrigins: Object.freeze([...opts.trustedMerchantIdentity.allowedOrigins]),
-                }),
-            }
-            : {}),
-    };
-    const evidence = new EvidenceLog();
-    // Pin an English locale: amount reconciliation reads the order summary by
-    // its visible labels (Subtotal/Taxes/Total), and merchants localize by
-    // Accept-Language (observed live 2026-08-16: a Shopify checkout redirected
-    // to /es-us and rendered "Impuestos estimados", so the total never parsed
-    // and the review refused fail-closed on a perfectly good checkout).
-    // Present Web Bot Auth (RFC 9421) credentials when, and only when, an
-    // operator directory is configured to resolve them. Off by default: an
-    // unresolvable signature fails verification and is worse than none. The
-    // signature covers @authority, so it is bound to the checkout host — a
-    // cross-origin redirect simply arrives unverified, never wrongly verified.
-    const webBotAuthHeaders = webBotAuthHeadersOrNone(options.webBotAuth ?? null, options.url, Date.now() / 1000);
-    const context = await options.browser.newContext({
-        locale: 'en-US',
-        ...(webBotAuthHeaders ? { extraHTTPHeaders: webBotAuthHeaders } : {}),
-    });
-    // Bound every action so a mis-detected or hidden element fails fast instead
-    // of stalling on Playwright's long default timeout.
-    context.setDefaultTimeout(6000);
-    context.setDefaultNavigationTimeout(15000);
-    const page = await context.newPage();
-    // Suppress Stripe Link before the first navigation so its consumer-session
-    // lookup never fires (no wallet modal, no OTP text). Guest-card fill — the
-    // path that carries the minted credential — is unaffected.
-    await suppressStripeLink(page, evidence);
-    const requiresAdapter = new Set();
-    let fields = {};
-    let keepOpen = false;
-    try {
-        evidence.step('navigation', {
-            url: options.trustedMerchantIdentity ? exactOrigin(options.url) : options.url,
-        });
-        const navigationResponse = await page.goto(options.url, { waitUntil: 'domcontentloaded' });
-        await waitForStableDom(page);
-        evidence.step('dom-stable', {
-            url: options.trustedMerchantIdentity ? exactOrigin(page.url()) : page.url(),
-        });
-        let merchantHost = new URL(page.url()).hostname;
-        let initialOriginVerdict = trustedMerchantOriginVerdict(options, page.url());
-        if (initialOriginVerdict?.code === 'trusted_origin_undeclared' &&
-            options.trustedMerchantIdentity) {
-            // #8669: the trusted path never got the Shopify primary-domain proof the
-            // generic path has carried since #8469, so every declared-business
-            // storefront that Shopify serves from its primary domain refused here.
-            const aliasOrigin = trustedShopifyAliasOrigin({
-                allowedOrigins: options.trustedMerchantIdentity.allowedOrigins,
-                initialUrl: options.url,
-                finalUrl: page.url(),
-                redirects: await navigationRedirectEvidence(navigationResponse),
-            });
-            if (aliasOrigin) {
-                evidence.step('note', {
-                    kind: 'shopify-primary-domain-alias',
-                    trusted: true,
-                    continuationHost: new URL(options.url).hostname,
-                    checkoutHost: new URL(aliasOrigin).hostname,
-                    shopifyProof: shopifyPrimaryDomainAlias({
-                        mandateHost: new URL(options.url).hostname,
-                        initialUrl: options.url,
-                        finalUrl: page.url(),
-                        redirects: await navigationRedirectEvidence(navigationResponse),
-                    }) !== null,
-                });
-                options.trustedMerchantIdentity = Object.freeze({
-                    ...options.trustedMerchantIdentity,
-                    allowedOrigins: Object.freeze([
-                        ...options.trustedMerchantIdentity.allowedOrigins,
-                        aliasOrigin,
-                    ]),
-                });
-                initialOriginVerdict = trustedMerchantOriginVerdict(options, page.url());
-            }
-        }
-        if (initialOriginVerdict) {
-            evidence.step('mandate-verdict', {
-                phase: 'trusted-origin',
-                ok: false,
-                reason: initialOriginVerdict.reason,
-                code: initialOriginVerdict.code,
-            });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return {
-                status: 'finished',
-                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, initialOriginVerdict.reason, undefined, undefined, initialOriginVerdict.code),
-            };
-        }
-        if (!options.trustedMerchantIdentity) {
-            const shopifyAlias = shopifyPrimaryDomainAlias({
-                mandateHost: options.mandate.merchantHost,
-                initialUrl: options.url,
-                finalUrl: page.url(),
-                redirects: await navigationRedirectEvidence(navigationResponse),
-            });
-            if (shopifyAlias) {
-                evidence.step('note', {
-                    kind: 'shopify-primary-domain-alias',
-                    mandateHost: options.mandate.merchantHost,
-                    checkoutHost: shopifyAlias,
-                });
-                // The proof is collected before any credential is minted. Bind this
-                // prepared session to Shopify's primary storefront host so every later
-                // approval and pre-submit revalidation stays strict on that host.
-                options.mandate = { ...options.mandate, merchantHost: shopifyAlias };
-            }
-        }
-        let reviewedOrigin;
-        const preFill = checkMandatePreFill(mandateForPage(options, page.url()), {
-            merchantHost,
-            currency: options.currency ?? null,
-        });
-        evidence.step('mandate-verdict', { phase: 'pre-fill', ...preFill });
-        if (!preFill.ok) {
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return {
-                status: 'finished',
-                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, preFill.reason, undefined, undefined, preFill.code),
-            };
-        }
-        // Payer-chosen amount (Stripe payment links): an empty customUnitAmount
-        // fails client-side validation at submit ("Enter an amount.") and no
-        // authorization is ever attempted. Fill the caller-approved amount BEFORE
-        // detection so review facts, mandate checks, and the submit all see the
-        // real total. Contains no credential — amount is caller-supplied config.
-        if (typeof options.amountMinor === 'number') {
-            const amountFill = await fillPayerChosenAmount(page, options.amountMinor);
-            if (amountFill.present) {
-                evidence.step('amount-fill', {
-                    ok: amountFill.filled,
-                    selector: amountFill.selector,
-                    readback: amountFill.readback,
-                });
-                if (!amountFill.filled) {
-                    evidence.setSnapshotSummary(await snapshotSummary(page));
-                    return {
-                        status: 'finished',
-                        result: makeResult('failed', fields, evidence, requiresAdapter, `payer-chosen amount field (${amountFill.selector}) did not accept the approved amount`),
-                    };
-                }
-                await waitForStableDom(page);
-            }
-        }
-        // Detection is read-only here. In particular, no adapter fill and no
-        // Instrument.getCredential() call can occur before an explicit approval.
-        let detected = await detectFields(page);
-        const shopifyPage = await isShopifyCheckoutPage(page);
-        if (shopifyPage) {
-            // Same checkout session, English presentation — the amount reader needs
-            // the English summary labels (see shopifyEnglishCheckoutUrl).
-            const englishUrl = shopifyEnglishCheckoutUrl(page.url());
-            if (englishUrl) {
-                await page.goto(englishUrl, { waitUntil: 'domcontentloaded' }).catch(() => { });
-                await waitForStableDom(page);
-                if (await isShopifyCheckoutPage(page)) {
-                    evidence.step('navigation', {
-                        url: options.trustedMerchantIdentity ? exactOrigin(page.url()) : page.url(),
-                        reason: 'shopify-locale-normalized',
-                    });
-                    detected = await detectFields(page);
-                }
-            }
-        }
-        let adapter = selectAdapter(detected, { shopify: shopifyPage });
-        if (options.contact && adapter.prepareContact) {
-            const recordPrefill = async (contact) => {
-                const result = await adapter.prepareContact(page, contact);
-                for (const field of result.filled) {
-                    evidence.step('contact-prefill', {
-                        role: field.role,
-                        confidence: field.confidence,
-                        source: field.source,
-                        frame: field.frame,
-                        value: field.value,
-                        ok: field.ok,
-                        error: field.error,
-                    });
-                }
-                return result;
-            };
-            let preparedContact = await recordPrefill(options.contact);
-            if (shopifyPage && options.checkoutRoute === 'guest-card') {
-                const guest = await ensureShopifyGuestCheckout(page);
-                evidence.step('note', {
-                    phase: 'contact-prefill',
-                    checkoutRoute: options.checkoutRoute,
-                    shopifyGuestStatus: guest.status,
-                    signal: guest.signal,
-                });
-                if (guest.status === 'action-required') {
-                    evidence.step('outcome', {
-                        outcome: 'action-required',
-                        signal: guest.signal,
-                        phase: 'contact-prefill',
-                    });
-                    evidence.setSnapshotSummary(await snapshotSummary(page));
-                    return {
-                        status: 'finished',
-                        result: makeResult('action-required', fields, evidence, requiresAdapter, guest.detail, undefined, 'human-action-required'),
-                    };
-                }
-                if (guest.status === 'transitioned') {
-                    // Do not write the recognized email a second time: Shopify can open
-                    // the same modal on every email input event. Only retry contact fill
-                    // when the takeover interrupted it, and omit email on that retry.
-                    if (!preparedContact.ok) {
-                        await settle(page);
-                        detected = await detectFields(page);
-                        adapter = selectAdapter(detected, { shopify: true });
-                        preparedContact = await recordPrefill({ ...options.contact, email: undefined });
-                    }
-                    const verifiedGuest = await assertShopifyGuestCheckout(page);
-                    if (verifiedGuest.status === 'action-required') {
-                        evidence.step('outcome', {
-                            outcome: 'action-required',
-                            signal: verifiedGuest.signal,
-                            phase: 'contact-prefill-guest-verification',
-                        });
-                        evidence.setSnapshotSummary(await snapshotSummary(page));
-                        return {
-                            status: 'finished',
-                            result: makeResult('action-required', fields, evidence, requiresAdapter, verifiedGuest.detail, undefined, 'human-action-required'),
-                        };
-                    }
-                }
-            }
-            if (!preparedContact.ok) {
-                evidence.setSnapshotSummary(await snapshotSummary(page));
-                return {
-                    status: 'finished',
-                    result: makeResult('failed', fields, evidence, requiresAdapter, preparedContact.detail ??
-                        'Shopify contact prefill did not complete; no payment credential was requested'),
-                };
-            }
-            await settle(page);
-            const prefillHost = new URL(page.url()).hostname;
-            const trustedPrefillVerdict = trustedMerchantOriginVerdict(options, page.url());
-            if (trustedPrefillVerdict || prefillHost !== merchantHost) {
-                const reason = trustedPrefillVerdict?.reason ??
-                    `merchant changed during contact prefill: ${merchantHost} -> ${prefillHost}`;
-                const code = trustedPrefillVerdict?.code ?? 'merchant_host_mismatch';
-                evidence.step('mandate-verdict', {
-                    phase: 'contact-prefill',
-                    ok: false,
-                    reason,
-                    code,
-                });
-                evidence.setSnapshotSummary(await snapshotSummary(page));
-                return {
-                    status: 'finished',
-                    result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, reason, undefined, undefined, code),
-                };
-            }
-            detected = await detectFields(page);
-            adapter = selectAdapter(detected, { shopify: shopifyPage });
-            evidence.step('adapter-selected', { adapter: adapter.name, phase: 'review' });
-        }
-        fields = detected.fields;
-        evidence.step('detect', {
-            phase: 'review',
-            attempt: 0,
-            roles: Object.keys(detected.fields),
-            psps: detected.psps,
-        });
-        for (const p of detected.psps) {
-            if (p.requiresAdapter) {
-                requiresAdapter.add(p.requiresAdapter);
-                evidence.step('psp-detected', { psp: p.psp, requiresAdapter: p.requiresAdapter });
-            }
-        }
-        // A checkout the runner cannot put a card INTO is not reviewable. Without a
-        // detected card-number field a later pay would fill nothing and dispatch
-        // whatever control the review happened to bind (observed live 2026-08-16:
-        // a Payhip storefront SEARCH form, a FastSpring "PayPal Checkout" label,
-        // and a Shopify discount-form "Submit" all reviewed clean this way — the
-        // real card fields sat in unreachable PSP iframes or an unrendered payment
-        // section). Every adapter fills from this same detection, so a missing
-        // number field here means no pay can ever succeed: refuse while it is
-        // still free.
-        if (!fields.number) {
-            const found = Object.keys(fields);
-            const reason = `no card number field detected (roles found: ${found.length ? found.join(', ') : 'none'}) — ` +
-                'the card form is likely inside a PSP iframe or behind a later step, so a credential cannot be entered on this page';
-            evidence.step('detect', { phase: 'review', missingCardNumber: true, reason });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return {
-                status: 'finished',
-                result: makeResult('failed', fields, evidence, requiresAdapter, reason, undefined, 'card-number-field-unavailable'),
-            };
-        }
-        // Contact/shipping and Shopify locale normalization may legitimately move
-        // between the exact service and business origins authorized by UCP. Freeze
-        // whichever declared origin is actually on-screen only after those
-        // credential-free steps, then require that exact origin for approval,
-        // credential fill, and submit.
-        const reviewOriginVerdict = trustedMerchantOriginVerdict(options, page.url());
-        if (reviewOriginVerdict) {
-            evidence.step('mandate-verdict', {
-                phase: 'review-origin',
-                ok: false,
-                reason: reviewOriginVerdict.reason,
-                code: reviewOriginVerdict.code,
-            });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return {
-                status: 'finished',
-                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, reviewOriginVerdict.reason, undefined, undefined, reviewOriginVerdict.code),
-            };
-        }
-        merchantHost = new URL(page.url()).hostname;
-        reviewedOrigin = options.trustedMerchantIdentity ? exactOrigin(page.url()) : undefined;
-        const facts = await readTransactionFacts(page, options, 'review');
-        recordTransactionFacts(evidence, 'review', facts);
-        if (!facts.ok) {
-            evidence.step('mandate-verdict', { phase: 'review', ok: false, reason: facts.reason });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return {
-                status: 'finished',
-                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, facts.detail, undefined, undefined, facts.code),
-            };
-        }
-        const verdict = checkMandate(mandateForPage(options, page.url()), {
-            merchantHost,
-            amountMinor: facts.amountMinor,
-            currency: facts.currency,
-        });
-        evidence.step('mandate-verdict', { phase: 'review', ...verdict });
-        if (!verdict.ok) {
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return {
-                status: 'finished',
-                result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, verdict.reason, undefined, undefined, verdict.code),
-            };
-        }
-        // Multi-step pages may expose the final submit control in a hidden section
-        // before a safe Continue reveals it. Fingerprint that exact control for the
-        // human review; the eventual click path still requires it to be usable.
-        const submit = await findSubmit(page, { allowDeferred: true });
-        const review = Object.freeze({
-            id: randomUUID(),
-            // A UCP continuation may contain a bearer-like path/query. The live page
-            // stays in the process-bound store; serializable review facts expose only
-            // the exact reviewed origin.
-            url: reviewedOrigin ?? page.url(),
-            merchantHost,
-            ...(reviewedOrigin ? { merchantOrigin: reviewedOrigin } : {}),
-            amountMinor: facts.amountMinor,
-            currency: facts.currency,
-            mandateMaxAmountMinor: options.mandate.maxAmountMinor,
-            mandateExpiresAt: options.mandate.expiresAt,
-            submitTarget: submit?.desc ?? null,
-            submitTargetFingerprint: submit ? Object.freeze({ ...submit.fingerprint }) : null,
-            detectedRoles: Object.freeze(Object.keys(fields)),
-            checkoutRoute: options.checkoutRoute,
-        });
-        evidence.step('review', {
-            reviewId: review.id,
-            merchantHost: review.merchantHost,
-            amountMinor: review.amountMinor,
-            currency: review.currency,
-            submitTarget: review.submitTarget,
-            submitTargetFingerprint: review.submitTargetFingerprint,
-            detectedRoles: review.detectedRoles,
-            checkoutRoute: review.checkoutRoute,
-        });
-        const checkout = Object.freeze({
-            review,
-            fields: Object.freeze({ ...fields }),
-            evidence,
-            requiresAdapter: Object.freeze([...requiresAdapter]),
-            checkoutRoute: options.checkoutRoute,
-        });
-        store.put(review.id, {
-            checkout,
-            context,
-            page,
-            options,
-            evidence,
-            fields,
-            requiresAdapter,
-        });
-        if (options.debugShotsDir) {
-            await captureDebugShot(page, options.debugShotsDir, checkout.review.id, '1-review', evidence, fields);
-        }
-        keepOpen = true;
-        return { status: 'ready', checkout };
-    }
-    catch (err) {
-        const detail = err.message;
-        evidence.step('outcome', { outcome: 'failed', error: detail });
-        return {
-            status: 'finished',
-            result: makeResult('failed', fields, evidence, requiresAdapter, detail),
-        };
-    }
-    finally {
-        if (!keepOpen)
-            await context.close().catch(() => { });
-    }
-}
-export async function submitApprovedCheckout(reviewId, opts, store = defaultPreparedCheckoutStore) {
-    // A prepared session is single-use even when approval validation fails.
-    const state = store.take(reviewId);
-    if (!state)
-        return unknownPreparedCheckoutResult(reviewId);
-    const { checkout } = state;
-    const { context, page, options, evidence, requiresAdapter } = state;
-    try {
-        if (reviewId !== checkout.review.id ||
-            opts.approval?.approved !== true ||
-            opts.approval.reviewId !== checkout.review.id) {
-            evidence.step('approval', {
-                approved: false,
-                reason: 'approval does not match prepared review',
-            });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('failed', state.fields, evidence, requiresAdapter, 'approval does not match prepared review');
-        }
-        // Revalidate the exact user-reviewed merchant, amount, and currency before
-        // the credential boundary. A changed checkout requires a fresh review.
-        await waitForStableDom(page);
-        const merchantHost = new URL(page.url()).hostname;
-        const approvalOriginVerdict = trustedMerchantOriginVerdict(options, page.url(), checkout.review.merchantOrigin);
-        if (approvalOriginVerdict) {
-            evidence.step('mandate-verdict', {
-                phase: 'approval-origin',
-                ok: false,
-                reason: approvalOriginVerdict.reason,
-                code: approvalOriginVerdict.code,
-            });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, approvalOriginVerdict.reason, undefined, undefined, approvalOriginVerdict.code);
-        }
-        const preFill = checkMandatePreFill(mandateForPage(options, page.url()), {
-            merchantHost,
-            currency: options.currency ?? null,
-        });
-        evidence.step('mandate-verdict', { phase: 'approval', ...preFill });
-        if (!preFill.ok) {
-            evidence.step('approval', { approved: false, reviewId: checkout.review.id });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, preFill.reason, undefined, undefined, preFill.code);
-        }
-        const approvedFacts = await readTransactionFacts(page, options, 'approval');
-        recordTransactionFacts(evidence, 'approval', approvedFacts);
-        if (!approvedFacts.ok) {
-            evidence.step('mandate-verdict', {
-                phase: 'approval',
-                ok: false,
-                reason: approvedFacts.reason,
-            });
-            evidence.step('approval', { approved: false, reviewId: checkout.review.id });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, approvedFacts.detail, undefined, undefined, approvedFacts.code);
-        }
-        const approvalVerdict = checkMandate(mandateForPage(options, page.url()), {
-            merchantHost,
-            amountMinor: approvedFacts.amountMinor,
-            currency: approvedFacts.currency,
-        });
-        evidence.step('mandate-verdict', { phase: 'approval', ...approvalVerdict });
-        if (!approvalVerdict.ok) {
-            evidence.step('approval', { approved: false, reviewId: checkout.review.id });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, approvalVerdict.reason, undefined, undefined, approvalVerdict.code);
-        }
-        const changedAtApproval = reviewChangeReason(checkout.review, merchantHost, approvedFacts, exactOrigin(page.url()) ?? undefined);
-        if (changedAtApproval) {
-            evidence.step('approval', {
-                approved: false,
-                reviewId: checkout.review.id,
-                reason: changedAtApproval,
-            });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, changedAtApproval, undefined, undefined, 'review_facts_changed');
-        }
-        // Revalidate the same future target before credential minting. This may be
-        // hidden on a multi-step checkout; the final lookup after reveal requires
-        // the reviewed control to be visible and usable before any click.
-        const approvalSubmit = await findSubmit(page, { allowDeferred: true });
-        const submitChangedAtApproval = submitTargetChangeReason(checkout.review, approvalSubmit);
-        if (submitChangedAtApproval) {
-            evidence.step('approval', {
-                approved: false,
-                reviewId: checkout.review.id,
-                reason: submitChangedAtApproval,
-            });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitChangedAtApproval, undefined, undefined, 'review_facts_changed');
-        }
-        if (opts.mode === 'submit' && !approvalSubmit) {
-            const reason = 'no submit target was available for human review';
-            evidence.step('approval', {
-                approved: false,
-                reviewId: checkout.review.id,
-                reason,
-            });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, reason);
-        }
-        evidence.step('approval', { approved: true, reviewId: checkout.review.id });
-        if (opts.mode === 'dry-run') {
-            evidence.step('credential-skipped', {
-                reason: 'dry-run stops before credential mint or merchant-page disclosure',
-            });
-            evidence.step('submit', { would: true, target: approvalSubmit?.desc ?? 'none found' });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('reviewed-dry-run', state.fields, evidence, requiresAdapter, approvalSubmit
-                ? `validated the reviewed checkout; would click ${approvalSubmit.desc}`
-                : 'validated the reviewed checkout; no submit control detected');
-        }
-        if (options.checkoutRoute === 'guest-card' && (await isShopifyCheckoutPage(page))) {
-            const guest = await assertShopifyGuestCheckout(page);
-            evidence.step('note', {
-                phase: 'pre-credential',
-                checkoutRoute: options.checkoutRoute,
-                shopifyGuestStatus: guest.status,
-                signal: guest.signal,
-            });
-            if (guest.status === 'action-required') {
-                evidence.step('outcome', {
-                    outcome: 'action-required',
-                    signal: guest.signal,
-                    phase: 'pre-credential',
-                });
-                evidence.setSnapshotSummary(await snapshotSummary(page));
-                return makeResult('action-required', state.fields, evidence, requiresAdapter, guest.detail, undefined, 'human-action-required');
-            }
-        }
-        const credential = await opts.instrument.getCredential({
-            merchantHost,
-            amountMinor: approvedFacts.amountMinor,
-            currency: approvedFacts.currency,
-        });
-        evidence.step('credential-minted', {
-            ...(credential.credentialExpiresAt
-                ? { credentialExpiresAt: credential.credentialExpiresAt }
-                : {}),
-            ...traceHandleFields(credential),
-        });
-        // Reveal + fill loop: fills whatever is present, then reveals the next
-        // surface (card radio / next step) until the card number is filled.
-        const clicked = new Set();
-        let adapterName = null;
-        let adapterFillOk = true;
-        let adapterFillDetail = null;
-        for (let attempt = 0; attempt < 4; attempt++) {
-            // A reveal/continue action can navigate between attempts. Never expose
-            // the credential to a host other than the one the human reviewed.
-            const fillHost = new URL(page.url()).hostname;
-            const fillOriginRefusal = trustedMerchantOriginRefusal(options, page.url(), checkout.review.merchantOrigin);
-            if (fillOriginRefusal ||
-                (!checkout.review.merchantOrigin && fillHost !== checkout.review.merchantHost)) {
-                const reason = fillOriginRefusal ??
-                    `merchant changed after review: ${checkout.review.merchantHost} -> ${fillHost}`;
-                evidence.step('mandate-verdict', {
-                    phase: 'approved-submit',
-                    ok: false,
-                    reason,
-                });
-                evidence.setSnapshotSummary(await snapshotSummary(page));
-                return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, reason);
-            }
-            const detected = await detectFields(page);
-            state.fields = detected.fields;
-            evidence.step('detect', {
-                phase: 'approved-submit',
-                attempt,
-                roles: Object.keys(detected.fields),
-                psps: detected.psps,
-            });
-            for (const p of detected.psps) {
-                if (p.requiresAdapter) {
-                    requiresAdapter.add(p.requiresAdapter);
-                    evidence.step('psp-detected', { psp: p.psp, requiresAdapter: p.requiresAdapter });
-                }
-            }
-            const adapter = selectAdapter(detected, {
-                shopify: await isShopifyCheckoutPage(page),
-            });
-            if (adapter.name !== adapterName) {
-                adapterName = adapter.name;
-                evidence.step('adapter-selected', { adapter: adapter.name });
-            }
-            const fill = await adapter.fill(page, detected.fields, credential, opts.contact);
-            adapterFillOk = fill.ok;
-            adapterFillDetail = fill.detail ?? null;
-            for (const f of fill.filled) {
-                evidence.step('field-fill', {
-                    role: f.role,
-                    confidence: f.confidence,
-                    source: f.source,
-                    frame: f.frame,
-                    value: f.value,
-                    ok: f.ok,
-                    error: f.error,
-                    ...(f.relocated ? { relocated: true } : {}),
-                });
-            }
-            const numberOk = fill.filled.some((f) => f.role === 'number' && f.ok);
-            if (numberOk)
-                break;
-            const revealed = await tryReveal(page, evidence, clicked);
-            if (!revealed)
-                break;
-            await settle(page);
-        }
-        const successfulRoles = new Set(evidence
-            .getSteps()
-            .filter((step) => step.type === 'field-fill' && step.data.ok === true)
-            .map((step) => String(step.data.role)));
-        const missingCredentialRoles = [
-            ...(successfulRoles.has('number') ? [] : ['number']),
-            ...(successfulRoles.has('cvc') ? [] : ['cvc']),
-            ...(successfulRoles.has('expCombined') ||
-                (successfulRoles.has('expMonth') && successfulRoles.has('expYear'))
-                ? []
-                : ['expiry']),
-        ];
-        // Roles the adapter TRIED to fill and never landed, across every reveal
-        // attempt. A job only exists when the field was detected, was visible, and
-        // we held a value for it (see `add()` in adapters/generic.ts) — so a failure
-        // here is never "the page didn't ask for it". It means the page asked, we
-        // answered, and the element refused.
-        //
-        // Roles that failed on an early attempt and succeeded after a reveal are
-        // excluded: `successfulRoles` spans all four attempts, same as above.
-        const failedFillRoles = [
-            ...new Set(evidence
-                .getSteps()
-                .filter((step) => step.type === 'field-fill' && step.data.ok === false)
-                .map((step) => String(step.data.role))),
-        ]
-            .filter((role) => !successfulRoles.has(role))
-            .sort();
-        evidence.step('fill-complete', {
-            // "Ready to submit", not "the card fields landed". Before 2026-08-17 this
-            // read only the credential roles, so a whop.com run whose city/state/
-            // postalCode all timed out recorded `ok: true` and clicked Get access on
-            // a form it knew was incomplete.
-            ok: missingCredentialRoles.length === 0 && failedFillRoles.length === 0,
-            missingCredentialRoles,
-            failedFillRoles,
-        });
-        if (options.debugShotsDir) {
-            await captureDebugShot(page, options.debugShotsDir, checkout.review.id, '2-filled', evidence, state.fields);
-        }
-        // Re-run the full gate after fill as well. Contact/shipping fields can
-        // change the total; any drift from the approved review refuses before a
-        // submit click and requires the caller to prepare a new review.
-        const submitFacts = await readTransactionFacts(page, options, 'pre-submit');
-        recordTransactionFacts(evidence, 'pre-submit', submitFacts);
-        if (!submitFacts.ok) {
-            evidence.step('mandate-verdict', {
-                phase: 'pre-submit',
-                ok: false,
-                reason: submitFacts.reason,
-            });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitFacts.detail, undefined, undefined, submitFacts.code);
-        }
-        const submitMerchantHost = new URL(page.url()).hostname;
-        const submitOriginVerdict = trustedMerchantOriginVerdict(options, page.url(), checkout.review.merchantOrigin);
-        if (submitOriginVerdict) {
-            evidence.step('mandate-verdict', {
-                phase: 'pre-submit-origin',
-                ok: false,
-                reason: submitOriginVerdict.reason,
-                code: submitOriginVerdict.code,
-            });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitOriginVerdict.reason, undefined, undefined, submitOriginVerdict.code);
-        }
-        const verdict = checkMandate(mandateForPage(options, page.url()), {
-            merchantHost: submitMerchantHost,
-            amountMinor: submitFacts.amountMinor,
-            currency: submitFacts.currency,
-        });
-        evidence.step('mandate-verdict', { phase: 'pre-submit', ...verdict });
-        if (!verdict.ok) {
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, verdict.reason, undefined, undefined, verdict.code);
-        }
-        const changedBeforeSubmit = reviewChangeReason(checkout.review, submitMerchantHost, submitFacts, exactOrigin(page.url()) ?? undefined);
-        if (changedBeforeSubmit) {
-            evidence.step('mandate-verdict', {
-                phase: 'pre-submit',
-                ok: false,
-                reason: changedBeforeSubmit,
-            });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, changedBeforeSubmit, undefined, undefined, 'review_facts_changed');
-        }
-        const submit = await findSubmit(page);
-        const submitChangedBeforeClick = submitTargetChangeReason(checkout.review, submit);
-        if (submitChangedBeforeClick) {
-            evidence.step('mandate-verdict', {
-                phase: 'pre-submit',
-                ok: false,
-                reason: submitChangedBeforeClick,
-            });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitChangedBeforeClick, undefined, undefined, 'review_facts_changed');
-        }
-        if (!adapterFillOk) {
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('failed', state.fields, evidence, requiresAdapter, adapterFillDetail ?? `${adapterName ?? 'checkout'} adapter fill incomplete`);
-        }
-        if (missingCredentialRoles.length > 0) {
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('failed', state.fields, evidence, requiresAdapter, `credential fill incomplete: missing ${missingCredentialRoles.join(', ')}`);
-        }
-        // STOP BEFORE THE CLICK when any field we tried to fill refused. Submitting
-        // a form we know is incomplete is how a PSP ends up holding a charge we
-        // cannot then confirm or account for: the 2026-08-17 whop.com run filled the
-        // card into Basis Theory iframes, watched city/state/postalCode time out at
-        // 5s each, clicked Get access anyway, and could never observe an outcome.
-        //
-        // This refusal happens BEFORE the submit click, so nothing can be charged by
-        // it — the safe direction, and the reason it is allowed to be strict. A
-        // merchant whose address widget we cannot drive now fails cleanly and
-        // retryably instead of dangerously.
-        if (failedFillRoles.length > 0) {
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            // Name the CAUSE per field, not just the field. The refusal is the only
-            // artifact that survives to the operator (a v2 receipt carries no evidence
-            // log), and "city, postalCode refused" without a reason means the next
-            // person has to reproduce a live merchant to learn anything. Each cause
-            // points at a different fix — see summarizeFillFailure.
-            //
-            // Last attempt wins: a role that failed differently across reveal passes
-            // is best described by how it failed when we finally gave up on it.
-            const lastFillError = (role) => {
-                const errors = evidence
-                    .getSteps()
-                    .filter((step) => step.type === 'field-fill' && step.data.ok === false && step.data.role === role)
-                    .map((step) => (typeof step.data.error === 'string' ? step.data.error : undefined));
-                return errors[errors.length - 1];
-            };
-            const reasons = failedFillRoles.map((role) => `${role} (${summarizeFillFailure(lastFillError(role))})`);
-            return makeResult('partial-fill', state.fields, evidence, requiresAdapter, `required field fill failed: ${reasons.join(', ')} — not submitting an incomplete form. Nothing was charged.`, undefined, 'required-field-unfillable');
-        }
-        if (!submit) {
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('failed', state.fields, evidence, requiresAdapter, 'no submit control detected');
-        }
-        // Capture the OTP poll watermark BEFORE the click. The click is what
-        // triggers the merchant's verification email, so the watermark must precede
-        // it — otherwise a fast OTP could arrive before we start looking (the 5s
-        // waitForMessage skew is a second line of defence, but ordering matters).
-        // This is just a timestamp — no PII — so it is safe to record.
-        const otpWatermark = new Date().toISOString();
-        evidence.step('note', { otpWatermarkCaptured: true });
-        // The suppressed Link lookup must settle before the click or it breaks
-        // Stripe's submit chain mid-flight (#5879) — see waitForLinkLookupQuiet.
-        const linkQuiet = await waitForLinkLookupQuiet(page);
-        evidence.step('note', { linkQuiet });
-        // This is deliberately the last await before the irreversible click.
-        // Mint-time validation is not enough: reveal/fill and Link suppression can
-        // consume a short-lived DAVV. Refuse malformed or <60s credentials so an
-        // expiry decline cannot masquerade as a form-fill failure.
-        const credentialExpiresAt = credential.credentialExpiresAt;
-        const expiryMissing = opts.instrument.kind === 'agentic-token' && credentialExpiresAt === undefined;
-        const expiresMs = credentialExpiresAt === undefined ? Number.NaN : Date.parse(credentialExpiresAt);
-        if (expiryMissing ||
-            (credentialExpiresAt !== undefined &&
-                (!Number.isFinite(expiresMs) || expiresMs - Date.now() < 60_000))) {
-            evidence.step('credential-expiry-check', {
-                ok: false,
-                reason: expiryMissing ? 'missing' : 'invalid-or-expiring',
-                ...(credentialExpiresAt !== undefined ? { credentialExpiresAt } : {}),
-            });
-            evidence.setSnapshotSummary(await snapshotSummary(page));
-            return makeResult('failed', state.fields, evidence, requiresAdapter, 'credential expired before submit; obtain a fresh intent and re-review');
-        }
-        if (credentialExpiresAt !== undefined) {
-            evidence.step('credential-expiry-check', {
-                ok: true,
-                credentialExpiresAt,
-            });
-        }
-        // ORDER IS LOAD-BEARING: record the click BEFORE performing it. The catch
-        // block classifies a throw by whether this step exists — recorded means
-        // "we may have charged" (`unverified`), absent means "retry is safe"
-        // (`failed`). Recording after `submit.click()` would let a throw raised by
-        // the click itself look retry-safe, which is the double-charge direction.
-        // Pinned by "a throw AFTER the pay control was clicked reports unverified".
-        evidence.step('submit', { clicked: true, target: submit.desc });
-        await submit.click();
-        await settle(page);
-        // Observe (poll) rather than read once: declines often render in place
-        // with no navigation, confirmations may arrive after several redirects or
-        // a processing interstitial. The observer returns the moment either
-        // definitive signal appears, or 'unknown' at the deadline.
-        let observed = await observeOutcome(page, { deadlineMs: opts.outcomeDeadlineMs });
-        if (observed.status === 'action-required' && opts.challengeHoldMs) {
-            // Opt-in human-in-the-loop: keep the challenge on screen and resume
-            // watching for the post-challenge outcome instead of ending the run
-            // (which tears down the browser and kills a live challenge).
-            evidence.step('challenge-hold', { signal: observed.signal, holdMs: opts.challengeHoldMs });
-            opts.onChallengeHold?.(observed.signal);
-            const held = await observeOutcome(page, {
-                deadlineMs: opts.challengeHoldMs,
-                holdThroughChallenge: true,
-            });
-            observed = reconcileHeldOutcome(observed, held);
-        }
-        // Agent-resolvable email OTP subroutine (SINGLE-USE). Fires only on a
-        // 'verification-required' verdict (the merchant emailed a code to the
-        // agent's own inbox) AND when a resolver is injected. Fills the code EXACTLY
-        // ONCE, re-submits, and re-observes. Merchants invalidate a code on first
-        // use, so a stale code is NEVER retried. On no resolver / timeout / missing
-        // code field it falls through to the action-required (human) path below —
-        // it never hangs and never re-fills credential material.
-        if (observed.status === 'verification-required' && opts.resolveEmailOtp) {
-            const otpDetect = await detectFields(page);
-            const codeField = otpDetect.fields.oneTimeCode;
-            if (!codeField) {
-                evidence.step('note', { emailOtp: 'no one-time-code field detected' });
-            }
-            else {
-                const resolution = await opts.resolveEmailOtp({
-                    after: otpWatermark,
-                    merchantHost: submitMerchantHost,
-                });
-                if (!resolution) {
-                    // Fail CLEAN: no code retrieved before the resolver's timeout.
-                    evidence.step('note', { emailOtp: 'not retrieved before timeout' });
-                }
-                else {
-                    // Fill once. maskOtp() ensures the code NEVER enters the evidence log
-                    // (receipt.ts's PAN backstop does not catch a 4-8 digit OTP). The
-                    // sender domain is a non-PII trust signal, safe to record.
-                    await page.locator(codeField.locator).fill(resolution.code);
-                    evidence.step('field-fill', {
-                        role: 'oneTimeCode',
-                        confidence: codeField.confidence,
-                        source: codeField.source,
-                        frame: codeField.frame,
-                        value: maskOtp(),
-                        ok: true,
-                        fromDomain: resolution.fromDomain,
-                    });
-                    const otpSubmit = await findSubmit(page);
-                    if (!otpSubmit) {
-                        evidence.step('note', { emailOtp: 'code filled but no submit control found' });
-                    }
-                    else {
-                        const otpLinkQuiet = await waitForLinkLookupQuiet(page);
-                        evidence.step('note', { linkQuiet: otpLinkQuiet, phase: 'post-otp' });
-                        evidence.step('submit', { clicked: true, target: otpSubmit.desc, phase: 'post-otp' });
-                        await otpSubmit.click();
-                        await settle(page);
-                        observed = await observeOutcome(page, { deadlineMs: opts.outcomeDeadlineMs });
-                    }
-                }
-            }
-        }
-        evidence.setSnapshotSummary(await snapshotSummary(page));
-        if (options.debugShotsDir) {
-            await captureDebugShot(page, options.debugShotsDir, checkout.review.id, '3-outcome', evidence, state.fields);
-        }
-        if (observed.status === 'declined') {
-            evidence.step('outcome', {
-                outcome: 'declined',
-                signal: observed.signal,
-                attempts: observed.attempts,
-                elapsedMs: observed.elapsedMs,
-            });
-            return makeResult('declined', state.fields, evidence, requiresAdapter, `declined (${observed.signal})`);
-        }
-        if (observed.status === 'action-required') {
-            // 3DS runs before authorization: a detected challenge means no charge
-            // exists yet and none will until a human completes it. Definitive for
-            // this run — the executor never attempts to interact with a challenge.
-            evidence.step('outcome', {
-                outcome: 'action-required',
-                signal: observed.signal,
-                attempts: observed.attempts,
-                elapsedMs: observed.elapsedMs,
-            });
-            return makeResult('action-required', state.fields, evidence, requiresAdapter, `issuer verification required (${observed.signal}) — a human must complete the challenge; no charge exists until it is completed`);
-        }
-        if (observed.status === 'verification-required') {
-            // Still needing an email code after the subroutine (no resolver injected,
-            // the code never arrived, or no code field) — hand off to a human. Mapped
-            // to the same action-required outcome; the code is single-use so we never
-            // retry here.
-            evidence.step('outcome', {
-                outcome: 'action-required',
-                signal: observed.signal,
-                reason: 'email verification code required but not auto-resolved',
-                attempts: observed.attempts,
-                elapsedMs: observed.elapsedMs,
-            });
-            return makeResult('action-required', state.fields, evidence, requiresAdapter, `email verification required (${observed.signal}) — a human must enter the code sent to the inbox`);
-        }
-        if (observed.status === 'confirmed') {
-            const confirmationRef = await readConfirmationRef(page);
-            evidence.step('outcome', {
-                outcome: 'confirmed',
-                confirmationRef,
-                signal: observed.signal,
-                attempts: observed.attempts,
-                elapsedMs: observed.elapsedMs,
-            });
-            return makeResult('confirmed', state.fields, evidence, requiresAdapter, undefined, confirmationRef);
-        }
-        // The pay control was clicked and the observer reached its deadline with no
-        // definitive answer. This is NOT a failure — it is the absence of an answer,
-        // and the charge may well have captured. Reporting it as `failed` is what
-        // let a caller re-run the 2026-08-17 whop.com purchase and draw a second $5.
-        evidence.step('outcome', {
-            outcome: 'unverified',
-            reason: 'no confirmation or decline signal',
-            lastSeen: observed.lastSeen,
-            attempts: observed.attempts,
-            elapsedMs: observed.elapsedMs,
-        });
-        return makeResult('unverified', state.fields, evidence, requiresAdapter, observed.lastSeen === 'processing'
-            ? 'submitted but outcome unknown (page still processing at deadline) — the charge may have gone through; verify with the merchant before any retry'
-            : 'submitted but outcome unknown — the charge may have gone through; verify with the merchant before any retry');
-    }
-    catch (err) {
-        const detail = err.message;
-        // A throw AFTER the pay control was clicked (browser teardown, navigation
-        // race, evidence I/O) leaves the same open question as the deadline path: we
-        // clicked, and we do not know what happened. It must not report `failed`
-        // either. A throw before the click never disclosed a payable form, so it
-        // stays a clean, retry-safe failure.
-        const submitted = evidence
-            .getSteps()
-            .some((step) => step.type === 'submit' && step.data.clicked === true);
-        if (submitted) {
-            evidence.step('outcome', { outcome: 'unverified', error: detail });
-            return makeResult('unverified', state.fields, evidence, requiresAdapter, `${detail} — the pay control was already clicked; the charge may have gone through, so verify with the merchant before any retry`);
-        }
-        evidence.step('outcome', { outcome: 'failed', error: detail });
-        return makeResult('failed', state.fields, evidence, requiresAdapter, detail);
-    }
-    finally {
-        await context.close().catch(() => { });
-    }
-}
-export async function cancelPreparedCheckout(reviewId, detail = 'checkout cancelled before approval', store = defaultPreparedCheckoutStore) {
-    const state = store.take(reviewId);
-    if (!state)
-        return unknownPreparedCheckoutResult(reviewId);
-    try {
-        state.evidence.step('approval', {
-            approved: false,
-            reviewId,
-            reason: detail,
-        });
-        state.evidence.setSnapshotSummary(await snapshotSummary(state.page));
-        return makeResult('cancelled', state.fields, state.evidence, state.requiresAdapter, detail);
-    }
-    finally {
-        await state.context.close().catch(() => { });
-    }
-}
-// Backward-compatible one-shot API. It creates the same review and immediately
-// approves that exact review ID. Human-in-the-loop callers should use the
-// explicit prepareCheckout()/submitApprovedCheckout() pair instead.
-export async function runCheckout(opts, store = defaultPreparedCheckoutStore) {
-    const { instrument, contact, mode, outcomeDeadlineMs, resolveEmailOtp, ...prepareOptions } = opts;
-    const preparation = await prepareCheckout({ ...prepareOptions, contact }, store);
-    if (preparation.status === 'finished')
-        return preparation.result;
-    return submitApprovedCheckout(preparation.checkout.review.id, {
-        approval: { approved: true, reviewId: preparation.checkout.review.id },
-        instrument,
-        contact,
-        mode,
-        outcomeDeadlineMs,
-        ...(resolveEmailOtp ? { resolveEmailOtp } : {}),
-    }, store);
-}