@visa/cli 4.1.0-rc.26 → 4.1.0-rc.260

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

@@ -18,6 +18,8 @@ export type CardMandateMerchant = {
     countryCode: string;
 };
 export type CreateCardMandateInput = {
+    /** Exact current runtime request key selected before human approval. */
+    agentJkt: string;
     tokenId: string;
     assuranceData: unknown;
     ceilingMinor: number;
@@ -26,7 +28,7 @@ export type CreateCardMandateInput = {
     expiresAt: string;
     /** Max draws the ceiling intent may fulfil; defaults to DEFAULT_MANDATE_MAX_DRAWS. */
     maxDraws?: number;
-    /** BUDGET mandate — spendable at any merchant (see CardMandateRecord.crossMerchant). */
+    /** Cross-host retail budget; network category eligibility still applies. */
     crossMerchant?: boolean;
 };
 export type CreateIntentFn = (input: {
@@ -49,7 +51,7 @@ export type CreateCardMandateDeps = {
     ledger: MandateLedger;
     /** verify-web origin the intent is minted against (persisted for later draws). */
     approvalBaseUrl: string;
-    /** Scoped mint token to persist for tap-free draws. */
+    /** @deprecated Accepted from older callers but deliberately never persisted. */
     mintToken?: string;
     now?: () => Date;
 };
@@ -60,6 +62,8 @@ export type CardMandateFacts = {
     currencyCode: string;
     merchant: CardMandateMerchant;
     expiresAt: string;
+    /** Network-enforced maximum purchase count disclosed at approval. */
+    maxDraws: number;
 };
 /**
  * Create a card mandate: approve a spend CEILING once (the passkey assurance

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

@@ -18,7 +18,7 @@
 // stays FAIL-CLEAN as defense-in-depth: the budget is decremented only after a
 // payable cryptogram returns; a network rejection leaves the budget untouched.
 // The caller (cli-engine) then marks the mandate unhonored so the NEXT
-// pay_merchant skips it and takes a fresh per-purchase tap — the same call is
+// pay_merchant skips it and surfaces the no-covering refusal (#7348) — the same call is
 // not retried in-flight. Never fail-open.
 import { decimalToMinor, minorToDecimal, validateCredential, } from '../vgs-live-instrument.js';
 import { CARD_MANDATE_LEDGER_VERSION, remainingMinor, } from './mandate-ledger.js';
@@ -61,6 +61,9 @@ export async function createCardMandate(input, deps) {
     }
     if (!input.tokenId?.trim())
         throw new Error('mandate requires a tokenId');
+    if (!/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/.test(input.agentJkt)) {
+        throw new Error('mandate requires a canonical agent request-key JKT');
+    }
     const now = (deps.now ?? (() => new Date()))();
     const expiryMs = Date.parse(input.expiresAt);
     if (!Number.isFinite(expiryMs))
@@ -109,6 +112,7 @@ export async function createCardMandate(input, deps) {
     const record = {
         version: CARD_MANDATE_LEDGER_VERSION,
         mandateId: intentId,
+        agentJkt: input.agentJkt,
         tokenId: input.tokenId,
         ceilingMinor: input.ceilingMinor,
         spentMinor: 0,
@@ -119,13 +123,13 @@ export async function createCardMandate(input, deps) {
         merchantHost: host,
         merchantCountryCode: input.merchant.countryCode.toUpperCase(),
         approvalBaseUrl: deps.approvalBaseUrl,
-        ...(deps.mintToken ? { mintToken: deps.mintToken } : {}),
         expiresAt: new Date(expiryMs).toISOString(),
+        maxDraws,
         createdAt: now.toISOString(),
         draws: [],
         ...(input.crossMerchant ? { crossMerchant: true } : {}),
     };
-    await deps.ledger.create(record);
+    await deps.ledger.create(record, now);
     return {
         mandateId: record.mandateId,
         ceilingMinor: record.ceilingMinor,
@@ -133,12 +137,13 @@ export async function createCardMandate(input, deps) {
         currencyCode,
         merchant: input.merchant,
         expiresAt: record.expiresAt,
+        maxDraws,
     };
 }
 const DRAW_REMEDY = 'the card-mandate draw did not complete — a ceiling-scoped assurance may not be honored ' +
     'for this sub-amount draw. The budget is untouched. If this was a transient network error ' +
     '(gateway 5xx / try again), retry — the mandate stays active; a persistent decline disables ' +
-    'the mandate and your next pay_merchant uses a fresh per-purchase tap';
+    'the mandate; a v4 card grant then requires a new mandate before another checkout';
 /**
  * Thrown ONLY for the post-reservation network/validation rejection class — the
  * cryptogram fetch failed or returned a non-payable credential (the DRAW_REMEDY
@@ -180,7 +185,7 @@ export async function drawFromMandate(input, deps) {
             `${JSON.stringify(input.transaction.transactionAmount)} (minor units)`);
     }
     // Currency must always match; merchant must match UNLESS this is a budget
-    // (crossMerchant) mandate the owner approved for any merchant. The network
+    // (crossMerchant) mandate the owner approved for eligible retail merchants. The network
     // honors a ceiling-scoped cryptogram cross-merchant, so a budget mandate is
     // deliberately not host-restricted — the ceiling + per-transaction limit still
     // bound it.

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

@@ -16,6 +16,8 @@ export type CardMandateRecord = {
     version: typeof CARD_MANDATE_LEDGER_VERSION;
     /** == the VGS intentId the ceiling approval created. */
     mandateId: string;
+    /** Exact runtime request key this budget was issued to. Absent on legacy rows. */
+    agentJkt?: string;
     tokenId: string;
     ceilingMinor: number;
     /** Permanently committed (drawn) spend, integer minor units. */
@@ -29,13 +31,11 @@ export type CardMandateRecord = {
     merchantCountryCode: string;
     /** verify-web origin the ceiling intent was minted against. */
     approvalBaseUrl: string;
-    /**
-     * Scoped mint token released by the ceiling approval, reused to draw
-     * cryptograms tap-free. Owner-only (0600) like the rest of the file; whether
-     * it stays valid across multiple draws is part of the unproven spike.
-     */
+    /** @deprecated Read-migration only. New writers never persist this bearer. */
     mintToken?: string;
     expiresAt: string;
+    /** Network purchase-count cap disclosed at approval. Absent on legacy rows. */
+    maxDraws?: number;
     createdAt: string;
     draws: CardMandateDraw[];
     /**
@@ -43,7 +43,7 @@ export type CardMandateRecord = {
      * ceiling-scoped assurance the acquirer would not honor for a sub-amount
      * draw). Distinct from a reservation `status`: it disables the whole mandate.
      * Once set, findCovering() SKIPS this mandate so the caller's next
-     * pay_merchant falls through to a fresh per-purchase tap instead of
+     * pay_merchant surfaces the no-covering-mandate refusal (#7348) instead of
      * re-selecting the same failing mandate forever. ISO 8601.
      */
     unhonoredAt?: string;
@@ -51,20 +51,24 @@ export type CardMandateRecord = {
      * Set when the delegated-draw register handshake FAILED at mandate-start (the
      * server-side `card_mandate_spend` row was never created), so a later
      * delegated (verdict-signed) draw would 404 `no_mandate`. Like `unhonoredAt`,
-     * findCovering() SKIPS a register-failed mandate so the next checkout falls
-     * through to a fresh per-purchase tap instead of surfacing a confusing
-     * `no_mandate`. Only set when a delegated binding was present and register was
-     * attempted; a bare bearer mandate (no binding) never carries it. ISO 8601.
+     * findCovering() SKIPS a register-failed mandate so the next checkout
+     * surfaces the no-covering-mandate refusal (#7348) instead of a confusing
+     * `no_mandate`. Mandate-start requires delegated card authority, so every
+     * created record attempted registration. ISO 8601.
      */
     registerFailedAt?: string;
     /**
-     * A BUDGET mandate: spendable at ANY merchant, not scoped to `merchantHost`.
-     * The card network honors a ceiling-scoped cryptogram cross-merchant (the
-     * mandate's merchant is only an advisory hint on the intent), so this is a
-     * deliberate product mode — the owner approved a spend budget usable anywhere,
-     * bounded by the same ceiling + per-transaction limit. When set, findCovering
-     * matches this mandate for any merchant and drawFromMandate skips the
-     * merchant-match guard. Absent/false = the default merchant-scoped mandate.
+     * 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
+     * applies the approved Retail/5999 category plus amount/count/time controls.
+     * `crossMerchant` is retained as the version-1 persisted field name.
      */
     crossMerchant?: boolean;
 };
@@ -76,6 +80,8 @@ export type CoverQuery = {
     merchantHost: string;
     currencyCode: string;
     amountMinor: number;
+    /** Exact selected request key; omitted means legacy unbound mandates only. */
+    agentJkt?: string;
     now?: Date;
 };
 /** Available headroom = ceiling - committed - reserved. Integer minor units. */
@@ -93,14 +99,20 @@ export declare class MandateLedger {
     private run;
     private load;
     private save;
-    /** Append a freshly-created mandate record. */
-    create(record: CardMandateRecord): Promise<CardMandateRecord>;
+    /**
+     * Append a freshly-created mandate record. `now` drives the expired-mandate
+     * prune below; it defaults to the wall clock but is injectable so callers (and
+     * tests) can pin it — every other mutating method takes the same clock, and a
+     * real `new Date()` here would otherwise make the prune non-deterministic
+     * against fixtures dated relative to a fixed reference time.
+     */
+    create(record: CardMandateRecord, now?: Date): Promise<CardMandateRecord>;
     /** Read a single mandate (no lock — a snapshot copy). */
     get(mandateId: string): Promise<CardMandateRecord | null>;
     /**
      * First ACTIVE mandate (not expired) whose merchant + currency match and whose
      * remaining headroom covers amountMinor. Used by pay_merchant to decide the
-     * tap-free draw path vs a fresh per-purchase tap.
+     * tap-free draw path vs the no-covering-mandate refusal (#7348).
      */
     findCovering(query: CoverQuery): Promise<CardMandateRecord | null>;
     /**
@@ -118,11 +130,39 @@ 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.
+     *
+     * The requested ceiling is only a request. At register, auth clamps it to the
+     * owner's live card-grant cap (`min(requested, grant daily limit)`) and writes
+     * that. The local record used to keep the requested figure, so a runtime whose
+     * request exceeded the grant reported — and selected against — a budget the
+     * owner never approved. The draw still failed closed at auth's verdict, so it
+     * was never over-spend; it was the runtime lying about its own headroom and
+     * then hitting a decline it could not explain.
+     *
+     * LOWERS ONLY. A value at or above the current ceiling is ignored, not
+     * written: the server clamps downward, so a higher number means an unexpected
+     * response, and honouring it would let a client-observed value hand a runtime
+     * headroom no human approved. Cap authority stays server-side either way —
+     * this only stops the local copy from overstating it.
+     *
+     * Atomic and idempotent on the same serialized chain as every other mutation.
+     * Throws only if the mandate is unknown.
+     */
+    applyApprovedCeiling(mandateId: string, approvedCeilingMinor: number): Promise<CardMandateRecord>;
     /**
      * Atomically reserve headroom for a draw. Fail-closed: refuses when the
-     * mandate is unknown, expired, or the amount exceeds remaining headroom. The
-     * reservation counts against availability immediately, closing the window in
-     * which two concurrent draws both see the same remaining balance.
+     * mandate is unknown, retired, expired, or the amount exceeds remaining
+     * headroom. The reservation counts against availability immediately, closing
+     * the window in which two concurrent draws both see the same remaining
+     * balance.
      */
     reserve(mandateId: string, amountMinor: number, now?: Date): Promise<string>;
     /** Commit a reservation to permanent spend and record the payable draw. */

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

@@ -11,8 +11,8 @@
 //
 // VGS's decline_threshold is a per-transaction NETWORK control; this ledger is
 // the SEPARATE cumulative budget control. The file holds identifiers and
-// accounting state plus the scoped mint token (owner-only) — never PAN, DPAN,
-// CVC, or cryptogram values. Cross-process concurrency is NOT solved by a file
+// accounting state only — never a bootstrap mint token, PAN, DPAN, CVC, or
+// cryptogram values. Cross-process concurrency is NOT solved by a file
 // (same caveat csmoove notes); the in-process mutex below serializes draws
 // within one CLI process, which is the live-spike target.
 //
@@ -36,7 +36,10 @@ const LEDGER_MAX_BYTES = 512 * 1024;
 // A tap-free draw's reserve -> commit/release cycle completes in one network
 // round-trip; a reservation older than this window can only be the debris of a
 // crash between reserve and commit/release, so load() sweeps it (L1 self-heal).
-const STALE_RESERVATION_MS = 5 * 60 * 1000;
+// Must match the server-authoritative TTL (CARD_MANDATE_RESERVATION_TTL_SECONDS
+// in apps/auth/src/server.ts, default 15 min) to avoid a window where the local
+// ledger over-reports available headroom.
+const STALE_RESERVATION_MS = 15 * 60 * 1000;
 // Mandates expired longer ago than this are pruned on the next create(). Generous
 // (a week) so a recently-expired mandate is still visible in `mandate list`, but
 // bounded so a long-lived heavy user cannot grow the owner-only ledger file into
@@ -75,6 +78,13 @@ function isExpired(record, now) {
     const end = Date.parse(record.expiresAt);
     return !Number.isFinite(end) || end <= now.getTime();
 }
+function committedDrawCount(record) {
+    return record.draws.filter((draw) => draw.status === 'committed').length;
+}
+function hasDrawCountHeadroom(record) {
+    return (record.maxDraws === undefined ||
+        committedDrawCount(record) + record.reservations.length < record.maxDraws);
+}
 function assertPositiveInteger(value, label) {
     if (!Number.isSafeInteger(value) || value <= 0) {
         throw new Error(`${label} must be a positive integer (minor units)`);
@@ -111,6 +121,18 @@ export class MandateLedger {
             if (!doc || !Array.isArray(doc.mandates)) {
                 return { version: CARD_MANDATE_LEDGER_VERSION, mandates: [] };
             }
+            // One-time migration for pre-hardening ledgers. The budget mint is a
+            // bootstrap bearer used only during create/register and must not survive
+            // process exit. Scrub it eagerly on read, not merely on the next mutation.
+            let scrubbedBootstrapToken = false;
+            for (const mandate of doc.mandates) {
+                if (Object.prototype.hasOwnProperty.call(mandate, 'mintToken')) {
+                    delete mandate.mintToken;
+                    scrubbedBootstrapToken = true;
+                }
+            }
+            if (scrubbedBootstrapToken)
+                await writeOwnerOnlyJson(this.path, doc);
             // Self-heal: prune reservations stranded by a crash before commit/release
             // so `remaining` reflects reality. In-memory here; a mutating caller then
             // persists the pruned state via save().
@@ -129,8 +151,14 @@ export class MandateLedger {
     async save(file) {
         await writeOwnerOnlyJson(this.path, file);
     }
-    /** Append a freshly-created mandate record. */
-    create(record) {
+    /**
+     * Append a freshly-created mandate record. `now` drives the expired-mandate
+     * prune below; it defaults to the wall clock but is injectable so callers (and
+     * tests) can pin it — every other mutating method takes the same clock, and a
+     * real `new Date()` here would otherwise make the prune non-deterministic
+     * against fixtures dated relative to a fixed reference time.
+     */
+    create(record, now = new Date()) {
         return this.run(async () => {
             const file = await this.load();
             if (file.mandates.some((m) => m.mandateId === record.mandateId)) {
@@ -140,14 +168,17 @@ export class MandateLedger {
             // are already invisible to `mandate list` and unselectable by findCovering,
             // so nothing references them. A mandate with an unparseable expiry is kept
             // (fail-safe — never prune what we cannot date).
-            const pruneBefore = new Date().getTime() - EXPIRED_PRUNE_GRACE_MS;
+            const pruneBefore = now.getTime() - EXPIRED_PRUNE_GRACE_MS;
             file.mandates = file.mandates.filter((m) => {
                 const exp = Date.parse(m.expiresAt);
                 return !Number.isFinite(exp) || exp >= pruneBefore;
             });
-            file.mandates.push(record);
+            // Even an older caller that still supplies the deprecated field cannot
+            // persist the bootstrap bearer.
+            const { mintToken: _discardedBootstrapToken, ...safeRecord } = record;
+            file.mandates.push(safeRecord);
             await this.save(file);
-            return record;
+            return safeRecord;
         });
     }
     /** Read a single mandate (no lock — a snapshot copy). */
@@ -158,7 +189,7 @@ export class MandateLedger {
     /**
      * First ACTIVE mandate (not expired) whose merchant + currency match and whose
      * remaining headroom covers amountMinor. Used by pay_merchant to decide the
-     * tap-free draw path vs a fresh per-purchase tap.
+     * tap-free draw path vs the no-covering-mandate refusal (#7348).
      */
     async findCovering(query) {
         const now = query.now ?? new Date();
@@ -168,25 +199,28 @@ export class MandateLedger {
         // mandate the network refused is skipped via `!m.unhonoredAt` so it can never
         // be re-selected. A register-failed mandate is skipped the same way
         // (`!m.registerFailedAt`): it has no server row, so a delegated draw would 404
-        // `no_mandate` — better to fall through to a fresh per-purchase tap.
+        // `no_mandate` — better to surface the no-covering refusal (#7348).
         // Selection order among covering candidates:
         //   1. Prefer a merchant-SCOPED mandate over a crossMerchant budget one —
         //      spend the dedicated grant for this merchant first and keep the broader
-        //      any-merchant budget for merchants that have no scoped mandate. Draining
+        //      broader retail budget for merchants that have no scoped mandate. Draining
         //      the budget for a purchase a scoped mandate already covers both wastes
         //      the general headroom and can later force a fresh tap at another merchant.
         //   2. Then the MOST headroom, then the latest expiry — never let a near-empty
         //      or near-expiry mandate get selected over a fuller, longer-lived sibling
         //      and then fail a draw the sibling would have covered.
         const candidates = file.mandates.filter((m) => 
-        // A crossMerchant (budget) mandate covers ANY merchant; a merchant-scoped
-        // one only its own host. A budget mandate the owner approved for "any
-        // merchant" is deliberately not host-restricted.
+        // A crossMerchant retail budget is locally cross-host; a merchant-scoped
+        // one only matches its own host. Network Retail/5999 eligibility is
+        // enforced downstream and is not inferred from a website hostname.
         (m.crossMerchant || m.merchantHost === query.merchantHost) &&
+            m.agentJkt === query.agentJkt &&
             m.currencyCode.toUpperCase() === query.currencyCode.toUpperCase() &&
             !m.unhonoredAt &&
             !m.registerFailedAt &&
+            !m.serverRevokedAt &&
             !isExpired(m, now) &&
+            hasDrawCountHeadroom(m) &&
             remainingMinor(m) >= query.amountMinor);
         candidates.sort((a, b) => 
         // A scoped mandate (crossMerchant falsy → 0) sorts before a budget one (1).
@@ -234,11 +268,67 @@ 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.
+     *
+     * The requested ceiling is only a request. At register, auth clamps it to the
+     * owner's live card-grant cap (`min(requested, grant daily limit)`) and writes
+     * that. The local record used to keep the requested figure, so a runtime whose
+     * request exceeded the grant reported — and selected against — a budget the
+     * owner never approved. The draw still failed closed at auth's verdict, so it
+     * was never over-spend; it was the runtime lying about its own headroom and
+     * then hitting a decline it could not explain.
+     *
+     * LOWERS ONLY. A value at or above the current ceiling is ignored, not
+     * written: the server clamps downward, so a higher number means an unexpected
+     * response, and honouring it would let a client-observed value hand a runtime
+     * headroom no human approved. Cap authority stays server-side either way —
+     * this only stops the local copy from overstating it.
+     *
+     * Atomic and idempotent on the same serialized chain as every other mutation.
+     * Throws only if the mandate is unknown.
+     */
+    applyApprovedCeiling(mandateId, approvedCeilingMinor) {
+        return this.run(async () => {
+            assertPositiveInteger(approvedCeilingMinor, 'approved mandate ceiling');
+            const file = await this.load();
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            if (approvedCeilingMinor >= record.ceilingMinor)
+                return record;
+            record.ceilingMinor = approvedCeilingMinor;
+            await this.save(file);
+            return record;
+        });
+    }
     /**
      * Atomically reserve headroom for a draw. Fail-closed: refuses when the
-     * mandate is unknown, expired, or the amount exceeds remaining headroom. The
-     * reservation counts against availability immediately, closing the window in
-     * which two concurrent draws both see the same remaining balance.
+     * mandate is unknown, retired, expired, or the amount exceeds remaining
+     * headroom. The reservation counts against availability immediately, closing
+     * the window in which two concurrent draws both see the same remaining
+     * balance.
      */
     reserve(mandateId, amountMinor, now = new Date()) {
         return this.run(async () => {
@@ -249,12 +339,24 @@ export class MandateLedger {
             const record = file.mandates.find((m) => m.mandateId === mandateId);
             if (!record)
                 throw new Error(`no such mandate ${mandateId}`);
+            if (record.serverRevokedAt) {
+                throw new Error(`mandate ${mandateId} was server-revoked at ${record.serverRevokedAt}`);
+            }
+            if (record.registerFailedAt) {
+                throw new Error(`mandate ${mandateId} registration failed at ${record.registerFailedAt}`);
+            }
+            if (record.unhonoredAt) {
+                throw new Error(`mandate ${mandateId} was unhonored at ${record.unhonoredAt}`);
+            }
             if (isExpired(record, now)) {
                 throw new Error(`mandate ${mandateId} expired at ${record.expiresAt}`);
             }
             if (amountMinor > remainingMinor(record)) {
                 throw new Error(`draw ${amountMinor} exceeds remaining budget ${remainingMinor(record)} (minor units)`);
             }
+            if (!hasDrawCountHeadroom(record)) {
+                throw new Error(`mandate ${mandateId} reached its approved purchase-count limit`);
+            }
             const reservationId = `rsv_${randomBytes(9).toString('base64url')}`;
             record.reservations.push({ reservationId, amountMinor, reservedAt: now.toISOString() });
             await this.save(file);
@@ -268,6 +370,11 @@ export class MandateLedger {
             const record = file.mandates.find((m) => m.mandateId === mandateId);
             if (!record)
                 throw new Error(`no such mandate ${mandateId}`);
+            // Revocation is authoritative even when it arrives after reserve(). Keep
+            // the reservation intact so this refusal cannot be mistaken for a commit.
+            if (record.serverRevokedAt) {
+                throw new Error(`mandate ${mandateId} was server-revoked at ${record.serverRevokedAt}`);
+            }
             const idx = record.reservations.findIndex((r) => r.reservationId === reservationId);
             if (idx === -1) {
                 throw new Error(`reservation ${reservationId} is not open (already committed or released)`);

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

@@ -0,0 +1,6 @@
+/**
+ * Where this device's checkout receipts live. Owned by its own module so the
+ * writer (cli-engine.ts) and the reader (confirmed-merchants.ts) can never
+ * drift onto two paths.
+ */
+export declare const RECEIPT_DIR: string;

package/dist/checkout-engine/receipt-dir.js

@@ -0,0 +1,8 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Where this device's checkout receipts live. Owned by its own module so the
+ * writer (cli-engine.ts) and the reader (confirmed-merchants.ts) can never
+ * drift onto two paths.
+ */
+export const RECEIPT_DIR = join(homedir(), '.visa-mcp', 'checkout-receipts');

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,55 @@ export type CheckoutReceipt = {
         snapshotSummary: string | null;
     };
 };
+export type CheckoutReceiptV2 = {
+    schema: 'checkout-agent-receipt/v2';
+    recordedAt: string;
+    /** Correlates terminal pre-review observations that have no reviewId yet. */
+    observationId?: string;
+    /** Explicitly distinguishes pre-submit review observations from payment attempts. */
+    phase?: 'review';
+    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;
+    };
+    /**
+     * Capability evidence for unsuccessful checkout surfaces. Optional so
+     * previously published v2 receipt producers remain source-compatible.
+     */
+    capability?: {
+        failureCode: string | null;
+        detectedRoles: string[];
+        requiresAdapter: string[];
+    };
+    /** 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;
@@ -43,9 +93,11 @@ export type ReceiptWriteReport = {
 export declare function buildReceipt(input: {
     mode: CheckoutMode;
     reviewId: string | null;
+    observationId?: string;
     merchant: {
         name: string;
         host: string;
+        url?: string;
     };
     transaction: {
         amount: string;
@@ -54,9 +106,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