@volter/twin-stripe 0.1.2 → 2.0.0

package/dist/src/stripe-twin.js

@@ -0,0 +1,1226 @@
+// Stripe twin REQUEST HANDLER — the canonical Stripe API surface for the twin and
+// the QA stack's authoritative Stripe (it replaced the old hand-made in-process
+// mock). Contract: handleStripeTwinRequest({method, path, body, mode}) -> {status,
+// body}. The whole point: this is backed by the event/action-log kernel and its
+// response SHAPES are conformant to real Stripe (see stripe-conformance), instead
+// of being invented — so the SDK/API call shapes the app relies on actually match
+// Stripe. HTTP wrapper: stripe-server.ts → createStripeTwinServer.
+//
+// State lives in the action log (R18): writes are local actions, reads are the
+// projection. No real Stripe is ever called.
+import { applyTwinWrite } from '@volter/world-core';
+import { projectResources } from '@volter/world-core';
+import { createStripeTwinFetch } from "./stripe-server.js";
+import { emitStripeEvent, eventTypeFor } from "./stripe-events.js";
+import { SERVED_VERSION } from "./stripe-version.js";
+import { planOf } from "./semantics/plans.js";
+import { platformAccountDefault } from "./semantics/connect.js";
+const SERVICE = 'stripe';
+// The Stripe API version a request that pins none is served in: the vendored spec's (stripe-version.ts renders
+// every answer in it). A request may override it via the `Stripe-Version` header (apiVersion);
+// the value is echoed onto every event the request produces, exactly like real Stripe,
+// whose stored Event.api_version reflects the version in force when the event was created.
+export const TWIN_API_VERSION = SERVED_VERSION;
+// Stripe API versions are dates (YYYY-MM-DD) optionally suffixed with a release channel
+// (e.g. 2024-06-20.acacia). A malformed Stripe-Version is rejected with a 400, like Stripe.
+const API_VERSION_RE = /^\d{4}-\d{2}-\d{2}(\.[a-z_]+)?$/;
+export function isValidApiVersion(v) {
+    return API_VERSION_RE.test(v);
+}
+// resource type → id prefix (Stripe's conventions).
+const PREFIX = {
+    charge: 'ch', customer: 'cus', payment_intent: 'pi', setup_intent: 'seti', payment_method: 'pm',
+    subscription: 'sub', price: 'price', product: 'prod', invoice: 'in', invoiceitem: 'ii',
+    refund: 're', verification_session: 'vs', ephemeral_key: 'ephkey', file_link: 'link',
+    dispute: 'dp', payout: 'po', balance_transaction: 'txn', event: 'evt',
+    checkout_session: 'cs', billing_portal_session: 'bps', billing_portal_configuration: 'bpc',
+    account: 'acct', transfer: 'tr',
+    tax_rate: 'txr', tax_calculation: 'taxcalc', tax_registration: 'taxreg',
+    credit_note: 'cn', tax_id: 'txi', customer_balance_transaction: 'cbtxn',
+    coupon: 'coupon', promotion_code: 'promo', payment_link: 'plink', quote: 'qt',
+    webhook_endpoint: 'we',
+    subscription_schedule: 'sub_sched', billing_meter: 'mtr', billing_meter_event: 'mtr_evt',
+    usage_record: 'mbur', test_clock: 'clock',
+    token: 'tok', mandate: 'mandate', application_fee: 'fee', fee_refund: 'fr',
+    transfer_reversal: 'trr', account_link: 'acctlink', person: 'person',
+    external_account: 'ba', file: 'file',
+    subscription_item: 'si', tax_transaction: 'tax', radar_review: 'prv',
+    radar_value_list: 'rsl', radar_value_list_item: 'rsli', radar_rule: 'rule',
+    // Issuing family (vendor-faithful Stripe id prefixes).
+    issuing_cardholder: 'ich', issuing_card: 'ic', issuing_authorization: 'iauth',
+    issuing_transaction: 'ipi', issuing_dispute: 'idp',
+    // Terminal family.
+    terminal_location: 'tml', terminal_reader: 'tmr', terminal_configuration: 'tmc',
+    // Top-ups, identity reports, reporting runs.
+    topup: 'tu', verification_report: 'vr', report_run: 'frr',
+    // Customer cash balance ledger + legacy sources.
+    cash_balance_transaction: 'ccsbtxn', source: 'src',
+    // Billing: prepaid credit grants + usage alerts.
+    credit_grant: 'credgr', billing_alert: 'alert',
+    // Entitlements: account-level features + per-customer active entitlements.
+    entitlements_feature: 'feat', active_entitlement: 'ent',
+    // Connect: embedded account sessions + apps secret store.
+    account_session: 'accts', apps_secret: 'apmc',
+    // Issuing: network tokens + card personalization designs.
+    issuing_token: 'iss_tok', personalization_design: 'pd',
+    // Treasury: financial accounts + money-movement flows + ledger.
+    financial_account: 'fa',
+    outbound_payment: 'obp', outbound_transfer: 'obt', inbound_transfer: 'ibt',
+    received_credit: 'rc', received_debit: 'rd',
+    treasury_transaction: 'trxn', treasury_transaction_entry: 'trxne',
+    // Climate (carbon removal): orders. (products/suppliers are a fixed read-only catalog.)
+    climate_order: 'climorder',
+    // Financial Connections: sessions + linked accounts + account transactions.
+    fc_session: 'fcsess', fc_account: 'fca', fc_transaction: 'fctxn',
+    // Forwarding (PAN forwarding) requests + Crypto onramp sessions.
+    forwarding_request: 'fwdr', onramp_session: 'cos',
+    // Entitlements: a product↔feature grant.
+    product_feature: 'prodft',
+    // Tax settings singleton.
+    tax_settings: 'taxset',
+};
+function err(message, status = 404, code) {
+    return { status, body: { error: { type: status === 404 ? 'invalid_request_error' : 'invalid_request_error', message, ...(code ? { code } : {}) } } };
+}
+// Fidelity: real Stripe rejects a charge/payment_intent missing or with a non-positive
+// amount, or missing currency, before any state change.
+export function validateMoney(params) {
+    const amount = params.amount;
+    if (amount === undefined)
+        return err('Missing required param: amount.', 400, 'parameter_missing');
+    if (typeof amount !== 'number' || !Number.isInteger(amount) || amount <= 0)
+        return err('Invalid integer: amount must be a positive integer.', 400, 'parameter_invalid_integer');
+    if (params.currency === undefined || params.currency === '')
+        return err('Missing required param: currency.', 400, 'parameter_missing');
+    return null;
+}
+// Raw test-PAN → outcome (null = success). Mirrors Stripe's documented test cards.
+const TEST_CARD_DECLINES = {
+    '4242424242424242': null, // Visa — always succeeds
+    '4000000000000002': { code: 'card_declined', decline_code: 'generic_decline', message: 'Your card was declined.' },
+    '4000000000009995': { code: 'card_declined', decline_code: 'insufficient_funds', message: 'Your card has insufficient funds.' },
+    '4000000000000069': { code: 'expired_card', message: 'Your card has expired.' },
+    '4000000000000127': { code: 'incorrect_cvc', message: "Your card's security code is incorrect." },
+    '4000000000000119': { code: 'processing_error', message: 'An error occurred while processing your card. Try again in a little bit.' },
+    // attaching it to a customer succeeds; charging it is declined (docs.stripe.com/testing#declined-payments)
+    '4000000000000341': { code: 'card_declined', decline_code: 'generic_decline', message: 'Your card was declined.' },
+};
+// Stripe's well-known test payment-method / source tokens → outcome (null = success).
+// These map to the same outcomes as the PANs above (pm_card_visa ≡ 4242…, etc.).
+export const TEST_TOKEN_DECLINES = {
+    pm_card_visa: null,
+    tok_visa: null,
+    pm_card_mastercard: null,
+    tok_mastercard: null,
+    pm_card_amex: null,
+    tok_amex: null,
+    pm_card_discover: null,
+    tok_discover: null,
+    pm_card_chargeDeclined: TEST_CARD_DECLINES['4000000000000002'],
+    tok_chargeDeclined: TEST_CARD_DECLINES['4000000000000002'],
+    pm_card_chargeDeclinedInsufficientFunds: TEST_CARD_DECLINES['4000000000009995'],
+    tok_chargeDeclinedInsufficientFunds: TEST_CARD_DECLINES['4000000000009995'],
+    // the Visa-branded names docs.stripe.com/testing#declined-payments lists for the same two cards
+    pm_card_visa_chargeDeclined: TEST_CARD_DECLINES['4000000000000002'],
+    tok_visa_chargeDeclined: TEST_CARD_DECLINES['4000000000000002'],
+    pm_card_visa_chargeDeclinedInsufficientFunds: TEST_CARD_DECLINES['4000000000009995'],
+    tok_visa_chargeDeclinedInsufficientFunds: TEST_CARD_DECLINES['4000000000009995'],
+    pm_card_chargeDeclinedExpiredCard: TEST_CARD_DECLINES['4000000000000069'],
+    tok_chargeDeclinedExpiredCard: TEST_CARD_DECLINES['4000000000000069'],
+    pm_card_chargeDeclinedIncorrectCvc: TEST_CARD_DECLINES['4000000000000127'],
+    tok_chargeDeclinedIncorrectCvc: TEST_CARD_DECLINES['4000000000000127'],
+    pm_card_chargeDeclinedProcessingError: TEST_CARD_DECLINES['4000000000000119'],
+    tok_chargeDeclinedProcessingError: TEST_CARD_DECLINES['4000000000000119'],
+    pm_card_chargeCustomerFail: TEST_CARD_DECLINES['4000000000000341'],
+    tok_chargeCustomerFail: TEST_CARD_DECLINES['4000000000000341'],
+};
+// Pull a card identifier out of whatever the caller attached, in Stripe's accepted
+// shapes: a raw PAN under card[number] / source[number], or a token/pm id under
+// payment_method / source / card (string). Returns either a normalized PAN (digits
+// only) or a token string, or undefined when nothing card-shaped is present.
+function resolveCardRef(params) {
+    const fromObj = (o) => {
+        // the form reader (the kernel's readParams) coerces an all-digit card[number] to a JS number, so accept both.
+        const n = o && typeof o === 'object' ? o.number : undefined;
+        if (typeof n === 'string' || typeof n === 'number')
+            return String(n).replace(/\D/g, '');
+        return undefined;
+    };
+    const pan = fromObj(params.card) ?? fromObj(params.source);
+    if (pan)
+        return pan;
+    // a payment method or token by name, or payment_method_data[card][number] (a raw PAN in the modern nested shape)
+    const named = (v) => (typeof v === 'string' && v ? v : v && typeof v === 'object' ? fromObj(v.card) : undefined);
+    return ['payment_method', 'source', 'card', 'payment_method_data'].map((key) => named(params[key])).find((ref) => ref !== undefined);
+}
+export function declineFor(find, ...paramSets) {
+    for (const params of paramSets) {
+        const ref = resolveCardRef(params);
+        if (ref === undefined)
+            continue;
+        if (ref in TEST_CARD_DECLINES)
+            return TEST_CARD_DECLINES[ref];
+        if (ref in TEST_TOKEN_DECLINES)
+            return TEST_TOKEN_DECLINES[ref];
+        const pm = find('payment_method', ref);
+        if (pm && Object.prototype.hasOwnProperty.call(pm, '_declineOutcome')) {
+            return pm._declineOutcome;
+        }
+    }
+    return undefined;
+}
+// Stripe's well-known 3DS / SCA test instruments: confirming with one of these does NOT
+// immediately succeed — it returns the PaymentIntent in `requires_action` with a
+// `next_action` of type use_stripe_sdk (the client must run the 3DS challenge), exactly
+// like a card that requires authentication. A SECOND confirm (after the simulated
+// challenge) completes it. Covers both the PM tokens and the raw 3DS test PANs.
+const THREE_DS_PANS = new Set(['4000002500003155', '4000002760003184', '4000003800000446', '4000000000003220']);
+const THREE_DS_TOKENS = new Set(['pm_card_authenticationRequired', 'pm_card_authenticationRequiredOnSetup', 'pm_card_threeDSecure2Required', 'tok_threeDSecure2Required']);
+export function requiresAuthentication(...paramSets) {
+    for (const params of paramSets) {
+        const ref = resolveCardRef(params);
+        if (ref === undefined)
+            continue;
+        if (THREE_DS_PANS.has(ref) || THREE_DS_TOKENS.has(ref))
+            return true;
+    }
+    return false;
+}
+// The canonical next_action Stripe attaches to a PaymentIntent that needs a 3DS challenge.
+export function threeDsNextAction() {
+    return {
+        type: 'use_stripe_sdk',
+        use_stripe_sdk: { type: 'three_d_secure_redirect', stripe_js: 'https://js.stripe.com/v3' },
+    };
+}
+// ---- MICRO-DEPOSIT VERIFICATION (ACH / SEPA delayed bank debit) ----
+// Confirming a PaymentIntent/SetupIntent with a us_bank_account PM that requires
+// micro-deposit verification leaves it in `requires_action` with a
+// `verify_with_microdeposits` next_action. Verification finishes by submitting the two
+// deposit amounts (Stripe's documented test descriptor verifies with amounts 32 + 45) OR
+// a `descriptor_code` (the test value `SM11AA`). We model that exact pair so the verify
+// can FAIL with the wrong amounts. The well-known token that triggers this flow:
+const MICRODEPOSIT_TOKENS = new Set(['pm_usBankAccount_requiresVerification', 'pm_us_bank_account']);
+const MICRODEPOSIT_AMOUNTS = [32, 45];
+const MICRODEPOSIT_DESCRIPTOR = 'SM11AA';
+export function requiresMicrodeposits(...paramSets) {
+    for (const params of paramSets) {
+        const ref = resolveCardRef(params);
+        if (ref !== undefined && MICRODEPOSIT_TOKENS.has(ref))
+            return true;
+    }
+    return false;
+}
+// The canonical next_action for a PI/SI awaiting micro-deposit verification.
+export function microdepositsNextAction() {
+    return {
+        type: 'verify_with_microdeposits',
+        verify_with_microdeposits: {
+            arrival_date: 0, hosted_verification_url: 'https://payments.twin.local/microdeposit', microdeposit_type: 'amounts',
+        },
+    };
+}
+/** The two deposits' amounts as sent: the test values (docs.stripe.com/payments/ach-direct-debit/accept-a-payment). */
+function amountsMatch(params) {
+    const got = params.amounts.map((a) => Math.trunc(Number(a) || 0));
+    return got.length === 2 && got[0] === MICRODEPOSIT_AMOUNTS[0] && got[1] === MICRODEPOSIT_AMOUNTS[1];
+}
+/** The deposit's descriptor code as sent: the test value. */
+function descriptorMatches(params) {
+    return String(params.descriptor_code) === MICRODEPOSIT_DESCRIPTOR;
+}
+/** Stripe's refusal of deposits that do not match what was sent. */
+function depositMismatch(byAmounts) {
+    return byAmounts
+        ? err('The amounts provided do not match the amounts that were sent to the bank account.', 400, 'payment_intent_microdeposit_verification_amounts_mismatch')
+        : err('The descriptor code provided does not match the one that was sent to the bank account.', 400, 'payment_intent_microdeposit_verification_descriptor_code_mismatch');
+}
+// Validate the submitted micro-deposit verification params against the modeled test values.
+// Returns a vendor 400 on missing/both/wrong inputs, or null when the verification matches.
+export function verifyMicrodeposits(params, _existing) {
+    const hasAmounts = Array.isArray(params.amounts);
+    const hasDescriptor = typeof params.descriptor_code === 'string' && params.descriptor_code !== '';
+    if (hasAmounts === hasDescriptor)
+        return err('You must pass exactly one of `amounts` and `descriptor_code`.', 400, 'parameter_missing');
+    const matches = hasAmounts ? amountsMatch(params) : descriptorMatches(params);
+    return matches ? null : depositMismatch(hasAmounts);
+}
+// Build the real Stripe card-error envelope (HTTP 402). `param` is 'card' for card
+// errors; charge/payment_intent ids are attached when known so SDK error objects carry
+// them (Stripe does this for confirm/charge failures).
+/** A card error's body: `charge` "For card errors, the ID of the failed charge", and `payment_intent` "The PaymentIntent
+ *  object for errors returned on a request involving a PaymentIntent" (docs.stripe.com/api/errors). */
+export function cardError(outcome, attach = {}) {
+    return {
+        status: 402,
+        body: {
+            error: {
+                type: 'card_error',
+                code: outcome.code,
+                ...(outcome.decline_code ? { decline_code: outcome.decline_code } : {}),
+                message: outcome.message,
+                param: 'card',
+                ...(attach.charge ? { charge: attach.charge } : {}),
+                ...(attach.payment_intent ? { payment_intent: attach.payment_intent } : {}),
+            },
+        },
+    };
+}
+export function nowUnix(occurredAt) {
+    return Math.floor((occurredAt ? Date.parse(occurredAt) : 0) / 1000);
+}
+function rows(type, root) {
+    return projectResources(SERVICE, root).filter((r) => r.type === type);
+}
+function nextId(type, root) {
+    const prefix = PREFIX[type] ?? type;
+    let max = 0;
+    for (const r of rows(type, root)) {
+        const m = new RegExp(`^${prefix}_twin_(\\d+)$`).exec(r.id);
+        if (m)
+            max = Math.max(max, Number(m[1]));
+    }
+    return `${prefix}_twin_${max + 1}`;
+}
+// Real Stripe embeds the resource's OWN id inside its client_secret (format
+// `<id>_secret_<random>`) — Stripe.js's confirmPayment/confirmSetup parse the id back
+// out of the client_secret (splitting on `_secret`) to build the same-origin confirm
+// URL (`/v1/payment_intents/<id>/confirm`), rather than being told the id separately.
+// A secret that doesn't carry the real id breaks that round trip: a browser Stripe.js
+// call would try to confirm a resource whose id it invented from the string
+// (`'pi_twin_secret'` → `'pi_twin'`, which was never actually created). Every PI/SI a
+// caller might confirm CLIENT-SIDE (real Stripe.js — see the QA proxy's browserRouting
+// in packages/twin/stripe/src/index.ts) must mint a secret this way.
+export function mintClientSecret(id) {
+    return `${id}_secret_twin`;
+}
+// Stripe resource view: inject `object` + `id`, drop kernel meta.
+//
+// The kernel reserves the field name `type` as its resource-type discriminator, so a
+// stored vendor field literally named `type` is dropped on projection (see actions.ts
+// META). Several Stripe objects (payout.type, balance_transaction.type, event.type,
+// dispute uses `reason` not `type`) DO have a vendor `type`, so the create path stashes
+// it under the reserved key `_stripe_type` (a `_`-prefixed twin-internal field that the
+// conformance gate exempts) and we restore it to `type` here. This keeps the vendor
+// field faithful without touching the kernel discriminator. (price.type stays a declared
+// deviation — its create path predates this and one_time/recurring is derivable.)
+// A few Stripe objects have a DOTTED `object` value that differs from the twin's
+// (identifier-safe) resource type — e.g. type 'checkout_session' emits object
+// 'checkout.session'. Map them on emit so the `object` field is vendor-faithful.
+// (stripe-conformance.ts emitted() mirrors this map.)
+export const OBJECT_NAME = {
+    checkout_session: 'checkout.session',
+    billing_portal_session: 'billing_portal.session',
+    billing_portal_configuration: 'billing_portal.configuration',
+    // Stripe Tax: the TaxRate object is `tax_rate`, but a Tax calculation/registration
+    // emit the dotted object names `tax.calculation` / `tax.registration`.
+    tax_calculation: 'tax.calculation',
+    tax_registration: 'tax.registration',
+    // Billing Meters live under the `billing.meter` object; a test clock is `test_helpers.test_clock`.
+    billing_meter: 'billing.meter',
+    test_clock: 'test_helpers.test_clock',
+    // A connected account's external account is the `bank_account` object; an application-fee
+    // refund is `fee_refund`; a transfer reversal is `transfer_reversal` (1:1, no mapping).
+    external_account: 'bank_account',
+    // Stripe Tax transactions emit the dotted object name `tax.transaction`. Radar objects
+    // are `radar.review` (NOTE: the public review object is just `review`), `radar.value_list`,
+    // `radar.value_list_item`, `radar.rule`.
+    tax_transaction: 'tax.transaction',
+    radar_review: 'review',
+    radar_value_list: 'radar.value_list',
+    radar_value_list_item: 'radar.value_list_item',
+    radar_rule: 'radar.rule',
+    // Issuing objects carry dotted `object` names.
+    issuing_cardholder: 'issuing.cardholder',
+    issuing_card: 'issuing.card',
+    issuing_authorization: 'issuing.authorization',
+    issuing_transaction: 'issuing.transaction',
+    issuing_dispute: 'issuing.dispute',
+    // Terminal objects carry dotted `object` names.
+    terminal_location: 'terminal.location',
+    terminal_reader: 'terminal.reader',
+    terminal_configuration: 'terminal.configuration',
+    // Identity VerificationReport + Reporting ReportRun.
+    verification_report: 'identity.verification_report',
+    report_run: 'reporting.report_run',
+    // Customer cash-balance ledger entry.
+    cash_balance_transaction: 'customer_cash_balance_transaction',
+    // Billing: prepaid credit grants + usage alerts.
+    credit_grant: 'billing.credit_grant', billing_alert: 'billing.alert',
+    // Entitlements: account feature + per-customer active entitlement.
+    entitlements_feature: 'entitlements.feature', active_entitlement: 'entitlements.active_entitlement',
+    // Connect: embedded account session + apps secret.
+    account_session: 'account_session', apps_secret: 'apps.secret',
+    // Issuing: network token + personalization design.
+    issuing_token: 'issuing.token', personalization_design: 'issuing.personalization_design',
+    // Treasury: financial account + money-movement flows + ledger.
+    financial_account: 'treasury.financial_account',
+    outbound_payment: 'treasury.outbound_payment', outbound_transfer: 'treasury.outbound_transfer',
+    inbound_transfer: 'treasury.inbound_transfer',
+    received_credit: 'treasury.received_credit', received_debit: 'treasury.received_debit',
+    treasury_transaction: 'treasury.transaction', treasury_transaction_entry: 'treasury.transaction_entry',
+    // Climate.
+    climate_order: 'climate.order',
+    verification_session: 'identity.verification_session',
+    // Financial Connections.
+    fc_session: 'financial_connections.session', fc_account: 'financial_connections.account',
+    fc_transaction: 'financial_connections.transaction',
+    // Forwarding + Crypto onramp.
+    forwarding_request: 'forwarding.request', onramp_session: 'crypto.onramp_session',
+};
+// Exported for the pack's own modules that must render the SAME vendor view of a stored
+// resource (stripe-emit.ts synthesizes `data.object` for emitted events from it) — one
+// projection, no drift. Not a public API for consumers.
+export function view(type, r) {
+    // `_subscription_data` is twin-internal (a Checkout Session's create-only
+    // subscription_data, held for the completion transition to copy onto the created
+    // subscription) — real Stripe never returns it on the Session, so strip it here.
+    const { type: _t, updatedAt: _u, _stripe_type, _subscription_data, ...rest } = r;
+    const out = { object: OBJECT_NAME[type] ?? type, ...rest, id: r.id };
+    if (_stripe_type !== undefined)
+        out.type = _stripe_type;
+    return out;
+}
+// Real Stripe list pagination. Honors limit (default 10, max 100, min 1),
+// starting_after (cursor: exclude up to & including that id), ending_before
+// (cursor: take the page ending just before that id); computes has_more against
+// the FULL filtered set. Items must already be in Stripe's list order (newest
+// first by `created`). Unknown params are ignored, like Stripe.
+/** The page ending just before a cursor: the limit items immediately preceding it (docs.stripe.com/api/pagination). */
+function pageBefore(items, endingBefore, limit) {
+    const idx = items.findIndex((r) => r.id === endingBefore);
+    const upTo = idx === -1 ? items.length : idx; // unknown cursor → from the start
+    const start = Math.max(0, upTo - limit);
+    return { page: items.slice(start, upTo), hasMore: start > 0 };
+}
+/** Where a page after a cursor starts (docs.stripe.com/api/pagination); an unknown cursor starts from the first. */
+function afterCursor(items, startingAfter) {
+    const idx = items.findIndex((r) => r.id === startingAfter);
+    return idx === -1 ? 0 : idx + 1;
+}
+export function paginate(items, params) {
+    let limit = 10;
+    if (params.limit !== undefined) {
+        const n = Number(params.limit);
+        if (Number.isFinite(n))
+            limit = Math.min(100, Math.max(1, Math.trunc(n)));
+    }
+    const startingAfter = typeof params.starting_after === 'string' ? params.starting_after : undefined;
+    const endingBefore = typeof params.ending_before === 'string' ? params.ending_before : undefined;
+    if (endingBefore)
+        return pageBefore(items, endingBefore, limit);
+    const from = startingAfter ? afterCursor(items, startingAfter) : 0;
+    const page = items.slice(from, from + limit);
+    return { page, hasMore: from + limit < items.length };
+}
+async function writeResource(type, id, fields, op, root, occurredAt, apiVersion) {
+    const { resource } = await applyTwinWrite(SERVICE, { operation: op, subjectType: type, subjectId: id, fields, ...(occurredAt ? { occurredAt } : {}), actor: { kind: 'agent' } }, root);
+    const out = view(type, resource);
+    await afterStripeWrite(type, op, out, root, occurredAt, apiVersion);
+    return out;
+}
+/** What follows every stored Stripe write: the webhook for the state change and the stored Event
+ *  the Events API lists. The derived pack's write hook (manifest.ts) is this same function. */
+export async function afterStripeWrite(type, op, out, root, occurredAt, apiVersion, stripeAccount) {
+    // R17: fire the Stripe event/webhook for this state change (no-op if none registered). An event is a connected
+    // account's when its resource lives in one (a request made as it, the Stripe-Account header) or is a connected
+    // account itself (its account.updated): docs.stripe.com/connect/webhooks, "Connected accounts" scope.
+    // A write with no header is still a connected account's when the row it wrote is kept on that account's books (a
+    // payout or ledger entry's `_account`: an automatic payout time makes for it, semantics/balance.ts).
+    const account = stripeAccount ?? (type === 'account' && typeof out.id === 'string' && out.id !== PLATFORM_ACCOUNT_ID ? out.id : undefined) ?? ownerOf(type, out.id, root);
+    // a plan is stored as the recurring price it is; its own events carry the plan object (semantics/plans.ts)
+    const object = type === 'price' && op.startsWith('plan.') ? planOf(out) : out;
+    // events.full_types: the Stripe `event` envelope for this state change is also stored, so it appears in GET
+    // /v1/events (independent of webhook registration), exactly like real Stripe's stored Events API. Skip when the op
+    // has no mapped event type, and never for event/_idempotency writes themselves (no recursion / no meta-events). The
+    // event's id is minted once and is the delivered webhook's id and the stored event's alike: one event, one id, which
+    // a consumer deduplicates by and retrieves by.
+    const eventType = type !== 'event' && type !== IDEMPOTENCY_TYPE ? eventTypeFor(op) : null;
+    const id = eventType ? nextStripeEventId(root) : undefined;
+    // stored before it is delivered: a consumer that looks its webhook's event up finds it
+    if (eventType)
+        await persistStripeEvent(eventType, object, root, occurredAt, apiVersion, account, id);
+    await emitStripeEvent(op, object, { occurredAt: occurredAt ?? '1970-01-01T00:00:00.000Z', endpoints: webhookTargets(root), ...(account ? { account } : {}), ...(id ? { id } : {}) });
+}
+/** Event numbers taken in this process, per root, before their events are stored: two writes whose events overlap
+ *  (a webhook handler calling back in, concurrent requests) never take the same number. */
+const takenEventNumbers = new Map();
+/** The id the World's next event takes: its place in the World's events, so it is deterministic and never repeats
+ *  within a World (a Balance has no id of its own, so nothing about the object can tell two events apart). The number
+ *  is taken synchronously — the count of stored events, or the last number taken, whichever is higher. */
+export function nextStripeEventId(root) {
+    const key = root ?? '';
+    const n = Math.max(rows('event', root).length, takenEventNumbers.get(key) ?? 0) + 1;
+    takenEventNumbers.set(key, n);
+    return `evt_twin_${n}`;
+}
+/** The connected account whose books a stored row is kept on (its `_account`), if any. */
+function ownerOf(type, id, root) {
+    if (typeof id !== 'string')
+        return undefined;
+    const owner = rows(type, root).find((r) => r.id === id)?._account;
+    return typeof owner === 'string' ? owner : undefined;
+}
+// Persist a Stripe `event` resource (object 'event') for a state change into the action
+// log so the Events API (GET /v1/events) lists/retrieves it. Deterministic id derived
+// from the per-root event count; data.object carries the resource snapshot. Written via
+// applyTwinWrite directly (NOT writeResource) to avoid re-emitting an event for the event.
+export async function persistStripeEvent(eventType, resource, root, occurredAt, apiVersion, account, id) {
+    const eventId = id ?? nextStripeEventId(root);
+    const fields = {
+        object: 'event', _stripe_type: eventType, created: nowUnix(occurredAt), livemode: false,
+        pending_webhooks: 0, api_version: apiVersion && isValidApiVersion(apiVersion) ? apiVersion : TWIN_API_VERSION,
+        request: { id: null, idempotency_key: null },
+        data: { object: resource },
+        // a connected account's event names it, and is listed to requests made as it (semantics/webhook-endpoints.ts)
+        ...(account ? { account } : {}),
+    };
+    await applyTwinWrite(SERVICE, { operation: 'event.record', subjectType: 'event', subjectId: eventId, fields, ...(occurredAt ? { occurredAt } : {}), actor: { kind: 'system' } }, root);
+}
+function getOne(type, id, root) {
+    const r = rows(type, root).find((x) => x.id === id);
+    return r ? view(type, r) : undefined;
+}
+// Stripe list order: newest first by `created` (or `date` for invoiceitem), ties
+// broken by id descending so the order is stable for cursor pagination.
+/** The World's live webhook endpoints, from its tree: delivery survives a restart and belongs to
+ *  this World alone. A disabled or deleted endpoint receives nothing, like the vendor. */
+function webhookTargets(root) {
+    // `connect` is a create parameter the endpoint object does not answer, so it is read off the stored row
+    return rows('webhook_endpoint', root)
+        .map((r) => ({ w: view('webhook_endpoint', r), connect: asBool(r.connect) }))
+        .filter(({ w }) => !w.deleted && w.status !== 'disabled' && typeof w.url === 'string')
+        .map(({ w, connect }) => ({ url: String(w.url), ...(typeof w.secret === 'string' ? { secret: w.secret } : {}), ...(Array.isArray(w.enabled_events) ? { enabledEvents: w.enabled_events.map(String) } : {}), connect }));
+}
+// Stripe's `active=true|false` filters arrive as strings/booleans; normalize.
+export function asBool(v) {
+    return v === true || v === 'true' || v === 1 || v === '1';
+}
+// Tokenize on top-level AND/OR (we treat the whole query as either all-AND or all-OR; mixed
+// precedence is uncommon in practice and Stripe groups with parens we don't model — kept simple).
+function parseSearchQuery(query) {
+    const trimmed = query.trim();
+    if (!trimmed)
+        return null;
+    const disjunction = / OR /i.test(trimmed) && !/ AND /i.test(trimmed);
+    const parts = trimmed.split(disjunction ? / OR /i : / AND /i);
+    const clauses = [];
+    const re = /^\s*([A-Za-z0-9_]+(?:\[[^\]]+\])?)\s*(>=|<=|>|<|:)\s*(.+?)\s*$/;
+    for (const part of parts) {
+        const m = re.exec(part);
+        if (!m)
+            return null;
+        let value = m[3].trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))
+            value = value.slice(1, -1);
+        clauses.push({ field: m[1], op: m[2], value });
+    }
+    return { clauses, disjunction };
+}
+// Resolve a query field path to a value on a resource view: supports plain fields and the
+// metadata["key"] accessor, its key quoted either way (docs.stripe.com/search writes both `metadata["key"]:"value"` and,
+// in its "Charges metadata search" example, `metadata['key']:'value'`).
+function searchFieldValue(item, field) {
+    const meta = /^metadata\[["']?([^"'\]]+)["']?\]$/.exec(field);
+    if (meta) {
+        const m = item.metadata;
+        return m && typeof m === 'object' ? m[meta[1]] : undefined;
+    }
+    return item[field];
+}
+/** A search's numeric comparison other than `>=` (docs.stripe.com/search#search-query-language). */
+function otherComparison(op, a, n) {
+    switch (op) {
+        case '>': return a > n;
+        case '<': return a < n;
+        case '<=': return a <= n;
+    }
+    return false;
+}
+function evalSearchClause(item, c) {
+    const actual = searchFieldValue(item, c.field);
+    if (c.op === ':') {
+        if (c.value === 'null')
+            return actual === null || actual === undefined;
+        // numeric exact when both look numeric; else string-equality (case-sensitive, like Stripe tokens)
+        if (typeof actual === 'number' && /^-?\d+(\.\d+)?$/.test(c.value))
+            return actual === Number(c.value);
+        if (typeof actual === 'boolean')
+            return String(actual) === c.value;
+        return String(actual) === c.value;
+    }
+    const n = Number(c.value);
+    const a = Number(actual);
+    if (!Number.isFinite(n) || !Number.isFinite(a))
+        return false;
+    return c.op === '>=' ? a >= n : otherComparison(c.op, a, n);
+}
+// A Stripe search over rows in list order: the search-result envelope (object 'search_result',
+// has_more, data, next_page), or a vendor 400 when `query` is missing or unparseable. The page
+// size honors `limit`.
+export function searchOver(items, params, path) {
+    const query = typeof params.query === 'string' ? params.query : '';
+    if (!query)
+        return err('Missing required param: query.', 400, 'parameter_missing');
+    const parsed = parseSearchQuery(query);
+    if (!parsed)
+        return err(`Invalid search query: '${query}'.`, 400, 'parameter_invalid');
+    const all = items.filter((item) => parsed.disjunction ? parsed.clauses.some((c) => evalSearchClause(item, c)) : parsed.clauses.every((c) => evalSearchClause(item, c)));
+    const { page, hasMore } = paginate(all, params);
+    return { status: 200, body: { object: 'search_result', url: path, has_more: hasMore, data: page, next_page: null, total_count: null } };
+}
+// Subscriptions `?price=` filters to subs that include that price. The twin stores
+// items in whatever shape the caller sent (commonly items[].data[].price[.id]); be
+// lenient about the nesting and also accept a flat stored `price` field.
+export function subscriptionHasPrice(sub, priceId) {
+    if (sub.price === priceId)
+        return true;
+    const items = sub.items;
+    const data = Array.isArray(items?.data) ? items.data : Array.isArray(sub.items) ? sub.items : [];
+    return data.some((it) => it?.price === priceId || (!!it?.price && typeof it.price === 'object' && it.price.id === priceId));
+}
+// The `coupon` a subscription create/update is attaching, accepting both the top-level
+// `coupon=` shorthand and Stripe's discounts[0][coupon] array form. Returns undefined when
+// no coupon param was sent at all (so update can distinguish "not set" from "clear" = '').
+export function subscriptionCouponParam(params) {
+    if ('coupon' in params)
+        return typeof params.coupon === 'string' ? params.coupon : '';
+    const ds = params.discounts;
+    return Array.isArray(ds) && ds[0] && typeof ds[0] === 'object' ? couponOfDiscounts(ds[0]) : undefined;
+}
+/** discounts[0][coupon], Stripe's array form of a subscription's coupon (docs.stripe.com/api/subscriptions/create#create_subscription-discounts). */
+function couponOfDiscounts(first) {
+    return typeof first.coupon === 'string' ? first.coupon : undefined;
+}
+// Build Stripe's canonical `discount` object from a coupon (the shape a subscription /
+// customer carries once a coupon is applied). id `di_`, references the source coupon +
+// customer; end is null for a forever/repeating coupon (we don't compute repeat windows).
+/** A coupon applied: the Discount object, naming what it applies to ("customer: The ID of the customer associated
+ *  with this discount"; "subscription: The subscription that this coupon is applied to, if it is applied to a
+ *  particular subscription", docs.stripe.com/api/discounts/object). */
+export function buildDiscount(coupon, customer, at, on = {}) {
+    return {
+        id: `di_twin_${coupon.id}`, object: 'discount', coupon, customer: customer || null,
+        start: at, end: null, subscription: on.subscription ?? null, subscription_item: null,
+        invoice: null, invoice_item: null, promotion_code: null, checkout_session: null,
+    };
+}
+// The (price id, quantity) pairs a subscription bills, normalized across the shapes the
+// twin stores items in (the create form array items:[{price,quantity}], or the canonical
+// items:{data:[{price}]} list). Used to compute upcoming-invoice lines.
+export function subscriptionItemPairs(sub) {
+    const items = sub.items;
+    const data = Array.isArray(items?.data) ? items.data : Array.isArray(sub.items) ? sub.items : [];
+    const out = [];
+    for (const it of data) {
+        const p = it?.price;
+        const id = typeof p === 'string' ? p : (p && typeof p === 'object' ? String(p.id ?? '') : '');
+        if (id)
+            out.push({ price: id, quantity: Math.max(1, Math.trunc(Number(it.quantity) || 1)) });
+    }
+    // a bare `price` field (the connector's flattened shape) counts as one item.
+    if (out.length === 0 && typeof sub.price === 'string' && sub.price)
+        out.push({ price: sub.price, quantity: 1 });
+    return out;
+}
+// The raw item entries a subscription/checkout-derived-subscription create sent,
+// normalized to an ordered array. The form reader already turns the bracket form
+// items[0][price]=… into an array of objects (see lineItemEntries() above for the
+// identical `line_items` case); accept that, and a single-object shape defensively.
+export function subscriptionItemEntries(value) {
+    return Array.isArray(value) ? value.filter((x) => x && typeof x === 'object') : [];
+}
+const BILLING_INTERVALS = new Set(['day', 'week', 'month', 'year']);
+// Resolve the (interval, interval_count) a new subscription bills on, from the FIRST
+// entry's price (Stripe requires every item on a subscription to share one
+// billing_cycle_anchor, so the first item's cadence drives current_period_end).
+// `entries` is whatever subscriptionItemEntries()/lineItemEntries() produced — each
+// entry's `price` may be a price id string or an already-resolved Price object
+// (the checkout-session line_items shape). Falls back to a defensive month/1 default
+// (`resolved: false`) when no entry resolves to a stored recurring price — e.g. an
+// inline price_data with no persisted Price, or (real Stripe would 400) no item at
+// all. This should not happen for a well-formed subscription create; it exists so
+// current_period_end is always populated rather than silently NaN/undefined.
+export function resolveSubscriptionBillingInterval(entries, find) {
+    // the first item whose price recurs sets the billing interval
+    const recurring = entries.map((entry) => {
+        const p = entry.price;
+        const priceId = typeof p === 'string' ? p : (p && typeof p === 'object' ? String(p.id ?? '') : '');
+        return (priceId ? find('price', priceId)?.recurring : undefined);
+    }).find((r) => r && typeof r === 'object' && typeof r.interval === 'string' && BILLING_INTERVALS.has(r.interval));
+    return recurring
+        ? { interval: recurring.interval, interval_count: Math.max(1, Math.trunc(Number(recurring.interval_count) || 1)), resolved: true }
+        : { interval: 'month', interval_count: 1, resolved: false };
+}
+// Add one billing period to a unix timestamp, real-Stripe-faithful: `month`/`year`
+// add CALENDAR months clamped to the target month's last day (Jan 31 + 1 month ->
+// Feb 28/29, not an overflow into March, matching how Stripe advances a billing_
+// cycle_anchor); `day`/`week` are exact multiples of 86400/604800 seconds.
+export function addBillingInterval(atUnix, interval, count) {
+    const n = Math.max(1, Math.trunc(count) || 1);
+    if (interval === 'day')
+        return atUnix + n * 24 * 3600;
+    if (interval === 'week')
+        return atUnix + n * 7 * 24 * 3600;
+    const months = interval === 'year' ? n * 12 : n;
+    const d = new Date(atUnix * 1000);
+    const anchorDay = d.getUTCDate();
+    const first = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + months, 1, d.getUTCHours(), d.getUTCMinutes(), d.getUTCSeconds()));
+    const daysInTargetMonth = new Date(Date.UTC(first.getUTCFullYear(), first.getUTCMonth() + 1, 0)).getUTCDate();
+    first.setUTCDate(Math.min(anchorDay, daysInTargetMonth));
+    return Math.floor(first.getTime() / 1000);
+}
+// Build the canonical items.data list Stripe returns on a subscription: a real
+// SubscriptionItem per entry, carrying the resolved Price object plus the
+// deprecated-but-still-served `plan` mirror (some integrations still read
+// item.plan.interval / .product / .id off a subscription item). `subId` is the
+// subscription's own (already-assigned, see the `id` pre-generation in the POST
+// handler) id, so each item's `subscription` back-reference round-trips. Fixes the
+// prior always-empty `items.data` on subscription create — real Stripe's create
+// response includes the actual items, mirroring what was requested.
+/** What a subscription item carries of its price: the Price itself and its plan view (a subscription item answers both,
+ *  docs.stripe.com/api/subscription_items/object), by the price's id or an already-resolved Price. */
+export function subscriptionItemPrice(p, find) {
+    const priceId = typeof p === 'string' ? p : (p && typeof p === 'object' ? String(p.id ?? '') : '');
+    const price = priceId ? find('price', priceId) : undefined;
+    const recurring = price?.recurring;
+    const plan = price ? {
+        id: price.id, object: 'plan', active: price.active ?? true, amount: price.unit_amount ?? null,
+        amount_decimal: price.unit_amount_decimal ?? null, billing_scheme: price.billing_scheme ?? 'per_unit',
+        currency: price.currency ?? 'usd', interval: recurring?.interval ?? null,
+        interval_count: recurring?.interval_count ?? 1, livemode: false,
+        metadata: price.metadata ?? {}, nickname: price.nickname ?? null,
+        product: price.product ?? null, tiers_mode: price.tiers_mode ?? null, usage_type: 'licensed',
+    } : null;
+    return { price: price ?? (priceId || null), plan };
+}
+export function buildSubscriptionItemsList(entries, subId, at, find) {
+    const data = entries.map((entry, i) => {
+        const quantity = entry.quantity !== undefined ? Math.max(1, Math.trunc(Number(entry.quantity) || 1)) : 1;
+        const { price, plan } = subscriptionItemPrice(entry.price, find);
+        return {
+            id: `si_twin_${subId}_${i + 1}`, object: 'subscription_item',
+            price, plan, quantity, subscription: subId,
+            created: at, metadata: {}, discounts: [], billing_thresholds: null, tax_rates: [],
+        };
+    });
+    return { object: 'list', data, has_more: false, total_count: data.length, url: `/v1/subscription_items?subscription=${subId}` };
+}
+/** What a per-unit price bills for a quantity: its `unit_amount` times the quantity, or, for a price given only as a
+ *  decimal (`unit_amount_decimal`, "represented as a decimal string with at most 12 decimal places", spec/openapi.json.gz),
+ *  the decimal times the quantity rounded to a whole amount: "rounding occurs after multiplying the quantity by the
+ *  decimal amount ... `0.05 * 30 = 1.5`, which rounds up to 2 cents" (docs.stripe.com/products-prices/manage-prices).
+ *  Where the documentation stops and the twin decides: the rounding is to the nearest whole amount, halves up. */
+export function priceAmount(price, quantity) {
+    if (!price)
+        return 0;
+    if (typeof price.unit_amount === 'number')
+        return price.unit_amount * quantity;
+    const decimal = Number(price.unit_amount_decimal);
+    return Number.isFinite(decimal) ? Math.round(decimal * quantity) : 0;
+}
+// Apply a coupon's discount to a subtotal (percent_off or amount_off), clamped at 0.
+export function applyCouponDiscount(subtotal, coupon) {
+    return !coupon ? 0 : typeof coupon.percent_off === 'number' ? Math.round((subtotal * coupon.percent_off) / 100) : typeof coupon.amount_off === 'number' ? amountOffDiscount(subtotal, coupon.amount_off) : 0;
+}
+/** A fixed-amount coupon's discount, never more than the subtotal (docs.stripe.com/api/coupons/object#coupon_object-amount_off). */
+function amountOffDiscount(subtotal, amountOff) {
+    return Math.min(subtotal, Math.trunc(amountOff));
+}
+// Resolve a subscription/checkout trial window from trial_period_days or trial_end. A
+// trial_end of "now" / 0 / absent means no trial. Returns {start,end} unix or undefined.
+export function resolveTrial(params, at) {
+    if (params.trial_period_days !== undefined) {
+        const days = Math.trunc(Number(params.trial_period_days) || 0);
+        if (days > 0)
+            return { start: at, end: at + days * 24 * 3600 };
+    }
+    if (params.trial_end !== undefined && params.trial_end !== 'now') {
+        const end = Math.trunc(Number(params.trial_end) || 0);
+        if (end > at)
+            return { start: at, end };
+    }
+    return undefined;
+}
+// Create a resource from form params, stamping object + id + created + the given
+// defaults. Only real Stripe field names are emitted (conformance-checked).
+// A vendor `type` field (a price's one_time or recurring, a payout's bank_account) always collides with the kernel's
+// row type, so it is stashed under `_stripe_type` and restored by view().
+export function stashVendorType(_type, fields) {
+    if (!('type' in fields))
+        return fields;
+    const { type: vt, ...rest } = fields;
+    return { ...rest, _stripe_type: vt };
+}
+async function create(type, params, defaults, req, opts = {}) {
+    // honor a caller-provided id (seeding uses the catalog's real prod_*/price_* ids);
+    // otherwise assign one. The id is identity, not a stored field.
+    const { id: providedId, ...rest } = params;
+    const id = typeof providedId === 'string' && providedId ? providedId : nextId(type, req.root);
+    // Most Stripe objects stamp `created`; a few (invoiceitem) use a differently-named
+    // timestamp instead (`date`) and have NO `created` field — honor that, don't fabricate.
+    const fields = stashVendorType(type, { object: OBJECT_NAME[type] ?? type, [opts.timeField ?? 'created']: nowUnix(req.occurredAt), ...defaults, ...rest });
+    return { status: 200, body: await writeResource(type, id, fields, `${type}.create`, req.root, req.occurredAt, req.apiVersion) };
+}
+// ── ISSUING helpers: spending controls, real-time-auth shapes ─────────────────────────
+// Authorization.card is the FULL Card object in every vendor egress (API responses and
+// webhook payloads) — it is not expandable (stripe@22.3.0 Issuing.Authorization.card:
+// Stripe.Issuing.Card). The twin stores the id internally and embeds at the boundary;
+// cardholder stays an id string (expandable, unexpanded default). Caught live: the
+// issuing-bridge reads event.data.object.card.id and refused every twin presentment.
+export function embedIssuingAuthorizationCard(body, root) {
+    if (typeof body.card === 'string') {
+        const cardRow = getOne('issuing_card', body.card, root);
+        if (cardRow !== undefined)
+            body.card = cardRow;
+    }
+    return body;
+}
+// The closed interval set for spending_controls[spending_limits][][interval]
+// (stripe@22.3.0 Issuing/Cards.d.ts SpendingLimit.Interval — a documented closed enum).
+const SPENDING_LIMIT_INTERVALS = new Set(['all_time', 'daily', 'monthly', 'per_authorization', 'weekly', 'yearly']);
+// The stored SpendingControls shape (stripe@22.3.0 Card.SpendingControls): categories and
+// countries are nullable arrays, spending_limits an array of {amount, categories, interval}.
+export function emptySpendingControls() {
+    return {
+        allowed_categories: null, allowed_merchant_countries: null,
+        blocked_categories: null, blocked_merchant_countries: null,
+        spending_limits: [], spending_limits_currency: null,
+    };
+}
+/** A malformed spending_controls dictionary's refusal, by what is wrong with it (normalizeSpendingControls). */
+function controlsRefused(what, i = 0) {
+    switch (what) {
+        case 'dictionary': return { error: err('Invalid spending_controls: must be a dictionary.', 400, 'parameter_invalid_dictionary') };
+        case 'categories': return { error: err('spending_controls[allowed_categories] cannot be set with spending_controls[blocked_categories].', 400) };
+        case 'countries': return { error: err('spending_controls[allowed_merchant_countries] cannot be set with spending_controls[blocked_merchant_countries].', 400) };
+        case 'limit': return { error: err(`Invalid spending_controls[spending_limits][${i}]: must be a dictionary.`, 400, 'parameter_invalid_dictionary') };
+        case 'amount': return { error: err(`Invalid integer: spending_controls[spending_limits][${i}][amount] must be a positive integer.`, 400, 'parameter_invalid_integer') };
+        case 'interval': return { error: err(`Invalid spending_controls[spending_limits][${i}][interval]: must be one of 'all_time', 'daily', 'monthly', 'per_authorization', 'weekly', or 'yearly'.`, 400, 'parameter_invalid_string_enum') };
+    }
+}
+// Validate + normalize a caller-provided spending_controls dictionary (card create/update).
+// Vendor rules enforced: interval must be in the closed enum; a spending limit amount is a
+// positive integer; allowed_categories "Cannot be set with blocked_categories" (and the
+// merchant-country pair likewise) — both restrictions verbatim from the SDK's field docs.
+export function normalizeSpendingControls(raw, currency) {
+    if (raw === undefined)
+        return {};
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return controlsRefused('dictionary');
+    const sc = raw;
+    const strArr = (v) => (Array.isArray(v) ? v.map(String) : undefined);
+    const allowedCats = strArr(sc.allowed_categories);
+    const blockedCats = strArr(sc.blocked_categories);
+    if (allowedCats?.length && blockedCats?.length)
+        return controlsRefused('categories');
+    const allowedCountries = strArr(sc.allowed_merchant_countries);
+    const blockedCountries = strArr(sc.blocked_merchant_countries);
+    if (allowedCountries?.length && blockedCountries?.length)
+        return controlsRefused('countries');
+    const limits = [];
+    const rawLimits = Array.isArray(sc.spending_limits) ? sc.spending_limits : [];
+    for (let i = 0; i < rawLimits.length; i++) {
+        const l = rawLimits[i];
+        if (!l || typeof l !== 'object' || Array.isArray(l))
+            return controlsRefused('limit', i);
+        const { amount, interval, categories } = l;
+        if (typeof amount !== 'number' || !Number.isInteger(amount) || amount <= 0)
+            return controlsRefused('amount', i);
+        if (typeof interval !== 'string' || !SPENDING_LIMIT_INTERVALS.has(interval))
+            return controlsRefused('interval', i);
+        const cats = strArr(categories);
+        limits.push({ amount, categories: cats?.length ? cats : null, interval });
+    }
+    const arrOrNull = (v) => (v === undefined ? undefined : v.length ? v : null);
+    const controls = {
+        ...emptySpendingControls(),
+        spending_limits: limits,
+        ...(limits.length ? { spending_limits_currency: typeof sc.spending_limits_currency === 'string' ? sc.spending_limits_currency : currency } : {}),
+    };
+    for (const [key, v] of [
+        ['allowed_categories', arrOrNull(allowedCats)], ['blocked_categories', arrOrNull(blockedCats)],
+        ['allowed_merchant_countries', arrOrNull(allowedCountries)], ['blocked_merchant_countries', arrOrNull(blockedCountries)],
+    ]) {
+        if (v !== undefined)
+            controls[key] = v;
+    }
+    return { controls };
+}
+// Start of the current spending-limit window, seconds since epoch (UTC calendar windows;
+// weekly starts Monday 00:00 UTC — the week-start day is not vendor-documented).
+function issuingWindowStartSec(interval, nowSec) {
+    if (interval === 'all_time')
+        return 0;
+    const d = new Date(nowSec * 1000);
+    if (interval === 'daily')
+        return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()) / 1000;
+    if (interval === 'weekly') {
+        const monOffset = (d.getUTCDay() + 6) % 7; // Monday = 0
+        return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() - monOffset) / 1000;
+    }
+    if (interval === 'monthly')
+        return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1) / 1000;
+    if (interval === 'yearly')
+        return Date.UTC(d.getUTCFullYear(), 0, 1) / 1000;
+    return 0;
+}
+// Evaluate one spending_controls dictionary against a presented authorization. Returns a
+// human-readable reason_message when a control declines the authorization, else null.
+// (The request_history.reason for any violation is 'spending_controls' — the vendor enum's
+// single value for controls declines.)
+export function spendingControlsViolation(controls, opts) {
+    if (!controls || typeof controls !== 'object')
+        return null;
+    const sc = controls;
+    const list = (v) => (Array.isArray(v) && v.length ? v.map(String) : null);
+    const allowedCats = list(sc.allowed_categories);
+    if (allowedCats && !allowedCats.includes(opts.category))
+        return `merchant category ${opts.category} is not in allowed_categories`;
+    const blockedCats = list(sc.blocked_categories);
+    if (blockedCats?.includes(opts.category))
+        return `merchant category ${opts.category} is in blocked_categories`;
+    const allowedCountries = list(sc.allowed_merchant_countries);
+    if (allowedCountries && (!opts.country || !allowedCountries.includes(opts.country)))
+        return `merchant country ${opts.country ?? '(none)'} is not in allowed_merchant_countries`;
+    const blockedCountries = list(sc.blocked_merchant_countries);
+    if (blockedCountries && opts.country && blockedCountries.includes(opts.country))
+        return `merchant country ${opts.country} is in blocked_merchant_countries`;
+    for (const rawLimit of Array.isArray(sc.spending_limits) ? sc.spending_limits : []) {
+        if (!rawLimit || typeof rawLimit !== 'object')
+            continue;
+        const l = rawLimit;
+        const limit = Number(l.amount) || 0;
+        if (limit <= 0)
+            continue;
+        const limCats = list(l.categories);
+        if (limCats && !limCats.includes(opts.category))
+            continue;
+        const interval = String(l.interval ?? '');
+        if (interval === 'per_authorization') {
+            if (opts.amount > limit)
+                return `amount exceeds the per_authorization spending limit of ${limit}`;
+            continue;
+        }
+        const start = issuingWindowStartSec(interval, opts.nowSec);
+        const spent = opts.priorApproved
+            .filter((a) => a.created >= start && (!limCats || limCats.includes(a.category)))
+            .reduce((s, a) => s + a.amount, 0);
+        if (spent + opts.amount > limit)
+            return `amount exceeds the ${interval} spending limit of ${limit}`;
+    }
+    return null;
+}
+// Stripe's dispute.evidence is a flat bag of (mostly null) string fields; the twin
+// emits the canonical empty shape so the object is shaped right without fabricating
+// content. Callers can overwrite individual fields via POST /v1/disputes/:id.
+export function disputeEvidence() {
+    return {
+        access_activity_log: null, billing_address: null, cancellation_policy: null,
+        cancellation_policy_disclosure: null, cancellation_rebuttal: null, customer_communication: null,
+        customer_email_address: null, customer_name: null, customer_purchase_ip: null, customer_signature: null,
+        duplicate_charge_documentation: null, duplicate_charge_explanation: null, duplicate_charge_id: null,
+        product_description: null, receipt: null, refund_policy: null, refund_policy_disclosure: null,
+        refund_refusal_explanation: null, service_date: null, service_documentation: null,
+        shipping_address: null, shipping_carrier: null, shipping_date: null, shipping_documentation: null,
+        shipping_tracking_number: null, uncategorized_file: null, uncategorized_text: null,
+        // required by the served spec; empty for a dispute not eligible for enhanced evidence (Visa CE 3.0 eligibility
+        // comes from its own test card, pm_card_createCe3EligibleDispute: docs.stripe.com/disputes/api/visa-ce3)
+        enhanced_evidence: {},
+    };
+}
+const subParams = (params, k) => (params[k] && typeof params[k] === 'object' ? params[k] : {});
+/** A card's own sub-object, from the number and expiry given. */
+function cardSubObject(params) {
+    const c = subParams(params, 'card');
+    // the form reader (the kernel's readParams) coerces an all-digit card[number] to a JS number (same as any
+    // other numeric-looking form field) — accept both shapes so a raw test PAN still
+    // produces its real last4 instead of silently falling back to the '4242' default.
+    const number = typeof c.number === 'string' ? c.number.replace(/\D/g, '')
+        : typeof c.number === 'number' ? String(c.number).replace(/\D/g, '') : '';
+    return { card: {
+            brand: 'visa', last4: number ? number.slice(-4) : '4242',
+            exp_month: Number(c.exp_month) || 12, exp_year: Number(c.exp_year) || 2034,
+            funding: 'credit', country: 'US',
+            checks: { address_line1_check: null, address_postal_code_check: null, cvc_check: 'pass' },
+            networks: { available: ['visa'], preferred: null },
+            three_d_secure_usage: { supported: true }, wallet: null,
+        } };
+}
+/** A SEPA Direct Debit account's sub-object, from its IBAN. */
+function sepaDebitSubObject(params) {
+    const s = subParams(params, 'sepa_debit');
+    const iban = typeof s.iban === 'string' ? s.iban.replace(/\s/g, '') : '';
+    return { sepa_debit: {
+            bank_code: '37040044', branch_code: '', country: iban ? iban.slice(0, 2).toUpperCase() : 'DE',
+            fingerprint: 'twin_sepa_fp', last4: iban ? iban.slice(-4) : '3000',
+            generated_from: { charge: null, setup_attempt: null }, mandate: null,
+        } };
+}
+/** A US bank account's sub-object, from its numbers. */
+function usBankAccountSubObject(params) {
+    const a = subParams(params, 'us_bank_account');
+    const num = typeof a.account_number === 'string' ? a.account_number.replace(/\D/g, '') : '';
+    return { us_bank_account: {
+            account_holder_type: a.account_holder_type ?? 'individual',
+            account_type: a.account_type ?? 'checking',
+            bank_name: 'STRIPE TEST BANK', financial_connections_account: null,
+            fingerprint: 'twin_ach_fp', last4: num ? num.slice(-4) : '6789',
+            networks: { preferred: 'ach', supported: ['ach'] },
+            routing_number: typeof a.routing_number === 'string' ? a.routing_number : '110000000',
+            status_details: {},
+        } };
+}
+/** A Link or Cash App Pay method's sub-object, which carries nothing the twin knows. */
+function walletSubObject(pmType) {
+    return pmType === 'link' ? { link: { email: null, persistent_token: null } } : { cashapp: { buyer_id: null, cashtag: null } };
+}
+/** Wallet / other rails the twin doesn't deep-model: an empty type bag, like Stripe's for a minimally-specified
+ *  PaymentMethod (the `type` field is the truth). */
+function otherSubObject(pmType) {
+    return { [pmType]: {} };
+}
+const SUB_OBJECTS = {
+    card: cardSubObject, sepa_debit: sepaDebitSubObject, us_bank_account: usBankAccountSubObject,
+    link: (_p, t) => walletSubObject(t), cashapp: (_p, t) => walletSubObject(t),
+};
+export function paymentMethodSubObject(pmType, params) {
+    return SUB_OBJECTS[pmType] ? SUB_OBJECTS[pmType](params, pmType) : otherSubObject(pmType);
+}
+// ---- CONNECT: connected accounts (vendor-faithful) ----
+// A connected account (Stripe Connect) represents a business onboarded onto the
+// platform. We model the OBJECT (id `acct_`, object 'account', type express|standard|
+// custom, country, email, charges_enabled/payouts_enabled/details_submitted booleans,
+// capabilities map, and the `requirements` hash) plus transfers to those accounts and
+// payout-to-account links. The hosted Connect onboarding flow is Stripe's own page — we
+// model the Account API object + its login_links, the API surface apps depend on. A freshly-created account is NOT yet active: charges/payouts disabled,
+// details_submitted false, and `requirements` lists the outstanding onboarding fields,
+// exactly like real Stripe before onboarding completes.
+export const ACCOUNT_TYPES = new Set(['express', 'standard', 'custom']);
+// The fixed id of the platform's OWN account (GET/POST /v1/account, singular).
+export const PLATFORM_ACCOUNT_ID = 'acct_twin_self';
+// Stripe's canonical "freshly created, not yet onboarded" requirements hash: a set of
+// currently-due fields, empty arrays for the other buckets, and a null deadline. This
+// matches the shape real Stripe returns for a brand-new account before onboarding.
+export function accountRequirements() {
+    return {
+        alternatives: [],
+        current_deadline: null,
+        currently_due: ['business_profile.mcc', 'business_profile.url', 'external_account', 'tos_acceptance.date', 'tos_acceptance.ip'],
+        disabled_reason: 'requirements.past_due',
+        errors: [],
+        eventually_due: ['business_profile.mcc', 'business_profile.url', 'external_account', 'tos_acceptance.date', 'tos_acceptance.ip'],
+        past_due: [],
+        pending_verification: [],
+    };
+}
+// Normalize the requested `capabilities` create param (Stripe sends
+// capabilities[card_payments][requested]=true) into the account.capabilities map,
+// whose values are the capability STATUS enum (active|inactive|pending). A requested
+// capability on a brand-new account starts `inactive` (not yet granted), like Stripe.
+export function accountCapabilities(params) {
+    const requested = params.capabilities;
+    const out = {};
+    if (requested && typeof requested === 'object') {
+        for (const key of Object.keys(requested))
+            out[key] = 'inactive';
+    }
+    return out;
+}
+// Normalize an account's `settings`, focusing on the payout SCHEDULE (the automatic-payout
+// cadence: settings.payouts.schedule.{interval, weekly_anchor, monthly_anchor, delay_days}).
+// Stripe's default is a daily automatic schedule with a default delay; an explicit schedule
+// merges over the existing one. Other settings sub-objects are emitted with canonical empty
+// shapes so the object is shaped right without fabricating values.
+export function accountSettings(input, existing) {
+    const base = existing ?? {};
+    const prevPayouts = (base.payouts && typeof base.payouts === 'object' ? base.payouts : {});
+    const prevSchedule = (prevPayouts.schedule && typeof prevPayouts.schedule === 'object' ? prevPayouts.schedule : {});
+    const inObj = (input && typeof input === 'object' ? input : {});
+    const inPayouts = (inObj.payouts && typeof inObj.payouts === 'object' ? inObj.payouts : {});
+    const inSchedule = (inPayouts.schedule && typeof inPayouts.schedule === 'object' ? inPayouts.schedule : {});
+    const interval = typeof inSchedule.interval === 'string' ? inSchedule.interval : (typeof prevSchedule.interval === 'string' ? prevSchedule.interval : 'daily');
+    const schedule = {
+        interval,
+        delay_days: inSchedule.delay_days !== undefined ? Math.trunc(Number(inSchedule.delay_days) || 0) : (prevSchedule.delay_days ?? 2),
+        weekly_anchor: interval === 'weekly' ? (inSchedule.weekly_anchor ?? prevSchedule.weekly_anchor ?? 'monday') : null,
+        monthly_anchor: interval === 'monthly' ? (inSchedule.monthly_anchor !== undefined ? Math.trunc(Number(inSchedule.monthly_anchor)) : (prevSchedule.monthly_anchor ?? 1)) : null,
+    };
+    // the sections a new account's settings answer with, as the Account object's example shows a fresh account's
+    // (docs.stripe.com/api/accounts/object); what the account has set is kept
+    const fresh = {
+        bacs_debit_payments: { display_name: null, service_user_number: null },
+        branding: { icon: null, logo: null, primary_color: null, secondary_color: null },
+        card_issuing: { tos_acceptance: { date: null, ip: null } },
+        card_payments: { decline_on: { avs_failure: false, cvc_failure: false }, statement_descriptor_prefix: null, statement_descriptor_prefix_kanji: null, statement_descriptor_prefix_kana: null },
+        dashboard: { display_name: null, timezone: 'Etc/UTC' },
+        invoices: { default_account_tax_ids: null, hosted_payment_method_save: null },
+        payments: { statement_descriptor: null, statement_descriptor_kana: null, statement_descriptor_kanji: null },
+        sepa_debit_payments: {},
+    };
+    const sections = Object.fromEntries(Object.entries(fresh).map(([k, v]) => [k, base[k] && typeof base[k] === 'object' ? { ...v, ...base[k] } : v]));
+    return {
+        ...base,
+        ...sections,
+        payouts: { ...prevPayouts, schedule, statement_descriptor: inPayouts.statement_descriptor ?? prevPayouts.statement_descriptor ?? null, debit_negative_balances: inPayouts.debit_negative_balances ?? prevPayouts.debit_negative_balances ?? true },
+    };
+}
+// Resolve the unit amount + currency for one line_items entry, preferring an existing
+// price (looked up in the action log) then inline price_data. Unknown/missing price →
+// 0 amount with the session currency (faithful: Stripe would 400, but we keep the
+// referenced-price path strict and leave amount 0 only when nothing is resolvable).
+export function resolveLineItem(entry, index, fallbackCurrency, find) {
+    const quantity = entry.quantity === undefined ? 1 : Math.max(0, Math.trunc(Number(entry.quantity) || 0));
+    let billed;
+    let currency = fallbackCurrency;
+    let priceField = null;
+    let priceMissing;
+    // a line item's description "Defaults to product name" (spec/openapi.json.gz, the `item` schema)
+    let description = null;
+    const priceRef = typeof entry.price === 'string' ? entry.price : undefined;
+    const priceData = entry.price_data && typeof entry.price_data === 'object' ? entry.price_data : undefined;
+    if (priceRef) {
+        const price = find('price', priceRef);
+        if (!price) {
+            priceMissing = priceRef;
+        }
+        else {
+            billed = price;
+            currency = typeof price.currency === 'string' ? price.currency : currency;
+            priceField = price;
+            const product = typeof price.product === 'string' ? find('product', price.product) : undefined;
+            description = typeof product?.name === 'string' ? product.name : null;
+        }
+    }
+    else if (priceData) {
+        billed = { unit_amount: priceData.unit_amount_decimal !== undefined ? undefined : Number(priceData.unit_amount) || 0, unit_amount_decimal: priceData.unit_amount_decimal };
+        currency = typeof priceData.currency === 'string' ? priceData.currency : currency;
+        priceField = null; // inline price_data is not persisted as a Price object
+        const productData = priceData.product_data;
+        const product = typeof priceData.product === 'string' ? find('product', priceData.product) : undefined;
+        description = typeof productData?.name === 'string' ? productData.name : typeof product?.name === 'string' ? product.name : null;
+    }
+    const amount_subtotal = priceAmount(billed, quantity);
+    const item = {
+        object: 'item', id: `li_twin_${index + 1}`, amount_discount: 0, amount_subtotal,
+        amount_tax: 0, amount_total: amount_subtotal, currency, description,
+        price: priceField, quantity,
+    };
+    return { item, priceMissing };
+}
+// Normalize the bracket-form line_items param to an ordered array. The form reader
+// turns line_items[0][price]=… into an array of objects already; accept that, and a
+// single-object shape defensively.
+export function lineItemEntries(params) {
+    const li = params.line_items;
+    return Array.isArray(li) ? li.filter((x) => x && typeof x === 'object') : [];
+}
+// ---- IDEMPOTENCY KEYS (vendor-faithful) ----
+// Real Stripe honors the `Idempotency-Key` header on POST: the first request with a
+// key executes and the (status + body) response is stored against the key; a replay
+// with the SAME key returns the SAME stored response WITHOUT re-applying the write.
+// We persist the stored response as an `_idempotency` resource in the action log
+// (per-root, so a fork has its own keyspace). `_idempotency` is a twin-internal type
+// (never served as a Stripe object), so it does not affect spec conformance.
+//
+// Note: real Stripe only persists idempotency for responses it considers "completed"
+// (2xx and most 4xx, including card 402s) and scopes the key to the account; here we
+// store every executed POST response (success and error alike), keyed per-root.
+const IDEMPOTENCY_TYPE = '_idempotency';
+// ── THE MONEY MODEL: a charge and the refunds taken out of it ──────────────────────────
+//
+// The rule this section exists to hold: A FACT RECORDED ON ONE MONEY OBJECT IS VISIBLE FROM
+// THE OBJECT IT CONCERNS. A twin that mints a `succeeded` Refund and leaves the Charge saying
+// `amount_refunded: 0` hands a consumer reconciling a ledger the wrong answer with NO error to
+// tell them it is wrong — worse than refusing, because it looks like it worked.
+//
+// Every Charge carries the same money spine: the captured/refunded scalars, and a `refunds`
+// sub-list (real Stripe's Charge always has one, empty or not).
+function emptyRefundsList(chargeId) {
+    return { object: 'list', data: [], has_more: false, total_count: 0, url: `/v1/charges/${chargeId}/refunds` };
+}
+export function chargeDefaults(chargeId, amount, captured, occurredAt) {
+    return {
+        status: 'succeeded', paid: true, captured, refunded: false, disputed: false,
+        amount_captured: captured ? amount : 0, amount_refunded: 0, metadata: {},
+        refunds: emptyRefundsList(chargeId),
+        ...(captured ? {} : { capture_before: nowUnix(occurredAt) + 7 * 24 * 3600 }),
+        billing_details: { address: null, email: null, name: null, phone: null }, livemode: false,
+    };
+}
+/**
+ * Public entry: honors the Idempotency-Key (replay → stored response, no re-write)
+ * then delegates to the router. Only POSTs are idempotent (matches Stripe; GET/DELETE
+ * pass straight through). A read-only twin never stores (it cannot write).
+ */
+/** Stripe's API as one call: the request goes through the pack's own dispatch (the derived dispatch over
+ *  its semantics, its derived core and the hand-written routes below), so a caller that holds no
+ *  HTTP server reaches exactly what an SDK does. `occurredAt` pins the World instant. */
+export async function handleStripeTwinRequest(req) {
+    const twin = createStripeTwinFetch({ ...(req.root !== undefined ? { root: req.root } : {}), readOnly: req.readOnly ?? false, ...(req.occurredAt ? { clock: () => req.occurredAt } : {}) });
+    const method = req.method.toUpperCase();
+    const headers = { 'content-type': 'application/x-www-form-urlencoded' };
+    if (req.idempotencyKey)
+        headers['idempotency-key'] = req.idempotencyKey;
+    if (req.apiVersion !== undefined)
+        headers['stripe-version'] = req.apiVersion;
+    if (req.stripeAccount)
+        headers['stripe-account'] = req.stripeAccount;
+    // a GET carries its parameters in the query; a caller that handed them as a body keeps them
+    let path = req.path.startsWith('/') ? req.path : `/${req.path}`;
+    if ((method === 'GET' || method === 'HEAD') && req.body)
+        path += (path.includes('?') ? '&' : '?') + req.body;
+    const response = await twin(new Request(`https://api.stripe.com${path}`, { method, headers, ...(method !== 'GET' && method !== 'HEAD' && req.body ? { body: req.body } : {}) }));
+    const text = await response.text();
+    return { status: response.status, body: text ? JSON.parse(text) : null };
+}
+/**
+ * The twin's doors: what stands in for an act Stripe's API does not have, each under `/_twin/`. The
+ * platform's own account settings (its payout schedule) change on Stripe's Dashboard, which has no API:
+ * POST /_twin/account stands in for that page. Answers nothing for any other path.
+ */
+export async function handleStripeDoor(req, params) {
+    const method = req.method.toUpperCase();
+    const path = (req.path.split('?')[0] ?? '/').replace(/\/+$/, '') || '/';
+    const seg = path.replace(/^\/+/, '').split('/');
+    if (seg[0] !== '_twin')
+        return undefined;
+    if (req.readOnly)
+        return err('twin is read-only; omit readOnly to accept writes', 405);
+    if (path === '/_twin/account' && method === 'POST') {
+        const ex = getOne('account', PLATFORM_ACCOUNT_ID, req.root);
+        const { type: _t, settings: rawSettings, business_profile: rawProfile, ...rest } = params;
+        // the platform's account is Stripe's default until the page first changes it (semantics/connect.ts, the same
+        // default GET /v1/account answers and the Public details page stores)
+        const fields = {
+            ...(ex ? {} : (({ id: _id, ...base }) => base)(platformAccountDefault())),
+            ...rest,
+            settings: accountSettings(rawSettings, ex?.settings),
+            // a hash is merged into what the account holds, as an update merges it (the name the Public details page saved stays)
+            ...(rawProfile && typeof rawProfile === 'object' ? { business_profile: { ...(ex?.business_profile ?? {}), ...rawProfile } } : {}),
+        };
+        return { status: 200, body: await writeResource('account', PLATFORM_ACCOUNT_ID, stashVendorType('account', fields), 'account.update', req.root, req.occurredAt) };
+    }
+    // Issuing network tokens are minted by the card network when a cardholder adds the card to a
+    // phone's wallet (docs.stripe.com/issuing/cards/digital-wallets): there is no API create, and the
+    // act happens in the phone's wallet app, not on a Stripe page. POST /_twin/issuing/cards/:card/wallets
+    // stands in for that act ({wallet_provider, network}); the API reads the token and moves its status.
+    // Where the documentation stops and the twin decides: the network approves at once (the token is active).
+    if (seg[0] === '_twin' && seg[1] === 'issuing' && seg[2] === 'cards' && seg[3] && seg[4] === 'wallets' && seg.length === 5 && method === 'POST') {
+        const card = decodeURIComponent(seg[3]);
+        const c = getOne('issuing_card', card, req.root);
+        if (!c)
+            return err(`No such card: '${card}'`, 400, 'resource_missing');
+        const wallet = typeof params.wallet_provider === 'string' && ['apple_pay', 'google_pay', 'samsung_pay'].includes(params.wallet_provider)
+            ? params.wallet_provider : 'apple_pay';
+        const network = typeof params.network === 'string' && ['visa', 'mastercard'].includes(params.network) ? params.network : 'visa';
+        const last4 = typeof c.last4 === 'string' ? c.last4 : '0000';
+        return create('issuing_token', { card, cardholder: typeof c.cardholder === 'string' ? c.cardholder : (c.cardholder?.id ?? null) }, {
+            status: 'active', wallet_provider: wallet, network, last4, livemode: false,
+            device_fingerprint: null, network_data: null, network_updated_at: nowUnix(req.occurredAt),
+        }, req);
+    }
+    return undefined;
+}
+// collection path segment → resource type, for the generic list of a collection Stripe does not
+// list at that path (the twin's test clocks, which Stripe lists under /v1/test_helpers).