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

package/dist/checkout-engine/executor.js

@@ -0,0 +1,1520 @@
+// 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 { detectShopifyChallenge, isShopifyCheckoutPage, readShopifyAmount, readStableShopifyAmount, shopifyEnglishCheckoutUrl, } from './adapters/shopify.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) {
+    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 } : {}),
+        ...(detail ? { detail } : {}),
+        ...(confirmationRef ? { confirmationRef } : {}),
+    };
+}
+async function readTransactionFacts(page, opts, phase) {
+    const shopify = await isShopifyCheckoutPage(page);
+    const amountRead = shopify
+        ? phase === 'review'
+            ? await readStableShopifyAmount(page)
+            : 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,
+            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,
+            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) {
+    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 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 },
+    };
+    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.url });
+        await page.goto(options.url, { waitUntil: 'domcontentloaded' });
+        await waitForStableDom(page);
+        evidence.step('dom-stable', { url: page.url() });
+        const merchantHost = new URL(page.url()).hostname;
+        const preFill = checkMandatePreFill(options.mandate, {
+            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),
+            };
+        }
+        // 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: page.url(), reason: 'shopify-locale-normalized' });
+                    detected = await detectFields(page);
+                }
+            }
+        }
+        let adapter = selectAdapter(detected, { shopify: shopifyPage });
+        if (options.contact && adapter.prepareContact) {
+            const preparedContact = await adapter.prepareContact(page, options.contact);
+            for (const field of preparedContact.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,
+                });
+            }
+            const challenge = await detectShopifyChallenge(page);
+            if (challenge) {
+                evidence.step('outcome', {
+                    outcome: 'action-required',
+                    signal: challenge.signal,
+                    phase: 'contact-prefill',
+                });
+                evidence.setSnapshotSummary(await snapshotSummary(page));
+                return {
+                    status: 'finished',
+                    result: makeResult('action-required', fields, evidence, requiresAdapter, `Shop Pay verification requires a human before review (${challenge.signal}); no payment credential was requested`),
+                };
+            }
+            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;
+            if (prefillHost !== merchantHost) {
+                const reason = `merchant changed during contact prefill: ${merchantHost} -> ${prefillHost}`;
+                evidence.step('mandate-verdict', {
+                    phase: 'contact-prefill',
+                    ok: false,
+                    reason,
+                });
+                evidence.setSnapshotSummary(await snapshotSummary(page));
+                return {
+                    status: 'finished',
+                    result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, reason),
+                };
+            }
+            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'),
+            };
+        }
+        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),
+            };
+        }
+        const verdict = checkMandate(options.mandate, {
+            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),
+            };
+        }
+        // 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(),
+            url: page.url(),
+            merchantHost,
+            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)),
+        });
+        evidence.step('review', {
+            reviewId: review.id,
+            merchantHost: review.merchantHost,
+            amountMinor: review.amountMinor,
+            currency: review.currency,
+            submitTarget: review.submitTarget,
+            submitTargetFingerprint: review.submitTargetFingerprint,
+            detectedRoles: review.detectedRoles,
+        });
+        const checkout = Object.freeze({
+            review,
+            fields: Object.freeze({ ...fields }),
+            evidence,
+            requiresAdapter: Object.freeze([...requiresAdapter]),
+        });
+        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 preFill = checkMandatePreFill(options.mandate, {
+            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);
+        }
+        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);
+        }
+        const approvalVerdict = checkMandate(options.mandate, {
+            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);
+        }
+        const changedAtApproval = reviewChangeReason(checkout.review, merchantHost, approvedFacts);
+        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);
+        }
+        // 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);
+        }
+        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');
+        }
+        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;
+            if (fillHost !== checkout.review.merchantHost) {
+                const reason = `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);
+        }
+        const submitMerchantHost = new URL(page.url()).hostname;
+        const verdict = checkMandate(options.mandate, {
+            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);
+        }
+        const changedBeforeSubmit = reviewChangeReason(checkout.review, submitMerchantHost, submitFacts);
+        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);
+        }
+        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);
+        }
+        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);
+}