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

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

@@ -1,175 +0,0 @@
-export declare const CARD_MANDATE_LEDGER_VERSION: 1;
-export type CardMandateReservation = {
-    reservationId: string;
-    amountMinor: number;
-    reservedAt: string;
-};
-export type CardMandateDraw = {
-    drawId: string;
-    reservationId: string;
-    amountMinor: number;
-    intentId: string;
-    status: 'committed' | 'released';
-    at: string;
-};
-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. */
-    spentMinor: number;
-    /** In-flight reservations (reserved but not yet committed/released). */
-    reservations: CardMandateReservation[];
-    currencyCode: string;
-    merchantName: string;
-    merchantUrl: string;
-    merchantHost: string;
-    merchantCountryCode: string;
-    /** verify-web origin the ceiling intent was minted against. */
-    approvalBaseUrl: string;
-    /** @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[];
-    /**
-     * Set when the network DECLINED a tap-free draw against this mandate (a
-     * 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 surfaces the no-covering-mandate refusal (#7348) instead of
-     * re-selecting the same failing mandate forever. ISO 8601.
-     */
-    unhonoredAt?: string;
-    /**
-     * 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
-     * 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;
-    /**
-     * 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;
-};
-export type CardMandateLedgerFile = {
-    version: typeof CARD_MANDATE_LEDGER_VERSION;
-    mandates: CardMandateRecord[];
-};
-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. */
-export declare function remainingMinor(record: CardMandateRecord): number;
-/**
- * The persisted card-mandate ledger. All mutating operations are serialized on
- * an in-process promise chain so two concurrent draws cannot both observe the
- * same remaining balance (the read-modify-write is atomic within the process).
- */
-export declare class MandateLedger {
-    private readonly path;
-    private chain;
-    constructor(path?: string);
-    /** Serialize a read-modify-write so concurrent draws can't race the file. */
-    private run;
-    private load;
-    private save;
-    /**
-     * 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 the no-covering-mandate refusal (#7348).
-     */
-    findCovering(query: CoverQuery): Promise<CardMandateRecord | null>;
-    /**
-     * Mark a mandate as unhonored — the network declined a ceiling-scoped draw
-     * against it, so it must never be selected again. Atomic, owner-only write on
-     * the same serialized chain as every other mutation. Idempotent: a second
-     * call keeps the first timestamp. Throws only if the mandate is unknown.
-     */
-    markUnhonored(mandateId: string, now?: Date): Promise<CardMandateRecord>;
-    /**
-     * Mark a mandate as register-failed — the delegated-draw register handshake
-     * did not create the server row at mandate-start, so it must never be selected
-     * for a (delegated) draw. Atomic, owner-only write on the same serialized chain
-     * as every other mutation. Idempotent: a second call keeps the first timestamp.
-     * 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, 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. */
-    commit(mandateId: string, reservationId: string, meta: {
-        intentId: string;
-    }, now?: Date): Promise<CardMandateRecord>;
-    /** Release a reservation back to availability (draw failed / not payable). */
-    release(mandateId: string, reservationId: string, now?: Date): Promise<CardMandateRecord>;
-}
-export declare function defaultLedgerPath(): string;

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

@@ -1,425 +0,0 @@
-// Owner-only persisted ledger for card mandates (budgets). One passkey approval
-// creates one VGS intent with a CEILING decline threshold; this ledger tracks
-// the cumulative budget the agent may draw against that intent without a fresh
-// tap. It deliberately MIRRORS csmoove530's standing-mandate ledger (#5600 /
-// #5724) so the two reconcile later rather than competing:
-//
-//   - owner-only (chmod 600) JSON artifact under ~/.visa-mcp/, atomic write;
-//   - integer minor-unit accounting only — no floating-point money;
-//   - atomic reserve -> commit | release around every draw, so approved plus
-//     in-flight spend can never exceed the authenticated ceiling.
-//
-// 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 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.
-//
-// SELF-HEALING: a reservation is persisted the instant it is taken and is only
-// removed by commit() or release(). A crash BETWEEN reserve and commit/release
-// would otherwise strand the reservation forever, permanently shrinking
-// `remaining`. The headroom-deciding paths (reserve() and findCovering()) run a
-// stale-reservation sweep on load: any reservation older than
-// STALE_RESERVATION_MS (a draw cannot legitimately stay in-flight that long) is
-// dropped, returning its headroom, so a stranded reservation can never block a
-// legitimate draw. reserve()'s save() persists the prune; findCovering() heals
-// its in-memory view. The sweep uses the caller's clock (michaelyang1 L1).
-import { randomBytes } from 'node:crypto';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { readOwnerOnlyJson, writeOwnerOnlyJson } from '../owner-only-file.js';
-export const CARD_MANDATE_LEDGER_VERSION = 1;
-// A ledger with a long draw history is larger than a single credential; cap
-// generously but still bounded (owner-only-file's default 16 KB is too small).
-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).
-// 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
-// its size cap — which would otherwise brick EVERY ledger op (create/reserve/
-// findCovering/commit/release all load the file first).
-const EXPIRED_PRUNE_GRACE_MS = 7 * 24 * 60 * 60 * 1000;
-function reservedTotal(record) {
-    return record.reservations.reduce((sum, r) => sum + r.amountMinor, 0);
-}
-/**
- * Drop reservations older than STALE_RESERVATION_MS across every mandate — the
- * debris of a crash between reserve and commit/release. Mutates in place and
- * returns true if anything was swept (so the caller can decide to persist).
- * A reservation with an unparseable `reservedAt` is treated as stale.
- */
-function sweepStaleReservations(file, nowMs) {
-    let swept = false;
-    for (const m of file.mandates) {
-        const kept = m.reservations.filter((r) => {
-            const reservedMs = Date.parse(r.reservedAt);
-            const stale = !Number.isFinite(reservedMs) || nowMs - reservedMs > STALE_RESERVATION_MS;
-            if (stale)
-                swept = true;
-            return !stale;
-        });
-        if (kept.length !== m.reservations.length)
-            m.reservations = kept;
-    }
-    return swept;
-}
-/** Available headroom = ceiling - committed - reserved. Integer minor units. */
-export function remainingMinor(record) {
-    return record.ceilingMinor - record.spentMinor - reservedTotal(record);
-}
-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)`);
-    }
-}
-/**
- * The persisted card-mandate ledger. All mutating operations are serialized on
- * an in-process promise chain so two concurrent draws cannot both observe the
- * same remaining balance (the read-modify-write is atomic within the process).
- */
-export class MandateLedger {
-    path;
-    chain = Promise.resolve();
-    constructor(path = defaultLedgerPath()) {
-        this.path = path;
-    }
-    /** Serialize a read-modify-write so concurrent draws can't race the file. */
-    run(fn) {
-        const next = this.chain.then(fn, fn);
-        // Keep the chain alive even if this op rejects; swallow only the chain copy.
-        this.chain = next.then(() => undefined, () => undefined);
-        return next;
-    }
-    // `nowMs` is the caller's clock for the stale-reservation sweep. The sweep
-    // deliberately runs only on the headroom-DECIDING loads — reserve() and
-    // findCovering() — which are the paths that must not be blocked by
-    // crash-stranded reservation debris. commit(), release(), and markUnhonored()
-    // pass NO clock on purpose: sweeping while finalizing a reservation could drop
-    // the very reservation being committed/released. Pure snapshot reads (get) and
-    // create() are likewise clock-independent.
-    async load(nowMs) {
-        try {
-            const doc = await readOwnerOnlyJson(this.path, 'card mandate ledger', LEDGER_MAX_BYTES);
-            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().
-            if (nowMs !== undefined)
-                sweepStaleReservations(doc, nowMs);
-            return doc;
-        }
-        catch (err) {
-            // A missing ledger is the normal first-run state.
-            if (err.code === 'ENOENT') {
-                return { version: CARD_MANDATE_LEDGER_VERSION, mandates: [] };
-            }
-            throw err;
-        }
-    }
-    async save(file) {
-        await writeOwnerOnlyJson(this.path, file);
-    }
-    /**
-     * 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)) {
-                throw new Error(`mandate ${record.mandateId} already exists in the ledger`);
-            }
-            // Bound ledger growth: drop mandates expired beyond the grace window. They
-            // 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 = now.getTime() - EXPIRED_PRUNE_GRACE_MS;
-            file.mandates = file.mandates.filter((m) => {
-                const exp = Date.parse(m.expiresAt);
-                return !Number.isFinite(exp) || exp >= pruneBefore;
-            });
-            // 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 safeRecord;
-        });
-    }
-    /** Read a single mandate (no lock — a snapshot copy). */
-    async get(mandateId) {
-        const file = await this.load();
-        return file.mandates.find((m) => m.mandateId === mandateId) ?? 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 the no-covering-mandate refusal (#7348).
-     */
-    async findCovering(query) {
-        const now = query.now ?? new Date();
-        const file = await this.load(now.getTime());
-        // Multiple mandates can now cover one merchant: a merchant-scoped mandate for
-        // this host AND any crossMerchant (budget) mandate both qualify (#6003). A
-        // 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 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
-        //      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 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).
-        (a.crossMerchant ? 1 : 0) - (b.crossMerchant ? 1 : 0) ||
-            remainingMinor(b) - remainingMinor(a) ||
-            Date.parse(b.expiresAt) - Date.parse(a.expiresAt));
-        return candidates[0] ?? null;
-    }
-    /**
-     * Mark a mandate as unhonored — the network declined a ceiling-scoped draw
-     * against it, so it must never be selected again. Atomic, owner-only write on
-     * the same serialized chain as every other mutation. Idempotent: a second
-     * call keeps the first timestamp. Throws only if the mandate is unknown.
-     */
-    markUnhonored(mandateId, now = new Date()) {
-        return this.run(async () => {
-            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.unhonoredAt) {
-                record.unhonoredAt = now.toISOString();
-                await this.save(file);
-            }
-            return record;
-        });
-    }
-    /**
-     * Mark a mandate as register-failed — the delegated-draw register handshake
-     * did not create the server row at mandate-start, so it must never be selected
-     * for a (delegated) draw. Atomic, owner-only write on the same serialized chain
-     * as every other mutation. Idempotent: a second call keeps the first timestamp.
-     * Throws only if the mandate is unknown.
-     */
-    markRegisterFailed(mandateId, now = new Date()) {
-        return this.run(async () => {
-            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.registerFailedAt) {
-                record.registerFailedAt = now.toISOString();
-                await this.save(file);
-            }
-            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, 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 () => {
-            assertPositiveInteger(amountMinor, 'draw amount');
-            // Sweep with the draw's clock so a crash-stranded reservation cannot block
-            // a legitimate draw; the save() below persists the pruned state.
-            const file = await this.load(now.getTime());
-            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);
-            return reservationId;
-        });
-    }
-    /** Commit a reservation to permanent spend and record the payable draw. */
-    commit(mandateId, reservationId, meta, now = new Date()) {
-        return this.run(async () => {
-            const file = await this.load();
-            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)`);
-            }
-            const [reservation] = record.reservations.splice(idx, 1);
-            record.spentMinor += reservation.amountMinor;
-            record.draws.push({
-                drawId: `drw_${randomBytes(9).toString('base64url')}`,
-                reservationId,
-                amountMinor: reservation.amountMinor,
-                intentId: meta.intentId,
-                status: 'committed',
-                at: now.toISOString(),
-            });
-            await this.save(file);
-            return record;
-        });
-    }
-    /** Release a reservation back to availability (draw failed / not payable). */
-    release(mandateId, reservationId, now = new Date()) {
-        return this.run(async () => {
-            const file = await this.load();
-            const record = file.mandates.find((m) => m.mandateId === mandateId);
-            if (!record)
-                throw new Error(`no such mandate ${mandateId}`);
-            const idx = record.reservations.findIndex((r) => r.reservationId === reservationId);
-            if (idx === -1) {
-                // Idempotent by refusal: a committed/released reservation cannot be
-                // released again, but a redundant release must not corrupt state.
-                return record;
-            }
-            const [reservation] = record.reservations.splice(idx, 1);
-            record.draws.push({
-                drawId: `drw_${randomBytes(9).toString('base64url')}`,
-                reservationId,
-                amountMinor: reservation.amountMinor,
-                intentId: record.mandateId,
-                status: 'released',
-                at: now.toISOString(),
-            });
-            await this.save(file);
-            return record;
-        });
-    }
-}
-export function defaultLedgerPath() {
-    return (process.env.VISA_CARD_MANDATE_LEDGER_FILE ?? join(homedir(), '.visa-mcp', 'card-mandates.json'));
-}

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

@@ -1,33 +0,0 @@
-export type Mandate = {
-    maxAmountMinor: number;
-    currency: string;
-    merchantHost?: string;
-    expiresAt: string;
-};
-export type MandateContext = {
-    merchantHost: string;
-    amountMinor: number;
-    currency: string;
-    now?: Date;
-};
-export type MandatePreFillContext = {
-    merchantHost: string;
-    currency?: string | null;
-    now?: Date;
-};
-/**
- * Bounded, machine-readable reason a review or pay was refused by the mandate
- * or trusted-identity gate. Callers branch on this instead of parsing the
- * human-readable reason sentence.
- */
-export type MandateRefusalCode = 'mandate_missing' | 'mandate_malformed' | 'mandate_expired' | 'currency_mismatch' | 'merchant_host_mismatch' | 'currency_unreadable' | 'amount_invalid' | 'amount_over_cap' | 'amount_unreadable' | 'trusted_handoff_expired' | 'trusted_origin_insecure' | 'trusted_origin_changed' | 'trusted_origin_undeclared' | 'review_facts_changed';
-export declare const MANDATE_REFUSAL_CODES: ReadonlySet<MandateRefusalCode>;
-export type MandateVerdict = {
-    ok: true;
-} | {
-    ok: false;
-    reason: string;
-    code: MandateRefusalCode;
-};
-export declare function checkMandatePreFill(mandate: Mandate | null | undefined, ctx: MandatePreFillContext): MandateVerdict;
-export declare function checkMandate(mandate: Mandate | null | undefined, ctx: MandateContext): MandateVerdict;