@volter/twin-stripe 0.1.1 → 2.0.0

package/src/manifest.ts

@@ -0,0 +1,1097 @@
+// Stripe's manifest: the vendor facts its published spec does not carry, and the resources the
+// derived core serves (docs/contributing/architecture.md, "Protocol 3"). The surface itself is
+// generated (./generated/surface.gen.json, from ../spec by scripts/derive-pack.ts).
+import type { DerivedManifest, StateField, Transition } from '@volter/world-core';
+import { afterStripeWrite, embedIssuingAuthorizationCard, isValidApiVersion, view } from './stripe-twin.ts';
+
+const unexpected = (verb: string, allowed: string) => ({
+  status: 400,
+  code: 'payment_intent_unexpected_state',
+  message: `This PaymentIntent could not be ${verb} because it has a status of {from}. ${allowed}`,
+});
+const OPEN = ['requires_payment_method', 'requires_confirmation', 'requires_action', 'requires_capture', 'processing'];
+
+/** A move no API call makes: Stripe's own (`vendor`), the clock's (`time`), or the person on a
+ *  Stripe-hosted page (`external`: Checkout, the billing portal, a hosted invoice or 3DS page). */
+const by = (actor: 'vendor' | 'time' | 'external', from: string[], to: string, source: string): Transition => ({ actor, from, to, source });
+/** A bank account's `status` as a payout or payment destination. Stripe validates its routing number,
+ *  verifies it (micro-deposits, or instantly) and marks it errored when a payout or debit to it fails
+ *  (the page each machine cites); no call the twin serves does any of that (the customer-source verify is
+ *  a gap), so no move of it is the twin's. */
+const bankAccountStatus = (_doc: string): StateField => ({ initial: 'new', transitions: [] });
+
+/** A flag an update sets either way. */
+const flag = (operation: string, source: string): Transition[] => ['true', 'false'].map((to) => ({ operation, from: '*' as const, to, source }));
+
+/** A PaymentIntent's `status`: which operation may move it from where, and what Stripe answers otherwise. */
+const paymentIntentStatus: StateField = {
+  // "After you create the PaymentIntent, its status is `requires_payment_method` until you attach a payment method"
+  // (docs.stripe.com/payments/paymentintents/lifecycle)
+  initial: 'requires_payment_method',
+  transitions: [
+    // created with its payment method, it "enters the `requires_confirmation` status and is ready to confirm" (the same page)
+    { operation: 'PostPaymentIntents', from: ['requires_payment_method'], to: 'requires_confirmation', source: 'https://docs.stripe.com/payments/paymentintents/lifecycle' },
+    // confirm lands on one of its outcomes, decided by the payment method and the capture method
+    ...['requires_payment_method', 'requires_action', 'requires_capture', 'succeeded'].map((to) => ({
+      operation: 'PostPaymentIntentsIntentConfirm',
+      from: ['requires_payment_method', 'requires_confirmation', 'requires_action'],
+      to,
+      refusal: { status: 400, code: 'payment_intent_unexpected_state', message: 'You cannot confirm this PaymentIntent because it has a status of {from}.' },
+      source: 'https://docs.stripe.com/api/payment_intents/confirm',
+    })),
+    // a bank debit confirmed (created with `confirm`, confirmed, or verified by micro-deposits) is submitted and
+    // processes: "The PaymentIntent you create initially has a status of `processing`"; "When the bank account is
+    // successfully verified, Stripe returns the PaymentIntent object with a status of `processing`"
+    ...['PostPaymentIntents', 'PostPaymentIntentsIntentConfirm'].map((operation) => ({
+      operation, from: ['requires_payment_method', 'requires_confirmation', 'requires_action'], to: 'processing',
+      source: 'https://docs.stripe.com/payments/ach-direct-debit/accept-a-payment?payment-ui=direct-api',
+    })),
+    // and succeeds: "After the payment has succeeded, the PaymentIntent status is updated from `processing`
+    // to `succeeded`" (semantics/payment-intents.ts settleBankDebits)
+    by('vendor', ['processing'], 'succeeded', 'https://docs.stripe.com/payments/ach-direct-debit/accept-a-payment?payment-ui=direct-api'),
+    // creating one with `confirm` confirms it at once, landing where a confirm lands
+    ...['requires_payment_method', 'requires_action', 'requires_capture', 'succeeded'].map((to) => ({
+      operation: 'PostPaymentIntents',
+      from: ['requires_payment_method', 'requires_confirmation'],
+      to,
+      source: 'spec:PostPaymentIntents "Set to `true` to attempt to [confirm this PaymentIntent](https://docs.stripe.com/api/payment_intents/confirm) immediately."',
+    })),
+    {
+      operation: 'PostPaymentIntentsIntentCapture',
+      from: ['requires_capture'],
+      to: 'succeeded',
+      refusal: unexpected('captured', 'Only a PaymentIntent with one of the following statuses may be captured: requires_capture.'),
+      source: 'https://docs.stripe.com/api/payment_intents/capture',
+    },
+    {
+      operation: 'PostPaymentIntentsIntentIncrementAuthorization',
+      from: ['requires_capture'],
+      to: 'requires_capture',
+      refusal: unexpected('incremented', 'Only a PaymentIntent with a status of requires_capture may be incremented.'),
+      source: 'https://docs.stripe.com/api/payment_intents/increment_authorization',
+    },
+    {
+      operation: 'PostPaymentIntentsIntentCancel',
+      from: OPEN,
+      to: 'canceled',
+      refusal: unexpected('canceled', 'Only a PaymentIntent with one of the following statuses may be canceled: requires_payment_method, requires_capture, requires_confirmation, requires_action, processing.'),
+      source: 'https://docs.stripe.com/api/payment_intents/cancel',
+    },
+    {
+      operation: 'PostPaymentIntentsIntentVerifyMicrodeposits',
+      from: ['requires_action'],
+      to: 'processing',
+      refusal: { status: 400, code: 'payment_intent_unexpected_state', message: 'This PaymentIntent could not be verified because it has a status of {from}.' },
+      source: 'https://docs.stripe.com/payments/ach-direct-debit/accept-a-payment?payment-ui=direct-api',
+    },
+    {
+      // paying the invoice an intent collects for settles the intent
+      operation: 'PostInvoicesInvoicePay',
+      from: OPEN,
+      to: 'succeeded',
+      source: 'https://docs.stripe.com/api/invoices/pay',
+    },
+    ...['succeeded', 'requires_action'].map((to) => ({
+      operation: 'PostPaymentIntentsIntentApplyCustomerBalance',
+      from: OPEN,
+      to,
+      refusal: { status: 400, code: 'payment_intent_unexpected_state', message: 'This PaymentIntent could not be updated because it has a status of {from}.' },
+      source: 'https://docs.stripe.com/api/payment_intents/apply_customer_balance',
+    })),
+    // a card presented to the Terminal reader processing an intent pays it (held, under manual capture)
+    ...['succeeded', 'requires_capture'].map((to) => ({
+      operation: 'PostTestHelpersTerminalReadersReaderPresentPaymentMethod', from: ['requires_payment_method', 'requires_confirmation'], to,
+      source: 'https://docs.stripe.com/api/terminal/readers/present_payment_method',
+    })),
+    // the customer pays, in the billing portal, the invoice an intent collects for after its charge was declined
+    by('external', ['requires_payment_method'], 'succeeded', 'https://docs.stripe.com/customer-management'),
+    // Stripe also fails a bank debit back to needing a payment method, completes 3-D Secure on the bank's page and
+    // cancels a hold left uncaptured; the twin's bank debits succeed unless their test account stays processing, it has no 3-D Secure page, and it keeps
+    // holds until they are captured or canceled
+  ],
+};
+
+/** A charge's `captured`: an authorization (capture=false) is captured once. */
+const chargeCaptured: StateField = {
+  initial: true,
+  transitions: [
+    {
+      operation: 'PostChargesChargeCapture',
+      from: ['false'],
+      to: 'true',
+      refusal: { status: 400, code: 'charge_already_captured', message: 'Charge ch_xxx has already been captured.' },
+      source: 'https://docs.stripe.com/api/charges/capture',
+    },
+    // a manual-capture intent's capture captures the charge its confirm authorized
+    { operation: 'PostPaymentIntentsIntentCapture', from: ['false'], to: 'true', source: 'https://docs.stripe.com/api/payment_intents/capture' },
+  ],
+};
+
+/** A charge's `refunded`: true once refunds take its whole amount, false again when a refund that made it so is
+ *  canceled. A capture or a cancel never makes it so: "`refunded` will no longer be `true` for payment cancellation
+ *  flows", and a partial capture makes no Refund (docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-partial-
+ *  capture-and-payment-cancellation-flow). */
+const chargeRefunded: StateField = {
+  initial: false,
+  transitions: [
+    ...['PostRefunds', 'PostChargesChargeRefunds', 'PostCreditNotes'].map((operation) => ({ operation, from: ['false'], to: 'true', source: 'https://docs.stripe.com/api/charges/object#charge_object-refunded' })),
+    { operation: 'PostRefundsRefundCancel', from: ['true'], to: 'false', source: 'https://docs.stripe.com/api/refunds/cancel' },
+    // (an authorization left uncaptured is canceled after seven days, "Uncaptured PaymentIntents are cancelled a set
+    // number of days (7 by default) after their creation", docs.stripe.com/api/payment_intents/capture; the twin keeps it)
+  ],
+};
+
+/** A charge's `status`: the twin settles a charge when it is made (a declined one is never
+ *  stored); an asynchronous one settles later, on the network's word. */
+const chargeStatus: StateField = {
+  initial: 'succeeded',
+  transitions: [
+    // (an asynchronous charge is pending at Stripe until it settles or fails; the twin's settle when made)
+  ],
+};
+
+/** A charge's `paid`: true once it succeeded or was authorized; a pending one becomes paid when it settles. */
+const chargePaid: StateField = {
+  initial: true,
+  // (a charge is paid when it settles; the twin's settle when made)
+  transitions: [],
+};
+
+/** A refund's `status`: only one waiting on the customer (requires_action) may be canceled; the
+ *  rest is the network's. */
+const refundStatus: StateField = {
+  initial: 'succeeded',
+  transitions: [
+    {
+      operation: 'PostRefundsRefundCancel',
+      from: ['requires_action'],
+      to: 'canceled',
+      refusal: { status: 400, code: 'refund_status_invalid', message: 'Refund {id} cannot be canceled because its status is {from}.' },
+      source: 'https://docs.stripe.com/api/refunds/cancel',
+    },
+    // a card refund the available balance does not cover is held pending, and made once the balance covers it: "Stripe
+    // holds the refund as pending for card transactions ... until your Stripe balance becomes sufficient"
+    // (docs.stripe.com/refunds; semantics/refunds.ts)
+    // (a paid invoice's credit note makes its refund as a refund call does: "Refunds: create a new refund (using
+    // refund_amount)", docs.stripe.com/api/credit_notes/create)
+    ...['PostRefunds', 'PostChargesChargeRefunds', 'PostCreditNotes'].map((operation) => ({ operation, from: ['succeeded'], to: 'pending', source: 'https://docs.stripe.com/refunds' })),
+    by('vendor', ['pending'], 'succeeded', 'https://docs.stripe.com/refunds'),
+    // a bank-transfer payment's refund waits in requires_action for the customer's bank details, and is made so
+    // (semantics/refunds.ts); (Stripe also fails some refunds; the twin's do not fail)
+  ],
+};
+
+const SETUP_OPEN = ['requires_payment_method', 'requires_confirmation', 'requires_action'];
+const setupUnexpected = (verb: string) => ({ status: 400, code: 'setup_intent_unexpected_state', message: `You cannot ${verb} this SetupIntent because it has a status of {from}.` });
+
+/** A SetupIntent's `status`: confirm settles it (or leaves a bank account awaiting micro-deposits),
+ *  cancel ends an open one, and verification completes the micro-deposit wait. */
+const setupIntentStatus: StateField = {
+  // "After you create the SetupIntent, it has a status of `requires_payment_method` until you attach a payment method"
+  // (docs.stripe.com/payments/paymentintents/lifecycle)
+  initial: 'requires_payment_method',
+  transitions: [
+    // created with its payment method, it "enters the `requires_confirmation` status and is ready to confirm" (the same page)
+    { operation: 'PostSetupIntents', from: ['requires_payment_method'], to: 'requires_confirmation', source: 'https://docs.stripe.com/payments/paymentintents/lifecycle' },
+    ...['requires_action', 'succeeded'].map((to) => ({
+      operation: 'PostSetupIntentsIntentConfirm',
+      from: SETUP_OPEN,
+      to,
+      refusal: setupUnexpected('confirm'),
+      source: 'https://docs.stripe.com/api/setup_intents/confirm',
+    })),
+    {
+      operation: 'PostSetupIntentsIntentCancel',
+      from: SETUP_OPEN,
+      to: 'canceled',
+      refusal: setupUnexpected('cancel'),
+      source: 'https://docs.stripe.com/api/setup_intents/cancel',
+    },
+    {
+      operation: 'PostSetupIntentsIntentVerifyMicrodeposits',
+      from: ['requires_action'],
+      to: 'succeeded',
+      refusal: { status: 400, code: 'setup_intent_unexpected_state', message: 'This SetupIntent could not be verified because it has a status of {from}.' },
+      source: 'https://docs.stripe.com/api/setup_intents/verify_microdeposits',
+    },
+    // (Stripe completes 3-D Secure on the bank's page and settles an asynchronous method from processing; the
+    // twin has no such page and settles every method at once)
+  ],
+};
+
+const invoiceRefusal = (message: string) => ({ status: 400, code: 'invoice_not_editable', message });
+
+/** An invoice's `status`: a draft is finalized (or sent, which finalizes it) into open, an open one
+ *  is paid, written off or voided. Sending leaves any other status where it is. */
+const invoiceStatus: StateField = {
+  initial: 'draft',
+  transitions: [
+    {
+      operation: 'PostInvoicesInvoiceFinalize',
+      from: ['draft'],
+      to: 'open',
+      refusal: invoiceRefusal('This invoice cannot be finalized because it has status {from}.'),
+      source: 'https://docs.stripe.com/api/invoices/finalize',
+    },
+    // docs.stripe.com/invoicing/integration: "To finalize a draft invoice, use the Dashboard, send it to the customer, or pay it."
+    { operation: 'PostInvoicesInvoiceSend', from: ['draft'], to: 'open', source: 'https://docs.stripe.com/invoicing/integration' },
+    { operation: 'PostInvoicesInvoiceSend', from: ['open', 'paid', 'uncollectible', 'void'], source: 'https://docs.stripe.com/api/invoices/send' },
+    {
+      operation: 'PostInvoicesInvoicePay',
+      from: ['open', 'uncollectible'],
+      to: 'paid',
+      refusal: invoiceRefusal('This invoice cannot be paid because it has status {from}.'),
+      refusals: { paid: { status: 400, code: 'invoice_payment_intent_requires_action', message: 'This invoice has already been paid.' } },
+      source: 'https://docs.stripe.com/api/invoices/pay',
+    },
+    {
+      operation: 'PostInvoicesInvoiceMarkUncollectible',
+      from: ['open'],
+      to: 'uncollectible',
+      refusal: invoiceRefusal('Only open invoices can be marked uncollectible (this one is {from}).'),
+      source: 'https://docs.stripe.com/api/invoices/mark_uncollectible',
+    },
+    {
+      // only a finalized invoice is voided; a draft is deleted
+      operation: 'PostInvoicesInvoiceVoid',
+      from: ['open', 'uncollectible'],
+      to: 'void',
+      refusal: invoiceRefusal('This invoice cannot be voided because it has status {from}.'),
+      source: 'https://docs.stripe.com/api/invoices/void',
+    },
+    // confirming or capturing the PaymentIntent an invoice collects through pays the invoice
+    ...['PostPaymentIntentsIntentConfirm', 'PostPaymentIntentsIntentCapture'].map((operation) => ({
+      operation, from: ['draft', 'open', 'uncollectible'], to: 'paid', source: 'https://docs.stripe.com/billing/subscriptions/build-subscriptions',
+    })),
+    // as does its bank debit succeeding once submitted (semantics/payment-intents.ts settleBankDebits)
+    by('vendor', ['draft', 'open', 'uncollectible'], 'paid', 'https://docs.stripe.com/billing/subscriptions/build-subscriptions'),
+    // a bank transfer that arrives in the customer's cash balance pays an open invoice that takes transfers
+    // (automatic reconciliation; in test mode the funding helper stands in for the transfer)
+    { operation: 'PostTestHelpersCustomersCustomerFundCashBalance', from: ['open'], to: 'paid', source: 'https://docs.stripe.com/payments/customer-balance/reconciliation' },
+    // a subscription's first invoice is paid on the Checkout page that started it
+    by('external', ['draft'], 'paid', 'https://docs.stripe.com/payments/checkout/how-checkout-works'),
+    // a subscription's renewal, drafted at its period's end, is finalized about an hour later and charged: paid, or
+    // open when the charge is declined (semantics/renewals.ts)
+    by('time', ['draft'], 'paid', 'https://docs.stripe.com/invoicing/integration/workflow-transitions#finalized'),
+    by('time', ['draft'], 'open', 'https://docs.stripe.com/billing/subscriptions/overview#payment-status'),
+    // an update that ends a subscription's trial invoices its new period and attempts payment at once: paid, or open
+    // when the charge is declined or not attempted (semantics/subscriptions.ts applyTrialEnd)
+    { operation: 'PostSubscriptionsSubscriptionExposedId', from: ['draft'], to: 'paid', source: 'https://docs.stripe.com/billing/subscriptions/upgrade-downgrade#immediate-payment' },
+    // a trialing subscription's first invoice, for nothing, is paid as it is made ("An immediate invoice is still
+    // created, but the amount is 0", docs.stripe.com/billing/subscriptions/trials/free-trials)
+    { operation: 'PostSubscriptions', from: ['draft'], to: 'paid', source: 'https://docs.stripe.com/billing/subscriptions/trials/free-trials' },
+    { operation: 'PostSubscriptionsSubscriptionExposedId', from: ['draft'], to: 'open', source: 'https://docs.stripe.com/billing/subscriptions/upgrade-downgrade#immediate-payment' },
+    // the customer pays an open invoice in the billing portal
+    by('external', ['open'], 'paid', 'https://docs.stripe.com/customer-management'),
+    // (Stripe also finalizes any other auto-advancing draft after an hour, retries an open invoice on its schedule
+    // and, retries exhausted, may write it off, and takes payment on the hosted invoice page; the twin's other
+    // invoices move only by the calls above)
+  ],
+};
+
+/** A subscription's `status` as the twin's own operations move it; canceling ends any subscription. */
+const subscriptionStatus: StateField = {
+  initial: 'active',
+  transitions: [
+    { operation: 'DeleteSubscriptionsSubscriptionExposedId', from: '*', to: 'canceled', source: 'https://docs.stripe.com/api/subscriptions/cancel' },
+    // (a test clock's advance moves no subscription itself: when the clock reaches its target, a trial that ended there
+    // ends by time's move below, on the next request; semantics/test-clocks.ts finishClockAdvances)
+    // "Deleting the simulation also deletes the test customers associated with the clock and cancels their
+    // subscriptions" (docs.stripe.com/billing/testing/test-clocks/api-advanced-usage)
+    { operation: 'DeleteTestHelpersTestClocksTestClock', from: '*', to: 'canceled', source: 'https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage' },
+    // "Cancels a subscription schedule and its associated subscription immediately" (docs.stripe.com/api/subscription_schedules/cancel)
+    { operation: 'PostSubscriptionSchedulesScheduleCancel', from: ['active', 'trialing', 'past_due', 'incomplete'], to: 'canceled', source: 'https://docs.stripe.com/api/subscription_schedules/cancel' },
+    // confirming or capturing the first invoice's PaymentIntent, or paying the invoice itself, pays it and
+    // activates the subscription
+    ...['PostPaymentIntentsIntentConfirm', 'PostPaymentIntentsIntentCapture'].map((operation) => ({
+      operation, from: ['incomplete'], to: 'active', source: 'https://docs.stripe.com/billing/subscriptions/build-subscriptions',
+    })),
+    // or when its bank debit succeeds once submitted (semantics/payment-intents.ts settleBankDebits)
+    by('vendor', ['incomplete'], 'active', 'https://docs.stripe.com/billing/subscriptions/build-subscriptions'),
+    // paying the invoice a subscription waits on (its first, or a renewal that failed) makes it active
+    { operation: 'PostInvoicesInvoicePay', from: ['incomplete', 'past_due'], to: 'active', source: 'https://docs.stripe.com/billing/subscriptions/overview#payment-status' },
+    // an update's `trial_end`: `now` ends a trial at once and charges the new period, active when paid and past_due when
+    // not; a future timestamp starts a trial on a subscription out of one (semantics/subscriptions.ts applyTrialEnd)
+    { operation: 'PostSubscriptionsSubscriptionExposedId', from: ['trialing'], to: 'active', source: 'https://docs.stripe.com/api/subscriptions/update#update_subscription-trial_end' },
+    { operation: 'PostSubscriptionsSubscriptionExposedId', from: ['trialing'], to: 'past_due', source: 'https://docs.stripe.com/billing/subscriptions/upgrade-downgrade#immediate-payment' },
+    {
+      operation: 'PostSubscriptionsSubscriptionExposedId', from: ['active', 'past_due'], to: 'trialing',
+      // (Where the documentation stops and the twin decides: the wording of the refusal for a subscription neither
+      // active nor past_due; a canceled one answers what Stripe answers any update of a canceled subscription.)
+      refusal: { status: 400, message: 'A trial can only be added to an active or past_due subscription; this one is {from}.' },
+      refusals: { canceled: { status: 400, message: 'A canceled subscription can only update its cancellation_details and metadata.' } },
+      source: 'https://docs.stripe.com/billing/subscriptions/trials/free-trials#adding-a-new-trial-to-a-subscription-previously-in-a-trial',
+    },
+    // a trial ends on its own clock (Stripe pauses one that ends with no payment method to bill; the twin's
+    // trials end active), and a renewal whose charge is declined leaves the subscription past_due
+    // (semantics/renewals.ts)
+    by('time', ['trialing'], 'active', 'https://docs.stripe.com/billing/subscriptions/trials'),
+    by('time', ['active'], 'past_due', 'https://docs.stripe.com/billing/subscriptions/overview#payment-status'),
+    // one set to cancel at its period's end is canceled when the period ends
+    by('time', ['active', 'trialing', 'past_due'], 'canceled', 'https://docs.stripe.com/billing/subscriptions/cancel#cancel-at-end-of-cycle'),
+    // the customer pays the invoice it waits on in the billing portal
+    by('external', ['past_due'], 'active', 'https://docs.stripe.com/customer-management'),
+    // (Stripe also expires an incomplete subscription after 23 hours, and retries a failed renewal on its schedule,
+    // the settings ending the retries unpaid or canceled; the twin makes no retry)
+    // the customer cancels in the billing portal
+    by('external', ['active', 'trialing', 'past_due', 'unpaid', 'paused'], 'canceled', 'spec:/components/schemas/portal_subscription_cancel "Whether to cancel subscriptions immediately or at the end of the billing period."'),
+  ],
+};
+
+const notOpen = (verb: string) => ({ status: 400, code: 'checkout_session_not_open', message: `You may only ${verb} a Checkout Session that is currently in the \`open\` state.` });
+
+/** A Checkout Session's `status`: an open session expires (asked to, or 24 hours on), or completes
+ *  when the customer pays on the hosted page. Completion is the external actor's move, the one the
+ *  hosted Checkout page (src/screens/checkout.tsx) performs. */
+const checkoutStatus: StateField = {
+  initial: 'open',
+  transitions: [
+    { operation: 'PostCheckoutSessionsSessionExpire', from: ['open'], to: 'expired', refusal: notOpen('expire'), source: 'https://docs.stripe.com/api/checkout/sessions/expire' },
+    { actor: 'external', from: ['open'], to: 'complete', refusal: notOpen('complete'), source: 'https://docs.stripe.com/api/checkout/sessions/object#checkout_session_object-status' },
+    // (Stripe expires an open session at expires_at; the twin keeps it open until asked)
+  ],
+};
+
+/** A Checkout Session's `payment_status`: the customer completing a payment or subscription session
+ *  pays it; a delayed payment method settles later. */
+const checkoutPaymentStatus: StateField = {
+  initial: 'unpaid',
+  transitions: [
+    { actor: 'external', from: '*', to: 'paid', source: 'https://docs.stripe.com/api/checkout/sessions/object#checkout_session_object-payment_status' },
+    // (a delayed method settles a session later at Stripe; the twin's settle on the page)
+  ],
+};
+
+/** A dispute's `status`: closing concedes it; the bank decides the rest, and an unanswered one is
+ *  lost when its evidence is due. */
+const disputeStatus: StateField = {
+  initial: 'warning_needs_response',
+  transitions: [
+    { operation: 'PostDisputesDisputeClose', from: '*', to: 'lost', source: 'https://docs.stripe.com/api/disputes/close' },
+    // submitting evidence puts a dispute (or an inquiry) under review; in test mode the evidence decides it
+    { operation: 'PostDisputesDispute', from: ['needs_response'], to: 'under_review', source: 'https://docs.stripe.com/api/disputes/update#update_dispute-submit' },
+    { operation: 'PostDisputesDispute', from: ['warning_needs_response'], to: 'warning_under_review', source: 'https://docs.stripe.com/api/disputes/update#update_dispute-submit' },
+    by('vendor', ['under_review'], 'won', 'https://docs.stripe.com/testing#evidence'),
+    by('vendor', ['under_review'], 'lost', 'https://docs.stripe.com/testing#evidence'),
+    // (the bank decides a dispute under review, escalates an inquiry and loses one left unanswered; the twin
+    // decides none)
+    // Stripe also closes an inquiry the bank drops (warning_closed); no inquiry the twin holds is dropped
+  ],
+};
+
+/** A payout's `status`: cancel ends it; reversing cancels it and pays a reversal, never twice. */
+const payoutStatus: StateField = {
+  initial: 'pending',
+  transitions: [
+    // only a pending payout can be canceled (docs.stripe.com/api/payouts/cancel); reversing a paid one makes a new
+    // payout and leaves the original paid (semantics/balance.ts)
+    { operation: 'PostPayoutsPayoutCancel', from: ['pending'], to: 'canceled', source: 'https://docs.stripe.com/api/payouts/cancel' },
+    // it arrives in the bank on its arrival date
+    by('time', ['pending'], 'paid', 'https://docs.stripe.com/payouts#payout-statuses'),
+    // (a bank may fail a payout at Stripe; the twin's arrive)
+  ],
+};
+
+/** A credit note's `status`: issued, then voided once. */
+const creditNoteStatus: StateField = {
+  initial: 'issued',
+  transitions: [
+    {
+      operation: 'PostCreditNotesIdVoid',
+      from: ['issued'],
+      to: 'void',
+      refusal: { status: 400, code: 'credit_note_already_voided', message: 'This credit note has already been voided.' },
+      source: 'https://docs.stripe.com/api/credit_notes/void',
+    },
+  ],
+};
+
+const scheduleEnded = (verb: string) => ({ status: 400, code: 'subscription_schedule_status_invalid', message: `This subscription schedule has status {from} and cannot be ${verb}.` });
+
+/** A subscription schedule's `status`: canceling or releasing ends it; an ended one refuses both. */
+const scheduleStatus: StateField = {
+  initial: 'active',
+  transitions: [
+    // "A subscription schedule can only be canceled if its status is not_started or active"; "A schedule can only be
+    // released if its status is not_started or active" (the cancel and release pages)
+    { operation: 'PostSubscriptionSchedulesScheduleCancel', from: ['active', 'not_started'], to: 'canceled', refusal: scheduleEnded('canceled'), source: 'https://docs.stripe.com/api/subscription_schedules/cancel' },
+    { operation: 'PostSubscriptionSchedulesScheduleRelease', from: ['active', 'not_started'], to: 'released', refusal: scheduleEnded('released'), source: 'https://docs.stripe.com/api/subscription_schedules/release' },
+    // its phases run on the clock: it starts at its start date and ends with its last phase
+    // (a schedule whose end_behavior is cancel completes at its end at Stripe; the twin's release)
+    // (Stripe starts a schedule at its start date and ends it with its last phase; the twin's start at once
+    // and end when canceled or released)
+  ],
+};
+
+const quoteRefusal = (verb: string) => ({ status: 400, code: 'quote_invalid_status', message: `This quote cannot be ${verb} because it has status {from}.` });
+
+/** A quote's `status`: a draft is finalized into open, an open one accepted, and either canceled. */
+const quoteStatus: StateField = {
+  initial: 'draft',
+  transitions: [
+    { operation: 'PostQuotesQuoteFinalize', from: ['draft'], to: 'open', refusal: quoteRefusal('finalized'), source: 'https://docs.stripe.com/api/quotes/finalize' },
+    { operation: 'PostQuotesQuoteAccept', from: ['open'], to: 'accepted', refusal: quoteRefusal('accepted'), source: 'https://docs.stripe.com/api/quotes/accept' },
+    { operation: 'PostQuotesQuoteCancel', from: ['draft', 'open'], to: 'canceled', refusal: quoteRefusal('canceled'), source: 'https://docs.stripe.com/api/quotes/cancel' },
+    // an open quote not accepted by its expires_at is canceled
+    // (Stripe cancels an open quote at its expires_at; the twin keeps it open)
+  ],
+};
+
+const setBy = (operation: string, values: string[], source: string): Transition[] => values.map((to) => ({ operation, from: '*' as const, to, source }));
+
+/** An Issuing authorization's `status`: approve and decline close a pending one, once; a capture
+ *  closes it, or leaves it pending when told not to close. */
+const issuingAuthorizationStatus: StateField = {
+  initial: 'pending',
+  transitions: [
+    // approving keeps it pending (approved) until the merchant captures; declining closes it
+    { operation: 'PostIssuingAuthorizationsAuthorizationApprove', from: ['pending'], refusal: { status: 400, code: 'authorization_already_finalized', message: 'This authorization has already been finalized (status {from}).' }, source: 'https://docs.stripe.com/issuing/purchases/authorizations' },
+    { operation: 'PostIssuingAuthorizationsAuthorizationDecline', from: ['pending'], to: 'closed', refusal: { status: 400, code: 'authorization_already_finalized', message: 'This authorization has already been finalized (status {from}).' }, source: 'https://docs.stripe.com/api/issuing/authorizations/decline' },
+    { operation: 'PostTestHelpersIssuingAuthorizationsAuthorizationCapture', from: ['pending'], to: 'closed', source: 'https://docs.stripe.com/api/issuing/authorizations/test_mode_capture' },
+    { operation: 'PostTestHelpersIssuingAuthorizationsAuthorizationCapture', from: ['pending'], source: 'https://docs.stripe.com/api/issuing/authorizations/test_mode_capture' },
+    // a real-time request no one answered is decided when its window ends: "If Stripe doesn't receive your approve or
+    // decline response within 2 seconds, the Authorization is automatically approved or declined based on your timeout
+    // settings" (semantics/issuing.ts lapseRealtimeRequests)
+    by('time', ['pending'], 'closed', 'https://docs.stripe.com/issuing/controls/real-time-authorizations'),
+    // (Stripe also closes, reverses and expires one as the merchant and the clock act; in test mode the
+    // capture helper above closes it, and the twin serves no other)
+  ],
+};
+
+/** A Treasury flow's `status` as the twin's own operations move it: only a processing flow cancels. */
+const flowCancel = (operation: string, code: string, name: string, network: Transition[]): StateField => ({
+  initial: 'processing',
+  transitions: [
+    { operation, from: ['processing'], to: 'canceled', refusal: { status: 400, code, message: `This ${name} cannot be canceled because it is no longer processing.` }, source: 'https://docs.stripe.com/api/treasury' },
+    ...network,
+  ],
+});
+/** An outbound flow on the network: Stripe posts or fails it and a posted one may come back returned (in
+ *  test mode by test helpers the twin does not serve), so none of those moves is the twin's. */
+const outbound = (_doc: string): Transition[] => [];
+
+export const manifest: DerivedManifest = {
+  vendor: 'stripe',
+  service: 'stripe',
+  body: { form: { coerce: true } },
+  ids: { template: '{prefix}_twin_{n}', acceptProvided: true },
+  // on declared resources, but never served by the twin: Stripe's unknown-URL answer
+  unmodeled: [
+    'DeleteAccountsAccountBankAccountsId',
+    'DeleteAccountsAccountPeoplePerson',
+    'DeleteCustomersCustomerSubscriptionsSubscriptionExposedId',
+    'DeleteTaxIdsId',
+    'GetAccountsAccountBankAccountsId',
+    'GetAccountsAccountPeople',
+    'GetAccountsAccountPeoplePerson',
+    'GetApplicationFeesFeeRefundsId',
+    'GetBalanceHistory',
+    'GetBalanceHistoryId',
+    'GetChargesChargeDispute',
+    'GetCustomersCustomerSubscriptions',
+    'GetCustomersCustomerSubscriptionsSubscriptionExposedId',
+    'GetFileLinks',
+    'GetFileLinksLink',
+    'GetFinancialConnectionsTransactionsTransaction',
+    'GetIdentityVerificationSessions',
+    'GetLinkAccountSessionsSession',
+    'GetLinkedAccounts',
+    'GetLinkedAccountsAccount',
+    'GetTaxIdsId',
+    'GetTransfersTransferReversalsId',
+    'PostAccountsAccountBankAccounts',
+    'PostAccountsAccountBankAccountsId',
+    'PostAccountsAccountExternalAccountsId',
+    'PostAccountsAccountPeople',
+    'PostAccountsAccountPeoplePerson',
+    'PostApplicationFeesFeeRefundsId',
+    'PostBillingMetersId',
+    'PostCustomersCustomerBalanceTransactionsTransaction',
+    'PostCustomersCustomerSubscriptions',
+    'PostCustomersCustomerSubscriptionsSubscriptionExposedId',
+    'PostFileLinksLink',
+    'PostIdentityVerificationSessionsSession',
+    'PostInvoicesInvoice',
+    'PostLinkAccountSessions',
+    'PostPaymentMethodsPaymentMethod',
+    'PostPayoutsPayout',
+    'PostQuotesQuote',
+    'PostTaxRegistrationsId',
+    'PostTransfersTransferReversalsId',
+  ],
+  time: 'unix',
+  error: { error: { type: '{kind}', message: '{message}', code: '{code}', param: '{param}' } },
+  errorOmitsAbsent: true,
+  defaultKind: 'invalid_request_error',
+  readOnly: { status: 405, kind: 'invalid_request_error', message: 'twin is read-only; omit readOnly to accept writes' },
+  version: {
+    header: 'stripe-version',
+    pattern: '^\\d{4}-\\d{2}-\\d{2}(\\.[a-z_]+)?$',
+    error: { status: 400, kind: 'invalid_request_error', code: 'invalid_api_version', message: 'Invalid Stripe version: {value}. Check the API version reference: https://stripe.com/docs/api/versioning' },
+  },
+  notFound: { status: 404, kind: 'invalid_request_error', code: 'resource_missing', message: "No such {object}: '{id}'" },
+  list: {
+    style: 'envelope',
+    envelope: { object: 'list', url: '{url}', has_more: '{has_more}', data: '{data}' },
+    limit: { param: 'limit', default: 10, max: 100 },
+    after: 'starting_after',
+    before: 'ending_before',
+  },
+  deleted: { id: '{id}', object: '{object}', deleted: true },
+  expandParam: 'expand',
+  idempotency: {
+    header: 'idempotency-key',
+    storedAs: '_idempotency',
+    conflict: {
+      status: 400,
+      kind: 'idempotency_error',
+      message: 'Keys for idempotent requests can only be used with the same parameters they were originally used with. Provide a new idempotency key, or use the original parameters that were used with this key.',
+    },
+  },
+  // The screens applications and people reach (docs/contributing/architecture.md, "Screens"). Demand is the
+  // ladder's 85 applications: the code that sends a customer to the page.
+  screens: [
+    {
+      id: 'checkout', kind: 'flow', host: 'checkout.stripe.com', path: '/c/pay/{session}', status: 'done',
+      demand: '16 of 85 applications send customers to Checkout',
+      controls: ['email', 'cardNumber', 'cardExpiry', 'cardCvc', 'billingName', 'billingCountry', 'billingPostalCode', 'Pay', '← Back'],
+      source: 'https://docs.stripe.com/payments/checkout/how-checkout-works',
+    },
+    {
+      id: 'billing-portal', kind: 'flow', host: 'billing.stripe.com', path: '/p/session/{session}', status: 'done',
+      demand: '15 of 85 applications send customers to the billing portal', controls: ['Cancel plan', 'Renew plan', '← Return to {business name}'],
+      source: 'https://docs.stripe.com/customer-management',
+    },
+    {
+      id: 'connect-onboarding', kind: 'flow', host: 'connect.stripe.com', path: '/setup/{account_link} → /setup/s/{session}', status: 'done',
+      demand: '3 of 85 applications onboard connected accounts with Account Links', controls: ['Agree and submit', '← Return to platform'],
+      source: 'https://docs.stripe.com/connect/hosted-onboarding',
+    },
+    {
+      id: 'identity-verification', kind: 'flow', host: 'verify.stripe.com', path: '/start/{verification_session}', status: 'done',
+      demand: 'a verification report is written only when a person completes this page', controls: ['Verify', 'Fail verification'],
+      source: 'https://docs.stripe.com/identity/how-sessions-work',
+    },
+    {
+      id: 'financial-connections', kind: 'flow', host: 'js.stripe.com', path: '/v3/financial-connections/{client_secret}', status: 'done',
+      demand: 'a linked bank account exists only once its holder links it here', controls: ['Link accounts', 'Cancel'],
+      source: 'https://docs.stripe.com/js/financial_connections/collect_financial_connections_accounts',
+    },
+    {
+      id: 'dashboard', kind: 'workspace', host: 'dashboard.stripe.com', path: '/test/{section}; /settings/public', status: 'done',
+      demand: 'testers and agents inspect payments, customers and subscriptions; an operator sets the business name Checkout shows (Public details)',
+      controls: ['Business name', 'Save'], source: 'https://docs.stripe.com/dashboard/basics',
+    },
+  ],
+  resources: {
+    'billing.meter': {
+      storedAs: 'billing_meter', idPrefix: 'mtr', notFound: "No such meter: '{id}'",
+      notState: ['event_time_window'], filters: ['status'],
+      state: { status: { initial: 'active', transitions: [
+        { operation: 'PostBillingMetersIdDeactivate', from: '*', to: 'inactive', source: 'https://docs.stripe.com/api/billing/meter/deactivate' },
+        { operation: 'PostBillingMetersIdReactivate', from: '*', to: 'active', source: 'https://docs.stripe.com/api/billing/meter/reactivate' },
+      ] } },
+    },
+    'billing.meter_event': { storedAs: 'billing_meter_event', idPrefix: 'mtr_evt' },
+    'billing.credit_grant': { storedAs: 'credit_grant', idPrefix: 'credgr', notState: ['category'], filters: ['customer'], notFound: "No such credit grant: '{id}'" },
+    'billing.alert': {
+      storedAs: 'billing_alert', idPrefix: 'alert', notFound: "No such alert: '{id}'",
+      state: { status: { initial: 'active', transitions: [
+        { operation: 'PostBillingAlertsIdActivate', from: '*', to: 'active', source: 'https://docs.stripe.com/api/billing/alert/activate' },
+        { operation: 'PostBillingAlertsIdDeactivate', from: '*', to: 'inactive', source: 'https://docs.stripe.com/api/billing/alert/deactivate' },
+        { operation: 'PostBillingAlertsIdArchive', from: '*', to: 'archived', source: 'https://docs.stripe.com/api/billing/alert/archive' },
+      ] } },
+    },
+    payment_intent: {
+      idPrefix: 'pi',
+      state: { status: paymentIntentStatus },
+      notState: ['cancellation_reason', 'capture_method', 'confirmation_method', 'setup_future_usage'],
+      embeds: { customer: 'customer', latest_charge: 'charge', payment_method: 'payment_method', invoice: 'invoice' },
+      filters: ['customer'],
+    },
+    // an update stores what it is given, nested objects whole, as the twin always has (Stripe merges
+    // metadata keys; `update: 'replace'` keeps the twin's answer)
+    customer: { idPrefix: 'cus', update: 'replace', notState: ['tax_exempt'], filters: ['email'] },
+    tax_id: { idPrefix: 'txi', notState: ['type'], filters: ['customer'] },
+    customer_balance_transaction: { idPrefix: 'cbtxn', notState: ['type'] },
+    customer_cash_balance_transaction: { storedAs: 'cash_balance_transaction', idPrefix: 'ccsbtxn', notState: ['type'] },
+    // a card is chargeable at once; any other source waits for its owner to authorize it through its
+    // flow, and is used up (single-use) or lapses
+    // what a customer's sources list answers (a card, a bank account, a Source, an account) as one
+    // resource over the stored sources; the card fields and an account's type/business_type are
+    // attributes. A customer's bank account verifies as a payout account does.
+    payment_source: {
+      storedAs: 'source',
+      idPrefix: 'src',
+      state: { status: bankAccountStatus('https://docs.stripe.com/api/customer_bank_accounts/object#customer_bank_account_object-status') },
+      notState: ['allow_redisplay', 'business_type', 'regulated_status', 'type'],
+    },
+    source: {
+      idPrefix: 'src',
+      state: {
+        status: {
+          initial: 'chargeable',
+          transitions: [
+            // (Stripe makes a redirect source chargeable when the customer authorizes it on the bank's page;
+            // the twin has no such page, so a non-card source stays pending)
+            // Stripe also fails a source the customer abandons, consumes a single-use one once charged and
+            // cancels one left unused; the twin's sources stay chargeable
+          ],
+        },
+      },
+      notState: ['allow_redisplay', 'type'],
+    },
+    charge: {
+      idPrefix: 'ch',
+      state: { status: chargeStatus, captured: chargeCaptured, paid: chargePaid, refunded: chargeRefunded },
+      embeds: { customer: 'customer', payment_intent: 'payment_intent', invoice: 'invoice', balance_transaction: 'balance_transaction' },
+      filters: ['customer', 'payment_intent'],
+    },
+    refund: {
+      idPrefix: 're',
+      update: 'replace',
+      state: { status: refundStatus },
+      notState: ['pending_reason', 'reason'],
+      embeds: { charge: 'charge', payment_intent: 'payment_intent', balance_transaction: 'balance_transaction' },
+      filters: ['charge', 'payment_intent'],
+    },
+    setup_intent: {
+      idPrefix: 'seti',
+      update: 'replace',
+      state: { status: setupIntentStatus },
+      notState: ['cancellation_reason'],
+      embeds: { customer: 'customer', payment_method: 'payment_method' },
+      filters: ['customer', 'payment_method'],
+    },
+    payment_method: { idPrefix: 'pm', notState: ['allow_redisplay', 'type'], embeds: { customer: 'customer' }, filters: ['customer', 'type'] },
+    subscription: {
+      idPrefix: 'sub',
+      state: { status: subscriptionStatus },
+      notState: ['collection_method'],
+      embeds: { customer: 'customer', latest_invoice: 'invoice', default_payment_method: 'payment_method', schedule: 'subscription_schedule' },
+      filters: ['customer'],
+    },
+    subscription_item: { idPrefix: 'si' },
+    invoice: {
+      idPrefix: 'in',
+      state: { status: invoiceStatus },
+      notState: ['billing_reason', 'collection_method', 'customer_tax_exempt'],
+      embeds: { customer: 'customer', subscription: 'subscription', charge: 'charge', payment_intent: 'payment_intent' },
+      filters: ['customer', 'status', 'subscription'],
+    },
+    invoiceitem: { idPrefix: 'ii', embeds: { customer: 'customer', price: 'price' }, filters: ['customer', 'invoice'], order: { field: 'date', direction: 'desc' } },
+    'checkout.session': {
+      storedAs: 'checkout_session',
+      idPrefix: 'cs',
+      state: { status: checkoutStatus, payment_status: checkoutPaymentStatus },
+      notState: ['billing_address_collection', 'customer_creation', 'locale', 'mode', 'origin_context', 'payment_method_collection', 'redirect_on_completion', 'submit_type', 'ui_mode'],
+      filters: ['customer', 'payment_intent', 'subscription', 'status'],
+      // the objects a session links to, as its x-expandableFields name them
+      embeds: { customer: 'customer', invoice: 'invoice', payment_intent: 'payment_intent', payment_link: 'payment_link', setup_intent: 'setup_intent', subscription: 'subscription' },
+    },
+    ephemeral_key: { idPrefix: 'ephkey' },
+    // a mandate's status is the network's to move; nothing here moves it
+    mandate: {
+      idPrefix: 'mandate',
+      state: {
+        status: {
+          initial: 'active',
+          transitions: [
+            // a single-use mandate is spent by its payment: inactive "The mandate was rejected, revoked, or previously
+            // used, and may not be used to initiate future payments" (semantics/payment-intents.ts settleBankDebits)
+            by('vendor', ['active'], 'inactive', 'https://docs.stripe.com/api/mandates/object'),
+            // (Stripe also activates a pending mandate and deactivates one revoked; the twin's are active when made)
+          ],
+        },
+      },
+      notState: ['type'],
+    },
+    dispute: { idPrefix: 'dp', update: 'replace', state: { status: disputeStatus }, notState: ['is_charge_refundable'], embeds: { charge: 'charge', payment_intent: 'payment_intent' }, filters: ['charge', 'payment_intent'] },
+    payout: { idPrefix: 'po', state: { status: payoutStatus }, notState: ['reconciliation_status', 'type'], embeds: { balance_transaction: 'balance_transaction', destination: 'account' } },
+    // the twin's ledger is seeded available; Stripe holds funds pending until their available_on
+    balance_transaction: {
+      idPrefix: 'txn',
+      state: { status: { initial: 'available', vendorInitial: 'pending', transitions: [by('time', ['pending'], 'available', 'https://docs.stripe.com/api/balance_transactions/object#balance_transaction_object-status')] } },
+      notState: ['balance_type', 'type'],
+      filters: ['type', 'currency'],
+    },
+    // a coupon lapses at its redeem_by: "Date after which the coupon can no longer be redeemed", and `valid` is
+    // "Taking account of the above properties, whether this coupon can still be applied to a customer" (the served
+    // spec's coupon); the twin keeps no redemption count, so max_redemptions never lapses one
+    coupon: {
+      idPrefix: 'coupon', update: 'replace', notState: ['duration'],
+      state: { valid: { initial: true, transitions: [by('time', ['true'], 'false', 'spec:/components/schemas/coupon/properties/redeem_by "Date after which the coupon can no longer be redeemed."')] } },
+    },
+    // switched on and off by an update (Stripe also lapses one at expires_at or when fully redeemed; the
+    // twin keeps no redemption count or expiry)
+    promotion_code: {
+      idPrefix: 'promo',
+      update: 'replace',
+      notFound: "No such promotion code: '{id}'",
+      state: {
+        active: {
+          initial: true,
+          transitions: [
+            ...flag('PostPromotionCodesPromotionCode', 'https://docs.stripe.com/api/promotion_codes/update'),
+          ],
+        },
+      },
+    },
+    credit_note: { idPrefix: 'cn', state: { status: creditNoteStatus }, notState: ['reason', 'type'], embeds: { customer: 'customer', invoice: 'invoice' }, filters: ['invoice', 'customer'] },
+    subscription_schedule: {
+      idPrefix: 'sub_sched',
+      update: 'replace',
+      state: { status: scheduleStatus },
+      notState: ['end_behavior'],
+      embeds: { customer: 'customer', subscription: 'subscription' },
+      filters: ['customer', 'subscription'],
+    },
+    'entitlements.feature': {
+      storedAs: 'entitlements_feature', idPrefix: 'feat', notFound: "No such feature: '{id}'",
+      state: { active: { initial: true, transitions: flag('PostEntitlementsFeaturesId', 'spec:PostEntitlementsFeaturesId "Update a feature’s metadata or permanently deactivate it."') } },
+    },
+    // an advance answers advancing and the clock is ready once it has reached the time (semantics/test-clocks.ts)
+    'test_helpers.test_clock': {
+      storedAs: 'test_clock',
+      idPrefix: 'clock',
+      notFound: "No such test clock: '{id}'",
+      state: {
+        status: {
+          initial: 'ready',
+          transitions: [
+            // "advancing: The clock has started to advance but hasn't reached the specified time"; "ready: The clock has
+            // completed advancing to the specified time" (docs.stripe.com/billing/testing/test-clocks/api-advanced-usage)
+            { operation: 'PostTestHelpersTestClocksTestClockAdvance', from: ['ready'], to: 'advancing', refusal: { status: 400, code: 'test_clock_not_ready', message: 'This test clock is still advancing.' }, source: 'https://docs.stripe.com/api/test_clocks/advance' },
+            by('vendor', ['advancing'], 'ready', 'https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage'),
+            // (Stripe may also end an advance in internal_failure; the twin's advances complete)
+          ],
+        },
+      },
+    },
+    event: { idPrefix: 'evt', filters: ['type'] },
+    // disabled and re-enabled by an update's `disabled` (Stripe also disables one that keeps failing; the
+    // twin counts no failures)
+    webhook_endpoint: {
+      idPrefix: 'we',
+      notFound: "No such webhook endpoint: '{id}'",
+      state: {
+        status: {
+          initial: 'enabled',
+          transitions: [
+            ...['enabled', 'disabled'].map((to) => ({ operation: 'PostWebhookEndpointsWebhookEndpoint', from: '*' as const, to, source: 'https://docs.stripe.com/api/webhook_endpoints/update#update_webhook_endpoint-disabled' })),
+          ],
+        },
+      },
+    },
+    account: { idPrefix: 'acct', notState: ['business_type', 'type'] },
+    person: { idPrefix: 'person', notState: ['political_exposure'], parent: { param: 'account', field: 'account', resource: 'account' } },
+    // a capability lives in its account's capability map; requesting one leaves it pending, withdrawing it inactive
+    capability: {
+      idPrefix: 'cap',
+      state: {
+        status: {
+          initial: 'unrequested',
+          transitions: [
+            ...['pending', 'inactive'].map((to) => ({ operation: 'PostAccountsAccountCapabilitiesCapability', from: '*' as const, to, source: 'https://docs.stripe.com/api/capabilities/update' })),
+            // Stripe reviews the account's requirements
+            by('vendor', ['pending', 'inactive'], 'active', 'https://docs.stripe.com/connect/account-capabilities#capability-status'),
+            by('vendor', ['active', 'pending'], 'inactive', 'https://docs.stripe.com/connect/account-capabilities#capability-status'),
+          ],
+        },
+      },
+    },
+    // allow_redisplay and regulated_status belong to a card destination: consent and the issuer's
+    // regulation, set when it is added, not a lifecycle
+    external_account: {
+      idPrefix: 'ba',
+      state: { status: bankAccountStatus('https://docs.stripe.com/api/external_account_bank_accounts/object#account_bank_account_object-status') },
+      notState: ['allow_redisplay', 'regulated_status'],
+    },
+    account_link: { idPrefix: 'acctlink' },
+    account_session: { idPrefix: 'accts' },
+    transfer: { idPrefix: 'tr', update: 'replace', filters: ['destination'] },
+    transfer_reversal: { idPrefix: 'trr' },
+    // refunded once fee refunds take its whole amount
+    application_fee: {
+      idPrefix: 'fee', notFound: "No such application fee: '{id}'", filters: ['charge'],
+      state: { refunded: { initial: false, transitions: [
+        { operation: 'PostApplicationFeesIdRefunds', from: ['false'], to: 'true', source: 'https://docs.stripe.com/api/fee_refunds/create' },
+        // a refund of its charge with refund_application_fee refunds it in proportion
+        ...['PostRefunds', 'PostChargesChargeRefunds'].map((operation) => ({ operation, from: ['false'], to: 'true', source: 'https://docs.stripe.com/api/refunds/create#create_refund-refund_application_fee' })),
+      ] } },
+    },
+    fee_refund: { idPrefix: 'fr' },
+    'apps.secret': { storedAs: 'apps_secret', idPrefix: 'apmc' },
+    token: { idPrefix: 'tok' },
+    file: { idPrefix: 'file', notState: ['purpose'], filters: ['purpose'] },
+    file_link: { idPrefix: 'link' },
+    // the user submits on Stripe's hosted verification page and Stripe checks it (the twin's own helper
+    // outside Stripe's surface, POST …/verify, stands in for both at once)
+    'identity.verification_session': {
+      storedAs: 'verification_session',
+      idPrefix: 'vs',
+      notFound: "No such VerificationSession: '{id}'",
+      state: {
+        status: {
+          initial: 'requires_input',
+          transitions: [
+            by('external', ['requires_input'], 'processing', 'https://docs.stripe.com/identity/how-sessions-work'),
+            by('vendor', ['processing'], 'verified', 'https://docs.stripe.com/identity/how-sessions-work'),
+            by('vendor', ['processing'], 'requires_input', 'https://docs.stripe.com/identity/how-sessions-work'),
+          ],
+        },
+      },
+      notState: ['type'],
+    },
+    'identity.verification_report': { storedAs: 'verification_report', idPrefix: 'vr', notFound: "No such verification report: '{id}'", notState: ['type'], filters: ['verification_session', 'type'] },
+    'billing_portal.session': { storedAs: 'billing_portal_session', idPrefix: 'bps', notState: ['locale'] },
+    // is_default is Stripe's: the configuration the dashboard made first
+    'billing_portal.configuration': {
+      storedAs: 'billing_portal_configuration', idPrefix: 'bpc', notFound: "No such configuration: '{id}'",
+      state: { active: { initial: true, transitions: flag('PostBillingPortalConfigurationsConfiguration', 'https://docs.stripe.com/api/customer_portal/configurations/update') } },
+      notState: ['is_default'],
+    },
+    // `state` is a US state code, not a lifecycle
+    tax_rate: {
+      idPrefix: 'txr', notFound: "No such tax rate: '{id}'",
+      state: { active: { initial: true, transitions: flag('PostTaxRatesTaxRate', 'https://docs.stripe.com/api/tax_rates/update') } },
+      notState: ['jurisdiction_level', 'rate_type', 'state', 'tax_type'],
+    },
+    // its status is derived on every read from whether a head office is set; nothing stores it
+    'tax.settings': { storedAs: 'tax_settings', idPrefix: 'taxset', notState: ['status'] },
+    'tax.calculation': { storedAs: 'tax_calculation', idPrefix: 'taxcalc', notFound: "No such tax calculation: '{id}'" },
+    // a registration is active from creation here; its dates move it on the clock
+    'tax.registration': {
+      storedAs: 'tax_registration', idPrefix: 'taxreg', notFound: "No such tax registration: '{id}'", filters: ['status'],
+      state: {
+        // Stripe schedules a registration with a future active_from and expires one at expires_at; the twin's
+        // are active from the start and never expire
+        status: { initial: 'active', transitions: [] },
+      },
+    },
+    'tax.transaction': { storedAs: 'tax_transaction', idPrefix: 'tax', notFound: "No such tax transaction: '{id}'", notState: ['type'] },
+    payment_link: {
+      idPrefix: 'plink',
+      update: 'replace', notFound: "No such payment link: '{id}'",
+      state: { active: { initial: true, transitions: flag('PostPaymentLinksPaymentLink', 'https://docs.stripe.com/api/payment_links/payment_links/update') } },
+      notState: ['billing_address_collection', 'customer_creation', 'payment_method_collection', 'submit_type'],
+    },
+    quote: { idPrefix: 'qt', state: { status: quoteStatus }, notState: ['collection_method'], filters: ['customer', 'status'] },
+    // a review is open until it is closed; approving closes it, once
+    review: {
+      storedAs: 'radar_review',
+      idPrefix: 'prv',
+      state: {
+        open: {
+          initial: true,
+          transitions: [
+            // (Stripe also closes one when the payment is refunded or disputed; the twin's close only on approval)
+            { operation: 'PostReviewsReviewApprove', from: ['true'], to: 'false', refusal: { status: 400, code: 'review_already_closed', message: 'This review has already been closed.' }, source: 'https://docs.stripe.com/api/radar/reviews/approve' },
+          ],
+        },
+      },
+      notState: ['closed_reason', 'opened_reason'],
+    },
+    'radar.value_list': { storedAs: 'radar_value_list', idPrefix: 'rsl', notFound: "No such radar value list: '{id}'", notState: ['item_type'], filters: ['alias'] },
+    'radar.value_list_item': { storedAs: 'radar_value_list_item', idPrefix: 'rsli', notFound: "No such radar value list item: '{id}'" },
+    'issuing.cardholder': {
+      storedAs: 'issuing_cardholder',
+      idPrefix: 'ich',
+      notFound: "No such cardholder: '{id}'",
+      state: { status: { initial: 'active', transitions: setBy('PostIssuingCardholdersCardholder', ['active', 'inactive', 'blocked'], 'https://docs.stripe.com/api/issuing/cardholders/update') } },
+      notState: ['type'],
+      filters: ['status', 'type', 'email'],
+    },
+    'issuing.card': {
+      storedAs: 'issuing_card',
+      idPrefix: 'ic',
+      notFound: "No such card: '{id}'",
+      state: { status: { initial: 'active', transitions: setBy('PostIssuingCardsCard', ['active', 'inactive', 'canceled'], 'https://docs.stripe.com/api/issuing/cards/update') } },
+      notState: ['cancellation_reason', 'replacement_reason', 'type'],
+      filters: ['cardholder', 'status', 'type'],
+    },
+    'issuing.authorization': { storedAs: 'issuing_authorization', idPrefix: 'iauth', state: { status: issuingAuthorizationStatus }, notState: ['authorization_method', 'card_presence'] },
+    'issuing.transaction': { storedAs: 'issuing_transaction', idPrefix: 'ipi', notFound: "No such transaction: '{id}'", notState: ['type', 'wallet'], filters: ['card', 'cardholder'] },
+    'issuing.dispute': {
+      storedAs: 'issuing_dispute',
+      idPrefix: 'idp',
+      notFound: "No such dispute: '{id}'",
+      state: {
+        status: {
+          initial: 'unsubmitted',
+          transitions: [
+            { operation: 'PostIssuingDisputesDisputeSubmit', from: ['unsubmitted'], to: 'submitted', refusal: { status: 400, code: 'dispute_unsubmitted_required', message: 'This dispute has already been submitted (status {from}).' }, source: 'spec:PostIssuingDisputesDisputeSubmit "Submits an Issuing <code>Dispute</code> to the card network."' },
+            // (Stripe decides a submitted dispute won or lost and expires one never submitted; the twin decides none)
+          ],
+        },
+      },
+      notState: ['loss_reason'],
+      filters: ['status', 'transaction'],
+    },
+    'issuing.token': {
+      storedAs: 'issuing_token',
+      idPrefix: 'iss_tok',
+      notFound: "No such issuing token: '{id}'",
+      state: { status: { initial: 'active', transitions: [...setBy('PostIssuingTokensToken', ['active', 'deleted', 'suspended'], 'https://docs.stripe.com/api/issuing/tokens/update')] } },
+      notState: ['network', 'wallet_provider'],
+      filters: ['card', 'status'],
+    },
+    // a design waits in review (inactive) until the review test helpers decide it
+    'issuing.personalization_design': {
+      storedAs: 'personalization_design',
+      idPrefix: 'pd',
+      notFound: "No such personalization design: '{id}'",
+      state: {
+        status: {
+          // a new design waits on Stripe's review (docs.stripe.com/issuing/cards/physical/personalization-design)
+          initial: 'review',
+          transitions: [
+            ...setBy('PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignActivate', ['active'], 'spec:PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignActivate "to <code>active</code>"'),
+            ...setBy('PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignDeactivate', ['inactive'], 'spec:PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignDeactivate "to <code>inactive</code>"'),
+            ...setBy('PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignReject', ['rejected'], 'spec:PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignReject "to <code>rejected</code>"'),
+            // (outside test mode Stripe's review decides it; the twin is test mode, where these helpers do)
+          ],
+        },
+      },
+    },
+    'terminal.location': { storedAs: 'terminal_location', idPrefix: 'tml', notFound: "No such location: '{id}'" },
+    // a simulated reader is online from registration; a real one drops off and comes back
+    'terminal.reader': {
+      storedAs: 'terminal_reader', idPrefix: 'tmr', notFound: "No such reader: '{id}'", notState: ['device_type'], filters: ['location', 'status'],
+      // (a real reader goes offline and back; the twin's simulated readers stay online)
+      state: { status: { initial: 'online', transitions: [] } },
+    },
+    'terminal.configuration': { storedAs: 'terminal_configuration', idPrefix: 'tmc', notFound: "No such configuration: '{id}'", notState: ['is_account_default'] },
+    topup: {
+      idPrefix: 'tu',
+      state: {
+        status: {
+          // a top-up starts pending (the create page's example answers "status": "pending") and its funds arrive days
+          // later: "USA (USD) ACH Debit Transfer 5 days" (docs.stripe.com/connect/top-ups; semantics/terminal.ts)
+          initial: 'pending',
+          transitions: [
+            { operation: 'PostTopupsTopupCancel', from: ['pending'], to: 'canceled', refusal: { status: 400, code: 'topup_unexpected_state', message: 'This top-up cannot be canceled because it has a status of {from}.' }, source: 'https://docs.stripe.com/api/topups/cancel' },
+            // to the Issuing balance alike: "Your top-ups can take up to 5 business days to become available"
+            // (docs.stripe.com/issuing/funding/balance)
+            by('vendor', ['pending'], 'succeeded', 'https://docs.stripe.com/connect/top-ups'),
+            // (Stripe also fails a top-up or reverses a settled one; the twin's top-ups do neither)
+          ],
+        },
+      },
+      notState: ['initiated_by'],
+      filters: ['status'],
+    },
+    // closing an account (POST …/close) is not modeled here; is_default is Stripe's
+    'treasury.financial_account': { storedAs: 'financial_account', idPrefix: 'fa', notFound: "No such financial account: '{id}'", state: { status: { initial: 'open', transitions: [] } }, notState: ['is_default'], filters: ['status'] },
+    'treasury.outbound_payment': {
+      storedAs: 'outbound_payment',
+      idPrefix: 'obp',
+      notFound: "No such outbound payment: '{id}'",
+      state: { status: flowCancel('PostTreasuryOutboundPaymentsIdCancel', 'outbound_payment_not_cancelable', 'OutboundPayment', outbound('https://docs.stripe.com/treasury/moving-money/financial-accounts/out-of/outbound-payments')) },
+      filters: ['financial_account', 'status'],
+    },
+    'treasury.outbound_transfer': {
+      storedAs: 'outbound_transfer',
+      idPrefix: 'obt',
+      notFound: "No such outbound transfer: '{id}'",
+      state: { status: flowCancel('PostTreasuryOutboundTransfersOutboundTransferCancel', 'outbound_transfer_not_cancelable', 'OutboundTransfer', outbound('https://docs.stripe.com/treasury/moving-money/financial-accounts/out-of/outbound-transfers')) },
+      filters: ['financial_account', 'status'],
+    },
+    'treasury.inbound_transfer': {
+      storedAs: 'inbound_transfer',
+      idPrefix: 'ibt',
+      notFound: "No such inbound transfer: '{id}'",
+      // "An InboundTransfer is processing if it is created and pending. The status changes to succeeded once the funds have
+      // been "confirmed""; in test mode the succeed helper confirms them (docs.stripe.com/api/treasury/inbound_transfers)
+      state: { status: flowCancel('PostTreasuryInboundTransfersInboundTransferCancel', 'inbound_transfer_not_cancelable', 'InboundTransfer', [
+        { operation: 'PostTestHelpersTreasuryInboundTransfersIdSucceed', from: ['processing'], to: 'succeeded', refusal: { status: 400, code: 'inbound_transfer_not_processing', message: 'This InboundTransfer cannot succeed because it is no longer processing.' }, source: 'https://docs.stripe.com/api/treasury/inbound_transfers' },
+      ]) },
+      filters: ['financial_account', 'status'],
+    },
+    // received credits and debits are materialized by the network (test helpers the twin does not serve)
+    'treasury.received_credit': { storedAs: 'received_credit', idPrefix: 'rc', notFound: "No such received credit: '{id}'", state: { status: { initial: 'succeeded', transitions: [] } }, notState: ['failure_code', 'network'], filters: ['financial_account', 'status'] },
+    'treasury.received_debit': { storedAs: 'received_debit', idPrefix: 'rd', notFound: "No such received debit: '{id}'", state: { status: { initial: 'succeeded', transitions: [] } }, notState: ['failure_code', 'network'], filters: ['financial_account', 'status'] },
+    // a ledger transaction is posted or left open by the flow that writes it; the network settles an open one
+    'treasury.transaction': {
+      storedAs: 'treasury_transaction', idPrefix: 'trxn', notFound: "No such treasury transaction: '{id}'", notState: ['flow_type'],
+      // void: "The Transaction never impacted the balance. For example, a Transaction would enter this state if an
+      // OutboundPayment was initiated but then canceled" (docs.stripe.com/api/treasury/transactions/object); canceling an
+      // outbound flow voids its open transaction (semantics/treasury.ts). (Stripe also posts an open transaction as its
+      // flow settles; the twin's outbound flows stay processing)
+      state: { status: { initial: 'open', transitions: [
+        ...['PostTreasuryOutboundPaymentsIdCancel', 'PostTreasuryOutboundTransfersOutboundTransferCancel', 'PostTreasuryInboundTransfersInboundTransferCancel'].map((operation) => ({ operation, from: ['open'], to: 'void', source: 'https://docs.stripe.com/api/treasury/transactions/object' })),
+        // an inbound transfer's transaction posts when it succeeds ("a transaction is created and posted")
+        { operation: 'PostTestHelpersTreasuryInboundTransfersIdSucceed', from: ['open'], to: 'posted', source: 'https://docs.stripe.com/api/treasury/inbound_transfers' },
+      ] } },
+    },
+    'treasury.transaction_entry': { storedAs: 'treasury_transaction_entry', idPrefix: 'trxne', notFound: "No such transaction entry: '{id}'", notState: ['flow_type', 'type'] },
+    'climate.order': {
+      storedAs: 'climate_order',
+      idPrefix: 'climorder',
+      notFound: "No such order: '{id}'",
+      state: {
+        status: {
+          // an order is created confirmed: the create page's example answers "status": "confirmed" with confirmed_at set
+          // (docs.stripe.com/api/climate/order/create)
+          initial: 'confirmed',
+          transitions: [
+            { operation: 'PostClimateOrdersOrderCancel', from: ['awaiting_funds', 'confirmed', 'open'], to: 'canceled', refusal: { status: 400, code: 'climate_order_not_cancelable', message: 'This order can no longer be canceled because it is {from}.' }, source: 'https://docs.stripe.com/api/climate/order/cancel' },
+            // funded, confirmed by the supplier, then delivered
+            // (Stripe funds, confirms and delivers an order over months; the twin's orders stay where they are made)
+          ],
+        },
+      },
+      notState: ['cancellation_reason'],
+    },
+    'financial_connections.session': { storedAs: 'fc_session', idPrefix: 'fcsess' },
+    'financial_connections.account': {
+      storedAs: 'fc_account',
+      idPrefix: 'fca',
+      notFound: "No such account: '{id}'",
+      state: {
+        status: {
+          initial: 'active',
+          transitions: [
+            { operation: 'PostFinancialConnectionsAccountsAccountDisconnect', from: '*', to: 'disconnected', source: 'https://docs.stripe.com/api/financial_connections/accounts/disconnect' },
+            // (Stripe marks an account inactive when the bank link breaks, and active again; the twin's links hold)
+          ],
+        },
+      },
+      notState: ['category', 'subcategory'],
+    },
+    // a linked account's transactions arrive posted here; the bank settles a pending one
+    'financial_connections.transaction': {
+      storedAs: 'fc_transaction', idPrefix: 'fctxn',
+      // (a bank's pending transaction posts or is voided at Stripe; the twin's arrive posted)
+      state: { status: { initial: 'posted', transitions: [] } },
+    },
+    'forwarding.request': { storedAs: 'forwarding_request', idPrefix: 'fwdr', notFound: "No such forwarding request: '{id}'" },
+    // the twin runs a report at once; Stripe runs it in the background
+    'reporting.report_run': {
+      storedAs: 'report_run', idPrefix: 'frr', notFound: "No such report run: '{id}'",
+      // "When first created, the object appears with status="pending""; "When the run completes, Stripe updates the
+      // object, and it has a status of succeeded" (docs.stripe.com/reports/api; semantics/platform.ts finishReportRuns).
+      // (Stripe may also fail a run; the twin's runs succeed)
+      state: { status: { initial: 'pending', transitions: [by('vendor', ['pending'], 'succeeded', 'https://docs.stripe.com/reports/api')] } },
+    },
+    // archived (active=false) and restored by an update
+    product: { idPrefix: 'prod', update: 'replace', state: { active: { initial: true, transitions: flag('PostProductsId', 'https://docs.stripe.com/api/products/update#update_product-active') } } },
+    product_feature: { idPrefix: 'prodft' },
+    price: {
+      idPrefix: 'price',
+      update: 'replace', notState: ['billing_scheme', 'tax_behavior', 'tiers_mode', 'type'], embeds: { product: 'product' },
+      // deleting a plan leaves its price for its subscribers, inactive: "Deleting plans means new subscribers can’t be added.
+      // Existing subscribers aren’t affected." (docs.stripe.com/api/plans/delete; semantics/plans.ts)
+      state: { active: { initial: true, transitions: [...flag('PostPricesPrice', 'https://docs.stripe.com/api/prices/update#update_price-active'), { operation: 'DeletePlansPlan', from: ['true'], to: 'false', source: 'https://docs.stripe.com/api/plans/delete' }] } },
+    },
+  },
+  view: (storedType, row) => view(storedType, row),
+  onWrite: async ({ operation, storedType, body, root, occurredAt, request }) => {
+    const version = request.headers.get('stripe-version') ?? undefined;
+    // an Issuing authorization carries its full card in every egress, webhooks included; the write
+    // hook is where the root is known, and the body it embeds into is the one the handler answers
+    if (storedType === 'issuing_authorization') embedIssuingAuthorizationCard(body, root);
+    await afterStripeWrite(storedType, operation, body, root, occurredAt, version && isValidApiVersion(version) ? version : undefined, request.headers.get('stripe-account') ?? undefined);
+  },
+};
+