@visa/cli 4.1.0-rc.3 → 4.1.0-rc.31

package/dist/checkout-engine/executor.js

@@ -0,0 +1,1306 @@
+// 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 -> mint credential -> 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 never
+//     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';
+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(() => { });
+}
+// Convert a human decimal like "$50.00" to integer minor units without
+// floats. Fail-closed on separator ambiguity: only layouts with exactly one
+// reading are parsed; anything else returns null and the caller refuses. The
+// dangerous direction is UNDER-reading (an EU "1.234,56" read as 1.23 lets an
+// over-cap total pass the gate), so no layout is ever guessed.
+// Only 2-decimal currencies are supported (see pageCurrency's ISO allowlist).
+export function minorFromDecimal(text) {
+    const m = text.match(/\d[\d.,]*/);
+    if (!m)
+        return null;
+    const token = m[0].replace(/[.,]+$/, '');
+    // "1234" — plain integer major units.
+    if (/^\d+$/.test(token))
+        return Number.parseInt(token, 10) * 100;
+    // "1,234.56" — thousands groups of exactly 3 plus a 2-digit decimal.
+    if (/^\d{1,3}(,\d{3})+\.\d{2}$/.test(token)) {
+        const [whole, frac] = token.replace(/,/g, '').split('.');
+        return Number.parseInt(whole, 10) * 100 + Number.parseInt(frac, 10);
+    }
+    // "1.234,56" — the EU mirror: dot thousands, comma decimal.
+    if (/^\d{1,3}(\.\d{3})+,\d{2}$/.test(token)) {
+        const [whole, frac] = token.replace(/\./g, '').split(',');
+        return Number.parseInt(whole, 10) * 100 + Number.parseInt(frac, 10);
+    }
+    // "49.99" / "49.9" — dot decimal. A 3-digit dot group ("1.234") is EU
+    // thousands, not a decimal, so only 1-2 fraction digits qualify.
+    if (/^\d+\.\d{1,2}$/.test(token)) {
+        const [whole, frac] = token.split('.');
+        return Number.parseInt(whole, 10) * 100 + Number.parseInt(frac.padEnd(2, '0'), 10);
+    }
+    // "49,99" / "49,9" — comma decimal. Unambiguous: a thousands group is
+    // always exactly 3 digits, so a 1-2 digit comma tail can only be a decimal.
+    if (/^\d+,\d{1,2}$/.test(token)) {
+        const [whole, frac] = token.split(',');
+        return Number.parseInt(whole, 10) * 100 + Number.parseInt(frac.padEnd(2, '0'), 10);
+    }
+    // Everything else ("1,234" thousands-or-3-decimals, "1.2.3", ...) is
+    // ambiguous: refuse rather than guess.
+    return null;
+}
+// Currency stated by the page's total text, when unambiguous. "$" is shared
+// by USD/CAD/AUD/... and never qualifies. The ISO allowlist is 2-decimal
+// currencies only, matching minorFromDecimal's scaling.
+const ISO_CURRENCIES = ['USD', 'EUR', 'GBP', 'CAD', 'AUD', 'CHF', 'NZD'];
+export function pageCurrency(text) {
+    const iso = text.match(/\b([A-Z]{3})\b/);
+    if (iso && ISO_CURRENCIES.includes(iso[1]))
+        return iso[1];
+    if (text.includes('€'))
+        return 'EUR';
+    if (text.includes('£'))
+        return 'GBP';
+    return null;
+}
+// Read the order total from the page. Prefers an explicit data-total-minor
+// attribute (machine-readable), else parses a labelled total from the page.
+// Either way the currency comes from the element's text, or stays null. A
+// total that is present but ambiguous is 'unreadable' — the executor refuses
+// rather than falling back to the caller amount, because the page is showing
+// the user a number we cannot verify against the mandate.
+async function readPageAmount(page) {
+    const explicitLoc = page.locator('[data-total-minor]').first();
+    if ((await explicitLoc.count().catch(() => 0)) > 0) {
+        const explicit = await explicitLoc.getAttribute('data-total-minor').catch(() => null);
+        if (explicit && /^\d+$/.test(explicit)) {
+            const text = (await explicitLoc.textContent().catch(() => null)) ?? '';
+            return {
+                kind: 'ok',
+                amountMinor: Number.parseInt(explicit, 10),
+                currency: pageCurrency(text),
+                source: 'page-attr',
+            };
+        }
+    }
+    const totalLoc = page.locator('#order-total, .order-total, [data-testid="order-total"]').first();
+    if ((await totalLoc.count().catch(() => 0)) > 0) {
+        const totalText = await totalLoc.textContent().catch(() => null);
+        if (totalText && /\d/.test(totalText)) {
+            const amountMinor = minorFromDecimal(totalText);
+            if (amountMinor == null)
+                return { kind: 'unreadable' };
+            return { kind: 'ok', amountMinor, currency: pageCurrency(totalText), source: 'page-text' };
+        }
+    }
+    return { kind: 'none' };
+}
+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 });
+}
+async function findSubmit(page) {
+    const submitBtn = page.locator('button[type="submit"], input[type="submit"]').first();
+    if ((await submitBtn.count().catch(() => 0)) > 0) {
+        const label = ((await submitBtn.textContent().catch(() => '')) || '').trim() ||
+            (await submitBtn.getAttribute('value').catch(() => '')) ||
+            'submit';
+        return {
+            desc: `submit button ("${label}")`,
+            fingerprint: await fingerprintSubmitTarget(submitBtn, 'submit-control', 'submit'),
+            click: () => submitBtn.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;
+}
+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=${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) {
+    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';
+    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 } : {}),
+        },
+        ...(detail ? { detail } : {}),
+        ...(confirmationRef ? { confirmationRef } : {}),
+    };
+}
+async function readTransactionFacts(page, opts) {
+    const pageAmount = await readPageAmount(page);
+    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'
+                ? '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 (page total present but ambiguous, e.g. separator layout); 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();
+    const context = await options.browser.newContext();
+    // 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.
+        const detected = await detectFields(page);
+        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 });
+            }
+        }
+        const facts = await readTransactionFacts(page, options);
+        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),
+            };
+        }
+        const submit = await findSubmit(page);
+        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);
+        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);
+        }
+        const approvalSubmit = await findSubmit(page);
+        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 });
+        const credential = await opts.instrument.getCredential({
+            merchantHost,
+            amountMinor: approvedFacts.amountMinor,
+            currency: approvedFacts.currency,
+        });
+        evidence.step('credential-minted', {
+            ...(credential.credentialExpiresAt
+                ? { credentialExpiresAt: credential.credentialExpiresAt }
+                : {}),
+        });
+        // 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;
+        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);
+            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);
+            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,
+                });
+            }
+            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']),
+        ];
+        evidence.step('fill-complete', {
+            ok: missingCredentialRoles.length === 0,
+            missingCredentialRoles,
+        });
+        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);
+        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 (opts.mode === 'dry-run') {
+            evidence.step('submit', { would: true, target: submit?.desc ?? 'none found' });
+            evidence.setSnapshotSummary(await snapshotSummary(page));
+            if (missingCredentialRoles.length > 0) {
+                const adapterRequired = requiresAdapter.size > 0;
+                return makeResult(adapterRequired ? 'adapter-required' : 'partial-fill', state.fields, evidence, requiresAdapter, adapterRequired
+                    ? `credential fields require adapter: ${[...requiresAdapter].join(', ')}; missing ${missingCredentialRoles.join(', ')}`
+                    : `credential fill incomplete: missing ${missingCredentialRoles.join(', ')}`);
+            }
+            return makeResult('filled-dry-run', state.fields, evidence, requiresAdapter, submit ? `would click ${submit.desc}` : 'no submit control detected');
+        }
+        if (missingCredentialRoles.length > 0) {
+            evidence.setSnapshotSummary(await snapshotSummary(page));
+            return makeResult('failed', state.fields, evidence, requiresAdapter, `credential fill incomplete: missing ${missingCredentialRoles.join(', ')}`);
+        }
+        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 });
+        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);
+        }
+        evidence.step('outcome', {
+            outcome: 'failed',
+            reason: 'no confirmation or decline signal',
+            lastSeen: observed.lastSeen,
+            attempts: observed.attempts,
+            elapsedMs: observed.elapsedMs,
+        });
+        return makeResult('failed', state.fields, evidence, requiresAdapter, observed.lastSeen === 'processing'
+            ? 'submitted but outcome unknown (page still processing at deadline)'
+            : 'submitted but outcome unknown');
+    }
+    catch (err) {
+        const detail = err.message;
+        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, 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);
+}