@volter/twin-stripe 2.0.38 → 3.0.0

package/src/semantics/shared.ts

@@ -1,24 +1,1401 @@
-// What every Stripe family's semantics share: Stripe's list envelope and order, its expand walk,
-// its create stamp, and the answers its hand-written routes gave. All of it is over the
-// SemanticsContext; the manifest (../manifest.ts) says which fields embed which resource.
-import type { SemanticsContext } from '@volter/world-core';
-import surface from '../generated/surface.gen.json' with { type: 'json' };
-import { manifest } from '../manifest.ts';
-import { OBJECT_NAME, paginate, searchOver, stashVendorType, view, type StripeResponse } from '../stripe-twin.ts';
+// What Stripe's manifest takes from its handlers' side: the events its writes send, as data the kernel renders, stores,
+// signs and delivers (world-core events.ts; ./events.ts renders each event's `data` and its further values).
+import type { EventsDecl, Handler, HandlerContext, TwinResource } from '@volter/world-core';
+import { NAMED_EVENTS, readDecision, STRIPE_EVENT_TYPES, STRIPE_REALTIME_AUTH_TIMEOUT_MS, type StripeAuthRequestOutcome, stripeSignature } from '../engine/webhooks.ts';
+import { redactKey, requestKey } from '../engine/oauth.ts';
+import { HOUR, INV, itemQuantity, itemsOf, keptAfter, oneTimeLines, RENEWING, SUB, unspentDiscounts } from '../engine/renewals.ts';
+import { DAY, payoutDay } from '../engine/balance.ts';
+import { AFTER_SUCCESS_CARDS, BY_NUMBER, type Outcome } from '../engine/after-payment.ts';
+import { accountSettings, addBillingInterval, applyCouponDiscount, asBool, buildDiscount, buildSubscriptionItemsList, cardError, chargeDefaults, type CheckoutItem, declineFor, disputeEvidence, lineItemEntries, microdepositsNextAction, mintClientSecret, nowUnix, OBJECT_NAME, paginate, paymentMethodSubObject, PLATFORM_ACCOUNT_ID, priceAmount, requiresAuthentication, requiresMicrodeposits, resolveLineItem, resolveSubscriptionBillingInterval, resolveTrial, searchOver, type StripeResponse, subscriptionItemEntries, subscriptionItemPrice, TEST_TOKEN_DECLINES, threeDsNextAction, validateMoney, view } from '../engine/stripe.ts';
+import { AUTO_VALIDATED, euVatCountry } from '../engine/customers.ts';
+import { SI } from '../engine/setup-intents.ts';
+import { BY_CLIENT_SECRET, PUBLISHABLE_CREATES } from '../engine/front.ts';
+import { WE } from '../engine/webhook-endpoints.ts';
+import { ENTRY, ENTRY_TYPES, FA, TX } from '../engine/treasury.ts';
+import { SECRET } from '../engine/apps-secrets.ts';
+import { draft, invoicePrefix, linesOf, sumLines, transitions, unlinkedLine } from '../engine/invoices.ts';
+import { CN } from '../engine/credit-notes.ts';
+import { CS, type EnteredCard, isOneTime, nestedMetadata } from '../engine/checkout.ts';
+import { externalList, type Find, refundDestination, type Row, SPEC_FIELDS } from '../engine/common.ts';
+import { noBilling, PM, TEST_PM_CARDS, testCardOf } from '../engine/payment-methods.ts';
+import { type Interval, SS } from '../engine/subscription-schedules.ts';
+import { OAUTH_CONNECTIONS } from '../engine/display.ts';
+import { intentCarries, PI, TYPES_GIVEN } from '../engine/payment-intents.ts';
+import { BT, BYPASS_NUMBERS, feeOf, onAccount, UNSENT } from '../engine/ledger.ts';
+import { withoutCard } from '../engine/charges.ts';
+import { MAX_TRIAL, movedTrial } from '../engine/subscriptions.ts';
+import { VL, VLI } from '../engine/radar.ts';
+import { AUTH, CARD, historyEntry, merchantData, PD, REALTIME_WINDOW_SECONDS, TXN } from '../engine/issuing.ts';
+import { has } from '../engine/onboarding.ts';
+import { REFUND_REASONS } from '../engine/refunds.ts';
+import { ADVANCE_SECONDS, CLOCK } from '../engine/test-clocks.ts';
+import { BYPASS_PENDING_CARDS } from '../engine/test-cards.ts';
+import { type ConnectOAuthSettings, PLATFORM_CLIENT_ID, SETTINGS } from '../engine/connect-settings.ts';
+import { controllerOf, customRequirements } from '../engine/connect.ts';
+import { READER } from '../engine/terminal.ts';
+import { expandOf, render, SERVED_VERSION, servesCurrent, withoutEndpointSecret } from '../engine/version.ts';
+import { ALERT, GRANT, METER } from '../engine/billing.ts';
+import { CHECKOUT_METHOD_TYPES, DOCUMENTED, methodTypesRemoved, oneOf, OPS, PAYMENT_METHOD_TYPES, REMOVED_TYPES, TYPED, TYPES_DOC } from '../engine/params.ts';
 
-export type Row = Record<string, unknown>;
+/** 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: EventsDecl = {
+  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' } },
+};
+
+// ── what the handlers share: Stripe's behaviour over the context ──
+
+export type Reads = Pick<HandlerContext, 'rowsRaw'>;
+
+/** Whether a connected account's OAuth connection to the platform was revoked (deauthorized, or its code reused). */
+export function connectionRevoked(ctx: Reads, account: string): boolean {
+  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: Reads, key: string): { account: string; scope: string } | null | undefined {
+  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: HandlerContext, customer: unknown): number {
+  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: HandlerContext, sub: Row): string | undefined {
+  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: HandlerContext, sub: Row): string | undefined {
+  const customer = typeof sub.customer === 'string' ? ctx.get('customer', sub.customer) : undefined;
+  const settings = customer?.invoice_settings as Row | undefined;
+  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: HandlerContext, invoice: Row): Promise<void> {
+  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 as Row[] | undefined) ?? [];
+  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: HandlerContext, sub: Row, o: { start: number; end: number; reason: 'subscription_create' | 'subscription_cycle' | 'subscription_update'; trial?: boolean; once?: Row[]; id?: string }): Promise<string> {
+  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 as Row) : 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 as Row[] | undefined) ?? [])[0];
+  const coupon = discount && typeof discount === 'object' ? (discount.coupon as Row | undefined) : 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: HandlerContext, invoiceId: string, at: number, actor: 'time' | 'external' | 'api', opts: { payer?: string; attempt?: boolean } = {}): Promise<boolean> {
+  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 as Row), 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: HandlerContext, invoiceId: string, paymentMethod: string): Promise<{ code: string; message: string } | undefined> {
+  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: string | null = 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 as Row), 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: HandlerContext, only?: (sub: Row) => boolean): Promise<void> {
+  // 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: HandlerContext, at: (t: number) => Promise<HandlerContext>, only?: (sub: Row) => boolean): Promise<boolean> {
+    // the earliest move that has come due, of any subscription
+    let next: { t: number; kind: 'period' | 'collect'; id: string } | undefined;
+    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: HandlerContext): string | undefined => actingAccount(ctx);
+
+export const payoutMissing = (ctx: HandlerContext, id: string): Response => 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: HandlerContext, acct: string | undefined = account(ctx)): Row {
+  const { available, pending, issuing } = balanceOf(ctx, acct);
+  const toArr = (m: Map<string, number>) => {
+    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: HandlerContext, acct: string | undefined = account(ctx)): Promise<string[]> {
+  const now = Number(nowUnix(ctx.occurredAt));
+  const paid: string[] = [];
+  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: HandlerContext, account: string, currency: string): string | null {
+  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: HandlerContext): Row => ({
+  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: HandlerContext, p: Row): Row {
+  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: HandlerContext, currency: string): Response {
+  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: HandlerContext): Promise<void> {
+  const now = Number(nowUnix(ctx.occurredAt));
+  const platform = ctx.get('account', PLATFORM_ACCOUNT_ID);
+  const accounts: Array<{ id: string | undefined; settings: unknown }> = [{ 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 as Row | undefined) ?? undefined).payouts as Row).schedule ?? {}) as Row;
+    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<unknown>();
+    for (const day of days) {
+      const due = unpaid.filter((t) => !paid.has(t.id) && (Number(t.available_on) || 0) <= day);
+      const byCurrency = new Map<string, Row[]>();
+      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: HandlerContext, ref: unknown): Outcome | undefined {
+  // 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 as Row).token === 'string') return afterSuccessOf(ctx, (ref as Row).token);
+  if (ref && typeof ref === 'object') return BY_NUMBER[String((ref as Row).number ?? '').replace(/\D/g, '')];
+  if (typeof ref !== 'string' || !ref) return undefined;
+  const stored = ctx.row('payment_method', ref);
+  if (stored) return (stored._afterSuccess as Outcome | undefined) ?? 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: HandlerContext, chargeId: string, charge: { amount: number; currency: string; payment_intent?: string | undefined; application_fee_amount?: unknown; destination?: unknown }, ref: unknown): Promise<void> {
+  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: HandlerContext, chargeId: string, pi: { payment_intent: string | null }): Promise<void> {
+  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 as Row | undefined) ?? {};
+  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: HandlerContext, paymentMethod: unknown, use: 'single_use' | 'multi_use', amount?: number, currency?: string): Promise<string> {
+  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: HandlerContext, id: string): Response => 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: HandlerContext, couponId: string): Row | Response {
+  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: HandlerContext, customer: string | undefined): Promise<Response> {
+  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: HandlerContext): { customer?: string } | Response {
+  const owner = (ctx.params.owner ?? {}) as Row;
+  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: HandlerContext, customer: string): Row {
+  const byCurrency: Record<string, number> = {};
+  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: HandlerContext, customer: string, currency: string, reference: string | null): Promise<void> {
+  const takesTransfers = (inv: Row): boolean => ((inv.payment_settings as Row | undefined)?.payment_method_types as unknown[] | undefined)?.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 as Row | null) ?? {})[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 as Row | undefined) ?? {}), paid_at: nowUnix(ctx.occurredAt) },
+    }, 'invoice.paid');
+  }
+}
+
+/** The customer's source the path names, or undefined. */
+export const customerSource = (ctx: HandlerContext): Row | undefined => {
+  const s = ctx.get('source', at(ctx, 'id'));
+  return s && s.customer === at(ctx, 'customer') ? s : undefined;
+};
+
+export const sourceMissing = (ctx: HandlerContext): Response => 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: HandlerContext, operationId: string): { si: Row } | { answer: Response } {
+  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: HandlerContext, url: string, event: Record<string, unknown>, secret: string): Promise<StripeAuthRequestOutcome> {
+  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: HandlerContext): Response | undefined {
+  // 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: HandlerContext): Response | undefined {
+  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 is string => !!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: HandlerContext, request: Request): Response | undefined {
+  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: HandlerContext, request: Request): Promise<Request | Response> {
+  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: HandlerContext, request: Request): 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: Row;
+  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 as Row).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 as Row) : {};
+    // 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 as Row) };
+    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: HandlerContext, id: string, we: Row, fields: Row, off: boolean): Promise<Response> {
+  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: HandlerContext, e: Row): boolean => (typeof e.account === 'string' ? e.account : undefined) === actingAccount(ctx);
+
+export const faMissing = (ctx: HandlerContext, id: string, status = 404): Response => fail(ctx, `No such financial account: '${id}'`, status, 'resource_missing');
+
+export const metadataOf = (ctx: HandlerContext): unknown => (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: HandlerContext, faId: string): Row {
+  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) as Row | undefined;
+  const name = ((platform?.business_profile as Row | undefined)?.name ?? ((platform?.settings as Row | undefined)?.dashboard as Row | undefined)?.display_name ?? PLATFORM_ACCOUNT_ID) as string;
+  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: HandlerContext, faId: string, active: string[]): Row[] => (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: HandlerContext, o: {
+  financial_account: string; amount: number; currency: string; flow: string; flow_type: string;
+  status: 'open' | 'posted'; balance_impact: Row; description: string; flowDetailKey?: string;
+}): Promise<string> {
+  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 as Record<string, Record<string, number>> | undefined) ?? { cash: {}, inbound_pending: {}, outbound_pending: {} };
+    const moved = Object.fromEntries((['cash', 'inbound_pending', 'outbound_pending'] as const).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: HandlerContext): string | Response {
+  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: HandlerContext, dest: string | null): Row {
+  const data = ctx.params.destination_payment_method_data && typeof ctx.params.destination_payment_method_data === 'object' ? (ctx.params.destination_payment_method_data as Row) : {};
+  const bank = data.us_bank_account && typeof data.us_bank_account === 'object' ? (data.us_bank_account as Row) : {};
+  const billing = data.billing_details && typeof data.billing_details === 'object' ? (data.billing_details as Row) : {};
+  const address = billing.address && typeof billing.address === 'object' ? (billing.address as Row) : {};
+  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: HandlerContext): Response {
+  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: HandlerContext, origin: string): Row | Response | undefined {
+  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: 'received_credit' | 'received_debit'): Handler {
+  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 as number;
+    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: string, param: string, name: string, operationId: string, op: string, checkCancelable: boolean): Handler {
+  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 as object), void_at: nowUnix(ctx.occurredAt) } }, 'treasury_transaction.voided');
+      const account = ctx.get(FA, String(txn.financial_account));
+      const impact = (txn.balance_impact as Record<string, number> | undefined) ?? {};
+      const cur = String(txn.currency ?? 'usd');
+      if (account) {
+        const bal = (account.balance as Record<string, Record<string, number>> | undefined) ?? { cash: {}, inbound_pending: {}, outbound_pending: {} };
+        const back = Object.fromEntries((['cash', 'inbound_pending', 'outbound_pending'] as const).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 as object), canceled_at: nowUnix(ctx.occurredAt) } }, op));
+  };
+}
+
+// the ledger is always read for one account
+export function ledger(resource: string, spec: Record<string, (r: Row, v: unknown) => boolean>): Handler {
+  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: HandlerContext): string {
+  const scope = ctx.params.scope && typeof ctx.params.scope === 'object' ? (ctx.params.scope as Row) : undefined;
+  const scopeType = scope && typeof scope.type === 'string' ? scope.type : 'account';
+  return scopeType === 'user' ? `user:${String(scope!.user)}` : 'account';
+}
+
+export const named = (ctx: HandlerContext, name: string): Row | undefined => ctx.rows(SECRET).find((s) => s.name === name && kept(ctx, SECRET, s, '_scope_key') === scopeKeyOf(ctx));
+
+export const invoiceMissing = (ctx: HandlerContext, id: string): Response => 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: HandlerContext, invoiceId: string, next: Row[]): Promise<Row> {
+  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: HandlerContext): Response {
+  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: HandlerContext, subId: string): Promise<void> {
+  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: HandlerContext, invoiceId: string): Promise<void> {
+  const inv = ctx.get(INV, invoiceId);
+  if (!inv || inv.status !== 'draft') return;
+  const next: Row[] = [];
+  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 as string) ?? 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: HandlerContext, priceRef: string, qty: number): { amount: number; currency: string | undefined } | Response {
+  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: HandlerContext, id: string): Response => 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: HandlerContext, customer: string, currency: string, parent: Row, lines: Array<{ price: unknown; quantity: number; amount: number; description: unknown }>): Promise<string> {
+  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 as Row).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: HandlerContext, invoiceId: string, inv: Row, item: Row, now: number): Promise<void> {
+  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 as string) ?? 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: HandlerContext, operationId: string): { inv: Row } | { answer: Response } {
+  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: HandlerContext, piId: string, inv: Row, invoiceId: string): Promise<void> {
+  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: HandlerContext, inv: Row, now: number): Row {
+  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: Row = { 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: 'add' | 'update' | 'remove'): Handler {
+  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 as Row[]) : raw && typeof raw === 'object' ? [raw as Row] : [];
+    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: HandlerContext, id: string): Response => 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: HandlerContext, id: string): Row | Response {
+  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: HandlerContext, invoiceId: string): Promise<void> {
+  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: HandlerContext, id: string, cn: Row): Promise<Row | Response> {
+  const params = ctx.params;
+  const out: Row = {};
+  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()) as Row;
+    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: HandlerContext, params: Record<string, unknown>): number | Response {
+  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: HandlerContext): Promise<void> {
+  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: HandlerContext, id: string): Response => 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: HandlerContext, p: Row | undefined): p is Row => !!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: HandlerContext): CheckoutItem[] | Response {
+  const entries = lineItemEntries(ctx.params);
+  const items: CheckoutItem[] = [];
+  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: HandlerContext, holder: Row): Response {
+  const li = holder.line_items as { data?: Row[] } | undefined;
+  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: HandlerContext, id: string): Response => fail(ctx, `No such payment link: '${id}'`, 404, 'resource_missing');
+
+// ── quotes ──
+
+export const quoteMissing = (ctx: HandlerContext, id: string): Response => fail(ctx, `No such quote: '${id}'`, 404, 'resource_missing');
 
-export const send = (ctx: SemanticsContext, r: StripeResponse): Response => ctx.reply(r.body, r.status);
+export function move(action: 'finalize' | 'accept' | 'cancel', operationId: string): Handler {
+  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: Row = {};
+    if (action === 'accept') {
+      const lines = ((q.line_items as Row | undefined)?.data as Row[] | undefined) ?? [];
+      const recurring = lines.some((l) => l.price && typeof l.price === 'object' && (l.price as Row).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 as Row) ?? {}), ...stamp },
+        ...(action === 'finalize' ? { number: `QT-${id.toUpperCase()}` } : {}),
+        ...made,
+      }, `quote.${action}`),
+    );
+  };
+}
+
+export const sessionMissing = (ctx: HandlerContext, id: string): Response => 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: HandlerContext, params: Row, now: number): { coupon: Row; promotion?: string } | Response | undefined {
+  const first = Array.isArray(params.discounts) ? (params.discounts[0] as Row | undefined) : undefined;
+  if (!first || typeof first !== 'object') return undefined;
+  const expired = (what: string) => ctx.refuse({ status: 400, code: 'coupon_expired', param: 'discounts', message: `This ${what} has expired.` });
+  let promotion: string | undefined;
+  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 as Row | undefined)?.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: HandlerContext): Response {
+  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: HandlerContext, destination: unknown): Response {
+  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: HandlerContext, data: unknown, now: number): Response | undefined {
+  if (!data || typeof data !== 'object') return undefined;
+  const { trial_end: end, trial_period_days: days } = data as Row;
+  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: HandlerContext, param: 'trial_end' | 'trial_period_days'): Response {
+  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: HandlerContext, id: string, existing: Row, card?: EnteredCard): Promise<Row> {
+  const link: Row = { 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 ?? {}) as Row).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 ?? {}) as Row;
+    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 as Row).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 as Array<Row | null> | undefined) ?? [];
+      const lines = ((existing.line_items as { data?: unknown } | undefined)?.data as Row[] | undefined) ?? [];
+      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 : {}) as Row;
+      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 as Row | undefined)?.data as Row[] | undefined) ?? []);
+      // 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: HandlerContext, lines: Row[], inline: Array<Row | null>): Promise<Row[]> {
+  const out: Row[] = [];
+  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 as Row) : 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 as Row) : 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: HandlerContext, customer: string | undefined, pm: Row | undefined): Promise<unknown> {
+  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: HandlerContext, id: string, customer: string, now: number): Row[] {
+  const d = ctx.row(CS, id)?._discount as Row | undefined;
+  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: HandlerContext, id: string, existing: Row, details: Row = {}, card?: EnteredCard): Promise<Row | Response> {
+  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 as Row | undefined;
+  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: HandlerContext, r: StripeResponse): Response => 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: SemanticsContext, message: string, status = 404, code?: string): Response => ctx.refuse({ status, message, ...(code ? { code } : {}) });
+export const fail = (ctx: HandlerContext, message: string, status = 404, code?: string): Response => ctx.refuse({ status, message, ...(code ? { code } : {}) });
 
 /** A file parameter whose description requires a purpose refuses a file of another one. The served spec requires it
  *  on every such parameter ("Must have a `purpose` value of `issuing_logo`", personalization designs' card_logo;
  *  "The file's `purpose` must be one of the following: …", file links' file). Where the documentation stops and the
  *  twin decides: Stripe documents no error for it (docs.stripe.com/error-codes names none), so the twin answers the
  *  400 invalid_request_error it answers for an unknown file, naming the parameter and the purposes allowed. */
-export function filePurposeRefused(ctx: SemanticsContext, param: string, allowed: readonly string[]): Response | undefined {
+export function filePurposeRefused(ctx: HandlerContext, param: string, allowed: readonly string[]): Response | undefined {
   const given = ctx.params[param];
   if (given === undefined || given === '') return undefined;
   const file = ctx.get('file', String(given));
@@ -29,15 +1406,15 @@ export function filePurposeRefused(ctx: SemanticsContext, param: string, allowed
 }
 
 /** The request's path, as the list envelope's `url` carries it. */
-export const path = (ctx: SemanticsContext): string => new URL(ctx.call.request.url).pathname.replace(/\/+$/, '') || '/';
+export const path = (ctx: HandlerContext): string => new URL(ctx.call.request.url).pathname.replace(/\/+$/, '') || '/';
 
 /** A path parameter, by the name the spec gives it. */
-export const at = (ctx: SemanticsContext, name: string): string => ctx.call.params[name] ?? '';
+export const at = (ctx: HandlerContext, name: string): string => ctx.call.params[name] ?? '';
 
 /** An update's fields laid over what is stored, as the derived core does: a nested hash is merged into the stored one,
  *  not put in its place (Stripe updates only the keys a request names; docs.stripe.com/api/metadata and each update
  *  reference), and an empty string unsets a key. */
-export function mergeUpdate(ctx: SemanticsContext, resource: string, id: string, fields: Row): Row {
+export function mergeUpdate(ctx: HandlerContext, resource: string, id: string, fields: Row): Row {
   const current = ctx.get(resource, id) ?? {};
   const out: Row = {};
   for (const [k, v] of Object.entries(fields)) {
@@ -49,27 +1426,14 @@ export function mergeUpdate(ctx: SemanticsContext, resource: string, id: string,
   return out;
 }
 
-/** The tree's type for a resource: what its rows are stored under. */
-export const stored = (resource: string): string => 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: SemanticsContext, resource: string, row: Row, key: string): unknown => 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: Row, now: unknown): Row {
-  const coupon = d.coupon && typeof d.coupon === 'object' ? String((d.coupon as Row).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,
-  };
-}
+export const kept = (ctx: HandlerContext, resource: string, row: Row, key: string): unknown => ctx.row(resource, String(row.id), { withDeleted: true })?.[key];
 
 /** 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. */
-export function confirmOnly(ctx: SemanticsContext, names: string[], confirm: boolean): Response | undefined {
+export function confirmOnly(ctx: HandlerContext, names: string[], confirm: boolean): Response | undefined {
   const sent = confirm ? undefined : names.find((n) => ctx.params[n] !== undefined);
   return sent ? fail(ctx, `\`${sent}\` can only be used when \`confirm\` is set to \`true\`.`, 400, 'parameter_invalid') : undefined;
 }
@@ -78,40 +1442,35 @@ export function confirmOnly(ctx: SemanticsContext, names: string[], confirm: boo
  *  applied to a customer" (the served spec's coupon), counts it, as the code's "Number of times this promotion code
  *  has been used" (its promotion_code). Where the documentation stops and the twin decides: reaching max_redemptions
  *  does not yet lapse the coupon. */
-export async function redeemCoupon(ctx: SemanticsContext, couponId: unknown, promotionCode?: unknown): Promise<void> {
+export async function redeemCoupon(ctx: HandlerContext, couponId: unknown, promotionCode?: unknown): Promise<void> {
   const coupon = typeof couponId === 'string' ? ctx.get('coupon', couponId) : undefined;
   if (coupon) await ctx.write('coupon', couponId as string, { times_redeemed: (Number(coupon.times_redeemed) || 0) + 1 }, 'coupon.redeemed');
   const code = typeof promotionCode === 'string' ? ctx.get('promotion_code', promotionCode) : undefined;
   if (code) await ctx.write('promotion_code', promotionCode as string, { times_redeemed: (Number(code.times_redeemed) || 0) + 1 }, 'promotion_code.redeemed');
 }
 
-export function newest(ctx: SemanticsContext, resource: string, timeField = 'created'): Row[] {
+export function newest(ctx: HandlerContext, resource: string, timeField = 'created'): Row[] {
   // 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: Row): number => 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: unknown, v: unknown): boolean {
-  const at = Number(t);
-  const r = (v && typeof v === 'object' ? v : { gte: v, lte: v }) as Row;
-  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. */
-export function at_(ctx: SemanticsContext): (t: number) => Promise<SemanticsContext> {
+export function at_(ctx: HandlerContext): (t: number) => Promise<HandlerContext> {
   return (t) => ctx.at(new Date(t * 1000).toISOString());
 }
 
-export function where(ctx: SemanticsContext, items: Row[], spec: Record<string, (item: Row, value: unknown) => boolean>): Row[] {
+export function where(ctx: HandlerContext, items: Row[], spec: Record<string, (item: Row, value: unknown) => boolean>): Row[] {
   let out = items;
   for (const [key, pred] of Object.entries(spec)) {
     const value = ctx.params[key];
@@ -120,107 +1479,1734 @@ export function where(ctx: SemanticsContext, items: Row[], spec: Record<string,
   return out;
 }
 
-function expandPaths(ctx: SemanticsContext): string[][] {
+export function expandPaths(ctx: HandlerContext): string[][] {
   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: SemanticsContext, t: Row): Row {
+ *  asked of the machine as a write asks it (./ledger.ts). */
+export function commonAsOf(ctx: HandlerContext, t: Row): Row {
   const due = Number(t.available_on);
-  if (t.status !== 'pending' || !Number.isFinite(due) || due > Number(ctx.now())) return t;
+  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. */
-export function expandRow(ctx: SemanticsContext, resource: string, body: Row, paths: string[][]): Row {
-  const embeds = manifest.resources[resource]?.embeds;
-  if (!embeds || paths.length === 0) return body;
-  let out = body;
-  const byHead = new Map<string, string[][]>();
-  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 as Row) : 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;
+/** 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: HandlerContext, resource: string, body: Row, paths: string[][]): Row {
+  if (paths.length === 0) return body;
+  const asOf = (v: unknown): unknown => {
+    if (Array.isArray(v)) return v.map(asOf);
+    if (!v || typeof v !== 'object') return v;
+    const o = Object.fromEntries(Object.entries(v as Row).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: SemanticsContext, resource: string, body: Row): Row => expandRow(ctx, resource, body, expandPaths(ctx));
+export const expanded = (ctx: HandlerContext, resource: string, body: Row): Row => expandRow(ctx, resource, body, expandPaths(ctx));
 
 /** Stripe's list envelope over rows already in list order: a page, `has_more`, and `expand[]=data.*`. */
-export function list(ctx: SemanticsContext, resource: string, items: Row[]): Response {
+export function list(ctx: HandlerContext, resource: string, items: Row[]): Response {
   const { page, hasMore } = paginate(items, ctx.params);
   const paths = expandPaths(ctx).filter((p) => p[0] === 'data').map((p) => p.slice(1)).filter((p) => p.length > 0);
   return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: paths.length ? page.map((r) => expandRow(ctx, resource, r, paths)) : page });
 }
 
 /** Stripe's search over a resource's rows (`query` in its search language). */
-export const search = (ctx: SemanticsContext, resource: string, timeField = 'created'): Response => send(ctx, searchOver(newest(ctx, resource, timeField), ctx.params, path(ctx)));
-
-const SPEC_FIELDS = new Map((surface.resources as Array<{ name: string; fields: Array<{ name: string }> }>).map((r) => [r.name, new Set(r.fields.map((f) => f.name))]));
+export const search = (ctx: HandlerContext, resource: string, timeField = 'created'): Response => send(ctx, searchOver(newest(ctx, resource, timeField), ctx.params, path(ctx)));
 
 /** 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.) */
-export async function created(ctx: SemanticsContext, resource: string, params: Row, defaults: Row, opts: { timeField?: string; operation?: string } = {}): Promise<Row> {
+ *  ./version.ts.) */
+export async function created(ctx: HandlerContext, resource: string, params: Row, defaults: Row, opts: { timeField?: string; operation?: string } = {}): Promise<Row> {
   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`);
 }
 
-/** A stored subject of any stored type, tombstones included, in the pack's view: what the pack's
- *  shared helpers look a price, a payment method or a card up by, read from the context's tree. */
-export type Find = (storedType: string, id: string) => Row | undefined;
-export const finder = (ctx: SemanticsContext): Find => {
-  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: Pick<HandlerContext, 'rowsRaw'>): Find => (storedType, id) => {
+  const r = ctx.rowsRaw(storedType, { withDeleted: true }).find((x) => x.id === id);
+  return r ? view(storedType, r as TwinResource) : 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: Row, type: 'refund' | 'reversal'): Row {
-  const pmd = charge.payment_method_details as Row | null | undefined;
-  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: string, data: Row[]): Row => ({ 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: SemanticsContext, account: string): Promise<void> {
+export async function syncExternals(ctx: HandlerContext, account: string): Promise<void> {
   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<T>(ctx: HandlerContext, decision: (rows: (resource: string) => Row[]) => { value: T; write?: { resource: string; id: string; fields: Row; operation: string } }): Promise<T> {
+  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: HandlerContext, data: Row[]): Response => ctx.reply({ object: 'list', url: path(ctx), has_more: false, data });
+
+export const orderMissing = (ctx: HandlerContext, id: string): Response => 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: HandlerContext): Promise<void> {
+  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: HandlerContext, lookupKey: string): Response {
+  return fail(ctx, `A feature with lookup_key '${lookupKey}' already exists.`, 400, 'resource_already_exists');
+}
+
+export const pmMissing = (ctx: HandlerContext, id: string): Response => 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: HandlerContext, ref: unknown): Row | undefined {
+  let card: Row | undefined;
+  // 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] as Row | undefined) ?? {};
+    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 as Row | undefined;
+    if (stored) card = stored;
+    else card = testCardOf(ref);
+  } else if (ref && typeof ref === 'object') card = paymentMethodSubObject('card', { card: ref }).card as Row;
+  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: HandlerContext, id: string): boolean => !!ctx.get(PM, id) || (id.startsWith('pm_card_') && (id in TEST_TOKEN_DECLINES || id in AFTER_SUCCESS_CARDS));
+
+export async function attachPaymentMethod(ctx: HandlerContext, id: string, customer: string): Promise<Row> {
+  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: HandlerContext, id: string, customer: string | null): Promise<Row> {
+  const card = TEST_PM_CARDS[id] ?? { brand: 'visa', number: '4242424242424242' };
+  const sub = paymentMethodSubObject('card', { card: { number: card.number } });
+  (sub.card as Record<string, unknown>).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: HandlerContext, data: unknown): Promise<string | undefined> {
+  if (!data || typeof data !== 'object') return undefined;
+  const d = data as Row;
+  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 as Row | undefined) ?? {}) },
+    ...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: HandlerContext, params: Row, intent: Row, pm: string | undefined): boolean {
+  const options = ((params.payment_method_options ?? intent.payment_method_options) as Row | undefined)?.us_bank_account as Row | undefined;
+  return options?.verification_method === 'microdeposits' && !!pm && ctx.get(PM, pm)?.type === 'us_bank_account';
+}
+
+export const scheduleMissing = (ctx: HandlerContext, id: string): Response => 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: HandlerContext, given: Row[], start: number): Row[] {
+  let cursor = start;
+  return given.map((p) => {
+    const items = (Array.isArray(p.items) ? (p.items as Row[]) : []).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 as string) : undefined;
+    const recurring = (price?.recurring as Row | undefined) ?? {};
+    const d = p.duration && typeof p.duration === 'object' ? (p.duration as Row) : undefined;
+    const startDate = cursor;
+    const end = p.end_date !== undefined && p.end_date !== 'now' ? Number(p.end_date)
+      : d ? addBillingInterval(startDate, String(d.interval) as Interval, Math.max(1, Number(d.interval_count) || 1))
+      : addBillingInterval(startDate, String(recurring.interval ?? 'month') as Interval, 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: 'cancel' | 'release'): Handler {
+  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: HandlerContext): Response {
+  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: HandlerContext, ba: Row): Row {
+  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: HandlerContext, id: string): Response => 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: HandlerContext): Response {
+  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: HandlerContext): Response {
+  return fail(ctx, 'This feature is already attached to the product.', 400, 'resource_already_exists');
+}
+
+export const productFeature = (ctx: HandlerContext): Row | undefined => {
+  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: HandlerContext): Response => 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: HandlerContext, params: Row): Promise<Response> {
+  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 as Row[]) : [];
+  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: HandlerContext, id: string): boolean =>
+  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: HandlerContext, r: StripeResponse): Response => ctx.reply(r.body, r.status);
+
+export async function mintCharge(ctx: HandlerContext, piId: string, pi: Row, amount: number): Promise<string> {
+  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 as Row | undefined)?.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: HandlerContext, piId: string, pi: Row, amount: number): Promise<string> {
+  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: HandlerContext, pi: Row, operationId: string, actor?: 'vendor'): Promise<void> {
+  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 as object) ?? {}), 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: HandlerContext, operationId: string): { pi: Record<string, unknown> } | { answer: Response } {
+  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: HandlerContext, method: unknown): string | undefined {
+  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: HandlerContext, existing: Row, params: Row): Response | undefined {
+  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 as unknown[]).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: HandlerContext, existing: Record<string, unknown>, params: Record<string, unknown>): Promise<Response> {
+  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: HandlerContext): Response {
+  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: HandlerContext, method: unknown): boolean {
+  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: HandlerContext, method: unknown): boolean {
+  if (method === 'pm_usBankAccount_processing') return true;
+  const bank = typeof method === 'string' ? (ctx.get('payment_method', method)?.us_bank_account as Row | undefined) : 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: HandlerContext, id: string, fields: Row): Promise<Row> {
+  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: HandlerContext): Promise<void> {
+  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) as Row | 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] as Row | undefined) ?? {}), 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: HandlerContext, pi: Row, fields: Row = {}): Promise<Row> {
+  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: HandlerContext, card: string | undefined): boolean {
+  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: HandlerContext): string | undefined => 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: HandlerContext, fields: Row, account: string | null | undefined = actingAccount(ctx)): Promise<string> {
+  // 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: HandlerContext, chargeId: string, amount: number, currency: string, card?: string): Promise<string> {
+  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: HandlerContext, refundId: string, amount: number, currency: string, account: string | null | undefined = actingAccount(ctx)): Promise<string> {
+  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: HandlerContext, account: string | undefined, currency: string, at: number): number {
+  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: HandlerContext, account: string | undefined, currency: string, from: number, until: number): number[] {
+  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: HandlerContext, disputeId: string, amount: number, currency: string): Promise<string> {
+  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: HandlerContext, disputeId: string, amount: number, currency: string): Promise<string> {
+  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: HandlerContext, account: string | undefined): Row[] {
+  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: HandlerContext, payoutId: string, amount: number, currency: string, account: string | undefined, at: number, entries: Row[]): Promise<string> {
+  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: HandlerContext, payoutId: string, amount: number, currency: string, account: string | null | undefined = actingAccount(ctx)): Promise<string> {
+  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: HandlerContext, transferId: string, amount: number, currency: string, destination: string, fromCharge?: number, fromPending = false): Promise<string> {
+  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: HandlerContext, reversalId: string, amount: number, currency: string, destination: string): Promise<string> {
+  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: HandlerContext, feeId: string, amount: number, currency: string, account: string): Promise<string> {
+  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: HandlerContext, topupId: string, amount: number, currency: string, destination: string): Promise<string> {
+  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: HandlerContext, account: string | undefined = actingAccount(ctx)): Promise<Row[]> {
+  const now = Number(nowUnix(ctx.occurredAt));
+  const moved: Row[] = [];
+  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: HandlerContext, account: string | undefined = actingAccount(ctx)): { available: Map<string, number>; pending: Map<string, number>; issuing: Map<string, number> } {
+  const available = new Map<string, number>();
+  const pending = new Map<string, number>();
+  const issuing = new Map<string, number>();
+  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: HandlerContext, amount: number, currency: string, account: string | undefined = actingAccount(ctx)): Response | undefined {
+  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: HandlerContext): Set<unknown> => new Set(ctx.rowsRaw(BT).filter((t) => onAccount(t, actingAccount(ctx))).map((t) => t.id));
+
+export const chargeMissing = (ctx: HandlerContext, id: string): Response => 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: HandlerContext, c: Row): Row {
+  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: HandlerContext, decline: { code: string; decline_code?: string; message: string }): Promise<Response> {
+  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: HandlerContext, existing: Row, fd: Row): Row | Response {
+  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 as Row) : {};
+  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: HandlerContext, ch: Row, operationId: string, given: Row = {}): Promise<Row> {
+  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: HandlerContext, ch: Row): Promise<Row> {
+  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: HandlerContext, ch: Row, toCapture: number, _operationId: string): Promise<Row> {
+  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: HandlerContext): Row | Response => {
+  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: HandlerContext, id: string): Response => 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: HandlerContext, couponId: string, sub: Row): Row[] | Response {
+  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: HandlerContext, value: unknown, now: number): Response | undefined {
+  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: HandlerContext): Response {
+  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: HandlerContext, sub: Row, fields: Row, now: number): Promise<{ invoice: string; payer?: string; attempt: boolean } | undefined> {
+  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: Row = { ...sub, ...fields, items: ctx.get(SUB, id)?.items ?? sub.items };
+  const { interval, interval_count } = resolveSubscriptionBillingInterval(((next.items as { data?: Row[] } | undefined)?.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: HandlerContext, sub: Row): string | undefined {
+  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: HandlerContext, sub: Row, discounts: Row[] | undefined): Response | undefined {
+  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: HandlerContext, price: unknown): Row | undefined {
+  return typeof price === 'string' ? ctx.get('price', price) : price && typeof price === 'object' ? (price as Row) : 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: HandlerContext, sub: Row, entries: Row[]): number {
+  const lines = new Map<string, { price: Row | undefined; quantity: number }>();
+  for (const it of ((sub.items as { data?: Row[] } | undefined)?.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: HandlerContext, lines: Map<string, { price: Row | undefined; quantity: number }>, e: Row, i: number): void {
+  // an inline price bills as the Price inlinePrice makes of it
+  const d = e.price_data && typeof e.price_data === 'object' ? (e.price_data as Row) : undefined;
+  const inline: Row | undefined = 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: HandlerContext, sub: Row): Response | undefined {
+  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: HandlerContext, sub: Row, discounts: Row[] | undefined): { due: number; pays: boolean; declined?: ReturnType<typeof declineFor> } {
+  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 as Row[] | undefined) ?? [])[0];
+  const coupon = discount && typeof discount === 'object' ? (discount.coupon as Row | undefined) : 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: HandlerContext): Response {
+  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: HandlerContext, declined: Parameters<typeof cardError>[0] | null | undefined): Response {
+  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: HandlerContext, subId: string, entries: Row[]): Promise<Response | undefined> {
+  // 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: HandlerContext, subId: string, entries: Row[]): Response | undefined {
+  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 as Row) : 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: HandlerContext, subId: string, entries: Row[]): Promise<undefined> {
+  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 as Row) : 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 as Row).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: HandlerContext, d: Row): Response | undefined {
+  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 as Row | undefined)?.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: HandlerContext, d: Row): Promise<string> {
+  const r = d.recurring as Row;
+  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: HandlerContext, subId: string, items: Row[]): Promise<void> {
+  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: HandlerContext, subId: string): Promise<void> {
+  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: HandlerContext, si: Row): Row => {
+  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: HandlerContext, id: string): Response => fail(ctx, `No such subscription_item: '${id}'`, 404, 'resource_missing');
+
+export const listMissing = (ctx: HandlerContext, id: string, status = 404): Response => 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: HandlerContext, listId: string): Promise<void> {
+  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: HandlerContext, resource: string, operationId: string, current: unknown, values: string[]): Response | undefined {
+  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: HandlerContext, a: Row): Row {
+  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: HandlerContext, id: string): Response => 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: HandlerContext, authId: string, auth: Row, amountCents: number): Promise<{ txnId: string; btId: string }> {
+  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: HandlerContext, what: 'card_status' | 'authorization_method' | 'not_capturable', auth?: Row): Response {
+  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: HandlerContext, auth: Row): Response | undefined {
+  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 as Row | null | undefined)?.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: boolean): Handler {
+  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 as Row[]) : [];
+    // 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: HandlerContext): Promise<void> {
+  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 as Row | undefined)?.object as Row | undefined)?.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 as Row[]) : []), 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: HandlerContext, authId: string, amount: number, currency: string): Promise<Row> {
+  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: HandlerContext, subject: Row, fields: Row, held: number, entry: Row): Promise<Response> {
+  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: HandlerContext, outcome: { kind: 'approved'; amount?: number } | { kind: 'declined' } | { kind: 'error'; message: string }, o: {
+  subject: Row; fields: Row; amount: number; controllable: boolean; entry: (e: { amount: number; approved: boolean; reason: string; reasonMessage: string | null }) => Row;
+  decline: (reason: string, message: string | null) => Promise<Response>;
+}): Promise<Response> {
+  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: HandlerContext, id: string): Response => 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: HandlerContext, id: string): Response => fail(ctx, `No such personalization design: '${id}'`, 404, 'resource_missing');
+
+export function review(action: 'activate' | 'deactivate' | 'reject', operationId: string): Handler {
+  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 as Row) : 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: HandlerContext): Response {
+  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: HandlerContext, customer: string, currency: string, amount: number, refundId: string): Promise<void> {
+  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: HandlerContext, charge: Row, amount: number, remaining: number, params: Row): Promise<Response> {
+  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: HandlerContext, charge: Row, params: Row): Promise<Response> {
+  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 as unknown[] | undefined) ?? []).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 as Row | null | undefined)?.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: number): number => Math.round((whole * amount) / (total || 1));
+  let transferReversal: string | null = 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 as Row | undefined) ?? { object: 'list', data: [], has_more: false, total_count: 0 };
+    const data = [...(((list.data as unknown[]) ?? [])), 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 as Row | undefined) ?? { object: 'list', data: [], has_more: false, total_count: 0 };
+      const data = [...(((list.data as unknown[]) ?? [])), 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: HandlerContext): Promise<void> {
+  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: HandlerContext): Row | Response {
+  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: HandlerContext, id: string): Response => 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: HandlerContext): Promise<void> {
+  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 as { advancing?: { target_frozen_time?: number } } | undefined)?.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: Pick<HandlerContext, 'rowsRaw'>): ConnectOAuthSettings {
+  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 as string[]) : [] };
+}
+
+export const accountMissing = (ctx: HandlerContext, id: string, status = 404): Response => 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: HandlerContext, id: string): Row | undefined => 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: HandlerContext, id: string): Promise<void> {
+  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: HandlerContext, id: string, account: Row): Promise<void> {
+  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: Row = {};
+  for (const [key, was] of Object.entries((account.capabilities as Row | undefined) ?? {})) {
+    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 as Row | undefined) ?? {}), 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: HandlerContext): Response => fail(ctx, `No such person: '${at(ctx, 'person')}'`, 404, 'resource_missing');
+
+export const accountPerson = (ctx: HandlerContext): Row | undefined => {
+  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: HandlerContext): Response => fail(ctx, `No such external account: '${at(ctx, 'id')}'`, 404, 'resource_missing');
+
+export const accountExternal = (ctx: HandlerContext): Row | undefined => {
+  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: HandlerContext, account: string): Response | undefined {
+  const row = accountRow(ctx, account);
+  const controller = (row?.controller as Row | undefined) ?? controllerOf(String(row?.type ?? 'standard'));
+  const dashboard = String(((controller.stripe_dashboard as Row | undefined)?.type) ?? '');
+  const losses = String(((controller.losses as Row | undefined)?.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: string, param: string, missing: string, op: string): Handler {
+  return (ctx) => patchRow(ctx, resource, param, missing, op);
+}
+
+export async function patchRow(ctx: HandlerContext, resource: string, param: string, missing: string, op: string): Promise<Response> {
+  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: Handler = patch(READER, 'reader', 'reader', 'terminal_reader.updated');
+
+export function remove(resource: string, param: string, missing: string, op: string, object: string): Handler {
+  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: HandlerContext, id: string): Response => fail(ctx, `No such reader: '${id}'`, 404, 'resource_missing');
+
+/** A card presented to a reader with no payment in progress. */
+export function nothingToPresent(ctx: HandlerContext): Response {
+  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: HandlerContext, piId: string, pi: Record<string, unknown>, pm: string, amount: number): Promise<void> {
+  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: HandlerContext): Promise<void> {
+  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: HandlerContext, id: string): Response => 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: HandlerContext, id: string, fields: Row): Promise<Response> {
+  return ctx.reply(await ctx.write('dispute', id, fields, 'dispute.update'));
+}
+
+export const meterMissing = (ctx: HandlerContext, id: string): Response => fail(ctx, `No such meter: '${id}'`, 404, 'resource_missing');
+
+export function activation(kind: 'deactivate' | 'reactivate'): Handler {
+  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: HandlerContext, id: string): Response => 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: 'expire' | 'void'): Handler {
+  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: 'activate' | 'deactivate' | 'archive', operationId: string): Handler {
+  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: HandlerContext, id: string): Response => fail(ctx, `No such transfer: '${id}'`, 404, 'resource_missing');
+
+/** A transfer to an account whose transfers capability is not active. */
+export function transfersInactive(ctx: HandlerContext): Response {
+  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: HandlerContext, amount: number, currency: string): Response | undefined {
+  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: HandlerContext, resource: string, flag: string, id: string): Response | undefined {
+  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: HandlerContext, o: {
+  parent: Row; parentResource: string; child: string; childFields: (amount: number) => Row; childDefaults: Row;
+  doneField: string; flag: string; listUrl: string; op: string; tooLarge: (remaining: number) => string;
+  /** what the money movement itself writes, once the child exists */
+  settle?: (child: Row, amount: number) => Promise<void>;
+}): Promise<Response> {
+  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'] as Row) ?? { object: 'list', data: [], has_more: false, total_count: 0 };
+  const data = [...((existing.data as unknown[]) ?? []), 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: HandlerContext, id: string): Response => 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: HandlerContext, opId: string, given: unknown): Response | undefined {
+  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: HandlerContext, version: string): Response =>
+  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: HandlerContext): Response | undefined {
+  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: HandlerContext, fileId: string): Promise<void> {
+  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: HandlerContext, id: string): Response => fail(ctx, `No such tax calculation: '${id}'`, 404, 'resource_missing');
+
+/** A page of the line items a stored object carries. */
+export function taxLinePage(ctx: HandlerContext, holder: Row): Response {
+  const li = holder.line_items as { data?: Row[] } | undefined;
+  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: HandlerContext, id: string, status = 404): Response => 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: Request, res: Response): Promise<Response> {
+  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 });
+}