@visa/cli 4.1.0-rc.154 → 4.1.0-rc.155

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

@@ -10,6 +10,16 @@ export interface CheckoutAdapter {
 }
 export declare function resolveLocator(page: Page, entry: FieldEntry): Locator;
 export declare function scrubFillErrorMessage(message: string, value: string): string;
+/**
+ * The contact record and the page rarely agree on name shape: the record may
+ * carry fullName while the page wants first/last inputs, or vice versa. Derive
+ * the missing shape so either page can be filled from either record.
+ */
+export declare function contactNameShapes(contact: Contact, cardholderName?: string): {
+    fullName?: string;
+    first?: string;
+    last?: string;
+};
 export declare function fillContactFieldMap(page: Page, fields: FieldMap, contact: Contact, opts?: {
     fillTimeoutMs?: number;
 }): Promise<FilledField[]>;

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

@@ -97,12 +97,24 @@ async function fillOne(page, role, entry, value, displayValue, fillTimeoutMs) {
         return { ...base, ok: false, error: scrubFillErrorMessage(err.message, value) };
     }
 }
+/**
+ * The contact record and the page rarely agree on name shape: the record may
+ * carry fullName while the page wants first/last inputs, or vice versa. Derive
+ * the missing shape so either page can be filled from either record.
+ */
+export function contactNameShapes(contact, cardholderName) {
+    const fullName = contact.fullName ??
+        (contact.firstName && contact.lastName
+            ? `${contact.firstName} ${contact.lastName}`
+            : cardholderName);
+    const first = contact.firstName ?? (fullName?.split(/\s+/)[0] || undefined);
+    const last = contact.lastName ?? (fullName?.split(/\s+/).slice(1).join(' ') || undefined);
+    return { fullName, first, last };
+}
 async function fillFields(page, fields, credential, contact, opts = {}) {
     const fillTimeoutMs = opts.fillTimeoutMs ?? DEFAULT_FILL_TIMEOUT_MS;
     const filled = [];
-    const fullName = contact.fullName ?? credential?.cardholderName;
-    const first = contact.firstName ?? fullName?.split(/\s+/)[0];
-    const last = contact.lastName ?? fullName?.split(/\s+/).slice(1).join(' ');
+    const { fullName, first, last } = contactNameShapes(contact, credential?.cardholderName);
     // Order matters a little: contact/name before card is harmless, but we fill
     // card fields explicitly per role so order is not load-bearing.
     const jobs = [];

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

@@ -2,7 +2,7 @@ import type { Page } from 'playwright-core';
 import { type PageAmountRead } from '../amount.js';
 import { type DetectResult, type FieldMap } from '../detect.js';
 import type { CardCredential } from '../instrument.js';
-import type { Contact, FillResult } from '../types.js';
+import type { Contact, FillResult, FilledField } from '../types.js';
 import { type CheckoutAdapter } from './generic.js';
 type ShopifySummary = {
     subtotalMinor: number | null;
@@ -20,6 +20,30 @@ export declare function isShopifyCheckoutPage(page: Page): Promise<boolean>;
 export declare function detectShopifyChallenge(page: Page): Promise<{
     signal: string;
 } | null>;
+/**
+ * The en-US variant of a localized Shopify checkout URL, or null when it is
+ * already English (or not locale-suffixed). Shopify renders the checkout in
+ * the URL's trailing locale segment, and amount reconciliation reads the
+ * order summary by its ENGLISH labels — a store whose primary market is not
+ * English serves /checkouts/cn/<token>/<locale> and the total never parses
+ * (observed live 2026-08-16: /es-us rendered "Precio total" and the review
+ * refused fail-closed on a good checkout). The locale segment is
+ * presentation-only: swapping it keeps the same checkout session and token.
+ */
+export declare function shopifyEnglishCheckoutUrl(current: string): string | null;
+export declare function missingContactRoles(filled: FilledField[], expected: string[]): string[];
+/**
+ * The contact surface to prefill. Shipping fields when the checkout has them —
+ * but a digital-goods (no-shipping) Shopify checkout renders exactly one
+ * address block and marks every field autocomplete="billing ..." (observed
+ * live 2026-08-16: all 18 candidates billing-classified, so the shipping map
+ * came back empty and the prefill reported every role missing). That billing
+ * block IS the primary contact surface, under its base roles.
+ */
+export declare function contactPrefillFieldMap(detected: DetectResult): {
+    fields: FieldMap;
+    surface: 'shipping' | 'billing-only';
+};
 export declare class ShopifyAdapter implements CheckoutAdapter {
     private readonly detected;
     name: string;

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

@@ -43,11 +43,23 @@ export function parseShopifySummary(text) {
     const discountMinor = parse(uniqueValue('discount', 'discounts')) ?? 0;
     const totalText = uniqueValue('total');
     const totalMinor = parse(totalText);
-    const verified = subtotalMinor != null &&
-        shippingMinor != null &&
-        taxMinor != null &&
-        totalMinor != null &&
-        subtotalMinor + shippingMinor + taxMinor - discountMinor === totalMinor;
+    // A digital-goods checkout renders no component rows at all — just a total
+    // ("Cost summary / Total / USD $6.00", observed live 2026-08-16), so there
+    // is nothing to reconcile against and a parsed total stands on its own. The
+    // moment ANY component label parsed by SUMMARY_LABELS appears — including a
+    // pending "Calculated at next step" — the full reconciliation is required again,
+    // so a mid-render pre-tax total still refuses.
+    // The discount-code entry form puts a bare "Discount" label on every
+    // checkout, value or not, and discount already defaults to 0 — only the
+    // additive components force reconciliation.
+    const componentLabelPresent = [...values.keys()].some((key) => key !== 'total' && key !== 'discount' && key !== 'discounts');
+    const verified = componentLabelPresent
+        ? subtotalMinor != null &&
+            shippingMinor != null &&
+            taxMinor != null &&
+            totalMinor != null &&
+            subtotalMinor + shippingMinor + taxMinor - discountMinor === totalMinor
+        : totalMinor != null;
     return {
         subtotalMinor,
         shippingMinor,
@@ -145,6 +157,30 @@ export async function detectShopifyChallenge(page) {
     }
     return null;
 }
+/**
+ * The en-US variant of a localized Shopify checkout URL, or null when it is
+ * already English (or not locale-suffixed). Shopify renders the checkout in
+ * the URL's trailing locale segment, and amount reconciliation reads the
+ * order summary by its ENGLISH labels — a store whose primary market is not
+ * English serves /checkouts/cn/<token>/<locale> and the total never parses
+ * (observed live 2026-08-16: /es-us rendered "Precio total" and the review
+ * refused fail-closed on a good checkout). The locale segment is
+ * presentation-only: swapping it keeps the same checkout session and token.
+ */
+export function shopifyEnglishCheckoutUrl(current) {
+    let url;
+    try {
+        url = new URL(current);
+    }
+    catch {
+        return null;
+    }
+    const match = url.pathname.match(/^(\/checkouts\/[^?#]+\/)([a-z]{2,3}(?:-[a-z0-9]+)*)(\/?)$/i);
+    if (!match || match[2].toLowerCase().startsWith('en'))
+        return null;
+    url.pathname = `${match[1]}en-us${match[3]}`;
+    return url.toString();
+}
 const BILLING_ROLES = new Set([
     'name',
     'nameFirst',
@@ -370,10 +406,62 @@ function requiredAddressRoles(address, prefix = '') {
         ...(address.country ? [role('country')] : []),
     ];
 }
-function missingRoles(filled, expected) {
-    const successful = new Set(filled.filter((field) => field.ok).map((field) => field.role));
+/**
+ * A checkout renders ONE name shape (a single full-name input, or first/last)
+ * while the contact record may carry the other, so the expected role and the
+ * filled role can disagree while the page is completely filled. Either shape
+ * satisfies the name requirement; same for the billing-prefixed variants.
+ */
+function withNameEquivalence(successful) {
+    const out = new Set(successful);
+    for (const [full, first, last] of [
+        ['name', 'nameFirst', 'nameLast'],
+        ['billingName', 'billingNameFirst', 'billingNameLast'],
+    ]) {
+        if (out.has(first) && out.has(last))
+            out.add(full);
+        if (out.has(full)) {
+            out.add(first);
+            out.add(last);
+        }
+    }
+    return out;
+}
+export function missingContactRoles(filled, expected) {
+    const successful = withNameEquivalence(new Set(filled.filter((field) => field.ok).map((field) => field.role)));
     return expected.filter((role) => !successful.has(role));
 }
+function hasAddressRole(fields) {
+    return Boolean(fields.addressLine1 ?? fields.city ?? fields.postalCode);
+}
+/**
+ * The contact surface to prefill. Shipping fields when the checkout has them —
+ * but a digital-goods (no-shipping) Shopify checkout renders exactly one
+ * address block and marks every field autocomplete="billing ..." (observed
+ * live 2026-08-16: all 18 candidates billing-classified, so the shipping map
+ * came back empty and the prefill reported every role missing). That billing
+ * block IS the primary contact surface, under its base roles.
+ */
+export function contactPrefillFieldMap(detected) {
+    const shipping = shippingFieldMap(detected);
+    if (hasAddressRole(shipping))
+        return { fields: shipping, surface: 'shipping' };
+    const fields = {};
+    for (const candidate of detected.candidates) {
+        const role = candidate.role;
+        if (!role || !CONTACT_ROLES.has(role) || !candidate.meta.visible)
+            continue;
+        if (isPaymentCandidate(candidate))
+            continue;
+        const entry = entryFromCandidate(candidate);
+        if (!entry)
+            continue;
+        const existing = fields[role];
+        if (!existing || entry.confidence > existing.confidence)
+            fields[role] = entry;
+    }
+    return { fields, surface: 'billing-only' };
+}
 export class ShopifyAdapter {
     detected;
     name = 'shopify';
@@ -384,15 +472,18 @@ export class ShopifyAdapter {
         return detected.candidates.some(isShopifyCandidate);
     }
     async prepareContact(page, contact) {
-        const shippingFilled = await fillContactFieldMap(page, shippingFieldMap(this.detected), contact);
+        const { fields: contactFields, surface } = contactPrefillFieldMap(this.detected);
+        const shippingFilled = await fillContactFieldMap(page, contactFields, contact);
         const shippingExpected = [...requiredAddressRoles(contact), ...(contact.phone ? ['phone'] : [])];
-        const shippingMissing = missingRoles(shippingFilled, shippingExpected);
-        if (!contact.billingAddress) {
+        const shippingMissing = missingContactRoles(shippingFilled, shippingExpected);
+        if (surface === 'billing-only' || !contact.billingAddress) {
             return {
                 ok: shippingMissing.length === 0,
                 filled: shippingFilled,
                 ...(shippingMissing.length
-                    ? { detail: `Shopify shipping prefill incomplete: missing ${shippingMissing.join(', ')}` }
+                    ? {
+                        detail: `Shopify ${surface === 'billing-only' ? 'contact' : 'shipping'} prefill incomplete: missing ${shippingMissing.join(', ')}`,
+                    }
                     : {}),
             };
         }
@@ -406,7 +497,7 @@ export class ShopifyAdapter {
         const billingFields = billingFieldMap(await detectFields(page));
         const billingFilled = labelBillingEvidence(await fillContactFieldMap(page, billingFields, billingContact(contact.billingAddress)));
         const billingExpected = requiredAddressRoles(contact.billingAddress, 'billing');
-        const missing = [...shippingMissing, ...missingRoles(billingFilled, billingExpected)];
+        const missing = [...shippingMissing, ...missingContactRoles(billingFilled, billingExpected)];
         return {
             ok: missing.length === 0,
             filled: [...shippingFilled, ...billingFilled],

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

@@ -34,6 +34,10 @@ export type CliReviewInput = {
     cardTokenId?: string;
     /** Exact request-key identity selected by the caller. */
     agentJkt?: string;
+    /** Owner-facing selected-agent label for the compact local receipt. */
+    agentName?: string;
+    /** Safe display suffix derived from the selected card grant label. */
+    cardLast4?: string;
     contact: Contact;
     approvalBaseUrl: string;
     merchantName?: string;

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

@@ -99,6 +99,9 @@ export function classifyCardDrawVerdictFailure(err) {
  * grant on every draw. Nothing here authorizes anything.
  */
 async function resolveCardInstrument(input) {
+    if (typeof input.cardTokenId === 'string' && input.cardTokenId.trim()) {
+        return { tokenId: input.cardTokenId.trim(), source: 'card-grant' };
+    }
     let credential = null;
     let readError = null;
     try {
@@ -110,9 +113,6 @@ async function resolveCardInstrument(input) {
     if (credential && typeof credential.tokenId === 'string' && credential.tokenId.trim()) {
         return credential;
     }
-    if (typeof input.cardTokenId === 'string' && input.cardTokenId.trim()) {
-        return { tokenId: input.cardTokenId, source: 'card-grant' };
-    }
     throw new Error('no card instrument is available to this runtime: there is no usable credential at ' +
         `${input.credentialPath} and no activated card:vic grant token was supplied. Run ` +
         '`visa agent grant-card <agent-id> --ceiling <usd> --per-transaction <usd> --wait` to ' +
@@ -917,6 +917,7 @@ export function createCliCheckoutEngine(deps = {}) {
                     merchant: {
                         name: session.target.merchantName,
                         host: new URL(session.target.merchantUrl).hostname,
+                        url: session.target.merchantUrl,
                     },
                     transaction: {
                         amount: session.target.transactionAmount,
@@ -925,6 +926,8 @@ export function createCliCheckoutEngine(deps = {}) {
                     },
                     result,
                     vicConfirmation,
+                    agentName: input.agentName,
+                    cardLast4: input.cardLast4,
                 }));
                 if (report.written)
                     receiptPath = report.path;

package/dist/checkout-engine/confirmed-merchants.js

@@ -23,28 +23,36 @@ import { RECEIPT_DIR } from './receipt-dir.js';
 /**
  * The URL a receipt's charge happened at.
  *
- * The receipt's top-level merchant block records the HOST only, on purpose: a
- * full checkout URL can carry cart/session identifiers, so it stays out of the
- * shareable summary. The evidence log still holds it (the executor's first
- * 'navigation' step is the page the run opened), so recover it from there and
- * fall back to the host when the evidence is absent or shaped differently.
+ * A compact v2 receipt carries an exact checkout URL only when it is already in
+ * the curated identity map; otherwise it carries the host. Legacy v1 receipts
+ * keep the URL in the evidence log (the executor's first 'navigation' step is
+ * the page the run opened), so recover it there and fall back to the host when
+ * that evidence is absent or shaped differently.
  */
 function checkoutUrlOf(receipt) {
+    if (receipt.schema === 'checkout-agent-receipt/v2') {
+        const checkoutUrl = receipt.merchant.checkoutUrl;
+        return checkoutUrl && KNOWN_MERCHANT_IDENTITIES[checkoutUrl]
+            ? checkoutUrl
+            : `https://${receipt.merchant.host}/`;
+    }
     const navigation = receipt.evidence.steps.find((step) => step?.type === 'navigation');
     const data = navigation?.data;
     const url = typeof data === 'object' && data !== null ? data.url : undefined;
     return typeof url === 'string' && url.length > 0 ? url : `https://${receipt.merchant.host}/`;
 }
 function isConfirmedCompletion(receipt) {
+    if (receipt.schema === 'checkout-agent-receipt/v2') {
+        return receipt.outcome === 'confirmed' && receipt.network.confirmation === 'APPROVED';
+    }
     return (receipt.outcome === 'confirmed' &&
         receipt.vicConfirmation?.posted === true &&
         receipt.vicConfirmation.transactionStatus === 'APPROVED');
 }
 /**
- * Parse one receipt file, or null when it is not a v1 receipt this module can
- * read. Deliberately permissive about everything the grouping does not touch:
- * the file was written by an older or newer engine and only has to carry the
- * fields read below.
+ * Parse one supported receipt file, or null when its fields cannot safely feed
+ * the registry. Deliberately permissive about everything the grouping does not
+ * touch: older and newer engines only have to carry the fields read below.
  */
 function parseReceipt(json) {
     let parsed;
@@ -57,19 +65,40 @@ function parseReceipt(json) {
     if (typeof parsed !== 'object' || parsed === null)
         return null;
     const receipt = parsed;
-    if (receipt.schema !== 'checkout-agent-receipt/v1')
-        return null;
-    if (typeof receipt.recordedAt !== 'string')
-        return null;
-    if (typeof receipt.merchant?.host !== 'string')
-        return null;
-    if (typeof receipt.transaction?.amount !== 'string')
-        return null;
-    if (typeof receipt.transaction?.currency !== 'string')
-        return null;
-    if (!Array.isArray(receipt.evidence?.steps))
-        return null;
-    return receipt;
+    if (receipt.schema === 'checkout-agent-receipt/v1') {
+        const v1 = receipt;
+        if (typeof v1.recordedAt !== 'string')
+            return null;
+        if (typeof v1.merchant?.host !== 'string')
+            return null;
+        if (typeof v1.transaction?.amount !== 'string')
+            return null;
+        if (typeof v1.transaction?.currency !== 'string')
+            return null;
+        if (!Array.isArray(v1.evidence?.steps))
+            return null;
+        return v1;
+    }
+    if (receipt.schema === 'checkout-agent-receipt/v2') {
+        const v2 = receipt;
+        if (typeof v2.recordedAt !== 'string')
+            return null;
+        if (typeof v2.merchant?.host !== 'string')
+            return null;
+        if (v2.merchant.checkoutUrl !== null && typeof v2.merchant.checkoutUrl !== 'string')
+            return null;
+        if (typeof v2.transaction?.amount !== 'string')
+            return null;
+        if (typeof v2.transaction?.currency !== 'string')
+            return null;
+        if (v2.network?.confirmation !== null &&
+            v2.network?.confirmation !== 'APPROVED' &&
+            v2.network?.confirmation !== 'DECLINED') {
+            return null;
+        }
+        return v2;
+    }
+    return null;
 }
 /**
  * Merchants this device has completed a real card checkout at, newest first.

package/dist/checkout-engine/executor.js

@@ -24,7 +24,7 @@ import { observeOutcome } from './outcome.js';
 import { selectAdapter } from './adapters/index.js';
 import { traceHandleFields } from './trace-handles.js';
 import { readGenericPageAmount } from './amount.js';
-import { detectShopifyChallenge, isShopifyCheckoutPage, readShopifyAmount, readStableShopifyAmount, } from './adapters/shopify.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;
@@ -674,7 +674,12 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
         mandate: { ...opts.mandate },
     };
     const evidence = new EvidenceLog();
-    const context = await options.browser.newContext();
+    // 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).
+    const context = await options.browser.newContext({ locale: 'en-US' });
     // Bound every action so a mis-detected or hidden element fails fast instead
     // of stalling on Playwright's long default timeout.
     context.setDefaultTimeout(6000);
@@ -732,6 +737,19 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
         // 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);
@@ -799,6 +817,26 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
                 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),
+            };
+        }
         const facts = await readTransactionFacts(page, options, 'review');
         recordTransactionFacts(evidence, 'review', facts);
         if (!facts.ok) {

package/dist/checkout-engine/mandate/mandate-ledger.d.ts

@@ -61,6 +61,13 @@ export type CardMandateRecord = {
      * created record attempted registration. ISO 8601.
      */
     registerFailedAt?: string;
+    /**
+     * Set after an authenticated owner-scoped server read proves this mandate was
+     * revoked. The local file is only an execution cache; server revocation is
+     * canonical and permanently retires the cached mandate from selection while
+     * retaining its receipt history for the owner.
+     */
+    serverRevokedAt?: string;
     /**
      * A cross-host retail budget, not scoped to one `merchantHost`. The local
      * selector may attempt it at any host, while the provider/network still
@@ -127,6 +134,12 @@ export declare class MandateLedger {
      * Throws only if the mandate is unknown.
      */
     markRegisterFailed(mandateId: string, now?: Date): Promise<CardMandateRecord>;
+    /**
+     * Retire a locally cached mandate after the authenticated account API proves
+     * it was revoked. This is idempotent and monotonic: an owner revocation can
+     * never be undone by a later stale/local read.
+     */
+    markServerRevoked(mandateId: string, revokedAt: string): Promise<CardMandateRecord>;
     /**
      * ONE SPENDING LIMIT: adopt the ceiling the SERVER actually approved.
      *

package/dist/checkout-engine/mandate/mandate-ledger.js

@@ -203,6 +203,7 @@ export class MandateLedger {
             m.currencyCode.toUpperCase() === query.currencyCode.toUpperCase() &&
             !m.unhonoredAt &&
             !m.registerFailedAt &&
+            !m.serverRevokedAt &&
             !isExpired(m, now) &&
             hasDrawCountHeadroom(m) &&
             remainingMinor(m) >= query.amountMinor);
@@ -252,6 +253,27 @@ export class MandateLedger {
             return record;
         });
     }
+    /**
+     * Retire a locally cached mandate after the authenticated account API proves
+     * it was revoked. This is idempotent and monotonic: an owner revocation can
+     * never be undone by a later stale/local read.
+     */
+    markServerRevoked(mandateId, revokedAt) {
+        return this.run(async () => {
+            const parsed = new Date(revokedAt);
+            if (Number.isNaN(parsed.getTime()))
+                throw new Error('server revocation timestamp is invalid');
+            const file = await this.load();
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            if (!record.serverRevokedAt) {
+                record.serverRevokedAt = parsed.toISOString();
+                await this.save(file);
+            }
+            return record;
+        });
+    }
     /**
      * ONE SPENDING LIMIT: adopt the ceiling the SERVER actually approved.
      *

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

@@ -1,7 +1,8 @@
 import type { EvidenceStep } from './evidence.js';
 import type { CheckoutMode, CheckoutOutcome, CheckoutResult, CredentialLifecycle, CredentialTiming } from './executor.js';
 import type { VicConfirmationReport } from './vic-confirmation.js';
-export type CheckoutReceipt = {
+/** Published v1 artifact shape. Retained so patch releases remain readable/typable. */
+export type CheckoutReceiptV1 = {
     schema: 'checkout-agent-receipt/v1';
     recordedAt: string;
     mode: CheckoutMode;
@@ -32,6 +33,42 @@ export type CheckoutReceipt = {
         snapshotSummary: string | null;
     };
 };
+export type CheckoutReceiptV2 = {
+    schema: 'checkout-agent-receipt/v2';
+    recordedAt: string;
+    merchant: {
+        name: string;
+        host: string;
+        checkoutUrl: string | null;
+    };
+    transaction: {
+        amount: string;
+        amountMinor: number;
+        currency: string;
+    };
+    outcome: CheckoutOutcome;
+    agent: {
+        name: string;
+    } | null;
+    rail: {
+        type: 'card';
+        cardLast4: string | null;
+    };
+    network: {
+        confirmation: 'APPROVED' | 'DECLINED' | null;
+    };
+    /** Local reviewed-attempt identifier. Keeps filenames stable across schema versions. */
+    receiptId: string | null;
+    /** Merchant confirmation reference only; never substituted with an internal review id. */
+    reference: string | null;
+    recovery: {
+        required: boolean;
+        retrySafe: boolean;
+        action: string;
+        actions: string[];
+    };
+};
+export type CheckoutReceipt = CheckoutReceiptV1 | CheckoutReceiptV2;
 export type ReceiptWriteReport = {
     written: true;
     path: string;
@@ -46,6 +83,7 @@ export declare function buildReceipt(input: {
     merchant: {
         name: string;
         host: string;
+        url?: string;
     };
     transaction: {
         amount: string;
@@ -54,9 +92,11 @@ export declare function buildReceipt(input: {
     };
     result: CheckoutResult;
     vicConfirmation: VicConfirmationReport | null;
+    agentName?: string;
+    cardLast4?: string;
     /** Injectable for tests; defaults to now. */
     recordedAt?: Date;
-}): CheckoutReceipt;
+}): CheckoutReceiptV2;
 /**
  * Defense-in-depth scrub before anything touches disk: any standalone
  * 12–19-digit run that passes Luhn is replaced — contiguous OR separated by