@volter/twin-stripe 2.0.37 → 3.0.0

package/dist/src/semantics/shared.js

@@ -1,6 +1,1402 @@
-import surface from '../generated/surface.gen.json' with { type: 'json' };
-import { manifest } from "../manifest.js";
-import { OBJECT_NAME, paginate, searchOver, stashVendorType, view } from "../stripe-twin.js";
+import { NAMED_EVENTS, readDecision, STRIPE_EVENT_TYPES, STRIPE_REALTIME_AUTH_TIMEOUT_MS, stripeSignature } from "../engine/webhooks.js";
+import { redactKey, requestKey } from "../engine/oauth.js";
+import { HOUR, INV, itemQuantity, itemsOf, keptAfter, oneTimeLines, RENEWING, SUB } from "../engine/renewals.js";
+import { DAY, payoutDay } from "../engine/balance.js";
+import { AFTER_SUCCESS_CARDS, BY_NUMBER } from "../engine/after-payment.js";
+import { accountSettings, addBillingInterval, applyCouponDiscount, asBool, buildDiscount, buildSubscriptionItemsList, cardError, chargeDefaults, declineFor, disputeEvidence, lineItemEntries, microdepositsNextAction, mintClientSecret, nowUnix, OBJECT_NAME, paginate, paymentMethodSubObject, PLATFORM_ACCOUNT_ID, priceAmount, requiresAuthentication, requiresMicrodeposits, resolveLineItem, resolveSubscriptionBillingInterval, resolveTrial, searchOver, subscriptionItemEntries, subscriptionItemPrice, TEST_TOKEN_DECLINES, threeDsNextAction, validateMoney, view } from "../engine/stripe.js";
+import { AUTO_VALIDATED, euVatCountry } from "../engine/customers.js";
+import { SI } from "../engine/setup-intents.js";
+import { BY_CLIENT_SECRET, PUBLISHABLE_CREATES } from "../engine/front.js";
+import { WE } from "../engine/webhook-endpoints.js";
+import { ENTRY, ENTRY_TYPES, FA, TX } from "../engine/treasury.js";
+import { SECRET } from "../engine/apps-secrets.js";
+import { draft, invoicePrefix, linesOf, sumLines, unlinkedLine } from "../engine/invoices.js";
+import { CN } from "../engine/credit-notes.js";
+import { CS, isOneTime, nestedMetadata } from "../engine/checkout.js";
+import { externalList, refundDestination, SPEC_FIELDS } from "../engine/common.js";
+import { noBilling, PM, TEST_PM_CARDS, testCardOf } from "../engine/payment-methods.js";
+import { SS } from "../engine/subscription-schedules.js";
+import { OAUTH_CONNECTIONS } from "../engine/display.js";
+import { intentCarries, PI, TYPES_GIVEN } from "../engine/payment-intents.js";
+import { BT, BYPASS_NUMBERS, feeOf, onAccount, UNSENT } from "../engine/ledger.js";
+import { withoutCard } from "../engine/charges.js";
+import { MAX_TRIAL, movedTrial } from "../engine/subscriptions.js";
+import { VL, VLI } from "../engine/radar.js";
+import { AUTH, CARD, historyEntry, merchantData, PD, REALTIME_WINDOW_SECONDS, TXN } from "../engine/issuing.js";
+import { REFUND_REASONS } from "../engine/refunds.js";
+import { ADVANCE_SECONDS, CLOCK } from "../engine/test-clocks.js";
+import { BYPASS_PENDING_CARDS } from "../engine/test-cards.js";
+import { PLATFORM_CLIENT_ID, SETTINGS } from "../engine/connect-settings.js";
+import { controllerOf, customRequirements } from "../engine/connect.js";
+import { READER } from "../engine/terminal.js";
+import { expandOf, render, SERVED_VERSION, servesCurrent, withoutEndpointSecret } from "../engine/version.js";
+import { ALERT, GRANT, METER } from "../engine/billing.js";
+import { CHECKOUT_METHOD_TYPES, DOCUMENTED, methodTypesRemoved, oneOf, OPS, PAYMENT_METHOD_TYPES, REMOVED_TYPES, TYPED, TYPES_DOC } from "../engine/params.js";
+/** Stripe's events: `Stripe-Signature: t=…,v1=…` over `${t}.${body}` keyed by the endpoint's secret
+ *  (docs.stripe.com/webhooks#verify-manually); the Event object (docs.stripe.com/api/events/object) kept as the account's
+ *  own (`GET /v1/events`), whether or not an endpoint takes it; an endpoint live while `enabled`, taking the types its
+ *  `enabled_events` names (`*` all, `<family>.*` a family), and a Connect endpoint (`connect: true`) its connected
+ *  accounts' events ("Connected accounts" scope, docs.stripe.com/connect/webhooks), any other the account's own. */
+export const STRIPE_EVENTS = {
+    scheme: { kind: 'timestamp-v1', header: 'Stripe-Signature' },
+    types: NAMED_EVENTS,
+    known: STRIPE_EVENT_TYPES,
+    store: 'event',
+    envelope: {
+        id: '$id', object: 'event', account: '$account', api_version: '$version', created: '$time.s', data: '$data', livemode: false,
+        pending_webhooks: 0, request: { id: null, idempotency_key: null }, type: '$type',
+    },
+    endpoints: { storedAs: 'webhook_endpoint', url: 'url', secret: 'secret', filter: 'enabled_events', status: { field: 'status', live: 'enabled' }, scope: { field: 'connect', value: '$account' } },
+};
+/** Whether a connected account's OAuth connection to the platform was revoked (deauthorized, or its code reused). */
+export function connectionRevoked(ctx, account) {
+    return ctx.rowsRaw(OAUTH_CONNECTIONS).some((c) => c.id === account && c.revoked === true);
+}
+/** The connected account an OAuth key acts as — the connection's current access_token (sk_test_oauth_…) or its
+ *  stripe_publishable_key (pk_test_oauth_…) — with the scope it was issued; undefined for any other key, and null for an
+ *  OAuth-shaped key no live connection holds (revoked, replaced by a refresh, or never issued). */
+export function oauthKeyAccount(ctx, key) {
+    if (!/^(sk|pk)_test_oauth_/.test(key))
+        return undefined;
+    const held = ctx.rowsRaw(OAUTH_CONNECTIONS).find((c) => c.revoked !== true && (c.access_token === key || c.publishable_key === key));
+    return held ? { account: String(held.id), scope: String(key.startsWith('pk_') ? held.scope : held.access_scope ?? held.scope) } : null;
+}
+/** A customer's now: its test clock's frozen time when it is on one (docs.stripe.com/billing/testing/test-clocks), the
+ *  World's otherwise. */
+export function clockNow(ctx, customer) {
+    const clock = typeof customer === 'string' ? ctx.get('customer', customer)?.test_clock : undefined;
+    const frozen = typeof clock === 'string' ? ctx.get('test_helpers.test_clock', clock)?.frozen_time : undefined;
+    return frozen !== undefined ? Number(frozen) : Number(nowUnix(ctx.occurredAt));
+}
+/** What a subscription's invoices charge: its own default payment method, else its customer's. */
+export function payerOf(ctx, sub) {
+    return typeof sub.default_payment_method === 'string' && sub.default_payment_method ? sub.default_payment_method : customerDefault(ctx, sub);
+}
+/** The customer's default for invoices, charged when the subscription names none of its own. */
+export function customerDefault(ctx, sub) {
+    const customer = typeof sub.customer === 'string' ? ctx.get('customer', sub.customer) : undefined;
+    const settings = customer?.invoice_settings;
+    return typeof settings?.default_payment_method === 'string' && settings.default_payment_method ? settings.default_payment_method : undefined;
+}
+/** A subscription whose invoice has just been finalized: the `once` coupon that invoice took is spent, and a once coupon
+ *  it did not take (added after it was drafted) stays for the next (unspentDiscounts). */
+export async function spendOnceCoupon(ctx, invoice) {
+    const subId = typeof invoice.subscription === 'string' ? invoice.subscription : undefined;
+    const sub = subId ? ctx.get(SUB, subId) : undefined;
+    if (!sub || !subId)
+        return;
+    const all = sub.discounts ?? [];
+    const kept = keptAfter(all, invoice);
+    if (kept.length !== all.length)
+        await ctx.write(SUB, subId, { discounts: kept }, 'subscription.discount_spent');
+}
+/** A draft invoice for one period of a subscription, its lines the subscription's items and any one-time lines `once`
+ *  gives it (a Checkout session's one-time prices, "on the initial invoice only", docs.stripe.com/api/checkout/sessions/
+ *  create#create_checkout_session-line_items), under the subscription's discount. Answers the invoice id. */
+export async function draftSubscriptionInvoice(ctx, sub, o) {
+    const id = o.id ?? ctx.mint(INV);
+    const currency = String(sub.currency ?? 'usd');
+    const lines = itemsOf(sub).map((it, i) => {
+        const price = it.price && typeof it.price === 'object' ? it.price : ctx.get('price', String(it.price ?? ''));
+        const quantity = itemQuantity(it);
+        return {
+            id: `il_twin_${id}_${i + 1}`, object: 'line_item', type: 'subscription',
+            // a trial's first invoice bills nothing for the trial period (docs.stripe.com/billing/subscriptions/trials)
+            amount: o.trial ? 0 : priceAmount(price, quantity), currency, quantity, proration: false,
+            price: price ?? null, subscription: sub.id, subscription_item: it.id ?? null, invoice_item: null,
+            period: { start: o.start, end: o.end }, description: o.trial ? `Trial period for ${String(ctx.get('product', String(price?.product ?? ''))?.name ?? 'the plan')}` : null,
+        };
+    });
+    if (o.once?.length)
+        lines.push(...oneTimeLines(id, sub, o.once, lines.length, o.start, currency));
+    const subtotal = lines.reduce((s, l) => s + l.amount, 0);
+    // a discount the subscription still carries applies; a `once` coupon is removed once an invoice finalizes
+    // (spendOnceCoupon), so it discounts one invoice (docs.stripe.com/billing/subscriptions/coupons#coupon-duration)
+    const discount = (sub.discounts ?? [])[0];
+    const coupon = discount && typeof discount === 'object' ? discount.coupon : undefined;
+    const off = coupon ? applyCouponDiscount(subtotal, coupon) : 0;
+    const total = Math.max(0, subtotal - off);
+    await created(ctx, INV, { id, customer: sub.customer, subscription: sub.id }, {
+        created: o.start, status: 'draft', livemode: false, currency, collection_method: 'charge_automatically',
+        billing_reason: o.reason, auto_advance: true, attempt_count: 0, attempted: false, next_payment_attempt: null,
+        amount_due: total, amount_paid: 0, amount_remaining: total, amount_overpaid: 0, amount_paid_off_stripe: 0, amount_shipping: 0,
+        subtotal, total, starting_balance: 0, post_payment_credit_notes_amount: 0, pre_payment_credit_notes_amount: 0,
+        // "The invoice that consumed the coupon still shows the applied discount" (docs.stripe.com/billing/subscriptions/coupons)
+        period_start: o.start, period_end: o.end, default_tax_rates: [], discounts: coupon && discount ? [discount] : [],
+        lines: { object: 'list', data: lines, has_more: false, total_count: lines.length, url: `/v1/invoices/${id}/lines` },
+        automatic_tax: { enabled: false, liability: null, status: null },
+        status_transitions: { finalized_at: null, marked_uncollectible_at: null, paid_at: null, voided_at: null },
+        issuer: { type: 'self' }, payment_settings: { default_mandate: null, payment_method_options: null, payment_method_types: null },
+        payment_intent: null, charge: null,
+    });
+    return id;
+}
+/** Finalize a subscription's draft invoice at `at` and charge what its subscription pays with. The move is time's (a
+ *  renewal), the customer's (the Checkout page they paid on) or the API's (an update that ends a trial, which names the
+ *  payer, may ask for no attempt, and moves the subscription itself: semantics/subscriptions.ts applyTrialEnd). Answers
+ *  whether it was paid. */
+export async function collectSubscriptionInvoice(ctx, invoiceId, at, actor, opts = {}) {
+    const inv = ctx.get(INV, invoiceId);
+    const sub = inv && typeof inv.subscription === 'string' ? ctx.get(SUB, inv.subscription) : undefined;
+    if (!inv || !sub || inv.status !== 'draft')
+        return false;
+    const total = Number(inv.total) || 0;
+    const numbered = { ...finalizedFields(ctx, inv, at), status_transitions: { ...inv.status_transitions, finalized_at: at } };
+    const op = ctx.call.operation.id;
+    // nothing due (a trial's first invoice) is paid as it is finalized; finalizing spends a `once` coupon
+    if (total <= 0) {
+        if (ctx.legal(INV, 'status', op, 'draft', 'paid', invoiceId, actor))
+            return false;
+        await spendOnceCoupon(ctx, inv);
+        await ctx.write(INV, invoiceId, { ...numbered, status: 'paid', paid: true, auto_advance: false, status_transitions: { ...numbered.status_transitions, paid_at: at } }, 'invoice.paid');
+        return true;
+    }
+    const payer = actor === 'api' ? opts.payer : payerOf(ctx, sub);
+    // default_incomplete finalizes the invoice without attempting payment (docs.stripe.com/api/subscriptions/update#update_subscription-payment_behavior)
+    const attempt = opts.attempt !== false;
+    const decline = payer && attempt ? declineFor(finder(ctx), { payment_method: payer }) : undefined;
+    const pays = attempt && !!payer && !decline;
+    if (ctx.legal(INV, 'status', op, 'draft', pays ? 'paid' : 'open', invoiceId, actor))
+        return false;
+    await spendOnceCoupon(ctx, inv);
+    const piId = ctx.mint('payment_intent');
+    const currency = String(inv.currency ?? 'usd');
+    const chargeId = pays ? await mintCharge(ctx, piId, { currency, customer: inv.customer, payment_method: payer, invoice: invoiceId }, total) : null;
+    await created(ctx, 'payment_intent', { id: piId, amount: total, currency, customer: inv.customer, invoice: invoiceId, payment_method: pays ? payer : null }, {
+        status: pays ? 'succeeded' : 'requires_payment_method', client_secret: mintClientSecret(piId, await ctx.secret(`client-secret:${piId}`)), livemode: false,
+        capture_method: 'automatic', amount_capturable: 0, amount_received: pays ? total : 0, next_action: null, latest_charge: chargeId,
+        last_payment_error: decline ? { type: 'card_error', code: decline.code, decline_code: decline.decline_code ?? null, message: decline.message, payment_method: { id: payer } } : null,
+        automatic_payment_methods: null, payment_method_types: ['card'], payment_method_options: {},
+    });
+    await ctx.write(INV, invoiceId, {
+        ...numbered, status: pays ? 'paid' : 'open', paid: pays, attempt_count: attempt ? 1 : 0, attempted: attempt, payment_intent: piId, charge: chargeId,
+        amount_paid: pays ? total : 0, amount_remaining: pays ? 0 : total, auto_advance: attempt && !pays, next_payment_attempt: null,
+        status_transitions: { ...numbered.status_transitions, paid_at: pays ? at : null },
+    }, pays ? 'invoice.paid' : attempt ? 'invoice.payment_failed' : 'invoice.finalized');
+    if (actor !== 'api' && !pays && sub.status !== 'past_due' && !ctx.legal(SUB, 'status', op, sub.status, 'past_due', String(sub.id), 'time')) {
+        await ctx.write(SUB, String(sub.id), { status: 'past_due' }, 'customer.subscription.updated');
+    }
+    return pays;
+}
+/** Pay a subscription's open invoice with `paymentMethod` (the customer on the portal, `external`): the charge on the
+ *  invoice's PaymentIntent, the invoice paid, a past_due subscription active. Answers the decline, if the card is refused. */
+export async function payOpenInvoice(ctx, invoiceId, paymentMethod) {
+    const inv = ctx.get(INV, invoiceId);
+    if (!inv || inv.status !== 'open')
+        return { code: 'invoice_not_open', message: 'This invoice is no longer open.' };
+    const decline = declineFor(finder(ctx), { payment_method: paymentMethod });
+    if (decline)
+        return decline;
+    const op = ctx.call.operation.id;
+    const refused = ctx.legal(INV, 'status', op, 'open', 'paid', invoiceId, 'external');
+    if (refused)
+        return { code: String(refused.code ?? 'invoice_not_open'), message: refused.message };
+    const total = Number(inv.amount_remaining ?? inv.total) || 0;
+    const now = Number(nowUnix(ctx.occurredAt));
+    const piId = typeof inv.payment_intent === 'string' ? inv.payment_intent : undefined;
+    let chargeId = null;
+    const pi = piId ? ctx.get('payment_intent', piId) : undefined;
+    if (piId && pi && !ctx.legal('payment_intent', 'status', op, pi.status, 'succeeded', piId, 'external')) {
+        chargeId = await mintCharge(ctx, piId, { ...pi, payment_method: paymentMethod, invoice: invoiceId }, total);
+        await ctx.write('payment_intent', piId, { status: 'succeeded', payment_method: paymentMethod, amount_received: total, last_payment_error: null, latest_charge: chargeId }, 'payment_intent.succeeded');
+    }
+    await ctx.write(INV, invoiceId, {
+        status: 'paid', paid: true, amount_paid: total, amount_remaining: 0, charge: chargeId, auto_advance: false,
+        attempt_count: (Number(inv.attempt_count) || 0) + 1, attempted: true,
+        status_transitions: { ...inv.status_transitions, paid_at: now },
+    }, 'invoice.paid');
+    const sub = typeof inv.subscription === 'string' ? ctx.get(SUB, inv.subscription) : undefined;
+    if (sub && sub.status === 'past_due' && !ctx.legal(SUB, 'status', op, 'past_due', 'active', String(sub.id), 'external')) {
+        await ctx.write(SUB, String(sub.id), { status: 'active' }, 'customer.subscription.updated');
+    }
+    return undefined;
+}
+/** Time's moves on subscriptions, caught up to each customer's clock in the order they fell due, each made at the
+ *  moment it was due: a period that ended renews (a trial's end among them) or, set to cancel, cancels; a renewal
+ *  drafted an hour or more ago is finalized and charged. */
+export async function advanceBilling(ctx, only) {
+    // Stripe's own move wherever a handler reaches it: a read that catches a renewal up records it with no caller
+    await ctx.asVendor(async () => {
+        const at = at_(ctx);
+        for (let guard = 0; guard < 10_000 && (await billingStep(ctx, at, only)); guard++)
+            ;
+    });
+}
+/** The earliest move that has come due, made at its moment; false when none has. */
+export async function billingStep(ctx, at, only) {
+    // the earliest move that has come due, of any subscription
+    let next;
+    for (const sub of ctx.rows(SUB)) {
+        if (only && !only(sub))
+            continue;
+        if (!RENEWING.includes(String(sub.status)) || typeof sub.current_period_end !== 'number' || sub.pause_collection)
+            continue;
+        if (sub.current_period_end <= clockNow(ctx, sub.customer) && (!next || sub.current_period_end < next.t))
+            next = { t: sub.current_period_end, kind: 'period', id: String(sub.id) };
+    }
+    for (const inv of ctx.rows(INV)) {
+        if (inv.status !== 'draft' || inv.billing_reason !== 'subscription_cycle' || inv.auto_advance !== true)
+            continue;
+        const sub = typeof inv.subscription === 'string' ? ctx.get(SUB, inv.subscription) : undefined;
+        if (!sub || (only && !only(sub)))
+            continue;
+        const t = Number(inv.created) + HOUR;
+        if (t <= clockNow(ctx, sub.customer) && (!next || t < next.t))
+            next = { t, kind: 'collect', id: String(inv.id) };
+    }
+    if (!next)
+        return false;
+    const c = await at(next.t);
+    if (next.kind === 'collect') {
+        await collectSubscriptionInvoice(c, next.id, next.t, 'time');
+        return true;
+    }
+    const id = next.id;
+    const sub = c.get(SUB, id);
+    const op = c.call.operation.id;
+    // one set to cancel at its period's end is canceled then, with no renewal
+    // (docs.stripe.com/billing/subscriptions/cancel#cancel-at-end-of-cycle)
+    if (sub.cancel_at_period_end === true) {
+        if (c.legal(SUB, 'status', op, sub.status, 'canceled', id, 'time'))
+            return false;
+        await c.write(SUB, id, { status: 'canceled', ended_at: next.t, canceled_at: sub.canceled_at ?? next.t }, 'customer.subscription.deleted');
+        return true;
+    }
+    const start = next.t;
+    const { interval, interval_count } = resolveSubscriptionBillingInterval(itemsOf(sub), finder(c));
+    const end = addBillingInterval(start, interval, interval_count);
+    const trialEnds = sub.status === 'trialing';
+    if (trialEnds && c.legal(SUB, 'status', op, 'trialing', 'active', id, 'time'))
+        return false;
+    const invoiceId = await draftSubscriptionInvoice(c, sub, { start, end, reason: 'subscription_cycle' });
+    await c.write(SUB, id, { current_period_start: start, current_period_end: end, latest_invoice: invoiceId, ...(trialEnds ? { status: 'active' } : {}) }, 'customer.subscription.updated');
+    return true;
+}
+export const account = (ctx) => actingAccount(ctx);
+export const payoutMissing = (ctx, id) => fail(ctx, `No such payout: '${id}'`, 404, 'resource_missing');
+/** The acting account's Balance object (docs.stripe.com/api/balance/balance_object). */
+export function balanceBody(ctx, acct = account(ctx)) {
+    const { available, pending, issuing } = balanceOf(ctx, acct);
+    const toArr = (m) => {
+        const out = [...m.entries()].map(([currency, amount]) => ({ amount, currency, source_types: { card: amount } }));
+        return out.length ? out : [{ amount: 0, currency: 'usd', source_types: { card: 0 } }];
+    };
+    // a platform's balance holds its connected accounts' reserve, "Funds held due to negative balances on connected accounts
+    // where account.controller.requirement_collection is `application`" (docs.stripe.com/api/balance/balance_object, whose
+    // example answers `[{"amount": 0, "currency": "usd"}]`); the twin models no such reserve, so it is zero in each currency
+    const reserved = acct ? {} : { connect_reserved: toArr(available).map((b) => ({ amount: 0, currency: b.currency })) };
+    return {
+        object: 'balance', available: toArr(available), pending: toArr(pending), ...reserved, livemode: false,
+        ...(issuing.size ? { issuing: { available: [...issuing.entries()].map(([currency, amount]) => ({ amount, currency, source_types: { card: amount } })) } } : {}),
+    };
+}
+/** Time's arrivals, written: each of the acting account's payouts whose arrival date has come moves pending → paid
+ *  (the clock's move, as asOf reads it), written as `payout.paid`, the event Stripe sends for it. Answers their ids. */
+export async function payDuePayouts(ctx, acct = account(ctx)) {
+    const now = Number(nowUnix(ctx.occurredAt));
+    const paid = [];
+    for (const p of newest(ctx, 'payout')) {
+        if ((acct ? kept(ctx, 'payout', p, '_account') !== acct : !!kept(ctx, 'payout', p, '_account')) || p.status !== 'pending' || Number(p.arrival_date) > now)
+            continue;
+        if (ctx.legal('payout', 'status', ctx.call.operation.id, 'pending', 'paid', String(p.id), 'time'))
+            continue;
+        await ctx.write('payout', String(p.id), { status: 'paid' }, 'payout.paid');
+        paid.push(String(p.id));
+    }
+    return paid;
+}
+/** Where a connected account's payout goes: "ID of the bank account or card the payout is sent to" (served spec,
+ *  payout.destination), its default external account for the currency, "When multiple accounts are available for a given
+ *  currency, Stripe uses the one set as `default_for_currency`" (docs.stripe.com/connect/payouts-bank-accounts), the
+ *  newest such. Where the documentation stops and the twin decides: the platform's own bank account is not modelled, so
+ *  its payouts name none. */
+export function payoutBank(ctx, account, currency) {
+    const banks = newest(ctx, 'external_account').filter((e) => e.account === account && String(e.currency ?? currency) === currency);
+    return String((banks.find((e) => e.default_for_currency === true) ?? banks[0])?.id ?? '') || null;
+}
+export const payoutDefaults = (ctx) => ({
+    method: 'standard', type: 'bank_account', source_type: 'card', automatic: false,
+    reconciliation_status: 'not_applicable', arrival_date: Number(nowUnix(ctx.occurredAt)) + 2 * DAY, livemode: false, metadata: {},
+});
+/** A payout as the clock reads it: paid once its arrival date has come, the clock's move, asked of the
+ *  machine as a write asks it. */
+export function asOf(ctx, p) {
+    if (p.status !== 'pending' || Number(p.arrival_date) > Number(nowUnix(ctx.occurredAt)))
+        return p;
+    ctx.legal('payout', 'status', ctx.call.operation.id, 'pending', 'paid', String(p.id), 'time');
+    return { ...p, status: 'paid' };
+}
+/** A connected account's payout in a currency none of its bank accounts takes. */
+export function noExternalAccount(ctx, currency) {
+    return fail(ctx, `Sorry, you don't have any external accounts in that currency (${currency}).`, 400);
+}
+/** Time's payouts, caught up to the World's clock: each account on an automatic schedule is paid out, on each of its
+ *  scheduled days that has come, what became available by then. */
+export async function advancePayouts(ctx) {
+    const now = Number(nowUnix(ctx.occurredAt));
+    const platform = ctx.get('account', PLATFORM_ACCOUNT_ID);
+    const accounts = [{ id: undefined, settings: platform?.settings }];
+    for (const a of ctx.rows('account')) {
+        if (a.id === PLATFORM_ACCOUNT_ID || a.payouts_enabled !== true)
+            continue;
+        if (!ctx.rows('external_account').some((e) => e.account === a.id))
+            continue;
+        accounts.push({ id: String(a.id), settings: a.settings });
+    }
+    for (const acct of accounts) {
+        const schedule = (accountSettings(acct.settings, acct.settings ?? undefined).payouts.schedule ?? {});
+        if (schedule.interval === 'manual')
+            continue;
+        const unpaid = unpaidEntries(ctx, acct.id);
+        const days = [...new Set(unpaid.map((t) => payoutDay(Number(t.available_on) || 0, schedule)))].filter((d) => d <= now).sort((x, y) => x - y);
+        const paid = new Set();
+        for (const day of days) {
+            const due = unpaid.filter((t) => !paid.has(t.id) && (Number(t.available_on) || 0) <= day);
+            const byCurrency = new Map();
+            for (const t of due)
+                byCurrency.set(String(t.currency ?? 'usd'), [...(byCurrency.get(String(t.currency ?? 'usd')) ?? []), t]);
+            for (const [currency, entries] of byCurrency) {
+                const amount = entries.reduce((n, t) => n + (Number(t.net) || 0), 0);
+                // nothing to pay yet: what came due is carried to the next payout
+                if (amount <= 0)
+                    continue;
+                // made on its day, as Stripe makes it, whenever the request that catches it up comes
+                const c = await at_(ctx)(day);
+                const id = c.mint('payout');
+                const bt = await settleAutomaticPayout(c, id, amount, currency, acct.id, day, entries);
+                await created(c, 'payout', { id, amount, currency }, {
+                    status: 'pending', ...payoutDefaults(c), arrival_date: day + 2 * DAY, automatic: true, balance_transaction: bt, destination: acct.id ? payoutBank(c, String(acct.id), currency) : null,
+                    description: 'STRIPE PAYOUT', ...(acct.id ? { _account: acct.id } : {}),
+                });
+                for (const t of entries)
+                    paid.add(t.id);
+            }
+        }
+    }
+}
+/** What Stripe does after a card succeeds: from a raw number, a test name (pm_card_* or tok_*), or a stored
+ *  PaymentMethod that recorded it when it was made. */
+export function afterSuccessOf(ctx, ref) {
+    // a card given as a token (card[token], payment_method_data[card][token]) is the card the token names
+    if (ref && typeof ref === 'object' && typeof ref.token === 'string')
+        return afterSuccessOf(ctx, ref.token);
+    if (ref && typeof ref === 'object')
+        return BY_NUMBER[String(ref.number ?? '').replace(/\D/g, '')];
+    if (typeof ref !== 'string' || !ref)
+        return undefined;
+    const stored = ctx.row('payment_method', ref);
+    if (stored)
+        return stored._afterSuccess ?? undefined;
+    return AFTER_SUCCESS_CARDS[ref.replace(/^tok_/, 'pm_card_')]?.outcome ?? BY_NUMBER[ref.replace(/\D/g, '')];
+}
+/** Stripe's acts on a charge that just succeeded: a dispute or a review its card brings, and the platform's fee. */
+export async function afterCharge(ctx, chargeId, charge, ref) {
+    const outcome = afterSuccessOf(ctx, ref);
+    const pi = charge.payment_intent ? { payment_intent: charge.payment_intent } : { payment_intent: null };
+    const now = Number(nowUnix(ctx.occurredAt));
+    if (outcome === 'dispute' || outcome === 'dispute_not_received' || outcome === 'inquiry') {
+        const dispute = await created(ctx, 'dispute', { charge: chargeId, ...pi, amount: charge.amount, currency: charge.currency }, {
+            reason: outcome === 'dispute_not_received' ? 'product_not_received' : 'fraudulent', status: outcome === 'inquiry' ? 'warning_needs_response' : 'needs_response', is_charge_refundable: false,
+            evidence: disputeEvidence(), evidence_details: { due_by: now + 7 * DAY, has_evidence: false, past_due: false, submission_count: 0, enhanced_eligibility: {} },
+            balance_transactions: [], livemode: false, metadata: {}, enhanced_eligibility_types: [],
+        });
+        // an inquiry moves no money; a dispute takes the amount and its fee until it is decided
+        if (outcome !== 'inquiry') {
+            const bt = await settleDispute(ctx, String(dispute.id), charge.amount, charge.currency);
+            await ctx.write('dispute', String(dispute.id), { balance_transactions: [ctx.get('balance_transaction', bt) ?? bt] }, 'dispute.funds_withdrawn');
+        }
+        await ctx.write('charge', chargeId, { disputed: true }, 'charge.dispute.created');
+    }
+    if (outcome === 'review')
+        await openReview(ctx, chargeId, pi);
+    const feeAmount = Math.trunc(Number(charge.application_fee_amount) || 0);
+    const destination = typeof charge.destination === 'string' && charge.destination ? charge.destination : undefined;
+    const direct = actingAccount(ctx);
+    const account = destination ?? direct;
+    // a destination charge transfers what it collected, less the platform's fee, available when the charge's funds are
+    if (destination) {
+        const amount = charge.amount - feeAmount;
+        const chargeBt = ctx.get('charge', chargeId)?.balance_transaction;
+        const availableOn = Number(ctx.get('balance_transaction', String(chargeBt))?.available_on ?? nowUnix(ctx.occurredAt));
+        const tr = await created(ctx, 'transfer', { amount, currency: charge.currency, destination }, {
+            amount_reversed: 0, balance_transaction: null, livemode: false, metadata: {}, reversed: false, source_type: 'card', source_transaction: chargeId,
+            reversals: { object: 'list', data: [], has_more: false, total_count: 0, url: '' },
+        });
+        const bt = await settleTransfer(ctx, String(tr.id), amount, charge.currency, destination, availableOn);
+        await ctx.write('transfer', String(tr.id), { balance_transaction: bt, destination_payment: `py_${String(tr.id).replace(/^tr_/, '')}`, reversals: { object: 'list', data: [], has_more: false, total_count: 0, url: `/v1/transfers/${String(tr.id)}/reversals` } }, 'transfer.created');
+        await ctx.write('charge', chargeId, { transfer: tr.id }, 'charge.updated');
+    }
+    if (feeAmount > 0 && account) {
+        const fee = await created(ctx, 'application_fee', { account, amount: feeAmount, charge: chargeId, currency: charge.currency }, {
+            amount_refunded: 0, application: 'ca_twin', balance_transaction: null, originating_transaction: null, refunded: false, livemode: false,
+        });
+        // a direct charge's fee moves from the connected account to the platform (a destination charge kept it back)
+        const bt = !destination && direct ? await settleApplicationFee(ctx, String(fee.id), feeAmount, charge.currency, direct) : null;
+        await ctx.write('application_fee', String(fee.id), { balance_transaction: bt, refunds: { object: 'list', data: [], has_more: false, total_count: 0, url: `/v1/application_fees/${String(fee.id)}/refunds` } }, 'application_fee.created');
+        await ctx.write('charge', chargeId, { application_fee: fee.id, application_fee_amount: feeAmount }, 'charge.updated');
+    }
+}
+/** Radar places an elevated-risk card's charge in review (docs.stripe.com/radar/reviews). */
+export async function openReview(ctx, chargeId, pi) {
+    const review = await created(ctx, 'review', { charge: chargeId, ...pi }, {
+        open: true, opened_reason: 'rule', reason: 'rule', closed_reason: null, billing_zip: null, ip_address: null, ip_address_location: null, session: null, livemode: false,
+    });
+    const existing = ctx.get('charge', chargeId)?.outcome ?? {};
+    await ctx.write('charge', chargeId, {
+        review: review.id,
+        outcome: { ...existing, type: 'manual_review', risk_level: 'elevated', risk_score: 67, seller_message: 'Stripe evaluated this payment as having elevated risk, and placed it in review.' },
+    }, 'review.opened');
+}
+/** The mandate a verified bank account carries for a payment (single use) or a setup (multi use). */
+export async function mintMandate(ctx, paymentMethod, use, amount, currency) {
+    const now = Number(nowUnix(ctx.occurredAt));
+    const mandate = await created(ctx, 'mandate', { payment_method: typeof paymentMethod === 'string' ? paymentMethod : null }, {
+        status: 'active', type: use, livemode: false,
+        customer_acceptance: { type: 'online', accepted_at: now, online: { ip_address: '127.0.0.1', user_agent: 'twin' } },
+        payment_method_details: { type: 'us_bank_account', us_bank_account: { collection_method: 'paper' } },
+        ...(use === 'single_use' ? { single_use: { amount: amount ?? 0, currency: currency ?? 'usd' } } : { multi_use: {} }),
+    }, { timeField: '_created' });
+    return String(mandate.id);
+}
+export const customerMissing = (ctx, id) => fail(ctx, `No such customer: '${id}'`, 404, 'resource_missing');
+/** The discount a customer's `coupon` makes, a parameter of API versions before the served one. */
+export function customerDiscount(ctx, couponId) {
+    const coupon = ctx.get('coupon', couponId);
+    return coupon ? buildDiscount(coupon, '', Number(nowUnix(ctx.occurredAt))) : fail(ctx, `No such coupon: '${couponId}'`, 400, 'resource_missing');
+}
+/** A tax ID for its owner: the account itself, or one of its customers. */
+export async function makeTaxId(ctx, customer) {
+    const given = ctx.params;
+    const { owner: _owner, ...params } = given;
+    if (params.type === undefined || params.type === '')
+        return fail(ctx, 'Missing required param: type.', 400, 'parameter_missing');
+    if (params.value === undefined || params.value === '')
+        return fail(ctx, 'Missing required param: value.', 400, 'parameter_missing');
+    const vatCountry = params.type === 'eu_vat' ? euVatCountry(String(params.value)) : undefined;
+    if (params.type === 'eu_vat' && !vatCountry)
+        return ctx.refuse({ status: 400, code: 'tax_id_invalid', param: 'value', message: `Invalid value for eu_vat.` });
+    return ctx.reply(await created(ctx, 'tax_id', { ...params, ...(customer ? { customer } : {}) }, {
+        livemode: false,
+        country: vatCountry ?? (typeof params.country === 'string' ? params.country : null),
+        owner: customer ? { type: 'customer', customer } : { type: 'self' },
+        verification: { status: AUTO_VALIDATED.has(String(params.type)) ? 'pending' : 'unavailable', verified_address: null, verified_name: null },
+    }));
+}
+/** The owner a top-level tax-ID call names: the account itself unless `owner[type]=customer` names a customer
+ *  (docs.stripe.com/api/tax_ids/list: owner defaults to self). */
+export function ownerOf(ctx) {
+    const owner = (ctx.params.owner ?? {});
+    const type = String(owner.type ?? 'self');
+    if (type === 'self')
+        return {};
+    if (type !== 'customer')
+        return fail(ctx, `Invalid owner[type]: must be one of self or customer.`, 400, 'parameter_invalid_string_enum');
+    const customer = typeof owner.customer === 'string' ? owner.customer : '';
+    if (!customer)
+        return fail(ctx, 'Missing required param: owner[customer].', 400, 'parameter_missing');
+    if (!ctx.get('customer', customer))
+        return customerMissing(ctx, customer);
+    return { customer };
+}
+// ── the cash balance: per-currency sums of the funding ledger, and the reconciliation setting ──
+export function cashBalance(ctx, customer) {
+    const byCurrency = {};
+    for (const t of ctx.rows('customer_cash_balance_transaction')) {
+        if (t.customer !== customer)
+            continue;
+        const cur = String(t.currency ?? 'usd');
+        byCurrency[cur] = (byCurrency[cur] ?? 0) + (Number(t.net_amount) || 0);
+    }
+    const cust = ctx.row('customer', customer);
+    const mode = typeof cust?._cash_balance_mode === 'string' ? cust._cash_balance_mode : 'automatic';
+    return {
+        object: 'cash_balance', customer,
+        available: Object.keys(byCurrency).length ? byCurrency : null,
+        settings: { reconciliation_mode: mode, using_merchant_default: mode === 'merchant_default' },
+        livemode: false,
+    };
+}
+/** Automatic reconciliation (docs.stripe.com/payments/customer-balance/reconciliation): funds that arrive pay the
+ *  customer's open invoices that take bank transfers (payment_method_types customer_balance), the one whose number
+ *  the transfer's reference names first, then the oldest. Where the documentation stops and the twin decides: an
+ *  invoice is paid only when the balance covers all of what remains; a smaller balance waits for more funds. */
+export async function reconcile(ctx, customer, currency, reference) {
+    const takesTransfers = (inv) => inv.payment_settings?.payment_method_types?.includes('customer_balance') === true;
+    const open = ctx.rows('invoice').filter((inv) => inv.customer === customer && inv.status === 'open' && String(inv.currency ?? 'usd') === currency && takesTransfers(inv))
+        .sort((a, b) => (reference && a.number === reference ? -1 : reference && b.number === reference ? 1 : Number(a.created) - Number(b.created)));
+    for (const inv of open) {
+        const available = Number((cashBalance(ctx, customer).available ?? {})[currency] ?? 0);
+        const amount = Number(inv.amount_remaining ?? inv.amount_due) || 0;
+        if (amount <= 0 || available < amount)
+            continue;
+        const id = String(inv.id);
+        if (ctx.legal('invoice', 'status', 'PostTestHelpersCustomersCustomerFundCashBalance', inv.status, 'paid', id))
+            continue;
+        // the payment the balance makes: the invoice's own PaymentIntent (every invoice finalized with an amount due has one,
+        // semantics/invoices.ts), paid from the cash balance, its charge, and the ledger's entry
+        const piId = String(inv.payment_intent);
+        await created(ctx, 'customer_cash_balance_transaction', { customer }, { currency, type: 'applied_to_payment', net_amount: -amount, ending_balance: available - amount, applied_to_payment: { payment_intent: piId }, livemode: false });
+        const charge = await mintCharge(ctx, piId, { currency, customer, invoice: id }, amount);
+        await ctx.write('payment_intent', piId, { status: 'succeeded', amount_received: amount, latest_charge: charge }, 'payment_intent.succeeded');
+        await ctx.write('invoice', id, {
+            status: 'paid', paid: true, amount_paid: amount, amount_remaining: 0, payment_intent: piId, charge,
+            status_transitions: { ...(inv.status_transitions ?? {}), paid_at: nowUnix(ctx.occurredAt) },
+        }, 'invoice.paid');
+    }
+}
+/** The customer's source the path names, or undefined. */
+export const customerSource = (ctx) => {
+    const s = ctx.get('source', at(ctx, 'id'));
+    return s && s.customer === at(ctx, 'customer') ? s : undefined;
+};
+export const sourceMissing = (ctx) => fail(ctx, `No such source: '${at(ctx, 'id')}'`, 404, 'resource_missing');
+/** The intent the path names, and the machine's refusal when this operation may not move it. */
+export function load(ctx, operationId) {
+    const id = at(ctx, 'intent');
+    const si = ctx.get(SI, id);
+    if (!si)
+        return { answer: fail(ctx, `No such setup_intent: '${id}'`, 404, 'resource_missing') };
+    const refused = ctx.legal(SI, 'status', operationId, si.status, undefined, id);
+    return refused ? { answer: ctx.refuse(refused) } : { si };
+}
+/** The request event asked of the endpoint, signed with its secret and rendered in the event's API version, and its
+ *  answer read as the decision. */
+export async function askForAuthorization(ctx, url, event, secret) {
+    const payload = JSON.stringify(render(event, typeof event.api_version === 'string' ? event.api_version : undefined));
+    const signature = stripeSignature(payload, secret, Math.floor(Date.parse(ctx.occurredAt) / 1000));
+    const answer = await ctx.ask(url, { method: 'POST', headers: { 'content-type': 'application/json', 'stripe-signature': signature }, body: payload }, STRIPE_REALTIME_AUTH_TIMEOUT_MS);
+    if (answer.missed === 'timeout')
+        return { kind: 'timeout', message: 'Webhook endpoint did not respond within the real-time authorization window.' };
+    if (answer.missed === 'unreachable')
+        return { kind: 'timeout', message: 'Webhook endpoint was unreachable within the real-time authorization window.' };
+    return readDecision(answer);
+}
+/** Stripe's refusal of a call a publishable key may not make, or undefined when the key may make it. */
+export function publishableKeyRefused(ctx) {
+    // the key however it is sent, Bearer or Basic's user (requestKey): a publishable key is public, and sent as Basic it
+    // is still one
+    if (!requestKey(ctx.call.request).startsWith('pk_'))
+        return undefined;
+    const op = ctx.call.operation.id;
+    if (PUBLISHABLE_CREATES.has(op))
+        return undefined;
+    const scoped = BY_CLIENT_SECRET[op];
+    if (!scoped)
+        return ctx.refuse({ status: 403, code: 'secret_key_required', message: 'The API key provided is a publishable key, but a secret key is required.' });
+    const secret = typeof ctx.params.client_secret === 'string' ? ctx.params.client_secret : '';
+    if (!secret)
+        return ctx.refuse({ status: 400, code: 'parameter_missing', param: 'client_secret', message: 'Missing required param: client_secret.' });
+    const id = ctx.call.params[scoped.param] ?? '';
+    return ctx.get(scoped.type, id)?.client_secret === secret ? undefined : ctx.refuse({ status: 404, code: 'resource_missing', param: scoped.param, message: `No such ${scoped.type}: '${id}'` });
+}
+// ── an account whose OAuth connection was revoked ──
+// "After revocation, the account can't be accessed by your platform in the Dashboard or through the API"
+// (docs.stripe.com/connect/oauth-reference, deauthorize; so too a connection revoked by a reused code). A call made as it
+// (the Stripe-Account header) or naming it (/v1/accounts/{account}…) is refused with the error Stripe documents for a
+// Stripe-Account the key cannot use: "account_invalid | The account ID provided as a value for the Stripe-Account header
+// is invalid" (docs.stripe.com/error-codes), as 403. Where the documentation stops and the twin decides: the message's
+// wording; an account the platform created itself, or never connected by OAuth, is not affected.
+export function revokedAccountRefused(ctx) {
+    const request = ctx.call.request;
+    const named = [request.headers.get('stripe-account') ?? undefined, ctx.call.operation.path.startsWith('/v1/accounts/{account}') ? ctx.call.params.account : undefined].filter((a) => !!a);
+    const revoked = named.find((a) => connectionRevoked(ctx, a));
+    if (!revoked)
+        return undefined;
+    return ctx.refuse({ status: 403, code: 'account_invalid', message: `The provided key '${redactKey(requestKey(request))}' does not have access to account '${revoked}' (or that account does not exist). Application access may have been revoked.` });
+}
+// A connected account's OAuth keys (../screens/connect-oauth.tsx): the token endpoint's access_token is "Use the
+// Stripe-Account header with your platform's secret key (that can make requests on behalf of this Stripe account)" and
+// its stripe_publishable_key the same with the publishable key (docs.stripe.com/connect/oauth-reference): a request made
+// with one acts as that account, as a request with the Stripe-Account header does. A key no live connection holds (its
+// connection revoked, or replaced by a refresh: "Any existing access token with the same scope and mode ... is
+// revoked") is Stripe's unknown key, 401 "Invalid API Key provided" (docs.stripe.com/api/authentication); one sent with
+// a Stripe-Account header naming another account cannot act as it (account_invalid). Where the documentation stops and
+// the twin decides: the messages' wording; a read_only key is not held to reads (manifest todo
+// stripe.connect.oauth_scope_enforcement).
+/** The platform's own keys, as the dashboard's API keys page makes them (the `appCredentials` door): a secret key and a
+ *  publishable key, held by their SHA-256. A request with no key is refused, as is a platform key Stripe never issued
+ *  ("Invalid API Key provided"); a connected account's OAuth key is checked where it is read (actingAsOAuthKey). */
+// source: https://docs.stripe.com/api/authentication "API requests without authentication also fail."
+export function platformKeyRefused(ctx, request) {
+    const key = requestKey(request);
+    if (!key)
+        return ctx.refuse({ status: 401, message: "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer YOUR_SECRET_KEY'). See https://stripe.com/docs/api#authentication for details, or we can help at https://support.stripe.com/." });
+    if (/^(sk|pk)_test_oauth_/.test(key))
+        return undefined;
+    const held = ctx.rowsRaw('_platform_key').some((k) => k._sha256 === ctx.crypto.sha256(key) && k.deleted !== true);
+    return held ? undefined : ctx.refuse({ status: 401, message: `Invalid API Key provided: ${redactKey(key)}` });
+}
+export async function actingAsOAuthKey(ctx, request) {
+    const key = requestKey(request);
+    if (!/^(sk|pk)_test_oauth_/.test(key))
+        return request;
+    const held = oauthKeyAccount(ctx, key);
+    if (!held)
+        return ctx.refuse({ status: 401, message: `Invalid API Key provided: ${redactKey(key)}` });
+    const named = request.headers.get('stripe-account');
+    if (named && named !== held.account)
+        return ctx.refuse({ status: 403, code: 'account_invalid', message: `The provided key '${redactKey(key)}' does not have access to account '${named}' (or that account does not exist). Application access may have been revoked.` });
+    const headers = new Headers(request.headers);
+    headers.set('stripe-account', held.account);
+    const bodied = request.method !== 'GET' && request.method !== 'HEAD';
+    return new Request(request.url, { method: request.method, headers, ...(bodied ? { body: await request.arrayBuffer() } : {}) });
+}
+// ── metadata ──
+// "This parameter uses a merge mechanism, which allows you to add new key-value pairs to an object in an update call
+// without affecting any existing metadata"; "Pass in the key with an empty string as the value to remove the key from the
+// metadata"; "Pass an empty string as the value for the metadata attribute to delete all of the keys simultaneously"
+// (docs.stripe.com/metadata), and "Individual keys can be unset by posting an empty value to them" holds on a create
+// too: an object never holds a key set to "" (stripe-node encodes a `null` value as `metadata[key]=`). The derived core
+// merges a nested hash on an update (dropping keys set to ""), so for it only a clear-all is rewritten; where a handler
+// stores the request's metadata whole, the request carries the merged hash, its removed keys as "". The rewritten
+// request is JSON.
+export function withMetadata(ctx, request) {
+    if (request.method !== 'POST' || (request.headers.get('content-type') ?? '').includes('multipart'))
+        return request;
+    if (!('metadata' in ctx.params))
+        return request;
+    const op = ctx.call.operation;
+    const given = ctx.params.metadata;
+    let metadata;
+    if (op.class === 'create') {
+        if (given === '')
+            metadata = {};
+        else if (given && typeof given === 'object' && !Array.isArray(given) && Object.values(given).includes(''))
+            metadata = Object.fromEntries(Object.entries(given).filter(([, v]) => v !== ''));
+        else
+            return request;
+    }
+    else if (op.class === 'update' && op.resource) {
+        // a plan is kept as the recurring price it is (../semantics/plans.ts)
+        const resource = op.resource === 'plan' ? 'price' : op.resource;
+        const id = Object.values(ctx.call.params).at(-1) ?? '';
+        const held = ctx.get(resource, id)?.metadata;
+        const prior = held && typeof held === 'object' ? held : {};
+        // the merged hash, a key removed carried as "" so a merging update (the derived core's) drops it too; an object
+        // never answers a key set to "" (../engine/version.ts render)
+        if (given === '')
+            metadata = Object.fromEntries(Object.keys(prior).map((k) => [k, '']));
+        else if (given && typeof given === 'object' && !Array.isArray(given))
+            metadata = { ...prior, ...given };
+        else
+            return request;
+    }
+    else
+        return request;
+    const headers = new Headers(request.headers);
+    headers.set('content-type', 'application/json');
+    return new Request(request.url, { method: request.method, headers, body: JSON.stringify({ ...ctx.params, metadata }) });
+}
+/** `disabled` switches delivery off or back on (docs.stripe.com/api/webhook_endpoints/update#update_webhook_endpoint-disabled). */
+export async function switchDelivery(ctx, id, we, fields, off) {
+    const status = off ? 'disabled' : 'enabled';
+    const refused = ctx.legal(WE, 'status', 'PostWebhookEndpointsWebhookEndpoint', we.status, status, id);
+    if (refused)
+        return ctx.refuse(refused);
+    return ctx.reply(await ctx.write(WE, id, { ...fields, status }, 'webhook_endpoint.update'));
+}
+/** Whether a stored event is the acting account's (no `account`: the platform's). */
+export const ownEvent = (ctx, e) => (typeof e.account === 'string' ? e.account : undefined) === actingAccount(ctx);
+export const faMissing = (ctx, id, status = 404) => fail(ctx, `No such financial account: '${id}'`, status, 'resource_missing');
+export const metadataOf = (ctx) => (ctx.params.metadata && typeof ctx.params.metadata === 'object' ? ctx.params.metadata : {});
+/** The account's bank address once financial_addresses.aba is active: "The FinancialAccount gains a FinancialAddress
+ *  when the `financial_addresses.aba` feature is active", and "A FinancialAddress is not added until the
+ *  financial_addresses.aba feature has been activated" (docs.stripe.com/treasury/account-management/financial-accounts),
+ *  whose test example answers "bank_name": "Stripe Test Bank", "routing_number": "000000001" and the networks "ach",
+ *  "us_domestic_wire", "rtp"; "The full account_number is only returned if the request expands it" (the same page).
+ *  Where the documentation stops and the twin decides: the account number is ten digits drawn from the account's id,
+ *  answered by its last four (the full number is null: expanding it is not modelled), and the holder's name is the
+ *  platform account's business name, its dashboard name or, with neither, its id. */
+export function abaAddress(ctx, faId) {
+    let n = 0;
+    for (const ch of faId)
+        n = (n * 31 + ch.charCodeAt(0)) % 10_000_000_000;
+    const number = String(n).padStart(10, '0');
+    const platform = ctx.get('account', PLATFORM_ACCOUNT_ID);
+    const name = (platform?.business_profile?.name ?? platform?.settings?.dashboard?.display_name ?? PLATFORM_ACCOUNT_ID);
+    return { type: 'aba', supported_networks: ['ach', 'us_domestic_wire', 'rtp'], aba: { account_holder_name: name, account_number: null, account_number_last4: number.slice(-4), bank_name: 'Stripe Test Bank', routing_number: '000000001' } };
+}
+export const addressesOf = (ctx, faId, active) => (active.includes('financial_addresses.aba') ? [abaAddress(ctx, faId)] : []);
+/** Post a flow's double entry: a ledger transaction with its net balance impact, and its one entry. */
+export async function post(ctx, o) {
+    const now = nowUnix(ctx.occurredAt);
+    const txnId = ctx.mint(TX);
+    await ctx.write(TX, txnId, {
+        object: 'treasury.transaction', created: now, livemode: false,
+        amount: o.amount, currency: o.currency, financial_account: o.financial_account,
+        flow: o.flow, flow_type: o.flow_type, flow_details: null,
+        status: o.status, balance_impact: o.balance_impact, description: o.description,
+        entries: { object: 'list', has_more: false, url: `/v1/treasury/transaction_entries?transaction=${txnId}`, data: [] },
+        status_transitions: { posted_at: o.status === 'posted' ? now : null, void_at: null },
+    }, 'treasury_transaction.created');
+    await ctx.write(ENTRY, ctx.mint(ENTRY), {
+        object: 'treasury.transaction_entry', created: now, livemode: false,
+        amount: o.amount, currency: o.currency, financial_account: o.financial_account,
+        flow: o.flow, flow_type: o.flow_type,
+        flow_details: o.flowDetailKey ? { type: o.flowDetailKey, [o.flowDetailKey]: o.flow } : null,
+        transaction: txnId, effective_at: now,
+        balance_impact: o.balance_impact,
+        // what the entry records: its flow's kind where Stripe names one (docs.stripe.com/api/treasury/transaction_entries/object);
+        // a vendor `type`, kept apart from the kernel's row type
+        type: ENTRY_TYPES.has(String(o.flow_type)) ? o.flow_type : 'other',
+    }, 'treasury_transaction_entry.created');
+    // the account's balance moves by the entry's impact: cash "Funds the user can spend right now", inbound_pending
+    // "Funds not spendable yet", outbound_pending "held for pending outbound flows" (the served spec's balance)
+    const account = ctx.get(FA, o.financial_account);
+    if (account) {
+        const bal = account.balance ?? { cash: {}, inbound_pending: {}, outbound_pending: {} };
+        const moved = Object.fromEntries(['cash', 'inbound_pending', 'outbound_pending'].map((k) => [k, { ...(bal[k] ?? {}), [o.currency]: ((bal[k] ?? {})[o.currency] ?? 0) + (Number(o.balance_impact[k]) || 0) }]));
+        await ctx.write(FA, o.financial_account, { balance: moved }, 'financial_account.balance_updated');
+    }
+    return txnId;
+}
+/** The request's funding account, or the refusal. */
+export function fundingAccount(ctx) {
+    const bad = validateMoney(ctx.params);
+    if (bad)
+        return send(ctx, bad);
+    const fa = typeof ctx.params.financial_account === 'string' ? ctx.params.financial_account : '';
+    if (!fa)
+        return fail(ctx, 'Missing required param: financial_account.', 400, 'parameter_missing');
+    return ctx.get(FA, fa) ? fa : faMissing(ctx, fa, 400);
+}
+/** Where an outbound flow sends its money, as the served spec's payment method details give it: the bank account's
+ *  holder type, last four digits and routing number from what the request sent (a saved method's, or the test bank's
+ *  when none is given), and its billing details (required): the name and email sent, the address lines null where not
+ *  given. Where the documentation stops and the twin decides: a saved method's details are the test bank's. */
+export function destinationDetails(ctx, dest) {
+    const data = ctx.params.destination_payment_method_data && typeof ctx.params.destination_payment_method_data === 'object' ? ctx.params.destination_payment_method_data : {};
+    const bank = data.us_bank_account && typeof data.us_bank_account === 'object' ? data.us_bank_account : {};
+    const billing = data.billing_details && typeof data.billing_details === 'object' ? data.billing_details : {};
+    const address = billing.address && typeof billing.address === 'object' ? billing.address : {};
+    const number = typeof bank.account_number === 'string' ? bank.account_number.replace(/\D/g, '') : '';
+    const billing_details = { name: billing.name ?? null, email: billing.email ?? null, address: Object.fromEntries(['city', 'country', 'line1', 'line2', 'postal_code', 'state'].map((k) => [k, address[k] ?? null])) };
+    if (dest && data.type === undefined && dest.startsWith('fa_'))
+        return { type: 'financial_account', financial_account: { id: dest, network: 'stripe' }, billing_details };
+    return {
+        type: 'us_bank_account', billing_details,
+        us_bank_account: { last4: number ? number.slice(-4) : '6789', network: 'ach', routing_number: typeof bank.routing_number === 'string' ? bank.routing_number : '110000000', account_holder_type: typeof bank.account_holder_type === 'string' ? bank.account_holder_type : 'individual', account_type: typeof bank.account_type === 'string' ? bank.account_type : 'checking', bank_name: 'STRIPE TEST BANK', mandate: null },
+    };
+}
+/** An outbound payment that names no destination: "You must provide either destination_payment_method or
+ *  destination_payment_method_data" (the served spec's outbound payment create). */
+export function noDestination(ctx) {
+    return fail(ctx, 'You must provide either `destination_payment_method` or `destination_payment_method_data`.', 400, 'parameter_missing');
+}
+/** The bank account an inbound transfer may pull from: "You must first set up the account-attached payment method for
+ *  inbound flows and verify the bank account using a SetupIntent", and invalid ones ("of unsupported types, containing
+ *  an unverified bank account, or not set up for inbound flows") "throw the same errors as in live mode"
+ *  (docs.stripe.com/treasury/moving-money/financial-accounts/into/inbound-transfers). A payment method is set up for
+ *  inbound flows by a SetupIntent whose flow_directions holds `inbound`, and verified when that SetupIntent succeeded
+ *  ("The bank account has been instantly verified or verification isn't necessary", its `succeeded` status,
+ *  docs.stripe.com/treasury/connect/legacy/v1/moving-money/working-with-bankaccount-objects).
+ *  Where the documentation stops and the twin decides: the page quotes no error, so the twin answers the documented code
+ *  for the class, payment_method_unexpected_state ("The provided payment method's state was incompatible with the
+ *  operation you were trying to perform", docs.stripe.com/error-codes), in its own words; an existing verified
+ *  BankAccount (`ba_`), which the page also allows, is not checked. Answers the payment method, or the refusal. */
+export function inboundOrigin(ctx, origin) {
+    if (origin.startsWith('ba_'))
+        return undefined;
+    const pm = ctx.get('payment_method', origin);
+    if (!pm)
+        return fail(ctx, `No such PaymentMethod: '${origin}'`, 400, 'resource_missing');
+    if (pm.type !== 'us_bank_account')
+        return fail(ctx, `The PaymentMethod '${origin}' is of type ${String(pm.type)}; an InboundTransfer pulls from a us_bank_account.`, 400, 'payment_method_unexpected_state');
+    const setUp = ctx.rows('setup_intent').some((si) => si.payment_method === origin && si.status === 'succeeded' && Array.isArray(si.flow_directions) && si.flow_directions.map(String).includes('inbound'));
+    if (!setUp)
+        return fail(ctx, `The PaymentMethod '${origin}' has not been set up for inbound flows and verified with a SetupIntent.`, 400, 'payment_method_unexpected_state');
+    return pm;
+}
+// test mode's stand-ins for money another party sends to the account or pulls from it
+// (docs.stripe.com/treasury/moving-money/receiving-funds, docs.stripe.com/api/treasury/received_credits/test_mode_create)
+export function received(kind) {
+    return async (ctx) => {
+        const fa = fundingAccount(ctx);
+        if (fa instanceof Response)
+            return fa;
+        const network = typeof ctx.params.network === 'string' ? ctx.params.network : '';
+        if (!['ach', 'us_domestic_wire', 'stripe'].includes(network))
+            return fail(ctx, 'Missing required param: network.', 400, 'parameter_missing');
+        const amount = ctx.params.amount;
+        const currency = String(ctx.params.currency);
+        const id = ctx.mint(`treasury.${kind}`);
+        const signed = kind === 'received_credit' ? amount : -amount;
+        const txn = await post(ctx, { financial_account: fa, amount: signed, currency, flow: id, flow_type: kind, status: 'posted', balance_impact: { cash: signed, inbound_pending: 0, outbound_pending: 0 }, description: kind === 'received_credit' ? 'ReceivedCredit' : 'ReceivedDebit', flowDetailKey: kind });
+        return ctx.reply(await created(ctx, `treasury.${kind}`, { id }, {
+            amount, currency, financial_account: fa, network, livemode: false, status: 'succeeded', failure_code: null,
+            description: typeof ctx.params.description === 'string' ? ctx.params.description : kind === 'received_credit' ? 'Received credit' : 'Received debit',
+            hosted_regulatory_receipt_url: null, transaction: txn, reversal_details: null,
+            initiating_payment_method_details: { type: 'us_bank_account', billing_details: { address: {}, email: null, name: null }, us_bank_account: { bank_name: 'STRIPE TEST BANK', last4: '6789', routing_number: '110000000' } },
+            linked_flows: kind === 'received_credit' ? { credit_reversal: null, issuing_authorization: null, issuing_transaction: null, source_flow: null, source_flow_type: null } : { debit_reversal: null, inbound_transfer: null, issuing_authorization: null, issuing_transaction: null, payout: null },
+        }));
+    };
+}
+/** Cancel a flow still processing; an outbound one must also still be cancelable. */
+export function cancel(resource, param, name, operationId, op, checkCancelable) {
+    return async (ctx) => {
+        const id = at(ctx, param);
+        const flow = ctx.get(resource, id);
+        if (!flow)
+            return fail(ctx, `No such ${name}: '${id}'`, 404, 'resource_missing');
+        // a processing flow that is no longer cancelable is refused as one no longer processing
+        const refused = ctx.legal(resource, 'status', operationId, checkCancelable && flow.cancelable !== true ? 'not_cancelable' : flow.status, undefined, id);
+        if (refused)
+            return ctx.refuse(refused);
+        // a canceled flow's open transaction is voided and what it held returns to the account (the reverse of its
+        // balance impact). Where the documentation stops and the twin decides: a flow already posted is only marked canceled
+        const txn = typeof flow.transaction === 'string' ? ctx.get(TX, flow.transaction) : undefined;
+        if (txn && txn.status === 'open') {
+            await ctx.write(TX, String(txn.id), { status: 'void', status_transitions: { ...txn.status_transitions, void_at: nowUnix(ctx.occurredAt) } }, 'treasury_transaction.voided');
+            const account = ctx.get(FA, String(txn.financial_account));
+            const impact = txn.balance_impact ?? {};
+            const cur = String(txn.currency ?? 'usd');
+            if (account) {
+                const bal = account.balance ?? { cash: {}, inbound_pending: {}, outbound_pending: {} };
+                const back = Object.fromEntries(['cash', 'inbound_pending', 'outbound_pending'].map((k) => [k, { ...(bal[k] ?? {}), [cur]: ((bal[k] ?? {})[cur] ?? 0) - (Number(impact[k]) || 0) }]));
+                await ctx.write(FA, String(account.id), { balance: back }, 'financial_account.balance_updated');
+            }
+        }
+        return ctx.reply(await ctx.write(resource, id, { status: 'canceled', cancelable: false, status_transitions: { ...flow.status_transitions, canceled_at: nowUnix(ctx.occurredAt) } }, op));
+    };
+}
+// the ledger is always read for one account
+export function ledger(resource, spec) {
+    return async (ctx) => {
+        if (typeof ctx.params.financial_account !== 'string' || !ctx.params.financial_account)
+            return fail(ctx, 'Missing required param: financial_account.', 400, 'parameter_missing');
+        return list(ctx, resource, where(ctx, newest(ctx, resource), spec));
+    };
+}
+export function scopeKeyOf(ctx) {
+    const scope = ctx.params.scope && typeof ctx.params.scope === 'object' ? ctx.params.scope : undefined;
+    const scopeType = scope && typeof scope.type === 'string' ? scope.type : 'account';
+    return scopeType === 'user' ? `user:${String(scope.user)}` : 'account';
+}
+export const named = (ctx, name) => ctx.rows(SECRET).find((s) => s.name === name && kept(ctx, SECRET, s, '_scope_key') === scopeKeyOf(ctx));
+export const invoiceMissing = (ctx, id) => fail(ctx, `No such invoice: '${id}'`, 404, 'resource_missing');
+/** Write a draft's line list and the totals derived from it. */
+export async function writeLines(ctx, invoiceId, next) {
+    const subtotal = sumLines(next);
+    const lines = { object: 'list', data: next, has_more: false, total_count: next.length, url: `/v1/invoices/${invoiceId}/lines` };
+    return ctx.write(INV, invoiceId, { lines, subtotal, total: subtotal, amount_due: subtotal, amount_remaining: subtotal }, 'invoice.update');
+}
+/** Paying an invoice with nothing to pay it: "If not set, defaults to the subscription's default payment method, if any,
+ *  or to the default payment method in the customer's invoice settings" (docs.stripe.com/api/invoices/object,
+ *  default_payment_method), and none of them is set. */
+export function nothingToPayWith(ctx) {
+    return fail(ctx, 'This customer has no attached payment source or default payment method. Please consider adding a default payment method.', 400, 'missing');
+}
+/** A subscription waiting on the invoice paid through the invoice's own pay (incomplete on its first, past_due on a
+ *  failed renewal) is active again. */
+export async function activatedByPayment(ctx, subId) {
+    await ctx.write('subscription', subId, { status: 'active' }, 'subscription.update');
+}
+/** Re-derive a draft's lines from the items still on it: an item that changed or was deleted moves the invoice with it. */
+export async function resyncDraftLines(ctx, invoiceId) {
+    const inv = ctx.get(INV, invoiceId);
+    if (!inv || inv.status !== 'draft')
+        return;
+    const next = [];
+    for (const line of linesOf(inv)) {
+        const itemId = typeof line.invoice_item === 'string' ? line.invoice_item : '';
+        if (!itemId)
+            next.push(unlinkedLine(line));
+        const item = itemId ? ctx.get('invoiceitem', itemId) : undefined;
+        if (item)
+            next.push({ ...line, amount: Number(item.amount) || 0, description: item.description ?? null });
+    }
+    await writeLines(ctx, invoiceId, next);
+}
+// ── invoice items: a price-based item takes its amount from the price; one naming a draft invoice
+// lands on its lines at once ──
+/** An item priced by a Price: its unit amount times the quantity, in its currency (docs.stripe.com/api/invoiceitems/create#create_invoiceitem-pricing). */
+export function pricedItem(ctx, priceRef, qty) {
+    const price = ctx.get('price', priceRef);
+    if (!price)
+        return fail(ctx, `No such price: '${priceRef}'`, 400, 'resource_missing');
+    return { amount: priceAmount(price, qty), currency: typeof price.currency === 'string' ? price.currency : undefined };
+}
+export const itemMissing = (ctx, id) => fail(ctx, `No such invoiceitem: '${id}'`, 404, 'resource_missing');
+/** A draft invoice another object makes (an accepted quote): its customer's, with an invoice item per line the
+ *  object gives, and the object named as its parent. Answers the invoice's id. */
+export async function draftInvoiceFor(ctx, customer, currency, parent, lines) {
+    const now = Number(nowUnix(ctx.occurredAt));
+    const id = ctx.mint(INV);
+    const holder = ctx.get('customer', customer);
+    const inv = await created(ctx, INV, { id, customer, currency, parent }, { ...draft(now), currency, customer_email: holder?.email ?? null, customer_name: holder?.name ?? null, lines: { object: 'list', data: [], has_more: false, total_count: 0, url: `/v1/invoices/${id}/lines` } });
+    for (const l of lines) {
+        const price = typeof l.price === 'string' ? l.price : l.price && typeof l.price === 'object' ? String(l.price.id) : null;
+        const item = await created(ctx, 'invoiceitem', { customer, currency, amount: l.amount, quantity: l.quantity, ...(price ? { price } : {}), description: l.description ?? null }, { date: now, livemode: false, metadata: {}, discountable: true, proration: false, period: { start: now, end: now } });
+        await pullPendingItem(ctx, id, inv, item, now);
+    }
+    return id;
+}
+/** A customer's pending invoice item, made before the invoice, pulled onto it (docs.stripe.com/api/invoices/create#create_invoice-pending_invoice_items_behavior). */
+export async function pullPendingItem(ctx, invoiceId, inv, item, now) {
+    const current = ctx.get(INV, invoiceId) ?? inv;
+    await writeLines(ctx, invoiceId, [...linesOf(current), {
+            id: `il_${String(item.id)}`, object: 'line_item', type: 'invoiceitem', amount: Number(item.amount) || 0, currency: String(current.currency ?? item.currency ?? 'usd'),
+            quantity: Number(item.quantity) || 1, proration: false, invoice_item: item.id, price: item.price ?? null,
+            period: item.period ?? { start: now, end: now }, description: item.description ?? null,
+            discountable: item.discountable ?? true, discounts: [], livemode: false, metadata: item.metadata ?? {}, tax_amounts: [], tax_rates: [],
+        }]);
+    await ctx.write('invoiceitem', String(item.id), { invoice: invoiceId }, 'invoiceitem.update');
+}
+/** The invoice the path names, and the machine's refusal when this operation may not move it. */
+export function invoicesLoad(ctx, operationId) {
+    const id = at(ctx, 'invoice');
+    const inv = ctx.get(INV, id);
+    if (!inv)
+        return { answer: invoiceMissing(ctx, id) };
+    const refused = ctx.legal(INV, 'status', operationId, inv.status, undefined, id);
+    return refused ? { answer: ctx.refuse(refused) } : { inv };
+}
+/** The PaymentIntent a charge_automatically invoice with a balance gets when it is finalized; it
+ *  waits for confirmation when the invoice already names a default payment method. */
+export async function openPaymentIntent(ctx, piId, inv, invoiceId) {
+    const defaultPaymentMethod = typeof inv.default_payment_method === 'string' ? inv.default_payment_method : undefined;
+    await created(ctx, 'payment_intent', {
+        id: piId, amount: Number(inv.amount_due) || 0, currency: String(inv.currency ?? 'usd'), customer: inv.customer, invoice: invoiceId,
+        ...(defaultPaymentMethod ? { payment_method: defaultPaymentMethod } : {}),
+    }, {
+        status: defaultPaymentMethod ? 'requires_confirmation' : 'requires_payment_method',
+        client_secret: mintClientSecret(piId, await ctx.secret(`client-secret:${piId}`)), livemode: false,
+        capture_method: 'automatic', amount_capturable: 0, amount_received: 0, next_action: null,
+        automatic_payment_methods: null, payment_method_types: ['card', 'link'], payment_method_options: {},
+    });
+}
+export function finalizedFields(ctx, inv, now) {
+    const customerId = typeof inv.customer === 'string' ? inv.customer : '';
+    const customer = customerId ? ctx.get('customer', customerId) : undefined;
+    const prefix = typeof customer?.invoice_prefix === 'string' && customer.invoice_prefix
+        ? customer.invoice_prefix
+        : invoicePrefix(customerId);
+    const numbered = ctx.rows(INV).filter((i) => i.customer === customerId && typeof i.number === 'string' && i.id !== inv.id).length;
+    const fields = { number: typeof inv.number === 'string' && inv.number ? inv.number : `${prefix}-${String(numbered + 1).padStart(4, '0')}` };
+    const days = Number(inv.days_until_due);
+    if (inv.collection_method === 'send_invoice' && inv.due_date == null && Number.isFinite(days) && days > 0)
+        fields.due_date = now + days * 86400;
+    return fields;
+}
+// add_lines, update_lines and remove_lines edit a draft's lines in bulk and re-derive its totals
+export function editLines(kind) {
+    return async (ctx) => {
+        const id = at(ctx, 'invoice');
+        const inv = ctx.get(INV, id);
+        if (!inv)
+            return invoiceMissing(ctx, id);
+        if (inv.status !== 'draft')
+            return fail(ctx, `You can only add/update/remove lines on a draft invoice (this one is ${String(inv.status)}).`, 400, 'invoice_not_editable');
+        const cur = linesOf(inv);
+        let next = [...cur];
+        const raw = ctx.params.lines;
+        const entries = Array.isArray(raw) ? raw : raw && typeof raw === 'object' ? [raw] : [];
+        if (entries.length === 0)
+            return fail(ctx, 'Missing required param: lines.', 400, 'parameter_missing');
+        const currency = String(inv.currency ?? 'usd');
+        if (kind === 'add') {
+            for (let i = 0; i < entries.length; i++) {
+                const e = entries[i];
+                const priceRef = typeof e.price === 'string' ? e.price : '';
+                const price = priceRef ? ctx.get('price', priceRef) : undefined;
+                if (priceRef && !price)
+                    return fail(ctx, `No such price: '${priceRef}'`, 400, 'resource_missing');
+                const quantity = e.quantity !== undefined ? Math.max(1, Math.trunc(Number(e.quantity) || 1)) : 1;
+                const unit = Math.trunc(Number(e.amount) || 0);
+                next.push({ id: `il_twin_${id}_${cur.length + i + 1}`, object: 'line_item', amount: price ? priceAmount(price, quantity) : unit, currency, quantity, price: price ?? (priceRef || null), description: typeof e.description === 'string' ? e.description : null, proration: false });
+            }
+        }
+        else if (kind === 'update') {
+            for (const e of entries) {
+                const lid = typeof e.id === 'string' ? e.id : '';
+                next = next.map((l) => (l.id === lid ? { ...l, ...(e.amount !== undefined ? { amount: Math.trunc(Number(e.amount) || 0) } : {}), ...(e.quantity !== undefined ? { quantity: Math.max(1, Math.trunc(Number(e.quantity) || 1)) } : {}), ...(e.description !== undefined ? { description: e.description } : {}) } : l));
+            }
+        }
+        else {
+            const remove = new Set(entries.map((e) => (typeof e.id === 'string' ? e.id : '')).filter(Boolean));
+            next = next.filter((l) => !remove.has(String(l.id)));
+        }
+        return ctx.reply(await writeLines(ctx, id, next));
+    };
+}
+export const noteMissing = (ctx, id) => fail(ctx, `No such credit note: '${id}'`, 404, 'resource_missing');
+/** The credit note the request describes (the `amount` form: one custom line), or Stripe's refusal. */
+export function build(ctx, id) {
+    const params = ctx.params;
+    const invoiceId = typeof params.invoice === 'string' ? params.invoice : '';
+    if (!invoiceId)
+        return fail(ctx, 'Missing required param: invoice.', 400, 'parameter_missing');
+    const invoice = ctx.get('invoice', invoiceId);
+    if (!invoice)
+        return fail(ctx, `No such invoice: '${invoiceId}'`, 404, 'resource_missing');
+    if (params.amount === undefined)
+        return fail(ctx, 'Missing required param: amount.', 400, 'parameter_missing');
+    const amount = Number(params.amount);
+    if (!Number.isInteger(amount) || amount <= 0)
+        return fail(ctx, 'Invalid integer: amount must be a positive integer.', 400, 'parameter_invalid_integer');
+    const vendorType = invoice.status === 'paid' ? 'post_payment' : 'pre_payment';
+    const outOfBand = Number(params.out_of_band_amount) || 0;
+    // a paid invoice's credit is paid back: "The sum of refunds, customer balance credits, and outside of Stripe credits
+    // must equal the post_payment_amount" (docs.stripe.com/api/credit_notes/create); the message's wording is the twin's
+    if (vendorType === 'post_payment') {
+        const split = (Number(params.refund_amount) || 0) + (Number(params.credit_amount) || 0) + outOfBand;
+        if (split !== amount)
+            return fail(ctx, `The sum of refund_amount, credit_amount and out_of_band_amount (${split}) must equal the credit note's post_payment_amount (${amount}).`, 400, 'parameter_invalid_integer');
+    }
+    const line = {
+        object: 'credit_note_line_item', id: `cnli_${id}_1`, type: 'custom_line_item',
+        amount, description: typeof params.memo === 'string' ? params.memo : null,
+        // a custom line credits no invoice line: invoice_line_item ("ID of the invoice line item being credited") is left
+        // out, the served spec not letting it be null
+        discount_amount: 0, discount_amounts: [], livemode: false,
+        pretax_credit_amounts: [], quantity: null, tax_rates: [], taxes: [],
+        unit_amount: null, unit_amount_decimal: null,
+    };
+    return {
+        amount, amount_shipping: 0, created: nowUnix(ctx.occurredAt), currency: typeof invoice.currency === 'string' ? invoice.currency : 'usd', customer: typeof invoice.customer === 'string' ? invoice.customer : null,
+        customer_balance_transaction: null,
+        // "The date when this credit note is in effect. Same as `created` unless overwritten" (the served spec)
+        discount_amount: 0, discount_amounts: [], effective_at: params.effective_at !== undefined ? Number(params.effective_at) : nowUnix(ctx.occurredAt), invoice: invoiceId,
+        lines: { object: 'list', data: [line], has_more: false, total_count: 1, url: `/v1/credit_notes/${id}/lines` },
+        livemode: false, memo: params.memo ?? null, metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {},
+        number: `${invoiceId}-CN-01`, out_of_band_amount: outOfBand || null,
+        pdf: `https://files.twin.local/credit_notes/${id}.pdf`,
+        post_payment_amount: vendorType === 'post_payment' ? amount : 0,
+        pre_payment_amount: vendorType === 'pre_payment' ? amount : 0,
+        pretax_credit_amounts: [],
+        reason: typeof params.reason === 'string' ? params.reason : null,
+        refunds: [], shipping_cost: null, status: 'issued',
+        subtotal: amount, subtotal_excluding_tax: amount,
+        type: vendorType, total: amount, total_excluding_tax: amount, total_taxes: [],
+        voided_at: null,
+    };
+}
+/** The invoice's credit-note sums, from its issued credit notes; a pre-payment credit lowers what is owed. */
+export async function syncInvoice(ctx, invoiceId) {
+    const inv = ctx.get('invoice', invoiceId);
+    if (!inv)
+        return;
+    let pre = 0;
+    let post = 0;
+    for (const cn of ctx.rows(CN)) {
+        if (cn.invoice !== invoiceId || cn.status === 'void')
+            continue;
+        if (cn.type === 'post_payment')
+            post += Number(cn.amount) || 0;
+        else
+            pre += Number(cn.amount) || 0;
+    }
+    const total = Number(inv.total ?? inv.amount_due) || 0;
+    const paid = Number(inv.amount_paid) || 0;
+    await ctx.write('invoice', invoiceId, { pre_payment_credit_notes_amount: pre, post_payment_credit_notes_amount: post, amount_remaining: Math.max(0, total - paid - pre) }, 'invoice.update');
+}
+/** What a post-payment credit pays back: "Refunds: create a new refund (using refund_amount)"; "Customer balance credit:
+ *  credit the customer's balance (using credit_amount) which will be automatically applied to their next invoice when
+ *  it's finalized" (docs.stripe.com/api/credit_notes/create). The refund is made on the invoice's charge as a refund
+ *  call makes it (refunds.ts); the credit is a customer balance transaction of type credit_note. Where the documentation
+ *  stops and the twin decides: the refund carries no reason of its own. */
+export async function payBack(ctx, id, cn) {
+    const params = ctx.params;
+    const out = {};
+    const refundAmount = Number(params.refund_amount) || 0;
+    if (refundAmount > 0) {
+        const invoice = ctx.get('invoice', String(cn.invoice));
+        const pi = typeof invoice?.payment_intent === 'string' ? ctx.get('payment_intent', invoice.payment_intent) : undefined;
+        const chargeId = typeof invoice?.charge === 'string' ? invoice.charge : typeof pi?.latest_charge === 'string' ? pi.latest_charge : undefined;
+        const charge = chargeId ? ctx.get('charge', chargeId) : undefined;
+        if (!charge)
+            return fail(ctx, 'This invoice was not paid with a charge that can be refunded.', 400, 'invoice_no_charge_to_refund');
+        const answer = await refundCharge(ctx, charge, { amount: refundAmount });
+        if (answer.status >= 400)
+            return answer;
+        const refund = (await answer.json());
+        out.refunds = [{ amount_refunded: refundAmount, refund: refund.id, type: 'refund', payment_record_refund: null }];
+    }
+    const creditAmount = Number(params.credit_amount) || 0;
+    const customer = typeof cn.customer === 'string' ? cn.customer : undefined;
+    if (creditAmount > 0 && customer) {
+        const ending = (Number(ctx.get('customer', customer)?.balance) || 0) - creditAmount;
+        const txn = await created(ctx, 'customer_balance_transaction', { customer, amount: -creditAmount, currency: cn.currency, credit_note: id, invoice: cn.invoice }, {
+            ending_balance: ending, type: 'credit_note', livemode: false, metadata: {}, description: null, checkout_session: null,
+        });
+        await ctx.write('customer', customer, { balance: ending }, `customer.balance_adjusted:${String(txn.id)}`);
+        out.customer_balance_transaction = txn.id;
+    }
+    return out;
+}
+/** A coupon for a fixed amount off, in its currency (docs.stripe.com/api/coupons/create#create_coupon-amount_off). */
+export function amountOffOf(ctx, params) {
+    const amountOff = Number(params.amount_off);
+    if (!Number.isInteger(amountOff) || amountOff <= 0)
+        return fail(ctx, 'Invalid integer: amount_off must be a positive integer.', 400, 'parameter_invalid_integer');
+    if (params.currency === undefined || params.currency === '')
+        return fail(ctx, 'Missing required param: currency.', 400, 'parameter_missing');
+    return amountOff;
+}
+/** Time's lapsing of coupons, caught up to the World's clock: a valid coupon whose redeem_by has passed is no longer
+ *  valid from that moment (manifest.ts). Where the documentation stops and the twin decides: the lapse sends no event
+ *  (the events page names none for it). */
+export async function lapseCoupons(ctx) {
+    const now = Number(nowUnix(ctx.occurredAt));
+    for (const c of ctx.rowsRaw('coupon')) {
+        if (c.valid !== true || typeof c.redeem_by !== 'number' || c.redeem_by > now)
+            continue;
+        const t = await at_(ctx)(c.redeem_by);
+        t.legal('coupon', 'valid', ctx.call.operation.id, 'true', 'false', String(c.id), 'time');
+        await t.write('coupon', String(c.id), { valid: false }, 'coupon.lapsed');
+    }
+}
+export const planMissing = (ctx, id) => fail(ctx, `No such plan: '${id}'`, 404, 'resource_missing');
+/** A recurring price the Plans API still answers: one whose plan was deleted is not a plan any more. */
+export const recurring = (ctx, p) => !!p && !!p.recurring && kept(ctx, 'price', p, '_plan_deleted') !== true;
+/** The request's line items resolved against their prices, or the refusal for a missing price. */
+export function resolved(ctx) {
+    const entries = lineItemEntries(ctx.params);
+    const items = [];
+    for (let i = 0; i < entries.length; i++) {
+        const { item, priceMissing } = resolveLineItem(entries[i], i, 'usd', finder(ctx));
+        if (priceMissing)
+            return fail(ctx, `No such price: '${priceMissing}'`, 400, 'resource_missing');
+        items.push(item);
+    }
+    return items;
+}
+/** A page of the line items a stored object carries. */
+export function linePage(ctx, holder) {
+    const li = holder.line_items;
+    const { page, hasMore } = paginate(Array.isArray(li?.data) ? li.data : [], ctx.params);
+    return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: page });
+}
+export const linkMissing = (ctx, id) => fail(ctx, `No such payment link: '${id}'`, 404, 'resource_missing');
+// ── quotes ──
+export const quoteMissing = (ctx, id) => fail(ctx, `No such quote: '${id}'`, 404, 'resource_missing');
+export function move(action, operationId) {
+    return async (ctx) => {
+        const id = at(ctx, 'quote');
+        const q = ctx.get('quote', id);
+        if (!q)
+            return quoteMissing(ctx, id);
+        const refused = ctx.legal('quote', 'status', operationId, q.status, undefined, id);
+        if (refused)
+            return ctx.refuse(refused);
+        const now = nowUnix(ctx.occurredAt);
+        const stamp = action === 'finalize' ? { finalized_at: now } : action === 'accept' ? { accepted_at: now } : { canceled_at: now };
+        // "Accepted quotes automatically generate an invoice, subscription, or subscription schedule"; "Quotes without
+        // recurring prices: A draft invoice is created with auto_advance set to false" (docs.stripe.com/quotes/overview),
+        // the quote its parent ("Details about the quote that generated this invoice", the served spec). Where the
+        // documentation stops and the twin decides: a quote with recurring prices makes no subscription yet.
+        let made = {};
+        if (action === 'accept') {
+            const lines = q.line_items?.data ?? [];
+            const recurring = lines.some((l) => l.price && typeof l.price === 'object' && l.price.recurring);
+            if (!recurring && typeof q.customer === 'string') {
+                const invoice = await draftInvoiceFor(ctx, q.customer, String(q.currency ?? 'usd'), { type: 'quote_details', quote_details: { quote: id }, subscription_details: null }, lines.map((l) => ({ price: l.price, quantity: Number(l.quantity) || 1, amount: Number(l.amount_subtotal ?? l.amount_total) || 0, description: l.description })));
+                made = { invoice };
+            }
+        }
+        return ctx.reply(await ctx.write('quote', id, {
+            status: action === 'finalize' ? 'open' : action === 'accept' ? 'accepted' : 'canceled',
+            status_transitions: { ...(q.status_transitions ?? {}), ...stamp },
+            ...(action === 'finalize' ? { number: `QT-${id.toUpperCase()}` } : {}),
+            ...made,
+        }, `quote.${action}`));
+    };
+}
+export const sessionMissing = (ctx, id) => fail(ctx, `No such checkout.session: '${id}'`, 404, 'resource_missing');
+// Stripe normalizes the create input into the Session: line_items become the list envelope, and
+// subscription_data (create-only) is kept aside for completion to copy onto the subscription
+/** The discount a session is created with (discounts[0][promotion_code] or [coupon]), or Stripe's refusal: an unknown
+ *  code or coupon, and one that has expired or been deactivated, are refused at create
+ *  (docs.stripe.com/api/checkout/sessions/create#create_checkout_session-discounts, docs.stripe.com/error-codes#coupon-expired).
+ *  Where the documentation stops and the twin decides: the refusals' wording. */
+export function discountOf(ctx, params, now) {
+    const first = Array.isArray(params.discounts) ? params.discounts[0] : undefined;
+    if (!first || typeof first !== 'object')
+        return undefined;
+    const expired = (what) => ctx.refuse({ status: 400, code: 'coupon_expired', param: 'discounts', message: `This ${what} has expired.` });
+    let promotion;
+    let couponId = typeof first.coupon === 'string' ? first.coupon : undefined;
+    if (typeof first.promotion_code === 'string') {
+        const pc = ctx.get('promotion_code', first.promotion_code);
+        if (!pc)
+            return ctx.refuse({ status: 400, code: 'resource_missing', param: 'discounts[0][promotion_code]', message: `No such promotion code: '${first.promotion_code}'` });
+        if (typeof pc.expires_at === 'number' && pc.expires_at <= now)
+            return expired('promotion code');
+        if (pc.active === false)
+            return ctx.refuse({ status: 400, param: 'discounts[0][promotion_code]', message: 'This promotion code is inactive.' });
+        promotion = String(pc.id);
+        couponId = typeof pc.coupon === 'string' ? pc.coupon : String(pc.coupon?.id ?? '');
+    }
+    const coupon = couponId ? ctx.get('coupon', couponId) : undefined;
+    if (!coupon)
+        return ctx.refuse({ status: 400, code: 'resource_missing', param: 'discounts[0][coupon]', message: `No such coupon: '${couponId ?? ''}'` });
+    if (coupon.valid === false || (typeof coupon.redeem_by === 'number' && coupon.redeem_by <= now))
+        return expired('coupon');
+    return { coupon, ...(promotion ? { promotion } : {}) };
+}
+/** A payment or subscription session with nothing to sell (docs.stripe.com/api/checkout/sessions/create#create_checkout_session-line_items). */
+export function noLineItems(ctx) {
+    return fail(ctx, 'You must provide at least one recurring price in `subscription` mode when not using `line_items[].price_data` or a Price with `recurring`, and at least one `line_items` for `payment` mode.', 400, 'parameter_missing');
+}
+/** A destination charge to an account the platform does not have (docs.stripe.com/connect/destination-charges). */
+export function checkoutNoDestination(ctx, destination) {
+    return ctx.refuse({ status: 400, code: 'resource_missing', param: 'payment_intent_data[transfer_data][destination]', message: `No such destination: '${String(destination)}'` });
+}
+/** A session's trial Stripe refuses: `subscription_data.trial_end` "Has to be at least 48 hours in the future", and
+ *  `subscription_data.trial_period_days` "Has to be at least 1" (docs.stripe.com/api/checkout/sessions/create). Where the
+ *  documentation stops and the twin decides: the refusals' wording. */
+export function sessionTrialRefused(ctx, data, now) {
+    if (!data || typeof data !== 'object')
+        return undefined;
+    const { trial_end: end, trial_period_days: days } = data;
+    const endRefused = end !== undefined && !(Number.isInteger(Number(end)) && Number(end) >= now + 48 * 3600);
+    const daysRefused = days !== undefined && !(Number.isInteger(Number(days)) && Number(days) >= 1);
+    return endRefused || daysRefused ? sessionTrialRefusal(ctx, endRefused ? 'trial_end' : 'trial_period_days') : undefined;
+}
+export function sessionTrialRefusal(ctx, param) {
+    const message = param === 'trial_end' ? 'The `subscription_data[trial_end]` timestamp has to be at least 48 hours in the future.' : 'The `subscription_data[trial_period_days]` has to be at least 1.';
+    return ctx.refuse({ status: 400, param: `subscription_data[${param}]`, message });
+}
+/** What completing a session makes, by its mode, as the fields that link it: a payment is a PaymentIntent paid with
+ *  the entered card, its charge in the ledger as any payment's is. */
+export async function complete(ctx, id, existing, card) {
+    const link = { status: 'complete' };
+    const customer = typeof existing.customer === 'string' ? existing.customer : undefined;
+    const currency = typeof existing.currency === 'string' ? existing.currency : 'usd';
+    // the entered card becomes a PaymentMethod carrying what a later charge to it answers and what Stripe does after it
+    // succeeds (docs.stripe.com/testing#declined-payments, #disputes)
+    const made = card ? await created(ctx, 'payment_method', {}, { type: 'card', customer: null, livemode: false, billing_details: { address: null, email: null, name: null, phone: null }, ...paymentMethodSubObject('card', { card }), _declineOutcome: declineFor(() => undefined, { card }) ?? null, ...(afterSuccessOf(ctx, card) ? { _afterSuccess: afterSuccessOf(ctx, card) } : {}) }) : undefined;
+    // and Checkout attaches it to the customer when it saves it: a subscription's card ("If your Checkout Session uses
+    // subscription mode, Stripe saves the payment method by default", docs.stripe.com/payments/checkout/how-checkout-works),
+    // a setup session's (it exists to save one), and a payment's only under payment_intent_data.setup_future_usage ("to have
+    // Checkout automatically attach the payment method to the Customer you pass in", docs.stripe.com/api/checkout/sessions/
+    // create#create_checkout_session-customer). Attaching is its own write, so payment_method.attached is delivered ("Occurs
+    // whenever a new payment method is attached to a customer", docs.stripe.com/api/events/types) before what the card then
+    // pays for. Where the documentation stops and the twin decides: the order of the events, which Stripe does not
+    // guarantee (docs.stripe.com/webhooks#event-ordering). A gap: the customer's own opt-in to save a payment's card
+    // (saved_payment_method_options.payment_method_save) is not modelled; the page offers no such box.
+    const saves = existing.mode !== 'payment' || !!(ctx.row(CS, id)?._payment_intent_data ?? {}).setup_future_usage;
+    const pm = made && customer && saves ? await ctx.write('payment_method', String(made.id), { customer }, 'payment_method.attach') : made;
+    if (existing.mode === 'payment') {
+        const amount = Number(existing.amount_total) || 0;
+        const piId = ctx.mint('payment_intent');
+        const pid = (ctx.row(CS, id)?._payment_intent_data ?? {});
+        const connect = {
+            ...(pid.application_fee_amount !== undefined ? { application_fee_amount: Math.trunc(Number(pid.application_fee_amount) || 0) } : {}),
+            ...(pid.transfer_data && typeof pid.transfer_data === 'object' ? { transfer_data: { destination: pid.transfer_data.destination } } : {}),
+            ...(typeof pid.description === 'string' ? { description: pid.description } : {}),
+            // the session's setup_future_usage is its PaymentIntent's (payment_intent_data: "A subset of parameters to be passed to PaymentIntent creation")
+            ...(typeof pid.setup_future_usage === 'string' ? { setup_future_usage: pid.setup_future_usage } : {}),
+            ...(nestedMetadata(pid.metadata) ? { metadata: nestedMetadata(pid.metadata) } : {}),
+        };
+        const fields = { amount, currency, id: piId, ...(customer ? { customer } : {}), ...(pm ? { payment_method: pm.id } : {}), ...connect };
+        await created(ctx, 'payment_intent', fields, { status: 'succeeded', amount_received: amount, client_secret: mintClientSecret(piId, await ctx.secret(`client-secret:${piId}`)), livemode: false, payment_method_types: Array.isArray(existing.payment_method_types) ? existing.payment_method_types : ['card'] });
+        const charge = await mintCharge(ctx, piId, fields, amount);
+        await ctx.write('payment_intent', piId, { latest_charge: charge }, 'payment_intent.succeeded');
+        link.payment_intent = piId;
+        link.payment_status = 'paid';
+    }
+    else if (existing.mode === 'subscription') {
+        if (customer) {
+            // the subscription bills the session's own (already resolved) line items, and takes the
+            // session's subscription_data: metadata, description, and a trial as its first period
+            const now = Number(nowUnix(ctx.occurredAt));
+            // "Line items with one-time Prices will be on the initial invoice only" (docs.stripe.com/api/checkout/sessions/
+            // create#create_checkout_session-line_items): the subscription's items are the recurring ones
+            const inline = ctx.row(CS, id)?._price_data ?? [];
+            const lines = existing.line_items?.data ?? [];
+            const allLineItems = inline.some(Boolean) ? await sessionPrices(ctx, lines, inline) : lines;
+            const sessionLineItems = allLineItems.filter((it) => !isOneTime(it));
+            const oneTime = allLineItems.filter((it) => isOneTime(it));
+            const { interval, interval_count } = resolveSubscriptionBillingInterval(sessionLineItems, finder(ctx));
+            const subId = ctx.mint('subscription');
+            // the session's view never carries its create-only subscription_data: read the stored row
+            const raw = ctx.row(CS, id)?._subscription_data;
+            const subData = (raw && typeof raw === 'object' ? raw : {});
+            const subMetadata = nestedMetadata(subData.metadata) ?? {};
+            // a trial of `trial_period_days` from now, or to `trial_end` (docs.stripe.com/payments/checkout/free-trials)
+            const trialEnd = resolveTrial(subData, now)?.end ?? null;
+            const sub = await created(ctx, 'subscription', { customer, id: subId }, {
+                status: trialEnd === null ? 'active' : 'trialing', livemode: false, currency, collection_method: 'charge_automatically',
+                // a trial's end is the billing anchor (docs.stripe.com/api/subscriptions/create#create_subscription-trial_end)
+                cancel_at_period_end: false, start_date: now, billing_cycle_anchor: trialEnd ?? now, metadata: subMetadata,
+                description: typeof subData.description === 'string' ? subData.description : null,
+                // the session's discount is the subscription's (docs.stripe.com/payments/checkout/discounts)
+                discounts: sessionDiscount(ctx, id, customer, now), billing_schedules: [],
+                trial_start: trialEnd === null ? null : now, trial_end: trialEnd,
+                current_period_start: now, current_period_end: trialEnd ?? addBillingInterval(now, interval, interval_count),
+                // Checkout saves the card as the subscription's default payment method (docs.stripe.com/payments/checkout/how-checkout-works)
+                default_payment_method: pm?.id ?? null,
+                items: buildSubscriptionItemsList(sessionLineItems, subId, now, finder(ctx)),
+                automatic_tax: { enabled: false, liability: null }, billing_mode: { type: 'classic' },
+                invoice_settings: { issuer: { type: 'self' } },
+            });
+            await storeItems(ctx, subId, sub.items?.data ?? []);
+            // its first invoice, paid on the page by the card just entered (nothing is due on a trial's)
+            // (docs.stripe.com/billing/subscriptions/overview#how-payments-work-subscriptions)
+            const invoice = await draftSubscriptionInvoice(ctx, sub, { start: now, end: Number(sub.current_period_end), reason: 'subscription_create', trial: trialEnd !== null, once: oneTime });
+            await collectSubscriptionInvoice(ctx, invoice, now, 'external');
+            await ctx.write('subscription', subId, { latest_invoice: invoice }, 'subscription.update');
+            link.subscription = sub.id;
+            link.invoice = invoice;
+        }
+        link.payment_status = 'paid';
+    }
+    else
+        link.setup_intent = await completeSetup(ctx, customer, pm);
+    return link;
+}
+/** A subscription session's lines at completion, each inline `price_data` made the Price it generates ("Data used to
+ *  generate a new Price object inline", the same page), under the product it names or one made from its product_data,
+ *  so the subscription's items bill it. Where the documentation stops and the twin decides: such a Price is archived
+ *  (active=false), as a subscription item's price_data makes one (docs.stripe.com/products-prices/manage-prices). */
+export async function sessionPrices(ctx, lines, inline) {
+    const out = [];
+    for (const [i, line] of lines.entries()) {
+        const d = inline[i];
+        if (!d) {
+            out.push(line);
+            continue;
+        }
+        const pd = d.product_data && typeof d.product_data === 'object' ? d.product_data : undefined;
+        const product = typeof d.product === 'string' ? d.product : String((await created(ctx, 'product', { name: pd?.name ?? 'Item' }, { active: true, livemode: false, images: [], marketing_features: [], metadata: {}, updated: nowUnix(ctx.occurredAt) })).id);
+        const r = d.recurring && typeof d.recurring === 'object' ? d.recurring : undefined;
+        const price = await created(ctx, 'price', {
+            product, currency: String(d.currency ?? line.currency ?? 'usd').toLowerCase(),
+            unit_amount: d.unit_amount_decimal !== undefined ? null : Math.trunc(Number(d.unit_amount) || 0),
+            unit_amount_decimal: d.unit_amount_decimal !== undefined ? String(d.unit_amount_decimal) : String(Math.trunc(Number(d.unit_amount) || 0)),
+            ...(r ? { recurring: { interval: r.interval, interval_count: Math.max(1, Math.trunc(Number(r.interval_count ?? 1)) || 1), usage_type: 'licensed', trial_period_days: null, meter: null } } : { recurring: null }),
+        }, { active: false, livemode: false, billing_scheme: 'per_unit', type: r ? 'recurring' : 'one_time', metadata: {}, lookup_key: null, nickname: null, tax_behavior: 'unspecified' });
+        out.push({ ...line, price });
+    }
+    return out;
+}
+/** A setup session saves the card through a succeeded SetupIntent (docs.stripe.com/payments/save-and-reuse?platform=checkout). */
+export async function completeSetup(ctx, customer, pm) {
+    const siId = ctx.mint('setup_intent');
+    const si = await created(ctx, 'setup_intent', { id: siId, ...(customer ? { customer } : {}), ...(pm ? { payment_method: pm.id } : {}) }, { status: 'succeeded', usage: 'off_session', client_secret: mintClientSecret(siId, await ctx.secret(`client-secret:${siId}`)), payment_method_types: ['card'], livemode: false });
+    return si.id;
+}
+/** The discount a completed subscription session gives its subscription. */
+export function sessionDiscount(ctx, id, customer, now) {
+    const d = ctx.row(CS, id)?._discount;
+    const coupon = d && typeof d.coupon === 'string' ? ctx.get('coupon', d.coupon) : undefined;
+    return coupon ? [{ ...buildDiscount(coupon, customer, now), promotion_code: d?.promotion_code ?? null, checkout_session: id }] : [];
+}
+/** The customer paying on the hosted page (src/screens/checkout.tsx): the external actor's move on the
+ *  session's machine, then what the payment made, linked, and the session stored complete. */
+export async function completeSession(ctx, id, existing, details = {}, card) {
+    const refused = ctx.legal(CS, 'status', 'PostCheckoutSessionsSession', existing.status, 'complete', id, 'external');
+    if (refused)
+        return ctx.refuse(refused);
+    const link = await complete(ctx, id, existing, card);
+    // the discount the buyer took is redeemed (shared.ts redeemCoupon)
+    const d = ctx.row(CS, id)?._discount;
+    if (d)
+        await redeemCoupon(ctx, d.coupon, d.promotion_code);
+    // the session's url "is only present when the session is active" (docs.stripe.com/api/checkout/sessions/object)
+    return ctx.write(CS, id, { ...details, ...link, url: null }, 'checkout.session.completed');
+}
 export const send = (ctx, r) => ctx.reply(r.body, r.status);
 /** Stripe's error body: an invalid_request_error with the message, and the code when there is one. */
 export const fail = (ctx, message, status = 404, code) => ctx.refuse({ status, message, ...(code ? { code } : {}) });
@@ -39,20 +1435,9 @@ export function mergeUpdate(ctx, resource, id, fields) {
     }
     return out;
 }
-/** The tree's type for a resource: what its rows are stored under. */
-export const stored = (resource) => manifest.resources[resource]?.storedAs ?? resource;
 /** A resource's rows in Stripe's list order: newest first by `timeField`, ties by mint order (as the derived core breaks them). */
 /** A subject's bookkeeping field (`_…`): kept on the stored row, never in the wire view ctx.get and ctx.rows answer. */
 export const kept = (ctx, resource, row, key) => ctx.row(resource, String(row.id), { withDeleted: true })?.[key];
-/** A removed discount as Stripe answers it: the discount, marked deleted (docs.stripe.com/api/discounts/delete). */
-export function deletedDiscount(d, now) {
-    const coupon = d.coupon && typeof d.coupon === 'object' ? String(d.coupon.id) : typeof d.coupon === 'string' ? d.coupon : null;
-    return {
-        id: d.id ?? `di_${coupon ?? 'twin'}`, object: 'discount', deleted: true, checkout_session: d.checkout_session ?? null, customer: d.customer ?? null,
-        invoice: d.invoice ?? null, invoice_item: d.invoice_item ?? null, promotion_code: d.promotion_code ?? null, subscription: d.subscription ?? null,
-        subscription_item: d.subscription_item ?? null, source: d.source ?? { type: 'coupon', coupon }, start: d.start ?? now,
-    };
-}
 /** A create's parameter that describes a confirmation, sent without confirm=true: the served spec gives each "This
  *  parameter can only be used with `confirm=true`" (off_session: "can only be used when confirm=true"); the message's
  *  wording is the twin's. Answers the refusal, or undefined. */
@@ -76,20 +1461,16 @@ export function newest(ctx, resource, timeField = 'created') {
     // an object Stripe gives no creation time is ordered by the one the twin keeps for it
     const raw = new Map(ctx.rowsRaw(resource).map((r) => [String(r.id), r]));
     const when = (r) => Number(r[timeField] ?? raw.get(String(r.id))?._created ?? 0);
-    return ctx.rows(resource).sort((a, b) => {
+    // ties by the order the World made them (an event's id is a digest, not a count)
+    const rows = ctx.rows(resource);
+    const made = new Map(rows.map((r, i) => [r, i]));
+    return rows.sort((a, b) => {
         const ta = when(a), tb = when(b);
         if (tb !== ta)
             return tb - ta;
-        return String(b.id).localeCompare(String(a.id), undefined, { numeric: true });
+        return made.get(b) - made.get(a);
     });
 }
-/** Keep the rows whose field equals the request's parameter of the same name, for each name given. */
-/** A list's range filter on a unix time (`created[gte]=…&created[lt]=…`, or one exact time). */
-export function inRange(t, v) {
-    const at = Number(t);
-    const r = (v && typeof v === 'object' ? v : { gte: v, lte: v });
-    return (r.gt === undefined || at > Number(r.gt)) && (r.gte === undefined || at >= Number(r.gte)) && (r.lt === undefined || at < Number(r.lt)) && (r.lte === undefined || at <= Number(r.lte));
-}
 /** A context at the moment Stripe would have made a move time makes (a renewal, a payout on its schedule), so what
  *  the move writes carries that moment (its events' occurredAt, `created`, a charge's funds' available_on), not the
  *  moment a later request caught it up. */
@@ -105,48 +1486,35 @@ export function where(ctx, items, spec) {
     }
     return out;
 }
-function expandPaths(ctx) {
+export function expandPaths(ctx) {
     const expand = ctx.params.expand;
     return Array.isArray(expand) ? expand.map((p) => String(p).split('.')) : [];
 }
 /** A balance transaction as the clock reads it: available once its available_on has passed, the clock's move,
- *  asked of the machine as a write asks it (semantics/ledger.ts). */
-export function asOf(ctx, t) {
+ *  asked of the machine as a write asks it (./ledger.ts). */
+export function commonAsOf(ctx, t) {
     const due = Number(t.available_on);
-    if (t.status !== 'pending' || !Number.isFinite(due) || due > Number(ctx.now()))
+    if (t.status !== 'pending' || !Number.isFinite(due) || due > Number(nowUnix(ctx.occurredAt)))
         return t;
     ctx.legal('balance_transaction', 'status', ctx.call.operation.id, 'pending', 'available', String(t.id), 'time');
     return { ...t, status: 'available' };
 }
-/** Stripe's expand walk: each dotted path replaces an id with the resource the manifest says it
- *  holds, one segment at a time; an id the tree lacks stays an id. A balance transaction reads as the clock has it
- *  (asOf), as its own retrieve does. */
+/** Stripe's expand walk (the kernel's, over the manifest's `embeds`): each dotted path replaces an id with the resource
+ *  it holds, one segment at a time; an id the tree lacks stays an id. An embedded balance transaction reads as the clock
+ *  has it (asOf), as its own retrieve does. */
 export function expandRow(ctx, resource, body, paths) {
-    const embeds = manifest.resources[resource]?.embeds;
-    if (!embeds || paths.length === 0)
+    if (paths.length === 0)
         return body;
-    let out = body;
-    const byHead = new Map();
-    for (const p of paths) {
-        if (p.length === 0)
-            continue;
-        const list = byHead.get(p[0]) ?? [];
-        list.push(p.slice(1));
-        byHead.set(p[0], list);
-    }
-    for (const [head, tails] of byHead) {
-        const target = embeds[head];
-        if (!target)
-            continue;
-        const cur = out[head];
-        const found = typeof cur === 'string' && cur ? ctx.get(target, cur) : cur && typeof cur === 'object' && !Array.isArray(cur) ? cur : undefined;
-        if (!found)
-            continue;
-        const sub = target === 'balance_transaction' ? asOf(ctx, found) : found;
-        const deeper = tails.filter((t) => t.length > 0);
-        out = { ...out, [head]: deeper.length ? expandRow(ctx, target, sub, deeper) : sub };
-    }
-    return out;
+    const asOf = (v) => {
+        if (Array.isArray(v))
+            return v.map(asOf);
+        if (!v || typeof v !== 'object')
+            return v;
+        const o = Object.fromEntries(Object.entries(v).map(([k, x]) => [k, asOf(x)]));
+        return o.object === 'balance_transaction' ? commonAsOf(ctx, o) : o;
+    };
+    const out = ctx.expand(resource, body, paths.map((p) => p.join('.')));
+    return Object.fromEntries(Object.entries(out).map(([k, v]) => [k, asOf(v)]));
 }
 /** One resource with the request's `expand[]` applied. */
 export const expanded = (ctx, resource, body) => expandRow(ctx, resource, body, expandPaths(ctx));
@@ -158,46 +1526,1644 @@ export function list(ctx, resource, items) {
 }
 /** Stripe's search over a resource's rows (`query` in its search language). */
 export const search = (ctx, resource, timeField = 'created') => send(ctx, searchOver(newest(ctx, resource, timeField), ctx.params, path(ctx)));
-const SPEC_FIELDS = new Map(surface.resources.map((r) => [r.name, new Set(r.fields.map((f) => f.name))]));
 /** A create as Stripe stamps it: the caller's id when it gave one (seeding uses real ids), else a
  *  minted one; `object`, the creation time, the defaults, then the request's own fields. An object
  *  Stripe gives no creation time keeps the twin's as `_created`, for ordering. (A request parameter the
  *  object has no field for stays on the row, where the rules read it; the wire answer leaves it out,
- *  stripe-version.ts.) */
+ *  ./version.ts.) */
 export async function created(ctx, resource, params, defaults, opts = {}) {
     const { id: provided, ...rest } = params;
-    const type = stored(resource);
+    const type = ctx.storedType(resource);
     const id = typeof provided === 'string' && provided ? provided : ctx.mint(resource);
     const known = SPEC_FIELDS.get(resource);
     const timeField = opts.timeField ?? 'created';
     const stamped = !known || known.has(timeField) || timeField in defaults || timeField in rest ? timeField : '_created';
-    const fields = stashVendorType(type, { object: OBJECT_NAME[type] ?? type, [stamped]: ctx.now(), ...defaults, ...rest });
+    const fields = { object: OBJECT_NAME[type] ?? type, [stamped]: nowUnix(ctx.occurredAt), ...defaults, ...rest };
     return ctx.write(resource, id, fields, opts.operation ?? `${type}.create`);
 }
-export const finder = (ctx) => {
-    const tree = ctx.tree();
-    return (storedType, id) => {
-        const r = tree.find((x) => x.type === storedType && x.id === id);
-        return r ? view(storedType, r) : undefined;
-    };
+export const finder = (ctx) => (storedType, id) => {
+    const r = ctx.rowsRaw(storedType, { withDeleted: true }).find((x) => x.id === id);
+    return r ? view(storedType, r) : undefined;
 };
-/** A refund's destination_details for a card charge: "If this is a `card` refund, this hash contains the transaction
- *  specific details" and its `type` "can be `refund`, `reversal`, or `pending`" — a reversal, where "The original charge
- *  will drop off the bank statement altogether", for an authorization released uncaptured, else a refund, "a credit entry
- *  on the bank statement" (docs.stripe.com/api/refunds/object). The network's reference number the twin never has. A
- *  charge not paid by card answers none. */
-export function refundDestination(charge, type) {
-    const pmd = charge.payment_method_details;
-    if (pmd && pmd.type !== 'card')
-        return {};
-    return { destination_details: { type: 'card', card: { reference: null, reference_status: null, reference_type: null, type } } };
-}
-/** An account's external_accounts, "External accounts (bank accounts and debit cards) currently attached to this
- *  account" (docs.stripe.com/api/accounts/object), as the list its example answers. */
-export const externalList = (account, data) => ({ object: 'list', data, has_more: false, total_count: data.length, url: `/v1/accounts/${account}/external_accounts` });
 /** The account's external_accounts list, rewritten from its external accounts after one is added or removed. */
 export async function syncExternals(ctx, account) {
     if (!ctx.get('account', account))
         return;
     await ctx.write('account', account, { external_accounts: externalList(account, newest(ctx, 'external_account').filter((e) => e.account === account)) }, 'account.external_accounts');
 }
+/** A decision over the rows and the write it makes, taken together: the read and the write follow one another with
+ *  nothing between them (a code spent once, a connection revoked once). */
+export async function decide(ctx, decision) {
+    const d = decision((resource) => ctx.rowsRaw(resource));
+    if (d.write)
+        await ctx.write(d.write.resource, d.write.id, d.write.fields, d.write.operation);
+    return d.value;
+}
+export const catalog = (ctx, data) => ctx.reply({ object: 'list', url: path(ctx), has_more: false, data });
+export const orderMissing = (ctx, id) => fail(ctx, `No such order: '${id}'`, 404, 'resource_missing');
+/** Each pending report run completes, caught up before anything is answered: "When the run completes, Stripe updates
+ *  the object, and it has a status of succeeded. It also has a nested result object, containing a URL that you can use
+ *  to access the file", the guide's example a File of purpose report_run and type csv (docs.stripe.com/reports/api).
+ *  "Most runs complete within a few minutes" (the same page). Where the documentation stops and the twin decides: a run
+ *  completes one minute after it was created (the guide's example: created 1580832900, succeeded_at 1580832960), and
+ *  its CSV holds the report type's header row alone (its size that row's bytes). */
+export async function finishReportRuns(ctx) {
+    for (const run of ctx.rowsRaw('reporting.report_run')) {
+        if (run.status !== 'pending')
+            continue;
+        const done = Number(run.created) + 60;
+        if (Number(nowUnix(ctx.occurredAt)) < done)
+            continue;
+        const id = String(run.id);
+        const header = 'category,currency,description,net_amount\n';
+        const file = await created(ctx, 'file', { purpose: 'report_run' }, {
+            filename: `${String(run.report_type)}_${id}.csv`, size: header.length, type: 'csv', title: null, expires_at: null, url: null,
+            links: { object: 'list', data: [], has_more: false, url: '' },
+        });
+        await ctx.write('file', String(file.id), { url: `https://files.twin.local/v1/files/${String(file.id)}/contents` }, 'file.updated');
+        ctx.legal('reporting.report_run', 'status', ctx.call.operation.id, 'pending', 'succeeded', id, 'vendor');
+        await ctx.write('reporting.report_run', id, { status: 'succeeded', succeeded_at: done, result: ctx.get('file', String(file.id)) }, 'reporting.report_run.succeeded');
+    }
+}
+/** A feature whose lookup_key an unarchived feature already has: "A unique key you provide as your own system identifier"
+ *  (docs.stripe.com/api/entitlements/feature/create). */
+export function lookupKeyTaken(ctx, lookupKey) {
+    return fail(ctx, `A feature with lookup_key '${lookupKey}' already exists.`, 400, 'resource_already_exists');
+}
+export const pmMissing = (ctx, id) => fail(ctx, `No such payment_method: '${id}'`, 404, 'resource_missing');
+/** The card a charge was paid with, as its payment_method_details reports it
+ *  (docs.stripe.com/api/charges/object#charge_object-payment_method_details): a stored PaymentMethod's card, a
+ *  documented test name (pm_card_* or tok_*, the same cards), or a raw card; undefined for anything else. */
+export function paymentMethodDetails(ctx, ref) {
+    let card;
+    // a payment method of another kind (a US bank account) is described by its own block, as the charge reports it
+    const stored = typeof ref === 'string' && ref ? ctx.get(PM, ref) : undefined;
+    // Stripe's US bank account test methods (pm_us_bank_account, pm_usBankAccount_*) are its test bank's account
+    const pm = stored ?? (typeof ref === 'string' && /^pm_us_?bank_?account/i.test(ref) ? { type: 'us_bank_account', ...paymentMethodSubObject('us_bank_account', {}) } : undefined);
+    if (pm && typeof pm.type === 'string' && pm.type !== 'card') {
+        const own = pm[pm.type] ?? {};
+        const pick = ['account_holder_type', 'account_type', 'bank_name', 'fingerprint', 'last4', 'routing_number'];
+        return { type: pm.type, [pm.type]: Object.fromEntries(pick.filter((k) => own[k] !== undefined).map((k) => [k, own[k]])) };
+    }
+    if (typeof ref === 'string' && ref) {
+        const stored = ctx.get(PM, ref)?.card;
+        if (stored)
+            card = stored;
+        else
+            card = testCardOf(ref);
+    }
+    else if (ref && typeof ref === 'object')
+        card = paymentMethodSubObject('card', { card: ref }).card;
+    if (!card)
+        return undefined;
+    return {
+        type: 'card',
+        card: {
+            brand: card.brand, last4: card.last4, exp_month: card.exp_month, exp_year: card.exp_year, funding: card.funding ?? 'credit',
+            country: card.country ?? 'US', network: card.brand, fingerprint: card.fingerprint ?? null,
+            checks: card.checks ?? { address_line1_check: null, address_postal_code_check: null, cvc_check: 'pass' },
+            three_d_secure: null, wallet: null, installments: null, mandate: null,
+        },
+    };
+}
+// attaching needs an existing customer; a well-known test token (pm_card_visa, …) is a template:
+// attaching it mints a new PaymentMethod on the customer carrying that card's outcome
+/** Whether a payment method can be attached: a stored one, or a documented test name that attaching mints. */
+export const attachable = (ctx, id) => !!ctx.get(PM, id) || (id.startsWith('pm_card_') && (id in TEST_TOKEN_DECLINES || id in AFTER_SUCCESS_CARDS));
+export async function attachPaymentMethod(ctx, id, customer) {
+    if (!ctx.get(PM, id))
+        return materializeTestMethod(ctx, id, customer);
+    return ctx.write(PM, id, { customer }, 'payment_method.attach');
+}
+/** A documented test name (pm_card_visa, pm_card_visa_chargeDeclined, …) made a real PaymentMethod, as Stripe
+ *  does when one is used: the brand and number it stands for (docs.stripe.com/testing#cards) and its outcome. */
+export async function materializeTestMethod(ctx, id, customer) {
+    const card = TEST_PM_CARDS[id] ?? { brand: 'visa', number: '4242424242424242' };
+    const sub = paymentMethodSubObject('card', { card: { number: card.number } });
+    sub.card.brand = card.brand;
+    const afterSuccess = AFTER_SUCCESS_CARDS[id]?.outcome;
+    return created(ctx, PM, { type: 'card', customer, livemode: false, billing_details: noBilling, ...sub, _declineOutcome: TEST_TOKEN_DECLINES[id] ?? null, ...(afterSuccess ? { _afterSuccess: afterSuccess } : {}) }, {});
+}
+/** A PaymentMethod made from a confirm's `payment_method_data` ("If provided, this hash will be used to create a
+ *  PaymentMethod", docs.stripe.com/api/setup_intents/confirm, docs.stripe.com/api/payment_intents/confirm), or none. */
+export async function methodFromData(ctx, data) {
+    if (!data || typeof data !== 'object')
+        return undefined;
+    const d = data;
+    const type = typeof d.type === 'string' ? d.type : 'card';
+    const made = await created(ctx, PM, {}, {
+        type, customer: null, livemode: false, metadata: {},
+        billing_details: { ...noBilling, ...(d.billing_details ?? {}) },
+        ...paymentMethodSubObject(type, d),
+        // what follows its card's success (a dispute, funds straight to available), as a PaymentMethod created directly carries
+        ...(type === 'card' && afterSuccessOf(ctx, d.card) ? { _afterSuccess: afterSuccessOf(ctx, d.card) } : {}),
+    });
+    return String(made.id);
+}
+/** Whether an intent sets up or pays with a bank account by micro-deposits because it asks for them:
+ *  payment_method_options[us_bank_account][verification_method]=microdeposits with a us_bank_account method
+ *  ("Microdeposit only verification", docs.stripe.com/payments/ach-direct-debit/set-up-payment). */
+export function microdepositsAsked(ctx, params, intent, pm) {
+    const options = (params.payment_method_options ?? intent.payment_method_options)?.us_bank_account;
+    return options?.verification_method === 'microdeposits' && !!pm && ctx.get(PM, pm)?.type === 'us_bank_account';
+}
+export const scheduleMissing = (ctx, id) => fail(ctx, `No such subscription_schedule: '${id}'`, 404, 'resource_missing');
+/** A schedule's phases as Stripe answers them (the served spec's subscription_schedule_phase_configuration): each
+ *  starts where the last ended (the first at the schedule's start_date, "now" or a timestamp), and ends at its
+ *  end_date or after its duration ("duration: interval, interval_count", the served spec's phases[] parameter) on the
+ *  calendar; its currency is its first price's, each item carries its price, quantity and (empty) discounts. Where the
+ *  documentation stops and the twin decides: a phase with neither lasts one interval of its first price. */
+export function phasesOf(ctx, given, start) {
+    let cursor = start;
+    return given.map((p) => {
+        const items = (Array.isArray(p.items) ? p.items : []).map((it) => ({ price: it.price ?? null, quantity: Math.max(1, Math.trunc(Number(it.quantity) || 1)), discounts: [], metadata: {}, tax_rates: [], billing_thresholds: null }));
+        const price = typeof items[0]?.price === 'string' ? ctx.get('price', items[0].price) : undefined;
+        const recurring = price?.recurring ?? {};
+        const d = p.duration && typeof p.duration === 'object' ? p.duration : undefined;
+        const startDate = cursor;
+        const end = p.end_date !== undefined && p.end_date !== 'now' ? Number(p.end_date)
+            : d ? addBillingInterval(startDate, String(d.interval), Math.max(1, Number(d.interval_count) || 1))
+                : addBillingInterval(startDate, String(recurring.interval ?? 'month'), Math.max(1, Number(recurring.interval_count) || 1));
+        cursor = end;
+        return {
+            add_invoice_items: [], application_fee_percent: null, automatic_tax: { enabled: false, liability: null, disabled_reason: null }, billing_cycle_anchor: null,
+            billing_thresholds: null, collection_method: null, currency: String(price?.currency ?? 'usd'), default_payment_method: null, default_tax_rates: [],
+            description: null, discounts: [], end_date: end, invoice_settings: null, items, metadata: p.metadata && typeof p.metadata === 'object' ? p.metadata : {},
+            on_behalf_of: null, proration_behavior: typeof p.proration_behavior === 'string' ? p.proration_behavior : 'create_prorations', start_date: startDate,
+            transfer_data: null, trial_end: null,
+        };
+    });
+}
+export function end(kind) {
+    return async (ctx) => {
+        const id = at(ctx, 'schedule');
+        const sched = ctx.get(SS, id);
+        if (!sched)
+            return scheduleMissing(ctx, id);
+        const refused = ctx.legal(SS, 'status', kind === 'cancel' ? 'PostSubscriptionSchedulesScheduleCancel' : 'PostSubscriptionSchedulesScheduleRelease', sched.status, undefined, id);
+        if (refused)
+            return ctx.refuse(refused);
+        const now = nowUnix(ctx.occurredAt);
+        const subId = typeof sched.subscription === 'string' ? sched.subscription : undefined;
+        const sub = subId ? ctx.get('subscription', subId) : undefined;
+        // "Cancels a subscription schedule and its associated subscription immediately (if the subscription schedule has an
+        // active subscription)" (docs.stripe.com/api/subscription_schedules/cancel); releasing "will remove its subscription
+        // property and set the subscription's ID to the released_subscription property", leaving the subscription in place
+        // (docs.stripe.com/api/subscription_schedules/release)
+        if (kind === 'cancel' && subId && sub && sub.status !== 'canceled') {
+            ctx.legal('subscription', 'status', 'PostSubscriptionSchedulesScheduleCancel', String(sub.status), 'canceled', subId);
+            await ctx.write('subscription', subId, { status: 'canceled', canceled_at: now, ended_at: now }, 'subscription.cancel');
+        }
+        if (kind === 'release' && subId && sub)
+            await ctx.write('subscription', subId, { schedule: null }, 'subscription.update');
+        const fields = kind === 'cancel'
+            ? { status: 'canceled', canceled_at: now, current_phase: null }
+            : { status: 'released', released_at: now, released_subscription: subId ?? null, subscription: null, current_phase: null };
+        return ctx.reply(await ctx.write(SS, id, fields, `subscription_schedule.${kind}`));
+    };
+}
+/** A token asked for none of what a token holds. */
+export function noTokenSource(ctx) {
+    return fail(ctx, 'You must provide one of the following parameters: card, bank_account, pii.', 400, 'parameter_missing');
+}
+/** A bank account token's account, as the legacy BankAccount object holds it. */
+export function bankAccountOf(ctx, ba) {
+    const acct = typeof ba.account_number === 'string' ? ba.account_number.replace(/\D/g, '') : '';
+    return {
+        id: ctx.mint('external_account'), object: 'bank_account', account_holder_name: ba.account_holder_name ?? null,
+        account_holder_type: ba.account_holder_type ?? null, bank_name: 'STRIPE TEST BANK',
+        country: ba.country ?? 'US', currency: ba.currency ?? 'usd', fingerprint: 'twin_ba_fp',
+        last4: acct ? acct.slice(-4) : '6789', routing_number: ba.routing_number ?? '110000000', status: 'new',
+    };
+}
+export const productMissing = (ctx, id) => fail(ctx, `No such product: '${id}'`, 404, 'resource_missing');
+// a product with prices cannot be deleted; Stripe says to deactivate it instead
+/** A product deleted while it has prices: "Deleting a product is only possible if it has no prices associated with it"
+ *  (docs.stripe.com/api/products/delete). */
+export function pricedProductRefused(ctx) {
+    return fail(ctx, 'You cannot delete the product because it has one or more prices. Deactivate the product instead.', 400, 'resource_already_exists');
+}
+// ── features: an entitlements feature granted to a product, at most once ──
+/** A feature attached to a product that already has it. */
+export function alreadyAttached(ctx) {
+    return fail(ctx, 'This feature is already attached to the product.', 400, 'resource_already_exists');
+}
+export const productFeature = (ctx) => {
+    const pf = ctx.get('product_feature', at(ctx, 'id'));
+    // the product a feature is attached to is its address, not a field Stripe answers
+    return pf && kept(ctx, 'product_feature', pf, '_product') === at(ctx, 'product') ? pf : undefined;
+};
+export const featureMissing = (ctx) => fail(ctx, `No such product feature: '${at(ctx, 'id')}'`, 404, 'resource_missing');
+// ── prices ──
+/** A tiered price: tiers_mode and tiers, each tier with up_to and a unit or flat amount; no single unit_amount, and
+ *  the last tier's up_to null (∞) (docs.stripe.com/products-prices/pricing-models#tiered-pricing). */
+export async function tieredPrice(ctx, params) {
+    const mode = typeof params.tiers_mode === 'string' ? params.tiers_mode : '';
+    if (mode !== 'graduated' && mode !== 'volume')
+        return fail(ctx, 'Missing required param: tiers_mode (graduated or volume).', 400, 'parameter_missing');
+    const rawTiers = Array.isArray(params.tiers) ? params.tiers : [];
+    if (rawTiers.length === 0)
+        return fail(ctx, 'Missing required param: tiers.', 400, 'parameter_missing');
+    const tiers = rawTiers.map((t) => {
+        const upToRaw = t.up_to;
+        return {
+            up_to: upToRaw === 'inf' || upToRaw === undefined || upToRaw === null ? null : Math.trunc(Number(upToRaw)),
+            unit_amount: t.unit_amount !== undefined ? Math.trunc(Number(t.unit_amount)) : null,
+            unit_amount_decimal: t.unit_amount !== undefined ? String(Math.trunc(Number(t.unit_amount))) : null,
+            flat_amount: t.flat_amount !== undefined ? Math.trunc(Number(t.flat_amount)) : null,
+            flat_amount_decimal: t.flat_amount !== undefined ? String(Math.trunc(Number(t.flat_amount))) : null,
+        };
+    });
+    if (tiers.some((t) => t.unit_amount === null && t.flat_amount === null))
+        return fail(ctx, 'Each tier must specify a unit_amount or flat_amount.', 400, 'parameter_invalid_empty');
+    const { tiers: _t, ...rest } = params;
+    return ctx.reply(await created(ctx, 'price', { ...rest, billing_scheme: 'tiered', tiers_mode: mode, tiers, unit_amount: null }, { active: true, livemode: false, type: rest.recurring ? 'recurring' : 'one_time', metadata: {} }));
+}
+/** Whether the intent's caller named its methods: on create (TYPES_GIVEN), or by an update that set its
+ *  payment_method_types ("Alternatively, update the allowed payment_method_types for this PaymentIntent",
+ *  methodNotAllowed below), which the generic update writes as given, so the intent's history holds it. */
+export const typesGiven = (ctx, id) => ctx.rowsRaw(TYPES_GIVEN).some((r) => r.id === id)
+    || ctx.history(PI, id).some((e) => e.operation !== 'payment_intent.create' && Array.isArray(e.fields?.payment_method_types));
+export const paymentIntentsSend = (ctx, r) => ctx.reply(r.body, r.status);
+export async function mintCharge(ctx, piId, pi, amount) {
+    const already = ctx.get(PI, piId)?.latest_charge;
+    if (typeof already === 'string' && ctx.get('charge', already)?.status === 'succeeded')
+        return already;
+    const chargeId = ctx.mint('charge');
+    const bt = await settleCharge(ctx, chargeId, amount, String(pi.currency ?? 'usd'), typeof pi.payment_method === 'string' ? pi.payment_method : undefined);
+    await created(ctx, 'charge', {
+        id: chargeId, amount, currency: pi.currency ?? 'usd', payment_intent: piId,
+        ...(typeof pi.customer === 'string' ? { customer: pi.customer } : {}),
+        ...(typeof pi.payment_method === 'string' ? { payment_method: pi.payment_method } : {}),
+        ...(typeof pi.invoice === 'string' ? { invoice: pi.invoice } : {}),
+        ...intentCarries(pi),
+    }, { ...chargeDefaults(chargeId, amount, true, ctx.occurredAt), balance_transaction: bt, payment_method_details: paymentMethodDetails(ctx, pi.payment_method) ?? null }, { operation: 'charge.succeeded' });
+    await afterCharge(ctx, chargeId, { amount, currency: String(pi.currency ?? 'usd'), payment_intent: piId, application_fee_amount: pi.application_fee_amount, destination: pi.transfer_data?.destination }, pi.payment_method);
+    return chargeId;
+}
+/** A manual-capture intent's authorization: "Separate payment authorization and capture to create a charge now, but
+ *  capture funds later", and on capture "A partial capture automatically releases the remaining amount"
+ *  (docs.stripe.com/payments/place-a-hold-on-a-payment-method). The charge succeeded and is not captured, holding the
+ *  amount until capture_before, with nothing on the balance yet. Written as
+ *  charge.succeeded, as a charge made with capture=false is (charges.ts); its capture writes charge.captured
+ *  (captureAuthorization). Where the documentation stops and the twin decides: the events page names no event for an
+ *  authorization of its own, so the authorized charge sends charge.succeeded, its status being succeeded. */
+export async function authorizeCharge(ctx, piId, pi, amount) {
+    const chargeId = ctx.mint('charge');
+    await created(ctx, 'charge', {
+        id: chargeId, amount, currency: pi.currency ?? 'usd', payment_intent: piId,
+        ...(typeof pi.customer === 'string' ? { customer: pi.customer } : {}),
+        ...(typeof pi.payment_method === 'string' ? { payment_method: pi.payment_method } : {}),
+        ...(typeof pi.invoice === 'string' ? { invoice: pi.invoice } : {}),
+        ...intentCarries(pi),
+    }, { ...chargeDefaults(chargeId, amount, false, ctx.occurredAt), balance_transaction: null, payment_method_details: paymentMethodDetails(ctx, pi.payment_method) ?? null }, { operation: 'charge.succeeded' });
+    return chargeId;
+}
+/**
+ * An intent an invoice collects through succeeded (the default_incomplete subscription flow: create
+ * now, confirm client-side): its invoice is paid and, when it is a subscription's first, the
+ * subscription leaves incomplete for active. Both are moves the invoice and subscription machines
+ * declare under the confirming operation. No-op when the intent names no invoice, or the invoice is
+ * already paid (a duplicate confirm) or void (voiding ends what it collects).
+ */
+export async function payInvoiceOf(ctx, pi, operationId, actor) {
+    const invoiceId = typeof pi.invoice === 'string' ? pi.invoice : undefined;
+    const invoice = invoiceId ? ctx.get('invoice', invoiceId) : undefined;
+    if (!invoiceId || !invoice || invoice.status === 'paid' || invoice.status === 'void')
+        return;
+    if (ctx.legal('invoice', 'status', operationId, invoice.status, 'paid', invoiceId, actor))
+        return;
+    const amount = Number(invoice.total ?? invoice.amount_due) || 0;
+    // `invoice.pay` is the event the standalone pay action sends: invoice.paid
+    await ctx.write('invoice', invoiceId, {
+        status: 'paid', paid: true, amount_paid: amount, amount_remaining: 0,
+        status_transitions: { ...(invoice.status_transitions ?? {}), paid_at: nowUnix(ctx.occurredAt) },
+    }, 'invoice.pay');
+    const subId = typeof invoice.subscription === 'string' ? invoice.subscription : undefined;
+    const sub = subId ? ctx.get('subscription', subId) : undefined;
+    if (subId && sub && sub.status === 'incomplete' && !ctx.legal('subscription', 'status', operationId, sub.status, 'active', subId, actor)) {
+        await ctx.write('subscription', subId, { status: 'active' }, 'subscription.update');
+    }
+}
+/** The intent the path names, and the machine's refusal when this operation may not move it. */
+export function paymentIntentsLoad(ctx, operationId) {
+    const pi = ctx.id ? ctx.get(PI, ctx.id) : undefined;
+    if (!pi)
+        return { answer: ctx.notFound(PI, String(ctx.id)) };
+    const refusal = ctx.legal(PI, 'status', operationId, pi.status);
+    return refusal ? { answer: ctx.refuse(refusal) } : { pi };
+}
+/** The type of the payment method an intent is paid with: its PaymentMethod's, or a documented test name's (pm_card_*,
+ *  tok_* a card; pm_usBankAccount_* a US bank account), else unknown. */
+export function methodType(ctx, method) {
+    if (typeof method !== 'string' || !method)
+        return undefined;
+    const row = ctx.get('payment_method', method);
+    if (row)
+        return typeof row.type === 'string' ? row.type : undefined;
+    if (/^pm_us_?bank_?account/i.test(method))
+        return 'us_bank_account';
+    if (/^(pm_card_|tok_)/.test(method))
+        return 'card';
+    return undefined;
+}
+/** A confirm with a payment method of a type the intent's caller did not allow, refused as Stripe refuses it: "The
+ *  PaymentMethod provided (card_present) is not allowed for this PaymentIntent. Please attach a PaymentMethod of one of
+ *  the following types: card. Alternatively, update the allowed payment_method_types for this PaymentIntent to include
+ *  "card_present"" (a real answer quoted in github.com/stripe/stripe-terminal-react-native/issues/745, an intent made
+ *  with payment_method_types ['card']). Only a list the caller gave restricts: without one Stripe offers the methods
+ *  the account enables, which the twin does not model. Where the evidence stops: that answer's code is not quoted; the
+ *  twin answers payment_intent_invalid_parameter ("One or more provided parameters wasn't allowed for the given
+ *  operation on the PaymentIntent", docs.stripe.com/error-codes), param payment_method. */
+export function methodNotAllowed(ctx, existing, params) {
+    const types = Array.isArray(params.payment_method_types) ? params.payment_method_types.map(String)
+        : Array.isArray(params.allowed_payment_method_types) ? params.allowed_payment_method_types.map(String)
+            : typesGiven(ctx, String(existing.id)) && Array.isArray(existing.payment_method_types) ? existing.payment_method_types.map(String) : undefined;
+    if (!types)
+        return undefined;
+    const type = methodType(ctx, params.payment_method ?? existing.payment_method);
+    if (!type || types.includes(type))
+        return undefined;
+    return ctx.refuse({ status: 400, code: 'payment_intent_invalid_parameter', param: 'payment_method', message: `The PaymentMethod provided (${type}) is not allowed for this PaymentIntent. Please attach a PaymentMethod of one of the following types: ${types.join(', ')}. Alternatively, update the allowed payment_method_types for this PaymentIntent to include "${type}"` });
+}
+/** Confirm an intent the confirm machine allows to move: the confirm action, and a create with `confirm=true`. */
+export async function confirmIntent(ctx, existing, params) {
+    const id = String(existing.id);
+    // a payment names a mandate only an active one authorizes: an inactive mandate "was rejected, revoked, or previously
+    // used, and may not be used to initiate future payments" (docs.stripe.com/api/mandates/object), refused as
+    // payment_intent_mandate_invalid, "The provided mandate is invalid and can't be used for the payment intent"
+    // (docs.stripe.com/error-codes)
+    const named = typeof params.mandate === 'string' ? params.mandate : typeof existing.mandate === 'string' ? existing.mandate : undefined;
+    if (named && ctx.get('mandate', named)?.status !== 'active')
+        return fail(ctx, 'The provided mandate is invalid and can\'t be used for the payment intent.', 400, 'payment_intent_mandate_invalid');
+    const notAllowed = methodNotAllowed(ctx, existing, params);
+    if (notAllowed)
+        return notAllowed;
+    // a declining test card leaves the intent needing a payment method, with the error on it and a 402
+    const decline = declineFor(finder(ctx), params, existing);
+    if (decline) {
+        // Stripe records the attempt: a failed charge the intent's latest_charge names, the declined card on
+        // last_payment_error (a test name made a real PaymentMethod), and no payment_method left on the intent
+        // (docs.stripe.com/payments/paymentintents/lifecycle, docs.stripe.com/declines)
+        const ref = params.payment_method ?? existing.payment_method;
+        let pmId = typeof ref === 'string' ? ref : undefined;
+        if (pmId && !ctx.get('payment_method', pmId) && pmId.startsWith('pm_card_'))
+            pmId = String((await materializeTestMethod(ctx, pmId, typeof existing.customer === 'string' ? existing.customer : null)).id);
+        const pm = pmId ? ctx.get('payment_method', pmId) : undefined;
+        const amount = Number(params.amount ?? existing.amount) || 0;
+        const chargeId = ctx.mint('charge');
+        await created(ctx, 'charge', {
+            id: chargeId, amount, currency: existing.currency ?? 'usd', payment_intent: id,
+            ...(typeof existing.customer === 'string' ? { customer: existing.customer } : {}),
+            ...(pmId ? { payment_method: pmId } : {}),
+            ...intentCarries({ ...existing, ...params }),
+        }, {
+            ...chargeDefaults(chargeId, amount, false, ctx.occurredAt), status: 'failed', paid: false, captured: false, capture_before: null,
+            failure_code: decline.code, failure_message: decline.message, balance_transaction: null,
+            outcome: { type: 'issuer_declined', network_status: 'declined_by_network', reason: decline.decline_code ?? decline.code, risk_level: 'normal', seller_message: 'The bank did not return any further details with this decline.' },
+            payment_method_details: pmId ? paymentMethodDetails(ctx, pmId) ?? null : null,
+        }, { operation: 'charge.failed' }); // "Occurs whenever a failed charge attempt occurs." (docs.stripe.com/api/events/types)
+        const { payment_method: _pm, ...rest } = params;
+        const last_payment_error = { type: 'card_error', code: decline.code, ...(decline.decline_code ? { decline_code: decline.decline_code } : {}), message: decline.message, param: 'card', charge: chargeId, payment_method: pm ?? null };
+        const failed = await ctx.write(PI, id, { ...rest, payment_method: null, latest_charge: chargeId, status: 'requires_payment_method', last_payment_error }, 'payment_intent.payment_failed');
+        return paymentIntentsSend(ctx, cardError(decline, { payment_intent: failed, charge: chargeId }));
+    }
+    // a bank debit that needs micro-deposit verification waits in requires_action
+    const method = typeof params.payment_method === 'string' ? params.payment_method : typeof existing.payment_method === 'string' ? existing.payment_method : undefined;
+    // a bank transfer is paid from the customer's cash balance, or waits for the transfer (fundFromCashBalance)
+    if (method && ctx.get('payment_method', method)?.type === 'customer_balance')
+        return ctx.reply(ctx.expand(PI, await fundFromCashBalance(ctx, { ...existing, ...params }, params)));
+    if (requiresMicrodeposits(params, existing) || microdepositsAsked(ctx, params, existing, method)) {
+        return ctx.reply(ctx.expand(PI, await ctx.write(PI, id, { ...params, status: 'requires_action', next_action: microdepositsNextAction(), last_payment_error: null }, 'payment_intent.requires_action')));
+    }
+    // 3DS: the first confirm asks for authentication; a second one completes it
+    if (existing.status !== 'requires_action' && requiresAuthentication(params, existing)) {
+        return ctx.reply(ctx.expand(PI, await ctx.write(PI, id, { ...params, status: 'requires_action', next_action: threeDsNextAction(), last_payment_error: null }, 'payment_intent.requires_action')));
+    }
+    // manual capture authorizes and waits for /capture: the authorization is a charge, succeeded and not captured, the
+    // intent's latest_charge
+    if ((params.capture_method ?? existing.capture_method) === 'manual') {
+        const amount = Number(existing.amount ?? params.amount ?? 0);
+        const charge = await authorizeCharge(ctx, id, { ...existing, ...params }, amount);
+        return ctx.reply(ctx.expand(PI, await ctx.write(PI, id, { ...params, status: 'requires_capture', amount_capturable: amount, amount_received: 0, next_action: null, last_payment_error: null, latest_charge: charge }, 'payment_intent.amount_capturable_updated')));
+    }
+    // a bank debit is submitted and settles later (beginBankDebit)
+    if (isBankDebit(ctx, method))
+        return ctx.reply(ctx.expand(PI, await beginBankDebit(ctx, id, params)));
+    const amount = Number(existing.amount ?? params.amount ?? 0);
+    // a succeeded intent has a Charge, and latest_charge names it: what a refund of it lands on
+    const charge = await mintCharge(ctx, id, { ...existing, ...params }, amount);
+    const body = await ctx.write(PI, id, { ...params, status: 'succeeded', amount_received: amount, next_action: null, last_payment_error: null, latest_charge: charge }, 'payment_intent.confirm');
+    await payInvoiceOf(ctx, body, 'PostPaymentIntentsIntentConfirm');
+    return ctx.reply(ctx.expand(PI, body));
+}
+/** An increment that does not raise the authorization. */
+export function incrementTooSmall(ctx) {
+    return ctx.refuse({ status: 400, code: 'parameter_invalid_integer', message: 'The new amount must be greater than the current amount of the PaymentIntent.' });
+}
+// ── a bank debit is submitted, and settles ──
+//
+// ACH Direct Debit "is a delayed notification payment method ... The PaymentIntent you create initially has a status
+// of `processing`. After the payment has succeeded, the PaymentIntent status is updated from `processing` to
+// `succeeded`"; verification by micro-deposits returns "a status of `processing`, and sends a payment_intent.processing
+// webhook event"; and, the twin being a test-mode account: "Test transactions settle instantly and are added to your
+// available test balance. This behavior differs from live mode, where transactions can take multiple days to settle"
+// (docs.stripe.com/payments/ach-direct-debit/accept-a-payment?payment-ui=direct-api). A confirm answers processing; the
+// debit succeeds at that same instant of the World's clock, caught up before the next request is answered (as
+// renewals and payouts are). The page's test accounts give each debit its outcome: pm_usBankAccount_success
+// (000123456789) "The payment succeeds"; pm_usBankAccount_processing (000000000009) "The payment stays in processing
+// indefinitely". Where the documentation stops and the twin decides: its Charge is made when it succeeds (the page
+// names none while it processes); the failing test accounts (closed, no account, insufficient funds, debit not
+// authorized, invalid currency, dispute, weekly limit, Radar block) are not modelled and succeed.
+/** Whether the method an intent is confirmed with is a bank debit: a us_bank_account PaymentMethod, or one of Stripe's
+ *  test bank accounts named as one (pm_usBankAccount_*, pm_us_bank_account). */
+export function isBankDebit(ctx, method) {
+    if (typeof method !== 'string')
+        return false;
+    return ctx.get('payment_method', method)?.type === 'us_bank_account' || /^pm_us_?bank_?account/i.test(method);
+}
+/** Whether a bank debit stays processing: the page's pm_usBankAccount_processing, or its account 000000000009. */
+export function staysProcessing(ctx, method) {
+    if (method === 'pm_usBankAccount_processing')
+        return true;
+    const bank = typeof method === 'string' ? ctx.get('payment_method', method)?.us_bank_account : undefined;
+    return bank?.last4 === '0009';
+}
+/** A bank debit submitted: the intent processes, nothing received yet, sent as payment_intent.processing; it is due to
+ *  settle at this instant, unless its test account stays processing. */
+export async function beginBankDebit(ctx, id, fields) {
+    const method = fields.payment_method ?? ctx.get(PI, id)?.payment_method;
+    return ctx.write(PI, id, { ...fields, status: 'processing', amount_received: 0, next_action: null, last_payment_error: null, _settles_at: staysProcessing(ctx, method) ? null : Number(nowUnix(ctx.occurredAt)) }, 'payment_intent.processing');
+}
+/** Time's settling of bank debits, caught up to the World's clock: each processing debit whose moment has come succeeds
+ *  then, its Charge made (naming the mandate it ran under) and the invoice it collects for paid. */
+export async function settleBankDebits(ctx) {
+    const now = Number(nowUnix(ctx.occurredAt));
+    const due = ctx.rowsRaw(PI).filter((p) => p.status === 'processing' && typeof p._settles_at === 'number' && p._settles_at <= now).sort((a, b) => Number(a._settles_at) - Number(b._settles_at));
+    for (const pi of due) {
+        const id = String(pi.id);
+        const c = await at_(ctx)(Number(pi._settles_at));
+        c.legal(PI, 'status', ctx.call.operation.id, 'processing', 'succeeded', id, 'vendor');
+        const amount = Number(pi.amount) || 0;
+        const charge = await mintCharge(c, id, pi, amount);
+        // the charge names the mandate its bank debit ran under (payment_method_details.us_bank_account.mandate)
+        const details = (c.get('charge', charge)?.payment_method_details ?? null);
+        const kind = typeof details?.type === 'string' ? details.type : undefined;
+        if (details && kind && typeof pi.mandate === 'string')
+            await c.write('charge', charge, { payment_method_details: { ...details, [kind]: { ...(details[kind] ?? {}), mandate: pi.mandate } } }, 'charge.mandate');
+        const body = await c.write(PI, id, { status: 'succeeded', amount_received: amount, latest_charge: charge, _settles_at: null }, 'payment_intent.succeeded');
+        // a single-use mandate is spent by its payment: "previously used, and may not be used to initiate future payments"
+        const used = typeof pi.mandate === 'string' ? c.get('mandate', pi.mandate) : undefined;
+        if (used && used.type === 'single_use' && used.status === 'active') {
+            c.legal('mandate', 'status', ctx.call.operation.id, 'active', 'inactive', String(used.id), 'vendor');
+            await c.write('mandate', String(used.id), { status: 'inactive' }, 'mandate.updated');
+        }
+        await payInvoiceOf(c, body, ctx.call.operation.id, 'vendor');
+    }
+}
+/** A customer_balance intent funded from the customer's cash balance: paid when the balance covers it ("If the customer
+ *  already has a balance high enough to cover the payment amount, the PaymentIntent immediately succeeds"), else
+ *  waiting for a transfer: "If the customer balance isn’t high enough to cover the request amount, the PaymentIntent
+ *  shows a requires_action status ... next_action ... display_bank_transfer_instructions" with the amount_remaining
+ *  (docs.stripe.com/payments/bank-transfers/accept-a-payment). Answers the intent as written. */
+export async function fundFromCashBalance(ctx, pi, fields = {}) {
+    const customer = typeof pi.customer === 'string' ? pi.customer : '';
+    const currency = String(pi.currency ?? 'usd');
+    // what the customer's funded cash balance holds in this currency, from its ledger
+    const available = customer ? ctx.rows('customer_cash_balance_transaction').filter((t) => t.customer === customer && String(t.currency) === currency).reduce((n, t) => n + (Number(t.net_amount) || 0), 0) : 0;
+    const amount = Number(pi.amount) || 0;
+    if (available >= amount) {
+        // the balance pays the intent: its ledger records what was applied
+        await created(ctx, 'customer_cash_balance_transaction', { customer }, { currency, type: 'applied_to_payment', net_amount: -amount, ending_balance: available - amount, applied_to_payment: { payment_intent: String(pi.id) }, livemode: false });
+        const charge = await mintCharge(ctx, String(pi.id), { ...pi, ...fields }, amount);
+        return ctx.write(PI, String(pi.id), { ...fields, status: 'succeeded', next_action: null, amount_received: amount, last_payment_error: null, latest_charge: charge }, 'payment_intent.succeeded');
+    }
+    // not enough yet: the intent waits for the rest, with the instructions to send it
+    const next_action = { type: 'display_bank_transfer_instructions', display_bank_transfer_instructions: { amount_remaining: amount - available, currency, type: 'us_bank_transfer' } };
+    return ctx.write(PI, String(pi.id), { ...fields, status: 'requires_action', next_action }, 'payment_intent.requires_action');
+}
+/** Whether a charge's funds go straight to the available balance: a bypass card as a raw number, a test name (pm_card_*
+ *  or tok_*), or a stored PaymentMethod made from one (which records it as what follows its success, after-payment.ts);
+ *  or a US bank account, stored or one of Stripe's test bank accounts named as one (pm_usBankAccount_*). */
+export function bypassesPending(ctx, card) {
+    if (!card)
+        return false;
+    const stored = ctx.row('payment_method', card);
+    // the row carries what the method recorded; its type is the vendor object's (ctx.get), not the row's envelope
+    if (stored)
+        return stored._afterSuccess === 'available' || ctx.get('payment_method', card)?.type === 'us_bank_account';
+    if (/^pm_us_?bank_?account/i.test(card))
+        return true;
+    return BYPASS_NUMBERS.has(card.replace(/\D/g, '')) || card.replace(/^tok_/, 'pm_card_') in BYPASS_PENDING_CARDS;
+}
+/** The connected account a request acts for, or undefined for the platform. */
+export const actingAccount = (ctx) => ctx.call.request.headers.get('stripe-account') ?? undefined;
+/** A ledger entry on an account's balance: the acting account's unless one is named (null names the platform). */
+export async function write(ctx, fields, account = actingAccount(ctx)) {
+    // a credit available at once waits for the drain's balance.available (settleDueEntries)
+    const unsent = (fields.status ?? 'available') === 'available' && Number(fields.net) > 0 ? { [UNSENT]: true } : {};
+    const bt = await created(ctx, BT, {}, { status: 'available', fee_details: [], description: null, exchange_rate: null, balance_type: 'payments', ...fields, ...unsent, ...(account ? { _account: account } : {}) });
+    return String(bt.id);
+}
+/** A captured charge's credit: its amount less the fee, pending two days unless the card bypasses the pending
+ *  balance (bypassesPending), when it is due at once. The
+ *  caller mints the charge's id first and stores the returned id as the charge's balance_transaction. */
+export async function settleCharge(ctx, chargeId, amount, currency, card) {
+    const now = Number(nowUnix(ctx.occurredAt));
+    const fee = feeOf(amount);
+    const atOnce = bypassesPending(ctx, card);
+    const id = await write(ctx, {
+        amount, currency, fee, net: amount - fee, type: 'charge', reporting_category: 'charge', source: chargeId,
+        ...(atOnce ? { status: 'available', available_on: now } : { status: 'pending', available_on: now + 2 * DAY }),
+        fee_details: fee ? [{ amount: fee, application: null, currency, description: 'Stripe processing fees', type: 'stripe_fee' }] : [],
+    });
+    return id;
+}
+/** A refund's debit, at once, on the acting account's balance unless one is named (null names the platform). */
+export async function settleRefund(ctx, refundId, amount, currency, account = actingAccount(ctx)) {
+    return write(ctx, { amount: -amount, currency, fee: 0, net: -amount, type: 'refund', reporting_category: 'refund', source: refundId, available_on: Number(nowUnix(ctx.occurredAt)) }, account);
+}
+/** What an account had available in a currency at a moment: every entry of its payments balance whose funds had come
+ *  due by then. */
+export function availableAt(ctx, account, currency, at) {
+    let sum = 0;
+    for (const t of ctx.rowsRaw(BT)) {
+        if (!onAccount(t, account) || t.balance_type === 'issuing' || String(t.currency ?? 'usd') !== currency)
+            continue;
+        const due = Number(t.available_on ?? t.created);
+        if (Number.isFinite(due) && due <= at)
+            sum += Number(t.net ?? 0);
+    }
+    return sum;
+}
+/** The moments after `from` and up to `until` when funds of an account came due, in order: when a held refund can
+ *  next be covered. */
+export function fundsDueBetween(ctx, account, currency, from, until) {
+    const times = ctx.rowsRaw(BT).filter((t) => onAccount(t, account) && String(t.currency ?? 'usd') === currency).map((t) => Number(t.available_on ?? t.created)).filter((d) => Number.isFinite(d) && d > from && d <= until);
+    return [...new Set(times)].sort((a, b) => a - b);
+}
+/** A dispute's debit, at once: the disputed amount and the dispute fee (the twin's 1500 cents, Stripe's US $15). */
+export async function settleDispute(ctx, disputeId, amount, currency) {
+    const fee = 1500;
+    return write(ctx, {
+        amount: -amount, currency, fee, net: -amount - fee, type: 'adjustment', reporting_category: 'dispute', source: disputeId, available_on: Number(nowUnix(ctx.occurredAt)),
+        fee_details: [{ amount: fee, application: null, currency, description: 'Dispute fee', type: 'stripe_fee' }],
+    });
+}
+/** A won dispute's credit, at once: the disputed amount returned (docs.stripe.com/disputes/how-disputes-work). Where the
+ *  documentation stops and the twin decides: the dispute fee is not returned. */
+export async function settleDisputeWon(ctx, disputeId, amount, currency) {
+    return write(ctx, { amount, currency, fee: 0, net: amount, type: 'adjustment', reporting_category: 'dispute_reversal', source: disputeId, available_on: Number(nowUnix(ctx.occurredAt)) });
+}
+/** An account's ledger entries an automatic payout has not yet paid out: every entry on its payments balance that no
+ *  automatic payout took (the automatic payouts' own debits excluded), as stored. */
+export function unpaidEntries(ctx, account) {
+    const automatic = new Set(ctx.rowsRaw('payout').filter((p) => p.automatic === true).map((p) => p.id));
+    return ctx.rowsRaw(BT).filter((t) => onAccount(t, account) && t.balance_type !== 'issuing' && !t._payout && !automatic.has(t.source));
+}
+/** An automatic payout's debit at `at`, and the entries it pays out marked with it, so the ledger lists them under
+ *  the payout (docs.stripe.com/api/balance_transactions/list#balance_transaction_list-payout). */
+export async function settleAutomaticPayout(ctx, payoutId, amount, currency, account, at, entries) {
+    for (const t of entries)
+        await ctx.write(BT, String(t.id), { _payout: payoutId }, 'balance_transaction.paid_out');
+    return write(ctx, { amount: -amount, currency, fee: 0, net: -amount, type: 'payout', reporting_category: 'payout', source: payoutId, available_on: at, _payout: payoutId }, account ?? null);
+}
+/** A payout's debit (negative) or a cancellation's or reversal's credit (positive), at once, on the payout's account. */
+export async function settlePayout(ctx, payoutId, amount, currency, account = actingAccount(ctx)) {
+    const type = amount < 0 ? 'payout' : 'payout_cancel';
+    return write(ctx, { amount, currency, fee: 0, net: amount, type, reporting_category: type === 'payout' ? 'payout' : 'payout_reversal', source: payoutId, available_on: Number(nowUnix(ctx.occurredAt)) }, account);
+}
+/** A transfer's two entries: out of the platform's balance at once, into the destination's when `fromCharge` (its
+ *  charge's funds' availability) comes (a plain transfer, with no `fromCharge`, moves funds available already).
+ *  Answers the platform's entry. */
+export async function settleTransfer(ctx, transferId, amount, currency, destination, fromCharge, fromPending = false) {
+    const availableOn = fromCharge ?? Number(nowUnix(ctx.occurredAt));
+    const settled = availableOn <= Number(nowUnix(ctx.occurredAt));
+    // a transfer from a charge's pending funds (source_transaction) leaves the platform when they arrive, not before
+    const platform = await write(ctx, { amount: -amount, currency, fee: 0, net: -amount, type: 'transfer', reporting_category: 'transfer', source: transferId, ...(fromPending ? { status: settled ? 'available' : 'pending', available_on: availableOn } : { available_on: Number(nowUnix(ctx.occurredAt)) }) }, null);
+    await write(ctx, { amount, currency, fee: 0, net: amount, type: 'payment', reporting_category: 'charge', source: transferId, status: settled ? 'available' : 'pending', available_on: availableOn }, destination);
+    return platform;
+}
+/** A transfer reversal's two entries: back into the platform's balance, out of the destination's. */
+export async function settleTransferReversal(ctx, reversalId, amount, currency, destination) {
+    const platform = await write(ctx, { amount, currency, fee: 0, net: amount, type: 'transfer_refund', reporting_category: 'transfer_reversal', source: reversalId, available_on: Number(nowUnix(ctx.occurredAt)) }, null);
+    await write(ctx, { amount: -amount, currency, fee: 0, net: -amount, type: 'payment_refund', reporting_category: 'refund', source: reversalId, available_on: Number(nowUnix(ctx.occurredAt)) }, destination);
+    return platform;
+}
+/** A direct charge's application fee: out of the connected account's balance, into the platform's. */
+export async function settleApplicationFee(ctx, feeId, amount, currency, account) {
+    await write(ctx, { amount: -amount, currency, fee: 0, net: -amount, type: 'application_fee', reporting_category: 'platform_earning', source: feeId, available_on: Number(nowUnix(ctx.occurredAt)) }, account);
+    return write(ctx, { amount, currency, fee: 0, net: amount, type: 'application_fee', reporting_category: 'platform_earning', source: feeId, available_on: Number(nowUnix(ctx.occurredAt)) }, null);
+}
+/** A top-up's credit, to the payments balance or, with `destination_balance=issuing`, to Issuing's
+ *  (docs.stripe.com/issuing/funding/balance). Where the documentation stops and the twin decides: a test-mode top-up
+ *  is available at once. */
+export async function settleTopup(ctx, topupId, amount, currency, destination) {
+    const issuing = destination === 'issuing';
+    return write(ctx, { amount, currency, fee: 0, net: amount, type: 'topup', reporting_category: 'topup', source: topupId, available_on: Number(nowUnix(ctx.occurredAt)), balance_type: issuing ? 'issuing' : 'payments' });
+}
+/** Time's settlements, written: each entry on the acting account's balance whose funds came due by the World's clock
+ *  moves pending → available (the clock's move the machine allows), so a settlement is recorded once. A read already
+ *  sees it (asOf); the record is what lets Stripe's balance.available be sent once (./front.ts, the drain).
+ *  Funds that were available at once and not yet sent are taken too, and marked sent. Answers the entries taken. */
+export async function settleDueEntries(ctx, account = actingAccount(ctx)) {
+    const now = Number(nowUnix(ctx.occurredAt));
+    const moved = [];
+    for (const t of ctx.rowsRaw(BT)) {
+        if (!onAccount(t, account))
+            continue;
+        if (t.status === 'available' && t[UNSENT] === true) {
+            await ctx.write(BT, String(t.id), { [UNSENT]: false }, 'balance_transaction.available_sent');
+            moved.push(t);
+            continue;
+        }
+        if (t.status !== 'pending' || !(Number(t.available_on) <= now))
+            continue;
+        if (ctx.legal(BT, 'status', ctx.call.operation.id, 'pending', 'available', String(t.id), 'time'))
+            continue;
+        await ctx.write(BT, String(t.id), { status: 'available' }, 'balance_transaction.available');
+        moved.push(t);
+    }
+    return moved;
+}
+/** An account's balance, by currency: what the clock has made available, what is still pending, and Issuing's own. */
+export function balanceOf(ctx, account = actingAccount(ctx)) {
+    const available = new Map();
+    const pending = new Map();
+    const issuing = new Map();
+    for (const raw of ctx.rowsRaw(BT)) {
+        if (!onAccount(raw, account))
+            continue;
+        const t = commonAsOf(ctx, raw);
+        const cur = String(t.currency ?? 'usd');
+        const net = Number(t.net ?? 0);
+        const bucket = t.balance_type === 'issuing' ? issuing : t.status === 'available' ? available : pending;
+        bucket.set(cur, (bucket.get(cur) ?? 0) + net);
+    }
+    return { available, pending, issuing };
+}
+/** balance_insufficient when a payout or transfer would take more than the account has available in its currency. */
+export function refusePayout(ctx, amount, currency, account = actingAccount(ctx)) {
+    const have = balanceOf(ctx, account).available.get(currency) ?? 0;
+    if (amount <= have)
+        return undefined;
+    return fail(ctx, "The transfer or payout couldn't be completed because the associated account doesn't have a sufficient balance available.", 400, 'balance_insufficient');
+}
+/** The ids of the ledger entries on the acting account's balance. */
+export const mine = (ctx) => new Set(ctx.rowsRaw(BT).filter((t) => onAccount(t, actingAccount(ctx))).map((t) => t.id));
+export const chargeMissing = (ctx, id) => fail(ctx, `No such charge: '${id}'`, 404, 'resource_missing');
+/** Every egress of a charge carries its refunds, derived from the refund rows in list order. */
+export function chargeBody(ctx, c) {
+    const data = newest(ctx, 'refund').filter((r) => r.charge === c.id);
+    return { ...c, refunds: { object: 'list', data, has_more: false, total_count: data.length, url: `/v1/charges/${String(c.id)}/refunds` } };
+}
+/** A Charges-API charge a declining test card refuses: a 402 card_error naming the failed charge Stripe records for the
+ *  attempt (docs.stripe.com/declines). */
+export async function declinedCharge(ctx, decline) {
+    const params = ctx.params;
+    const failedId = ctx.mint('charge');
+    const amount = Number(params.amount) || 0;
+    await created(ctx, 'charge', { ...withoutCard(params), id: failedId }, {
+        ...chargeDefaults(failedId, amount, false, ctx.occurredAt), status: 'failed', paid: false, captured: false, capture_before: null,
+        failure_code: decline.code, failure_message: decline.message, balance_transaction: null,
+        outcome: { type: 'issuer_declined', network_status: 'declined_by_network', reason: decline.decline_code ?? decline.code, risk_level: 'normal', seller_message: 'The bank did not return any further details with this decline.' },
+        payment_method_details: paymentMethodDetails(ctx, params.payment_method ?? params.source ?? params.card) ?? null,
+    }, { operation: 'charge.failed' });
+    return send(ctx, cardError(decline, { charge: failedId }));
+}
+/** A charge's fraud report: "user_report … Assessments reported by you. If set, possible values of are `safe` and
+ *  `fraudulent`" (docs.stripe.com/api/charges/object, fraud_details). */
+export function fraudReport(ctx, existing, fd) {
+    const report = String(fd.user_report);
+    if (report !== 'safe' && report !== 'fraudulent')
+        return fail(ctx, "Invalid fraud_details[user_report]: must be 'safe' or 'fraudulent'.", 400, 'parameter_invalid_string_enum');
+    const prior = existing.fraud_details && typeof existing.fraud_details === 'object' ? existing.fraud_details : {};
+    return { user_report: report, stripe_report: prior.stripe_report ?? null };
+}
+/** A capture=false charge refunded while uncaptured: its authorization is released by the refund, as it would be
+ *  "automatically refunded if uncaptured" (spec/openapi.json.gz, `capture_before`). The charge stays uncaptured and
+ *  becomes refunded in full, a Refund records the release, and no money moves: none was ever received. Written as
+ *  charge.refunded. Where the documentation stops and the twin decides: Stripe's basil change ("Partially capturing or
+ *  canceling payments no longer creates a Refund", docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-partial-
+ *  capture-and-payment-cancellation-flow) names partial capture and cancellation, not a refund asked for, so a refund
+ *  still makes one; its reason is null and it has no balance transaction. Answers the Refund. */
+export async function releaseAuthorization(ctx, ch, operationId, given = {}) {
+    const id = String(ch.id);
+    const full = Number(ch.amount) || 0;
+    if (ch.refunded !== true)
+        ctx.legal('charge', 'refunded', operationId, 'false', 'true', id);
+    const refund = await created(ctx, 'refund', { ...given, charge: id, amount: full - (Number(ch.amount_refunded) || 0), currency: String(ch.currency ?? 'usd') }, {
+        status: 'succeeded', metadata: {}, reason: null, receipt_number: null,
+        balance_transaction: null, source_transfer_reversal: null, transfer_reversal: null, ...refundDestination(ch, 'reversal'),
+        ...(typeof ch.payment_intent === 'string' ? { payment_intent: ch.payment_intent } : {}),
+    });
+    await ctx.write('charge', id, { amount_refunded: full, refunded: true }, 'charge.refunded');
+    return refund;
+}
+/** A PaymentIntent's authorization released by its cancel: "For PaymentIntents with a `status` of `requires_capture`, the
+ *  remaining `amount_capturable` is automatically refunded" (docs.stripe.com/api/payment_intents/cancel), and since basil
+ *  a cancellation makes no Refund: "`amount_captured` will be 0 instead of `nil` in payment cancellation flows",
+ *  "`amount_refunded` will no longer be updated by these actions", "`refunded` will no longer be `true` for payment
+ *  cancellation flows", and no charge.refunded is sent (docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-
+ *  partial-capture-and-payment-cancellation-flow). The charge stays uncaptured; nothing is written as an event. */
+export async function cancelAuthorization(ctx, ch) {
+    return ctx.write('charge', String(ch.id), { amount_captured: 0 }, 'charge.authorization_released');
+}
+/** An authorized charge captured, by the charge's capture or its PaymentIntent's: what is captured credits the balance.
+ *  Written as charge.captured, "Occurs whenever a previously uncaptured charge is captured" (docs.stripe.com/api/events/types).
+ *  A partial capture releases the rest with no Refund and leaves amount_refunded and refunded as they were: "The following
+ *  flows no longer result in a `Refund` object created and linked to the payment: Partial capture", "`amount_refunded`
+ *  will no longer be updated by these actions", and "There will only be a single balance transaction for partial captures"
+ *  (docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-partial-capture-and-payment-cancellation-flow).
+ *  The caller has asked the machine whether it may capture. */
+export async function captureAuthorization(ctx, ch, toCapture, _operationId) {
+    const id = String(ch.id);
+    const bt = toCapture > 0 ? await settleCharge(ctx, id, toCapture, String(ch.currency ?? 'usd'), String(ch.source ?? ch.payment_method ?? '')) : null;
+    return ctx.write('charge', id, { captured: true, amount_captured: toCapture, balance_transaction: bt }, 'charge.captured');
+}
+export const chargeRefund = (ctx) => {
+    if (!ctx.get('charge', at(ctx, 'charge')))
+        return chargeMissing(ctx, at(ctx, 'charge'));
+    const r = ctx.get('refund', at(ctx, 'refund'));
+    return r && r.charge === at(ctx, 'charge') ? r : fail(ctx, `No such refund: '${at(ctx, 'refund')}'`, 404, 'resource_missing');
+};
+export const subMissing = (ctx, id) => fail(ctx, `No such subscription: '${id}'`, 404, 'resource_missing');
+/** A coupon that replaces the subscription's discount, or an empty one that clears it (docs.stripe.com/api/subscriptions/update#update_subscription-discounts). */
+export function replacedDiscounts(ctx, couponId, sub) {
+    if (couponId === '')
+        return [];
+    const coupon = ctx.get('coupon', couponId);
+    return coupon ? [buildDiscount(coupon, String(sub.customer ?? ''), Number(nowUnix(ctx.occurredAt)), { subscription: String(sub.id) })] : fail(ctx, `No such coupon: '${couponId}'`, 400, 'resource_missing');
+}
+/** A `trial_end` Stripe refuses: the parameter is `"now" | timestamp` (docs.stripe.com/api/subscriptions/update), and a
+ *  timestamp that is not in the future answers "Invalid timestamp: must be an integer Unix timestamp in the future."
+ *  (Stripe's own message, as its SDKs' users report it: github.com/stripe/stripe-dotnet/issues/805,
+ *  github.com/stripe/stripe-ruby/issues/682). Where the documentation stops and the twin decides: a value that is no
+ *  number at all, and one more than two years on, answer that same message. */
+export function trialEndRefused(ctx, value, now) {
+    const t = typeof value === 'number' ? value : typeof value === 'string' && /^\d+$/.test(value.trim()) ? Number(value) : NaN;
+    return value === undefined || value === 'now' || (Number.isInteger(t) && t > now && t <= now + MAX_TRIAL) ? undefined : invalidTrialEnd(ctx);
+}
+export function invalidTrialEnd(ctx) {
+    return ctx.refuse({ status: 400, param: 'trial_end', message: 'Invalid timestamp: must be an integer Unix timestamp in the future.' });
+}
+/** An update's `trial_end` on the subscription, into `fields`.
+ *
+ *  `now` on a trialing subscription ends its trial at once: "The special value `now` can be provided to end the customer's
+ *  trial immediately" (docs.stripe.com/api/subscriptions/update#update_subscription-trial_end; the trials guide's "To end a
+ *  trial early … setting the `trial_end` value to … **now** to end immediately", docs.stripe.com/billing/subscriptions/
+ *  trials/free-trials). The update resets the billing date and charges at once: "Switching prices does not normally change
+ *  the billing date or generate an immediate charge unless … A trial starts or ends. In these cases, we … immediately
+ *  charge the customer using the new price, and reset the billing date" (docs.stripe.com/api/subscriptions/update), and
+ *  "Stripe immediately attempts payment when a subscription's billing cycle anchor is reset … When billing is performed
+ *  immediately, but the required payment fails, the subscription change request succeeds and the subscription transitions
+ *  to `past_due`" (docs.stripe.com/billing/subscriptions/upgrade-downgrade#immediate-payment). So a new period starts now,
+ *  its invoice is made (`invoice.created`) and charged to the subscription's default payment method, else the
+ *  customer's (paid: `invoice.paid`, the subscription `active`; declined or none: the invoice open, `past_due`), and the
+ *  subscription's own write sends `customer.subscription.updated`. `payment_behavior` (the same page): `error_if_incomplete`
+ *  answers 402 and leaves the subscription as it was, `default_incomplete` leaves the invoice open without an attempt.
+ *
+ *  A future timestamp moves the trial's end, and the period and billing anchor with it: "The `billing_cycle_anchor` will be
+ *  updated to the `trial_end` value" (the same parameter); on a subscription out of its trial it starts a new one ("You can
+ *  add a new trial on a non-trialing subscription by updating the subscription while specifying trial_end", and for
+ *  classic billing mode "the `trial_start` field remains set to the start of the first trial", docs.stripe.com/billing/
+ *  subscriptions/trials/free-trials).
+ *
+ *  Where the documentation stops and the twin decides: the invoice's billing_reason is `subscription_update` ("A
+ *  subscription was updated", docs.stripe.com/api/invoices/object#invoice_object-billing_reason); `now` on a subscription
+ *  that is not trialing has no trial to end and changes nothing; the credit Stripe prorates for the unused time when a new
+ *  trial starts mid-period is not made (as `proration_behavior=none` would have it); `pending_if_incomplete` answers as
+ *  `allow_incomplete` (no pending update is modelled). Answers a refusal, or the invoice to collect once the subscription is written. */
+export async function applyTrialEnd(ctx, sub, fields, now) {
+    const value = ctx.params.trial_end;
+    delete fields.trial_end;
+    const id = String(sub.id);
+    if (value !== 'now' || sub.status !== 'trialing')
+        return value === 'now' ? undefined : movedTrial(sub, fields, Number(value), now);
+    // the period's invoice bills the items as this update leaves them, under its discount
+    const next = { ...sub, ...fields, items: ctx.get(SUB, id)?.items ?? sub.items };
+    const { interval, interval_count } = resolveSubscriptionBillingInterval((next.items?.data) ?? [], finder(ctx));
+    const period = { start: now, end: addBillingInterval(now, interval, interval_count) };
+    const invoice = await draftSubscriptionInvoice(ctx, next, { ...period, reason: 'subscription_update' });
+    Object.assign(fields, { trial_end: now, billing_cycle_anchor: now, current_period_start: period.start, current_period_end: period.end, latest_invoice: invoice });
+    const payer = trialPayer(ctx, sub);
+    return { invoice, ...(payer ? { payer } : {}), attempt: ctx.params.payment_behavior !== 'default_incomplete' };
+}
+/** What ending the trial charges: the update's own default payment method, else the subscription's, else its customer's. */
+export function trialPayer(ctx, sub) {
+    const given = ctx.params.default_payment_method;
+    return typeof given === 'string' && given ? given : payerOf(ctx, sub);
+}
+/** What an update's `trial_end` refuses before anything is written: a new trial the machine does not allow from the
+ *  subscription's status, or, under `error_if_incomplete`, ending a trial that cannot be paid at once ("If payment fails,
+ *  return an HTTP `402` status code and don't update the subscription", docs.stripe.com/api/subscriptions/update). */
+export function trialEndBlocked(ctx, sub, discounts) {
+    if (ctx.params.trial_end !== 'now')
+        return newTrialRefused(ctx, sub);
+    if (sub.status !== 'trialing')
+        return undefined;
+    const charge = trialEndCharge(ctx, sub, discounts);
+    if (ctx.params.payment_behavior === 'error_if_incomplete' && charge.due > 0 && !charge.pays)
+        return firstPaymentRefused(ctx, charge.declined);
+    // the move ending the trial makes (paid or nothing due: active; else past_due) is the machine's, asked before
+    // anything is written
+    const refused = ctx.legal(SUB, 'status', ctx.call.operation.id, 'trialing', charge.due <= 0 || charge.pays ? 'active' : 'past_due', String(sub.id));
+    return refused ? ctx.refuse(refused) : undefined;
+}
+/** A price named by id, or given as an object. */
+export function priceRow(ctx, price) {
+    return typeof price === 'string' ? ctx.get('price', price) : price && typeof price === 'object' ? price : undefined;
+}
+/** One period of the subscription's items as an update's `items` would leave them, before any discount: an entry naming
+ *  an item changes its price and quantity (a new price resets the quantity to 1 unless one is given) or deletes it, and
+ *  one naming none adds an item (applyItemChanges). */
+export function dueAfter(ctx, sub, entries) {
+    const lines = new Map();
+    for (const it of (sub.items?.data) ?? [])
+        lines.set(String(it.id), { price: priceRow(ctx, it.price), quantity: itemQuantity(it) });
+    entries.forEach((e, i) => entryAfter(ctx, lines, e, i));
+    return [...lines.values()].reduce((sum, l) => sum + priceAmount(l.price, l.quantity), 0);
+}
+/** One entry of an update's `items` on the lines it would leave (dueAfter). */
+export function entryAfter(ctx, lines, e, i) {
+    // an inline price bills as the Price inlinePrice makes of it
+    const d = e.price_data && typeof e.price_data === 'object' ? e.price_data : undefined;
+    const inline = d ? (d.unit_amount_decimal !== undefined ? { unit_amount_decimal: String(d.unit_amount_decimal) } : { unit_amount: Math.trunc(Number(d.unit_amount) || 0) }) : undefined;
+    const price = typeof e.price === 'string' && e.price ? priceRow(ctx, e.price) : inline;
+    const named = typeof e.id === 'string' && e.id;
+    const key = named ? String(e.id) : `new_${i}`;
+    // only a named item is deleted; an entry naming none adds one, as applyItemChanges does
+    if (named && asBool(e.deleted)) {
+        lines.delete(key);
+        return;
+    }
+    const was = lines.get(key);
+    const quantity = e.quantity !== undefined ? Math.max(0, Math.trunc(Number(e.quantity) || 0)) : price && was && price.id !== was.price?.id ? 1 : was?.quantity ?? 1;
+    lines.set(key, { price: price ?? was?.price, quantity });
+}
+/** A new trial on a subscription whose status the machine does not let start one. */
+export function newTrialRefused(ctx, sub) {
+    const refused = sub.status === 'trialing' ? undefined : ctx.legal(SUB, 'status', ctx.call.operation.id, sub.status, 'trialing', String(sub.id));
+    return refused ? ctx.refuse(refused) : undefined;
+}
+/** What ending the trial charges, judged before anything is written: the period of the items as this update leaves them
+ *  (dueAfter) under the discount it leaves, and whether the payer pays it (an attempt made, a payer, no decline). */
+export function trialEndCharge(ctx, sub, discounts) {
+    const subtotal = dueAfter(ctx, sub, subscriptionItemEntries(ctx.params.items));
+    // the discount the subscription carries after this update takes this invoice (renewals.ts draftSubscriptionInvoice)
+    const discount = (discounts ?? sub.discounts ?? [])[0];
+    const coupon = discount && typeof discount === 'object' ? discount.coupon : undefined;
+    const due = subtotal - (coupon ? applyCouponDiscount(subtotal, coupon) : 0);
+    const payer = trialPayer(ctx, sub);
+    const attempt = ctx.params.payment_behavior !== 'default_incomplete';
+    const declined = payer && attempt ? declineFor(finder(ctx), { payment_method: payer }) : undefined;
+    return { due, pays: attempt && !!payer && !declined, ...(declined ? { declined } : {}) };
+}
+/** A new item named with neither `price` nor `price_data`: "One of `price` or `price_data` is required"
+ *  (docs.stripe.com/api/subscriptions/update). */
+export function noItemPrice(ctx) {
+    return fail(ctx, 'Missing required param: items[price].', 400, 'parameter_missing');
+}
+/** A subscription asked to fail when its first invoice cannot be paid at once (payment_behavior=error_if_incomplete):
+ *  the card's decline, or no payment method to charge (docs.stripe.com/api/subscriptions/create#create_subscription-payment_behavior). */
+export function firstPaymentRefused(ctx, declined) {
+    return declined ? send(ctx, cardError(declined)) : fail(ctx, 'This customer has no attached payment source or default payment method.', 400, 'resource_missing');
+}
+/** An update's `items`: "A list of up to 20 subscription items, each with an attached price"
+ *  (docs.stripe.com/api/subscriptions/update): an entry naming an item's `id` changes that item (its price, quantity,
+ *  metadata) or, with `deleted` ("A flag that, if set to `true`, will delete the specified item"), removes it; "If you
+ *  omit `id`, the API adds a new subscription item rather than updating the existing one". Each takes `price` or
+ *  `price_data`, "Data used to generate a new Price object inline. One of `price` or `price_data` is required", and
+ *  "When changing a subscription item's price, `quantity` is set to 1 unless a `quantity` parameter is provided". An
+ *  inline price is made as the manage-prices guide says: "By default, prices created with `price_data` are effectively
+ *  archived (they're marked as `active=false`)" (docs.stripe.com/products-prices/manage-prices).
+ *  Where the documentation stops and the twin decides: the update is all or nothing, every entry checked before any is
+ *  written (Stripe answers one error for the request); the refusals are worded by the twin. */
+export async function applyItemChanges(ctx, subId, entries) {
+    // every entry is checked first: a refusal leaves the subscription as it was
+    const refused = itemChangesRefused(ctx, subId, entries);
+    if (refused)
+        return refused;
+    return writeItemChanges(ctx, subId, entries);
+}
+/** The refusal of an update's `items`, checked entry by entry before any is written (applyItemChanges). */
+export function itemChangesRefused(ctx, subId, entries) {
+    for (const entry of entries) {
+        const priceRef = typeof entry.price === 'string' && entry.price ? entry.price : undefined;
+        if (priceRef && !ctx.get('price', priceRef))
+            return fail(ctx, `No such price: '${priceRef}'`, 400, 'resource_missing');
+        const inline = !priceRef && entry.price_data && typeof entry.price_data === 'object' ? entry.price_data : undefined;
+        if (inline) {
+            const refused = refuseInlinePrice(ctx, inline);
+            if (refused)
+                return refused;
+        }
+        if (typeof entry.id === 'string' && entry.id) {
+            const si = ctx.get('subscription_item', entry.id);
+            if (!si || si.subscription !== subId)
+                return fail(ctx, `No such subscription_item: '${entry.id}'`, 400, 'resource_missing');
+        }
+        else if (!priceRef && !inline)
+            return noItemPrice(ctx);
+    }
+    return undefined;
+}
+/** An update's checked `items`, written. */
+export async function writeItemChanges(ctx, subId, entries) {
+    for (const entry of entries) {
+        const inline = typeof entry.price === 'string' && entry.price ? undefined : entry.price_data && typeof entry.price_data === 'object' ? entry.price_data : undefined;
+        const priceRef = typeof entry.price === 'string' && entry.price ? entry.price : inline ? await inlinePrice(ctx, inline) : undefined;
+        // only a price that changes resets the quantity; one naming the item's own price leaves it
+        const was = typeof entry.id === 'string' && entry.id ? ctx.get('subscription_item', entry.id)?.price : undefined;
+        const wasId = typeof was === 'string' ? was : was && typeof was === 'object' ? String(was.id ?? '') : undefined;
+        const quantity = entry.quantity !== undefined ? { quantity: Math.max(0, Math.trunc(Number(entry.quantity) || 0)) } : priceRef && priceRef !== wasId ? { quantity: 1 } : {};
+        const metadata = entry.metadata && typeof entry.metadata === 'object' ? { metadata: entry.metadata } : {};
+        if (typeof entry.id === 'string' && entry.id) {
+            if (asBool(entry.deleted)) {
+                await ctx.write('subscription_item', entry.id, { deleted: true }, 'subscription_item.delete');
+                continue;
+            }
+            await ctx.write('subscription_item', entry.id, { ...(priceRef ? subscriptionItemPrice(priceRef, finder(ctx)) : {}), ...quantity, ...metadata }, 'subscription_item.update');
+        }
+        else {
+            await created(ctx, 'subscription_item', { subscription: subId, ...subscriptionItemPrice(priceRef, finder(ctx)), quantity: 1, ...quantity, ...metadata }, { livemode: false, metadata: {}, discounts: [], tax_rates: [], billing_thresholds: null });
+        }
+    }
+    await syncItems(ctx, subId);
+    return undefined;
+}
+/** A subscription item's `price_data` Stripe would refuse: its required `currency`, `product` (an existing one) and
+ *  `recurring[interval]`, and "Only one of `unit_amount` and `unit_amount_decimal` can be set". */
+export function refuseInlinePrice(ctx, d) {
+    for (const name of ['currency', 'product'])
+        if (typeof d[name] !== 'string' || !d[name])
+            return fail(ctx, `Missing required param: items[price_data][${name}].`, 400, 'parameter_missing');
+    if (!ctx.get('product', String(d.product)))
+        return fail(ctx, `No such product: '${String(d.product)}'`, 400, 'resource_missing');
+    const interval = d.recurring?.interval;
+    if (!['day', 'week', 'month', 'year'].includes(String(interval)))
+        return fail(ctx, 'Missing required param: items[price_data][recurring][interval].', 400, 'parameter_missing');
+    if (d.unit_amount !== undefined && d.unit_amount_decimal !== undefined)
+        return fail(ctx, 'Only one of `unit_amount` and `unit_amount_decimal` can be set.', 400, 'parameter_invalid');
+    return undefined;
+}
+/** The inline Price a `price_data` generates: recurring, archived (active=false). Answers its id. */
+export async function inlinePrice(ctx, d) {
+    const r = d.recurring;
+    const decimal = d.unit_amount_decimal !== undefined ? String(d.unit_amount_decimal) : String(Math.trunc(Number(d.unit_amount) || 0));
+    const price = await created(ctx, 'price', {
+        product: d.product, currency: String(d.currency).toLowerCase(),
+        // a decimal amount that is not a whole number of the smallest unit has no integer unit_amount (as semantics/plans.ts)
+        unit_amount: d.unit_amount_decimal !== undefined ? (Number.isInteger(Number(d.unit_amount_decimal)) ? Number(d.unit_amount_decimal) : null) : Math.trunc(Number(d.unit_amount) || 0), unit_amount_decimal: decimal,
+        recurring: { interval: r.interval, interval_count: Math.max(1, Math.trunc(Number(r.interval_count ?? 1)) || 1), usage_type: 'licensed', trial_period_days: null, meter: null },
+        tax_behavior: typeof d.tax_behavior === 'string' ? d.tax_behavior : 'unspecified',
+    }, { active: false, livemode: false, billing_scheme: 'per_unit', type: 'recurring', metadata: {}, lookup_key: null, nickname: null });
+    return String(price.id);
+}
+// ── items: each write keeps the parent subscription's items.data in step, rebuilt from the live items ──
+/** A new subscription's items, each its own subscription_item as Stripe keeps it (/v1/subscription_items/{id}). */
+export async function storeItems(ctx, subId, items) {
+    for (const item of items) {
+        if (typeof item.id !== 'string' || ctx.get('subscription_item', item.id))
+            continue;
+        await ctx.write('subscription_item', item.id, { ...item, subscription: subId }, 'subscription_item.create');
+    }
+}
+export async function syncItems(ctx, subId) {
+    if (!subId)
+        return;
+    const items = ctx.rows('subscription_item').filter((r) => r.subscription === subId);
+    await ctx.write(SUB, subId, { items: { object: 'list', data: items, has_more: false, total_count: items.length, url: `/v1/subscription_items?subscription=${subId}` } }, 'subscription.items_synced');
+}
+/** A subscription item with its billing period: its subscription's (basil moved the period onto the items). */
+export const withPeriod = (ctx, si) => {
+    const sub = ctx.get(SUB, String(si.subscription));
+    return { ...si, current_period_start: si.current_period_start ?? sub?.current_period_start ?? null, current_period_end: si.current_period_end ?? sub?.current_period_end ?? null };
+};
+export const subscriptionsItemMissing = (ctx, id) => fail(ctx, `No such subscription_item: '${id}'`, 404, 'resource_missing');
+export const listMissing = (ctx, id, status = 404) => fail(ctx, `No such radar value list: '${id}'`, status, 'resource_missing');
+/** A value list's list_items, "List of items contained within this value list" (the served spec), kept in step with
+ *  its items, at the address the fixture names (/v1/radar/value_list_items?value_list=…). */
+export async function radarSyncItems(ctx, listId) {
+    const data = newest(ctx, VLI).filter((i) => i.value_list === listId);
+    await ctx.write(VL, listId, { list_items: { object: 'list', data, has_more: false, url: `/v1/radar/value_list_items?value_list=${listId}` } }, 'radar.value_list.items_synced');
+}
+/** A requested move of a state field the machine declares, legal or refused; a value the machine
+ *  does not name is written as given, as the hand-written route did. */
+export function requestedMove(ctx, resource, operationId, current, values) {
+    const to = ctx.params.status;
+    if (typeof to !== 'string' || !values.includes(to))
+        return undefined;
+    const refused = ctx.legal(resource, 'status', operationId, current, to);
+    return refused ? ctx.refuse(refused) : undefined;
+}
+// ── authorizations ──
+/** An authorization as every egress carries it: its card embedded in full. */
+export function withCard(ctx, a) {
+    const out = { ...a };
+    if (typeof out.card === 'string') {
+        const card = ctx.get(CARD, out.card);
+        if (card)
+            out.card = card;
+    }
+    return out;
+}
+export const authMissing = (ctx, id) => fail(ctx, `No such authorization: '${id}'`, 404, 'resource_missing');
+/** A capture: an Issuing transaction (negative: it debits) and the issuing balance's debit. */
+export async function capture(ctx, authId, auth, amountCents) {
+    const currency = typeof auth.currency === 'string' ? auth.currency : 'usd';
+    const bt = await created(ctx, 'balance_transaction', {}, {
+        amount: -amountCents, currency, fee: 0, net: -amountCents, type: 'issuing_transaction',
+        status: 'available', balance_type: 'issuing', reporting_category: 'issuing_transaction',
+        available_on: nowUnix(ctx.occurredAt), fee_details: [],
+    });
+    const txn = await created(ctx, TXN, { authorization: authId, card: auth.card, cardholder: auth.cardholder }, {
+        type: 'capture', amount: -amountCents, currency,
+        merchant_amount: -amountCents, merchant_currency: typeof auth.merchant_currency === 'string' ? auth.merchant_currency : currency,
+        merchant_data: auth.merchant_data ?? merchantData(undefined),
+        livemode: false, metadata: {}, dispute: null, wallet: null, network_data: null,
+        amount_details: null, purchase_details: null, balance_transaction: bt.id,
+    });
+    return { txnId: String(txn.id), btId: String(bt.id) };
+}
+/** Issuing refusals of a request no story sends: an unknown card status or authorization method, and a capture of an
+ *  authorization that is not approved and pending. */
+export function issuingRefusal(ctx, what, auth) {
+    switch (what) {
+        case 'card_status': return fail(ctx, "Invalid status: must be one of 'active', 'inactive', or 'canceled'.", 400, 'parameter_invalid_string_enum');
+        case 'authorization_method': return fail(ctx, "Invalid authorization_method: must be one of 'chip', 'contactless', 'keyed_in', 'online', or 'swipe'.", 400, 'parameter_invalid_string_enum');
+        case 'not_capturable': return fail(ctx, `This authorization cannot be captured because it is not an approved pending authorization (status: ${String(auth?.status)}, approved: ${auth?.approved === true}).`, 400);
+    }
+}
+/** A partial approval's refusal: "You can specify the amount you want to approve by setting the amount in the webhook
+ *  response body or the approve call" only "When an authorization is partially authorized, the is_amount_controllable
+ *  field on the authorization request is set to true" (docs.stripe.com/issuing/purchases/authorizations), and never a
+ *  credit. Answers the refusal, or undefined when the amount may be approved. */
+export function partialApprovalRefused(ctx, auth) {
+    if (Math.trunc(Number(ctx.params.amount) || 0) <= 0)
+        return fail(ctx, 'Invalid integer: amount must be a positive integer.', 400, 'parameter_invalid_integer');
+    if (auth.pending_request?.is_amount_controllable !== true)
+        return fail(ctx, 'amount may only be provided when the authorization was presented with is_amount_controllable.', 400);
+    return undefined;
+}
+// the (deprecated but real) API decision on a pending authorization: it lands in request_history
+// as the webhook's answer would, consumes the pending request, and an approval captures
+export function issuingDecide(approved) {
+    return async (ctx) => {
+        const id = at(ctx, 'authorization');
+        const auth = ctx.get(AUTH, id);
+        if (!auth)
+            return authMissing(ctx, id);
+        const finalized = { status: 400, code: 'authorization_already_finalized', message: `This authorization has already been finalized (status ${String(auth.status)}).` };
+        // a webhook-approved authorization is decided, though still pending
+        if (auth.approved === true)
+            return ctx.refuse(finalized);
+        const refused = ctx.legal(AUTH, 'status', approved ? 'PostIssuingAuthorizationsAuthorizationApprove' : 'PostIssuingAuthorizationsAuthorizationDecline', auth.status, undefined, id);
+        if (refused)
+            return ctx.refuse(refused);
+        // a partial approval only for an amount-controllable presentment, and never a credit
+        const badAmount = approved && ctx.params.amount !== undefined ? partialApprovalRefused(ctx, auth) : undefined;
+        if (badAmount)
+            return badAmount;
+        const decidedAmount = approved && ctx.params.amount !== undefined ? Math.trunc(Number(ctx.params.amount) || 0) : Number(auth.amount) || 0;
+        const currency = typeof auth.currency === 'string' ? auth.currency : 'usd';
+        const history = Array.isArray(auth.request_history) ? auth.request_history : [];
+        // an approval holds the funds and waits for the merchant's capture; a decline closes it
+        // (docs.stripe.com/issuing/purchases/authorizations, docs.stripe.com/issuing/funding/balance)
+        const hold = approved ? await holdFor(ctx, id, decidedAmount, currency) : null;
+        return ctx.reply(withCard(ctx, await ctx.write(AUTH, id, {
+            ...(approved ? {} : { status: 'closed' }), approved, pending_request: null,
+            ...(approved && ctx.params.amount !== undefined ? { amount: decidedAmount } : {}),
+            request_history: [...history, historyEntry({
+                    amount: decidedAmount, currency, approved, reason: approved ? 'webhook_approved' : 'webhook_declined', reasonMessage: null,
+                    createdSec: Number(nowUnix(ctx.occurredAt)), merchantAmount: Number(auth.merchant_amount) || decidedAmount,
+                    merchantCurrency: typeof auth.merchant_currency === 'string' ? auth.merchant_currency : currency,
+                })],
+            ...(hold ? { balance_transactions: [...(Array.isArray(auth.balance_transactions) ? auth.balance_transactions : []), hold.id] } : {}),
+        }, 'issuing_authorization.updated')));
+    };
+}
+/** Time's decision on a real-time request no one answered, caught up to the World's clock: once its window has ended,
+ *  a pending authorization whose issuing_authorization.request went unanswered, and that no approve or decline decided,
+ *  is decided automatically, its request_history reason webhook_timeout ("webhook_timeout for all other failure modes",
+ *  the same page, beside webhook_error for a response Stripe cannot process).
+ *  Where the documentation stops and the twin decides: the timeout setting is the Dashboard's, which the API does not
+ *  answer, and the twin's is to decline; the window is measured in World time from the authorization's created. */
+export async function lapseRealtimeRequests(ctx) {
+    const now = Number(nowUnix(ctx.occurredAt));
+    const requested = new Set(ctx.rows('event').filter((e) => e.type === 'issuing_authorization.request').map((e) => String(e.data?.object?.id ?? '')));
+    for (const a of ctx.rowsRaw(AUTH)) {
+        if (a.status !== 'pending' || a.approved === true || !a.pending_request || !requested.has(String(a.id)))
+            continue;
+        const at = Number(a.created) + REALTIME_WINDOW_SECONDS;
+        if (now < at)
+            continue;
+        const id = String(a.id);
+        const currency = typeof a.currency === 'string' ? a.currency : 'usd';
+        const amount = Number(a.amount) || 0;
+        ctx.legal(AUTH, 'status', ctx.call.operation.id, 'pending', 'closed', id, 'time');
+        await ctx.write(AUTH, id, {
+            status: 'closed', approved: false, pending_request: null,
+            request_history: [...(Array.isArray(a.request_history) ? a.request_history : []), historyEntry({
+                    amount, currency, approved: false, reason: 'webhook_timeout', reasonMessage: null, createdSec: at,
+                    merchantAmount: Number(a.merchant_amount) || amount, merchantCurrency: typeof a.merchant_currency === 'string' ? a.merchant_currency : currency,
+                })],
+        }, 'issuing_authorization.updated');
+    }
+}
+/** An approval's hold: "If you approve the authorization, we deduct the `amount` from your Issuing balance and hold it
+ *  in reserve until the authorization is either captured, voided, or expired without capture"
+ *  (docs.stripe.com/issuing/purchases/authorizations). */
+export async function holdFor(ctx, authId, amount, currency) {
+    return created(ctx, 'balance_transaction', {}, {
+        amount: -amount, currency, fee: 0, net: -amount, type: 'issuing_authorization_hold',
+        status: 'available', balance_type: 'issuing', reporting_category: 'issuing_authorization_hold',
+        available_on: nowUnix(ctx.occurredAt), fee_details: [], source: authId,
+    });
+}
+/** An authorization approved as it is presented, its amount held: approved and pending until the merchant captures. */
+export async function approvedAtOnce(ctx, subject, fields, held, entry) {
+    const hold = await holdFor(ctx, String(subject.id), held, String(fields.currency ?? 'usd'));
+    return ctx.reply(withCard(ctx, await created(ctx, AUTH, subject, { ...fields, amount: held, status: 'pending', approved: true, pending_request: null, request_history: [entry], balance_transactions: [hold.id] })));
+}
+/** An authorization as the platform's real-time answer makes it: approved (in part, only when the request was
+ *  amount-controllable), declined, or declined for an answer Stripe cannot read (docs.stripe.com/issuing/controls/
+ *  real-time-authorizations: the response's `approved` and `amount`; webhook_error "if we can't process your response"). */
+export async function answeredByEndpoint(ctx, outcome, o) {
+    if (outcome.kind === 'approved') {
+        const held = o.controllable && outcome.amount !== undefined ? outcome.amount : o.amount;
+        return approvedAtOnce(ctx, o.subject, o.fields, held, o.entry({ amount: held, approved: true, reason: 'webhook_approved', reasonMessage: null }));
+    }
+    return outcome.kind === 'declined' ? o.decline('webhook_declined', null) : o.decline('webhook_error', outcome.message);
+}
+// ── disputes: opened against a transaction, unsubmitted until submitted ──
+export const disputeMissing = (ctx, id) => fail(ctx, `No such dispute: '${id}'`, 404, 'resource_missing');
+// ── personalization designs: in review until Stripe's review (the test helpers in test mode) decides ──
+export const designMissing = (ctx, id) => fail(ctx, `No such personalization design: '${id}'`, 404, 'resource_missing');
+export function review(action, operationId) {
+    return async (ctx) => {
+        const id = at(ctx, 'personalization_design');
+        const d = ctx.get(PD, id);
+        if (!d)
+            return designMissing(ctx, id);
+        const refused = ctx.legal(PD, 'status', operationId, d.status, undefined, id);
+        if (refused)
+            return ctx.refuse(refused);
+        const status = action === 'activate' ? 'active' : action === 'deactivate' ? 'inactive' : 'rejected';
+        // a rejection records its reasons: the reject helper's required rejection_reasons, "The reason(s) the
+        // personalization design was rejected" (the served spec), per card_logo and carrier_text
+        const given = ctx.params.rejection_reasons && typeof ctx.params.rejection_reasons === 'object' ? ctx.params.rejection_reasons : undefined;
+        if (action === 'reject' && !given)
+            return fail(ctx, 'Missing required param: rejection_reasons.', 400, 'parameter_missing');
+        const reasons = action === 'reject' ? { rejection_reasons: { card_logo: Array.isArray(given.card_logo) ? given.card_logo : [], carrier_text: Array.isArray(given.carrier_text) ? given.carrier_text : [] } } : {};
+        return ctx.reply(await ctx.write(PD, id, { status, ...reasons }, `personalization_design.${action}`));
+    };
+}
+/**
+ * Create a refund and land it on its charge. An omitted amount is the whole remaining balance. The
+ * charge's write records `charge.refunded`, the event Stripe sends carrying the charge's new totals;
+ * `refunded` is true only at the full amount.
+ */
+/** A reason Stripe does not take (docs.stripe.com/api/refunds/create#create_refund-reason). */
+export function badReason(ctx) {
+    return fail(ctx, `Invalid refund reason: must be one of ${[...REFUND_REASONS].join(', ')}.`, 400, 'parameter_invalid_string_enum');
+}
+/** A bank-transfer payment refunded with origin=customer_balance goes back to the cash balance
+ *  (docs.stripe.com/payments/customer-balance/refunding). */
+export async function backToCashBalance(ctx, customer, currency, amount, refundId) {
+    const before = ctx.rows('customer_cash_balance_transaction').filter((t) => t.customer === customer && String(t.currency) === currency).reduce((n, t) => n + (Number(t.net_amount) || 0), 0);
+    await created(ctx, 'customer_cash_balance_transaction', { customer }, { currency, type: 'refunded_from_payment', net_amount: amount, ending_balance: before + amount, refunded_from_payment: { refund: refundId }, livemode: false });
+}
+/** A capture=false charge's refund, which releases its whole authorization (see the header). */
+export async function refundUncaptured(ctx, charge, amount, remaining, params) {
+    if (amount < remaining)
+        return fail(ctx, `Charge ${String(charge.id)} is uncaptured: refunding it releases the whole authorization (${remaining}).`, 400, 'amount_too_small');
+    const { reason, metadata } = params;
+    return ctx.reply(await releaseAuthorization(ctx, charge, ctx.call.operation.id, { ...(reason !== undefined ? { reason } : {}), ...(metadata !== undefined ? { metadata } : {}) }));
+}
+export async function refundCharge(ctx, charge, params) {
+    const chargeId = String(charge.id);
+    const total = Number(charge.amount) || 0;
+    const already = Number(charge.amount_refunded) || 0;
+    const remaining = Math.max(0, total - already);
+    const amount = params.amount === undefined ? remaining : Math.trunc(Number(params.amount));
+    if (!Number.isFinite(amount) || amount <= 0)
+        return fail(ctx, 'Invalid integer: amount must be a positive integer.', 400, 'parameter_invalid_integer');
+    if (amount > remaining)
+        return fail(ctx, `Refund amount (${amount}) is greater than unrefunded amount on charge (${remaining}).`, 400, 'amount_too_large');
+    if (params.reason !== undefined && !REFUND_REASONS.has(String(params.reason)))
+        return badReason(ctx);
+    // an authorization is released, never refunded out of the balance: a PaymentIntent's by cancelling the intent, a
+    // capture=false charge's by its refund (refundUncaptured)
+    if (charge.captured === false && typeof charge.payment_intent === 'string')
+        return fail(ctx, `Charge ${chargeId} is uncaptured and can't be refunded directly; cancel its PaymentIntent (${charge.payment_intent}) to release the authorization.`, 400, 'payment_intent_unexpected_state');
+    if (charge.captured === false)
+        return refundUncaptured(ctx, charge, amount, remaining, params);
+    const refunded = already + amount;
+    // the refund that takes the rest refunds the charge: the charge machine's move under this operation
+    if (refunded >= total && charge.refunded !== true) {
+        const refused = ctx.legal('charge', 'refunded', ctx.call.operation.id, 'false', 'true', chargeId);
+        if (refused)
+            return ctx.refuse(refused);
+    }
+    // a refund has no `livemode` field; it debits the balance at once
+    const refundId = ctx.mint('refund');
+    const currency = String(charge.currency ?? 'usd');
+    const pi = typeof charge.payment_intent === 'string' ? ctx.get('payment_intent', charge.payment_intent) : undefined;
+    const byTransfer = (pi?.payment_method_types ?? []).includes('customer_balance');
+    const toCashBalance = byTransfer && params.origin === 'customer_balance';
+    const awaitsBank = byTransfer && !toCashBalance;
+    const now = Number(nowUnix(ctx.occurredAt));
+    const customer = typeof charge.customer === 'string' ? charge.customer : typeof pi?.customer === 'string' ? pi.customer : undefined;
+    const emailTo = typeof params.instructions_email === 'string' ? params.instructions_email : (customer ? ctx.get('customer', customer)?.email : undefined) ?? null;
+    // "Refunds use your available Stripe balance (not including pending amounts). If your available balance doesn't
+    // cover the amount of the refund, Stripe holds the refund as pending for card transactions ... until your Stripe
+    // balance becomes sufficient" (docs.stripe.com/refunds): the refund waits, moving no money, until the balance covers
+    // it (settleHeldRefunds). Where the documentation stops and the twin decides: a refund of another payment method
+    // short of balance is not modelled (Stripe fails it); the twin makes it as a card's.
+    const account = actingAccount(ctx);
+    const isCard = charge.payment_method_details?.type === 'card';
+    const held = !awaitsBank && !toCashBalance && isCard && availableAt(ctx, account, currency, now) < amount;
+    if (held)
+        ctx.legal('refund', 'status', ctx.call.operation.id, 'succeeded', 'pending', refundId);
+    const bt = awaitsBank || held ? null : await settleRefund(ctx, refundId, amount, currency);
+    if (toCashBalance && customer)
+        await backToCashBalance(ctx, customer, currency, amount, refundId);
+    const { reverse_transfer: reverseTransfer, refund_application_fee: refundFee, instructions_email: _email, origin: _origin, ...stored } = params;
+    const share = (whole) => Math.round((whole * amount) / (total || 1));
+    let transferReversal = null;
+    const transfer = typeof charge.transfer === 'string' ? ctx.get('transfer', charge.transfer) : undefined;
+    if (reverseTransfer !== undefined && asBool(reverseTransfer) && transfer) {
+        const back = Math.min(share(Number(transfer.amount) || 0), (Number(transfer.amount) || 0) - (Number(transfer.amount_reversed) || 0));
+        const trr = await created(ctx, 'transfer_reversal', { amount: back, currency, transfer: transfer.id }, { balance_transaction: null, destination_payment_refund: null, source_refund: refundId, metadata: {} });
+        const trrBt = await settleTransferReversal(ctx, String(trr.id), back, currency, String(transfer.destination));
+        const reversal = await ctx.write('transfer_reversal', String(trr.id), { balance_transaction: trrBt }, 'transfer_reversal.updated');
+        const reversed = (Number(transfer.amount_reversed) || 0) + back;
+        const list = transfer.reversals ?? { object: 'list', data: [], has_more: false, total_count: 0 };
+        const data = [...((list.data ?? [])), reversal];
+        await ctx.write('transfer', String(transfer.id), { amount_reversed: reversed, reversed: reversed >= (Number(transfer.amount) || 0), reversals: { ...list, data, total_count: data.length, url: `/v1/transfers/${String(transfer.id)}/reversals` } }, 'transfer.reversed');
+        transferReversal = String(trr.id);
+    }
+    const fee = typeof charge.application_fee === 'string' ? ctx.get('application_fee', charge.application_fee) : undefined;
+    if (refundFee !== undefined && asBool(refundFee) && fee) {
+        const feeTotal = Number(fee.amount) || 0;
+        const back = Math.min(share(feeTotal), feeTotal - (Number(fee.amount_refunded) || 0));
+        const done = (Number(fee.amount_refunded) || 0) + back;
+        if (!(done >= feeTotal && fee.refunded !== true && ctx.legal('application_fee', 'refunded', ctx.call.operation.id, 'false', 'true', String(fee.id)))) {
+            const fr = await created(ctx, 'fee_refund', { amount: back, currency, fee: fee.id }, { balance_transaction: null, metadata: {} });
+            const list = fee.refunds ?? { object: 'list', data: [], has_more: false, total_count: 0 };
+            const data = [...((list.data ?? [])), fr];
+            await ctx.write('application_fee', String(fee.id), { amount_refunded: done, refunded: done >= feeTotal, refunds: { ...list, data, total_count: data.length, url: `/v1/application_fees/${String(fee.id)}/refunds` } }, 'application_fee.refunded');
+        }
+    }
+    const body = await created(ctx, 'refund', {
+        ...stored, id: refundId, charge: chargeId, amount, currency, transfer_reversal: transferReversal,
+        ...(typeof charge.payment_intent === 'string' ? { payment_intent: charge.payment_intent } : {}),
+    }, {
+        status: awaitsBank ? 'requires_action' : held ? 'pending' : 'succeeded', metadata: {}, reason: null, receipt_number: null,
+        ...(held ? { pending_reason: 'insufficient_funds', _account: account ?? null } : {}),
+        balance_transaction: bt, source_transfer_reversal: null,
+        // a bank transfer's refund goes to the customer's bank (a us_bank_transfer) or back to its cash balance
+        // (customer_cash_balance): "If this is a `us_bank_transfer` refund, this hash contains the transaction specific details",
+        // "If this is a `customer_cash_balance` refund ..." (docs.stripe.com/api/refunds/object, destination_details)
+        ...(byTransfer
+            ? { destination_details: toCashBalance ? { type: 'customer_cash_balance', customer_cash_balance: {} } : { type: 'us_bank_transfer', us_bank_transfer: { reference: null, reference_status: null } } }
+            : refundDestination(charge, 'refund')),
+        ...(awaitsBank ? { next_action: { type: 'display_details', display_details: { email_sent: { email_sent_at: now, email_sent_to: emailTo }, expires_at: now + 30 * 86_400 } } } : {}),
+    });
+    await ctx.write('charge', chargeId, { amount_refunded: refunded, refunded: refunded >= total }, 'charge.refunded');
+    return ctx.reply(body);
+}
+/** Time's settling of held refunds, caught up to the World's clock: each refund held for want of balance, oldest first,
+ *  is made at the first moment the account's available balance covers it (the funds that come due then), its debit
+ *  written then, as `refund.updated`. Where the documentation stops and the twin decides: a held refund is made the
+ *  moment the balance covers it. */
+export async function settleHeldRefunds(ctx) {
+    const now = Number(nowUnix(ctx.occurredAt));
+    const heldRefunds = ctx.rowsRaw('refund').filter((r) => r.status === 'pending' && r.pending_reason === 'insufficient_funds').sort((a, b) => Number(a.created) - Number(b.created));
+    for (const r of heldRefunds) {
+        const account = typeof r._account === 'string' ? r._account : undefined;
+        const currency = String(r.currency ?? 'usd');
+        const amount = Number(r.amount) || 0;
+        const when = [Number(r.created), ...fundsDueBetween(ctx, account, currency, Number(r.created), now)].find((t) => availableAt(ctx, account, currency, t) >= amount);
+        if (when === undefined)
+            continue;
+        const c = await at_(ctx)(when);
+        c.legal('refund', 'status', ctx.call.operation.id, 'pending', 'succeeded', String(r.id), 'vendor');
+        const bt = await settleRefund(c, String(r.id), amount, currency, account ?? null);
+        await c.write('refund', String(r.id), { status: 'succeeded', pending_reason: null, balance_transaction: bt }, 'refund.updated');
+    }
+}
+/** The charge a refund aims at: named directly, or reached through its PaymentIntent. */
+export function target(ctx) {
+    const chargeId = typeof ctx.params.charge === 'string' ? ctx.params.charge : '';
+    const piId = typeof ctx.params.payment_intent === 'string' ? ctx.params.payment_intent : '';
+    if (!chargeId && !piId)
+        return fail(ctx, 'One of `charge` or `payment_intent` is required.', 400, 'parameter_missing');
+    if (chargeId)
+        return ctx.get('charge', chargeId) ?? fail(ctx, `No such charge: '${chargeId}'`, 404, 'resource_missing');
+    const pi = ctx.get('payment_intent', piId);
+    if (!pi)
+        return fail(ctx, `No such payment_intent: '${piId}'`, 404, 'resource_missing');
+    const latest = typeof pi.latest_charge === 'string' ? pi.latest_charge : undefined;
+    const ch = (latest ? ctx.get('charge', latest) : undefined) ?? newest(ctx, 'charge').find((c) => c.payment_intent === piId);
+    return ch ?? fail(ctx, `This PaymentIntent does not have a successful charge to refund. Its status is ${String(pi.status)}.`, 400, 'payment_intent_unexpected_state');
+}
+export const refundMissing = (ctx, id) => fail(ctx, `No such refund: '${id}'`, 404, 'resource_missing');
+/** Each advancing clock whose advance has taken its time reaches its target, caught up before anything is answered:
+ *  its frozen_time moves, it is ready, and its customers' trials and periods that ended by then end
+ *  (./renewals.ts advanceBilling). The advance's own write is when it began (the kernel's updatedAt). */
+export async function finishClockAdvances(ctx) {
+    const now = Number(nowUnix(ctx.occurredAt));
+    for (const clock of ctx.rowsRaw(CLOCK)) {
+        if (clock.status !== 'advancing')
+            continue;
+        if (Date.parse(String(clock.updatedAt)) / 1000 + ADVANCE_SECONDS > now)
+            continue;
+        const id = String(clock.id);
+        const target = Number(clock.status_details?.advancing?.target_frozen_time);
+        ctx.legal(CLOCK, 'status', ctx.call.operation.id, 'advancing', 'ready', id, 'vendor');
+        await ctx.write(CLOCK, id, { frozen_time: target, status: 'ready', status_details: {} }, 'test_clock.ready');
+        await advanceBilling(ctx, (sub) => typeof sub.customer === 'string' && ctx.get('customer', sub.customer)?.test_clock === id);
+    }
+}
+/** What the platform saved, or the settings a new platform starts with (OAuth off, no redirect URI). */
+export function connectOAuthSettings(ctx) {
+    const row = ctx.rowsRaw(SETTINGS).find((r) => r.id === PLATFORM_CLIENT_ID);
+    return { oauth_enabled: row?.oauth_enabled === true, redirect_uris: Array.isArray(row?.redirect_uris) ? row.redirect_uris : [] };
+}
+export const accountMissing = (ctx, id, status = 404) => fail(ctx, `No such account: '${id}'`, status, 'resource_missing');
+/** The account, tombstones included where the hand-written routes looked past a deletion. */
+export const accountRow = (ctx, id) => ctx.row('account', id, { withDeleted: true });
+/** Stripe's review of a Custom account once the platform gives it something: with nothing left due, its requested
+ *  capabilities become active and it can take charges and receive payouts; with something due again (its bank account
+ *  removed), they stop. Where the documentation stops and the twin decides: test-mode verification is immediate, and
+ *  it owes what customRequirements lists. An Express or Standard account is onboarded on Stripe's own pages. */
+export async function connectReview(ctx, id) {
+    const account = ctx.get('account', id);
+    if (account && account.type === 'custom')
+        await reviewCustom(ctx, id, account);
+}
+/** The review of a Custom account (see review). */
+export async function reviewCustom(ctx, id, account) {
+    const bank = ctx.rows('external_account').some((e) => e.account === id);
+    const persons = ctx.rows('person').filter((p) => p.account === id);
+    const { now: due, later } = customRequirements(account, bank, persons);
+    // one account, one review: "If a connected account has both card_payments and transfers, and the status of either one
+    // is inactive, then both capabilities are disabled" (docs.stripe.com/connect/account-capabilities)
+    const ready = due.length === 0;
+    const capabilities = {};
+    for (const [key, was] of Object.entries(account.capabilities ?? {})) {
+        const to = ready ? 'active' : 'inactive';
+        // Stripe's review moves each capability, as the machine declares it may
+        if (was !== to)
+            ctx.legal('capability', 'status', ctx.call.operation.id, String(was), to, key, 'vendor');
+        capabilities[key] = to;
+    }
+    const requirements = { ...(account.requirements ?? {}), currently_due: due, eventually_due: [...due, ...later], past_due: [], disabled_reason: ready ? null : 'requirements.past_due', current_deadline: null };
+    await ctx.write('account', id, { capabilities, requirements, charges_enabled: ready, payouts_enabled: ready, details_submitted: ready }, ready ? 'account.updated' : 'account.update');
+}
+// ── persons on an account ──
+export const personMissing = (ctx) => fail(ctx, `No such person: '${at(ctx, 'person')}'`, 404, 'resource_missing');
+export const accountPerson = (ctx) => {
+    const p = ctx.get('person', at(ctx, 'person'));
+    return p && p.account === at(ctx, 'account') ? p : undefined;
+};
+// ── external accounts: a payout destination from a token or a bank_account hash ──
+export const externalMissing = (ctx) => fail(ctx, `No such external account: '${at(ctx, 'id')}'`, 404, 'resource_missing');
+export const accountExternal = (ctx) => {
+    const e = ctx.get('external_account', at(ctx, 'id'));
+    return e && e.account === at(ctx, 'account') ? e : undefined;
+};
+/** Whether the platform may create, update or delete an account's external accounts: "A platform can create, update, or
+ *  delete external accounts only for connected accounts without access to either the full Stripe or Express Dashboard
+ *  and where the platform is responsible for negative balances" (docs.stripe.com/connect/payouts-bank-accounts); it can
+ *  still view an Express account's ("A platform can view the external accounts of connected accounts that don’t have
+ *  access to the full Stripe Dashboard"). Where the documentation stops and the twin decides: the refusal. Stripe's
+ *  pages give no error code for it; the twin answers 403, which the errors page gives as "The API key doesn’t have
+ *  permissions to perform the request" (docs.stripe.com/api/errors), with the twin's own wording. The create page says
+ *  it too: "You can only specify connected accounts where account.controller.requirement_collection is `application`"
+ *  (docs.stripe.com/api/external_account_bank_accounts/create). */
+export function refuseExternalWrite(ctx, account) {
+    const row = accountRow(ctx, account);
+    const controller = row?.controller ?? controllerOf(String(row?.type ?? 'standard'));
+    const dashboard = String((controller.stripe_dashboard?.type) ?? '');
+    const losses = String((controller.losses?.payments) ?? '');
+    if (dashboard === 'none' && losses === 'application')
+        return undefined;
+    return ctx.refuse({ status: 403, message: `This application does not have the required permissions to manage the external accounts of account '${account}': they can only be managed through the account's ${dashboard === 'express' ? 'Express' : 'Stripe'} Dashboard.` });
+}
+/** Update and delete by id, finding tombstones as the hand-written routes did, with Stripe's own operation names. */
+export function patch(resource, param, missing, op) {
+    return (ctx) => patchRow(ctx, resource, param, missing, op);
+}
+export async function patchRow(ctx, resource, param, missing, op) {
+    const id = at(ctx, param);
+    if (!ctx.row(resource, id, { withDeleted: true }))
+        return fail(ctx, `No such ${missing}: '${id}'`, 404, 'resource_missing');
+    return ctx.reply(await ctx.write(resource, id, ctx.params, op));
+}
+// A reader's update takes its label and metadata only; it moves to another location by registering it
+// there again (https://docs.stripe.com/api/terminal/readers/update, docs.stripe.com/terminal/fleet/locations-and-zones)
+// (the parameter check refuses anything else, as Stripe does: ./params.ts)
+export const updateReader = patch(READER, 'reader', 'reader', 'terminal_reader.updated');
+export function remove(resource, param, missing, op, object) {
+    return async (ctx) => {
+        const id = at(ctx, param);
+        if (!ctx.row(resource, id, { withDeleted: true }))
+            return fail(ctx, `No such ${missing}: '${id}'`, 404, 'resource_missing');
+        const row = ctx.get(resource, id);
+        await ctx.write(resource, id, { deleted: true }, op);
+        // a deleted reader still says what device it was
+        return ctx.reply({ id, object, deleted: true, ...(object === 'terminal.reader' && row ? { device_type: row.device_type, serial_number: row.serial_number } : {}) });
+    };
+}
+export const readerMissing = (ctx, id) => fail(ctx, `No such reader: '${id}'`, 404, 'resource_missing');
+/** A card presented to a reader with no payment in progress. */
+export function nothingToPresent(ctx) {
+    return fail(ctx, 'This reader has no in-progress payment to present a payment method to.', 400, 'terminal_reader_invalid_state');
+}
+/** Under manual capture the presented card only holds the amount (docs.stripe.com/terminal/payments/collect-card-payment#capture-payment):
+ *  the hold is an uncaptured charge, as an online authorization's is (authorizeCharge), which the intent's capture takes. */
+export async function holdForCapture(ctx, piId, pi, pm, amount) {
+    const charge = await authorizeCharge(ctx, piId, { ...pi, payment_method: pm }, amount);
+    await ctx.write('payment_intent', piId, { status: 'requires_capture', payment_method: pm, amount_capturable: amount, latest_charge: charge }, 'payment_intent.amount_capturable_updated');
+}
+/** Time's settling of top-ups, caught up to the World's clock: a pending top-up succeeds on its expected_availability_date,
+ *  its funds entered then in the balance it names. */
+export async function settleTopups(ctx) {
+    const now = Number(nowUnix(ctx.occurredAt));
+    for (const t of ctx.rowsRaw('topup')) {
+        if (t.status !== 'pending' || Number(t.expected_availability_date) > now)
+            continue;
+        const c = await at_(ctx)(Number(t.expected_availability_date));
+        c.legal('topup', 'status', ctx.call.operation.id, 'pending', 'succeeded', String(t.id), 'vendor');
+        const bt = await settleTopup(c, String(t.id), Number(t.amount), String(t.currency), t.destination_balance === 'issuing' ? 'issuing' : 'payments');
+        await c.write('topup', String(t.id), { status: 'succeeded', balance_transaction: bt }, 'topup.succeeded');
+    }
+}
+export const disputesDisputeMissing = (ctx, id) => fail(ctx, `No such dispute: '${id}'`, 404, 'resource_missing');
+/** Evidence staged without submitting it (submit=false), or on a dispute already under review or decided. */
+export async function keepEvidence(ctx, id, fields) {
+    return ctx.reply(await ctx.write('dispute', id, fields, 'dispute.update'));
+}
+export const meterMissing = (ctx, id) => fail(ctx, `No such meter: '${id}'`, 404, 'resource_missing');
+export function activation(kind) {
+    return async (ctx) => {
+        const id = at(ctx, 'id');
+        const m = ctx.get(METER, id);
+        if (!m)
+            return meterMissing(ctx, id);
+        const refused = ctx.legal(METER, 'status', kind === 'deactivate' ? 'PostBillingMetersIdDeactivate' : 'PostBillingMetersIdReactivate', m.status, undefined, id);
+        if (refused)
+            return ctx.refuse(refused);
+        const fields = { ...(kind === 'deactivate' ? { status: 'inactive', status_transitions: { deactivated_at: nowUnix(ctx.occurredAt) } } : { status: 'active', status_transitions: { deactivated_at: null } }), updated: nowUnix(ctx.occurredAt) };
+        return ctx.reply(await ctx.write(METER, id, fields, `billing_meter.${kind}`));
+    };
+}
+export const grantMissing = (ctx, id) => fail(ctx, `No such credit grant: '${id}'`, 404, 'resource_missing');
+// expiring or voiding a grant stamps the instant; it no longer counts toward the balance
+export function endGrant(kind) {
+    return async (ctx) => {
+        const id = at(ctx, 'id');
+        if (!ctx.get(GRANT, id))
+            return grantMissing(ctx, id);
+        return ctx.reply(await ctx.write(GRANT, id, { ...(kind === 'void' ? { voided_at: nowUnix(ctx.occurredAt) } : { expires_at: nowUnix(ctx.occurredAt) }), updated: nowUnix(ctx.occurredAt) }, `credit_grant.${kind}`));
+    };
+}
+export function alertMove(kind, operationId) {
+    return async (ctx) => {
+        const id = at(ctx, 'id');
+        const a = ctx.get(ALERT, id);
+        if (!a)
+            return fail(ctx, `No such alert: '${id}'`, 404, 'resource_missing');
+        const refused = ctx.legal(ALERT, 'status', operationId, a.status, undefined, id);
+        if (refused)
+            return ctx.refuse(refused);
+        const status = kind === 'activate' ? 'active' : kind === 'deactivate' ? 'inactive' : 'archived';
+        return ctx.reply(await ctx.write(ALERT, id, { status }, `billing_alert.${kind}`));
+    };
+}
+export const transferMissing = (ctx, id) => fail(ctx, `No such transfer: '${id}'`, 404, 'resource_missing');
+/** A transfer to an account whose transfers capability is not active. */
+export function transfersInactive(ctx) {
+    return ctx.refuse({ status: 400, code: 'insufficient_capabilities_for_transfer', param: 'destination', message: 'Your destination account needs to have at least one of the following capabilities enabled: transfers, crypto_transfers, legacy_payments' });
+}
+/** A transfer from a charge whose funds have settled: "With a source_transaction, the transfer request returns success
+ *  regardless of your available balance if the related charge hasn't settled yet" (docs.stripe.com/connect/separate-
+ *  charges-and-transfers), so a settled one comes out of the available balance. */
+export function settledSourceRefused(ctx, amount, currency) {
+    return refusePayout(ctx, amount, currency, undefined);
+}
+/** An application fee refunded to its whole through its own refunds endpoint: the fee machine's move, or its refusal. */
+export function feeFullyRefunded(ctx, resource, flag, id) {
+    const refused = ctx.legal(resource, flag, ctx.call.operation.id, 'false', 'true', id);
+    return refused ? ctx.refuse(refused) : undefined;
+}
+/** Take `amount` (the remainder by default) back out of a parent's total, as a child row appended to its list. */
+export async function giveBack(ctx, o) {
+    const id = String(o.parent.id);
+    const total = Number(o.parent.amount ?? 0);
+    const already = Number(o.parent[o.doneField] ?? 0);
+    const remaining = total - already;
+    const amount = ctx.params.amount !== undefined ? Math.trunc(Number(ctx.params.amount) || 0) : remaining;
+    if (amount <= 0 || amount > remaining)
+        return fail(ctx, o.tooLarge(remaining), 400, 'amount_too_large');
+    const done = already + amount;
+    // a fee refunded in full is `refunded`: the application fee machine's move (a transfer's `reversed` is no state)
+    const feeRefusal = o.parentResource === 'application_fee' && done >= total && o.parent[o.flag] !== true ? feeFullyRefunded(ctx, o.parentResource, o.flag, id) : undefined;
+    if (feeRefusal)
+        return feeRefusal;
+    // the `metadata` a reversal or a fee refund is created with is its own ("Set of key-value pairs that you can attach to
+    // an object", docs.stripe.com/api/transfer_reversals/create, docs.stripe.com/api/fee_refunds/create)
+    const metadata = ctx.params.metadata && typeof ctx.params.metadata === 'object' ? { metadata: ctx.params.metadata } : {};
+    const child = await created(ctx, o.child, { ...o.childFields(amount), ...metadata }, o.childDefaults);
+    if (o.settle)
+        await o.settle(child, amount);
+    const existing = o.parent[o.flag === 'reversed' ? 'reversals' : 'refunds'] ?? { object: 'list', data: [], has_more: false, total_count: 0 };
+    const data = [...(existing.data ?? []), child];
+    await ctx.write(o.parentResource, id, {
+        [o.doneField]: done, [o.flag]: done >= total,
+        [o.flag === 'reversed' ? 'reversals' : 'refunds']: { ...existing, data, total_count: data.length, url: o.listUrl },
+    }, o.op);
+    return ctx.reply(child);
+}
+export const feeMissing = (ctx, id) => fail(ctx, `No such application fee: '${id}'`, 404, 'resource_missing');
+/** An earlier version's payment_method_types refused: the first value that names no payment method type the
+ *  operation takes, in the intent's words or (a Checkout Session) the enum's. */
+export function unknownMethodType(ctx, opId, given) {
+    const values = Array.isArray(given) ? given : given && typeof given === 'object' ? Object.values(given) : [given];
+    const checkout = opId === 'PostCheckoutSessions';
+    const known = checkout ? CHECKOUT_METHOD_TYPES : PAYMENT_METHOD_TYPES;
+    const i = values.findIndex((v) => !known.includes(String(v)));
+    if (i < 0)
+        return undefined;
+    if (checkout) {
+        const param = `payment_method_types[${i}]`;
+        return ctx.refuse({ status: 400, param, message: `Invalid ${param}: must be one of ${oneOf(known)}` });
+    }
+    const doc = TYPES_DOC[opId.startsWith('PostSetupIntents') ? 'setup_intents' : 'payment_intents'];
+    return ctx.refuse({ status: 400, param: 'payment_method_types', message: `The payment method type "${String(values[i])}" is invalid. See ${doc} for the full list of supported payment method types.` });
+}
+/** payment_method_types refused where the caller's version removed it. */
+export const noLongerSupported = (ctx, version) => ctx.refuse({ status: 400, code: 'payment_method_types_no_longer_supported', param: 'payment_method_types', message: `payment_method_types is no longer supported in API version ${version}. Use allowed_payment_method_types, or dynamic payment methods, instead.` });
+/** Stripe's refusal of a request whose top-level parameters the operation does not take, or undefined. */
+export function refuseParameters(ctx) {
+    const op = OPS.get(ctx.call.operation.id);
+    if (!op)
+        return undefined;
+    const pinned = ctx.call.request.headers.get('stripe-version');
+    const params = ctx.params;
+    if (pinned && pinned < SERVED_VERSION) {
+        if (!TYPED.has(op.id))
+            return undefined;
+        if (params.payment_method_types === undefined)
+            return undefined;
+        if (REMOVED_TYPES.has(op.id) && methodTypesRemoved(pinned))
+            return noLongerSupported(ctx, pinned);
+        return unknownMethodType(ctx, op.id, params.payment_method_types);
+    }
+    const method = ctx.call.request.method.toUpperCase();
+    const known = new Set([...(op.query ?? []), ...(op.body ?? [])].map((p) => p.name).concat(DOCUMENTED[op.id] ?? []));
+    if (REMOVED_TYPES.has(op.id) && params.payment_method_types !== undefined)
+        return noLongerSupported(ctx, pinned ?? SERVED_VERSION);
+    for (const name of Object.keys(params)) {
+        if (!known.has(name))
+            return ctx.refuse({ status: 400, code: 'parameter_unknown', param: name, message: `Received unknown parameter: ${name}` });
+    }
+    const required = method === 'GET' || method === 'DELETE' ? (op.query ?? []) : (op.body ?? []);
+    for (const p of required) {
+        if (p.required && params[p.name] === undefined)
+            return ctx.refuse({ status: 400, code: 'parameter_missing', param: p.name, message: `Missing required param: ${p.name}.` });
+    }
+    return undefined;
+}
+/** A file's links, kept in step with the links made to it, at the address Stripe lists them
+ *  (/v1/file_links?file=…, the File object's example). */
+export async function syncLinks(ctx, fileId) {
+    const data = newest(ctx, 'file_link').filter((l) => l.file === fileId);
+    await ctx.write('file', fileId, { links: { object: 'list', data, has_more: false, url: `/v1/file_links?file=${fileId}` } }, 'file.links_synced');
+}
+// ── calculations: each line's tax on top of its amount; no `created`, a tax_date instead ──
+export const calcMissing = (ctx, id) => fail(ctx, `No such tax calculation: '${id}'`, 404, 'resource_missing');
+/** A page of the line items a stored object carries. */
+export function taxLinePage(ctx, holder) {
+    const li = holder.line_items;
+    const { page, hasMore } = paginate(Array.isArray(li?.data) ? li.data : [], ctx.params);
+    return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: page });
+}
+export const txMissing = (ctx, id, status = 404) => fail(ctx, `No such tax transaction: '${id}'`, status, 'resource_missing');
+/** An answer in the shape of the API version the caller is served (./version.ts), a webhook endpoint's `secret` shown
+ *  only at its creation ("Only returned at creation", docs.stripe.com/api/webhook_endpoints/object). */
+export async function rendered(request, res) {
+    const creates = request.method === 'POST' && new URL(request.url).pathname.replace(/\/+$/, '') === '/v1/webhook_endpoints';
+    const pinned = request.headers.get('stripe-version');
+    if (!(res.headers.get('content-type') ?? '').includes('json'))
+        return res;
+    if (!servesCurrent(pinned) && creates)
+        return res;
+    const expand = await expandOf(request.clone());
+    const body = await res.json();
+    const answered = creates ? body : withoutEndpointSecret(body);
+    return new Response(JSON.stringify(servesCurrent(pinned) ? render(answered, pinned, expand) : answered), { status: res.status, statusText: res.statusText, headers: res.headers });
+}