@volter/twin-stripe 2.0.37 → 3.0.0

package/dist/src/manifest.js

@@ -1,443 +1,6 @@
-import { afterStripeWrite, embedIssuingAuthorizationCard, isValidApiVersion, view } from "./stripe-twin.js";
-const unexpected = (verb, allowed) => ({
-    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, from, to, source) => ({ 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) => ({ initial: 'new', transitions: [] });
-/** A flag an update sets either way. */
-const flag = (operation, source) => ['true', 'false'].map((to) => ({ operation, from: '*', to, source }));
-/** A PaymentIntent's `status`: which operation may move it from where, and what Stripe answers otherwise. */
-const paymentIntentStatus = {
-    // "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 = {
-    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 = {
-    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 = {
-    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 = {
-    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 = {
-    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) => ({ 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 = {
-    // "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) => ({ 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 = {
-    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 = {
-    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) => ({ 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 = {
-    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 = {
-    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 = {
-    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 = {
-    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 = {
-    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) => ({ 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 = {
-    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) => ({ 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 = {
-    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, values, source) => values.map((to) => ({ operation, from: '*', 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 = {
-    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, code, name, network) => ({
-    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) => [];
+import { data, values } from "./semantics/events.js";
+import { STRIPE_EVENTS } from "./semantics/shared.js";
+import { states } from "./semantics/states.js";
 export const manifest = {
     vendor: 'stripe',
     service: 'stripe',
@@ -445,6 +8,90 @@ export const manifest = {
     ids: { template: '{prefix}_twin_{n}', acceptProvided: true },
     // on declared resources, but never served by the twin: Stripe's unknown-URL answer
     unmodeled: [
+        // served by the core on a declared resource, but no application's demand (../journeys/demand.json) names them: the gap
+        'DeleteWebhookEndpointsWebhookEndpoint',
+        'GetAccountsAccountPersons',
+        'GetApplicationFees',
+        'GetApplicationFeesId',
+        'GetBillingAlertsId',
+        'GetBillingCreditGrants',
+        'GetBillingCreditGrantsId',
+        'GetBillingPortalConfigurationsConfiguration',
+        'GetClimateOrders',
+        'GetClimateOrdersOrder',
+        'GetCoupons',
+        'GetCreditNotes',
+        'GetEntitlementsFeaturesId',
+        'GetFiles',
+        'GetFilesFile',
+        'GetFinancialConnectionsAccountsAccount',
+        'GetForwardingRequests',
+        'GetForwardingRequestsId',
+        'GetIdentityVerificationReports',
+        'GetIdentityVerificationReportsReport',
+        'GetIdentityVerificationSessionsSession',
+        'GetIssuingCardholders',
+        'GetIssuingCardholdersCardholder',
+        'GetIssuingCardsCard',
+        'GetIssuingDisputes',
+        'GetIssuingDisputesDispute',
+        'GetIssuingPersonalizationDesignsPersonalizationDesign',
+        'GetIssuingTokens',
+        'GetIssuingTokensToken',
+        'GetIssuingTransactions',
+        'GetIssuingTransactionsTransaction',
+        'GetMandatesMandate',
+        'GetPaymentLinksPaymentLink',
+        'GetQuotes',
+        'GetQuotesQuote',
+        'GetRadarValueListItemsItem',
+        'GetRadarValueLists',
+        'GetRadarValueListsValueList',
+        'GetReportingReportRuns',
+        'GetReportingReportRunsReportRun',
+        'GetReviews',
+        'GetReviewsReview',
+        'GetSetupIntentsIntent',
+        'GetSourcesSource',
+        'GetSubscriptionSchedules',
+        'GetTaxCalculationsCalculation',
+        'GetTaxRatesTaxRate',
+        'GetTaxRegistrations',
+        'GetTaxRegistrationsId',
+        'GetTaxTransactionsTransaction',
+        'GetTerminalConfigurations',
+        'GetTerminalConfigurationsConfiguration',
+        'GetTerminalLocations',
+        'GetTerminalLocationsLocation',
+        'GetTerminalReaders',
+        'GetTerminalReadersReader',
+        'GetTestHelpersTestClocks',
+        'GetTokensToken',
+        'GetTopups',
+        'GetTopupsTopup',
+        'GetTransfersTransfer',
+        'GetTreasuryFinancialAccounts',
+        'GetTreasuryFinancialAccountsFinancialAccount',
+        'GetTreasuryInboundTransfers',
+        'GetTreasuryInboundTransfersId',
+        'GetTreasuryOutboundPayments',
+        'GetTreasuryOutboundPaymentsId',
+        'GetTreasuryOutboundTransfers',
+        'GetTreasuryOutboundTransfersOutboundTransfer',
+        'GetTreasuryReceivedCredits',
+        'GetTreasuryReceivedCreditsId',
+        'GetTreasuryReceivedDebits',
+        'GetTreasuryReceivedDebitsId',
+        'GetTreasuryTransactionEntriesId',
+        'GetTreasuryTransactionsId',
+        'GetWebhookEndpoints',
+        'GetWebhookEndpointsWebhookEndpoint',
+        'PostCouponsCoupon',
+        'PostPaymentIntentsIntent',
+        'PostPaymentLinksPaymentLink',
+        'PostRefundsRefund',
+        'PostSetupIntentsIntent',
+        'PostTransfersTransfer',
         'DeleteAccountsAccountBankAccountsId',
         'DeleteAccountsAccountPeoplePerson',
         'DeleteCustomersCustomerSubscriptionsSubscriptionExposedId',
@@ -516,6 +163,64 @@ export const manifest = {
             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 pack as the World registers it (world-core packRegistry)
+    // the fail-closed ceiling on live calls against Stripe (world-core rateBudget.ts, architecture D8)
+    rateBudget: {
+        windowMs: 60_000,
+        ceiling: 120,
+        defaultWeight: 1,
+        maxRetryAfterSeconds: 300,
+        rules: [
+            { match: '^POST /v1/payouts$', weight: 5 },
+            { match: '^(POST|DELETE) ', weight: 2 },
+        ],
+        reason: 'Stripe documents scalar limits (docs.stripe.com/rate-limits, read 2026-07-26): 100 requests/second in live mode, 25/second in ' +
+            'sandbox, 25/second for an individual endpoint unless noted, 15 payout creates/second; over it, 429 with a Stripe-Rate-Limited-Reason ' +
+            'header. 120 weighted units / 60s is 2 requests/second, 2% of live mode and 8% of the tightest general limit. POST/DELETE cost 2, a ' +
+            'judgement about blast radius (a write creates a charge, refund or receipt e-mail and cannot be taken back), not a published ratio; ' +
+            "POST /v1/payouts costs 5 because payout creation is documented at 15/second. Stripe's own window is a second, so an intra-second " +
+            'burst reaches its limiter first; the 429 cooldown is the backstop for that shape.',
+    },
+    descriptor: {
+        protocol: '3',
+        transport: 'rest',
+        archetype: 'crud',
+        bin: 'world-stripe',
+        resources: ['charge', 'customer', 'payment_intent', 'setup_intent', 'payment_method', 'subscription', 'price', 'product', 'invoice', 'invoiceitem', 'refund', 'event'],
+        specSource: "Stripe's OpenAPI document (spec/, provenance in spec/SOURCE.md)",
+        description: 'Stripe REST twin — spec-correct shapes, signed events, and the hosted pages an application sends people through.',
+        // Stripe.js calls the same-origin '/v1/…' and loads from api.stripe.com — the dev proxy forwards '/v1/' to the twin
+        // and strips the absolute host so calls come back same-origin
+        browserRouting: { apiPathPrefix: '/v1/', loaderHost: 'https://api.stripe.com' },
+        // the official server SDK and its Python bindings, and the STRIPE_* credential stems (NEXT_PRIVATE_STRIPE_* too);
+        // `stripeconnect` is deliberately not claimed: no Connect-only credential stem is modelled
+        adoption: { pypi: ['stripe'], sdks: ['stripe'], envStems: ['STRIPE', 'NEXTPRIVATESTRIPE'] },
+        // the API and the screens' hosts, each claimed for the paths its screens serve: an application that sends a person
+        // to one of their urls lands in the World; any other path on a claimed host is refused in a World rather than sent
+        // to the real Stripe
+        // a World's applications hold the platform's keys the dashboard shows (the credential door), never fixtures: the API
+        // refuses a key Stripe did not issue
+        credentialDoor: { path: '/_twin/app-credentials', body: {}, fill: { STRIPE_SECRET_KEY: 'secret_key', STRIPE_API_KEY: 'secret_key', STRIPE_PRIVATE_KEY: 'secret_key', BILLING_STRIPE_API_KEY: 'secret_key', STRIPE_PUBLISHABLE_KEY: 'publishable_key', NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: 'publishable_key', NEXT_PUBLIC_STRIPE_PUBLIC_KEY: 'publishable_key', NEXT_PUBLIC_STRIPE_KEY: 'publishable_key', STRIPE_WEBHOOK_SECRET: 'webhook_secret', STRIPE_WEBHOOK_SIGNING_SECRET: 'webhook_secret', STRIPE_ENDPOINT_SECRET: 'webhook_secret', STRIPE_WEBHOOK_SECRET_KEY: 'webhook_secret', NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET: 'webhook_secret', BILLING_STRIPE_WEBHOOK_SECRET: 'webhook_secret', STRIPE_CONNECT_WEBHOOK_SECRET: 'connect_webhook_secret', STRIPE_WEBHOOK_SECRET_CONNECT: 'connect_webhook_secret', STRIPE_CONNECT_WEBHOOK_SIGNING_SECRET: 'connect_webhook_secret' } },
+        hosts: [
+            { host: 'api.stripe.com' }, { host: 'checkout.stripe.com', pathPattern: '^/c/pay/' }, { host: 'billing.stripe.com', pathPattern: '^/p/session/' },
+            { host: 'connect.stripe.com', pathPattern: '^/setup/|^/oauth/(authorize|token|deauthorize)/?$' },
+            { host: 'dashboard.stripe.com', pathPattern: '^/settings/public/?$|^/(test/)?settings/connect(/onboarding-options/oauth)?/?$' },
+            { host: 'verify.stripe.com', pathPattern: '^/start/' },
+            { host: 'js.stripe.com', pathPattern: '^/v3/financial-connections/|^/v3/?$|^/(v3|[a-z]+)/stripe\\.js$' },
+        ],
+    },
+    // what GET /twin says this twin is
+    discovery: {
+        twinOf: 'the Stripe REST API, its hosted pages (Checkout, the customer portal, Connect onboarding and OAuth, Identity, Financial Connections) and Stripe.js',
+        stores: 'customers, payment objects, checkout sessions, products and prices, subscriptions and invoices, Connect accounts, Issuing, Treasury, and webhook endpoints (signed events)',
+    },
+    // the World's doors (./semantics/doors.ts): what stands in for an act Stripe's API does not have
+    doors: [
+        { id: 'account', method: 'POST', path: '/_twin/account', note: "the platform's own account settings, as the Dashboard changes them" },
+        { id: 'appCredentials', method: 'POST', path: '/_twin/app-credentials', note: 'the platform\'s API keys (secret and publishable), as the runtime issues them' },
+        { id: 'webhookEndpoints', method: 'POST', path: '/_twin/webhook-endpoints', note: '{ url, events, connect? }: an endpoint added on the Dashboard\'s Webhooks page, signed with the secret the World\'s application holds' },
+        { id: 'drain', method: 'POST', path: '/_twin/drain', note: "time's events, sent when a runner drives them: payouts paid and funds made available" },
+    ],
     // 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: [
@@ -531,63 +236,51 @@ export const manifest = {
             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',
+            // an Account Link's url (/setup/{account_link}) opens the onboarding session the page is (/setup/s/{session})
+            id: 'connect-onboarding', kind: 'flow', host: 'connect.stripe.com', path: '/setup', 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: 'connect-oauth', kind: 'flow', host: 'connect.stripe.com', path: '/oauth/authorize', status: 'done',
+            // the authorize page, and the token and deauthorize endpoints the platform's server calls (not in Stripe's spec)
+            id: 'connect-oauth', kind: 'flow', host: 'connect.stripe.com', path: '/oauth', status: 'done',
             demand: "Cal.com's Stripe app connects each organizer's Standard account through Connect OAuth", controls: ['Skip this form', 'Deny access'],
             source: 'https://docs.stripe.com/connect/oauth-reference',
         },
         {
-            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',
+            // Stripe.js, the client library an application's page loads: /v3/, /v3/stripe.js and /<release train>/stripe.js
+            id: 'stripe-js', kind: 'content', host: 'js.stripe.com', path: '/', status: 'done',
+            demand: "Dub's upgrade button loads Stripe.js and calls redirectToCheckout",
+            source: 'https://docs.stripe.com/js',
         },
         {
-            id: 'dashboard', kind: 'workspace', host: 'dashboard.stripe.com', path: '/test/{section}; /settings/public; /settings/connect/onboarding-options/oauth', status: 'done',
-            demand: 'testers and agents inspect payments, customers and subscriptions; an operator sets the business name Checkout shows (Public details) and a Connect platform its OAuth client_id and redirect URIs',
+            id: 'dashboard', kind: 'workspace', host: 'dashboard.stripe.com', path: '/', status: 'done',
+            demand: 'an operator sets the business name Checkout shows (Public details: /settings/public) and a Connect platform its OAuth client_id and redirect URIs (/settings/connect/onboarding-options/oauth)',
             controls: ['Business name', 'Save', 'Enable OAuth for Standard accounts', 'Redirect URIs'], 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' },
-                    ] } },
+            storedAs: 'billing_meter', idPrefix: 'mtr', notFound: "No such meter: '{id}'", ...states["billing.meter"], filters: ['status'],
         },
         '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.credit_grant': { storedAs: 'credit_grant', idPrefix: 'credgr', ...states["billing.credit_grant"], 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' },
-                    ] } },
+            storedAs: 'billing_alert', idPrefix: 'alert', notFound: "No such alert: '{id}'", ...states["billing.alert"],
         },
         payment_intent: {
-            idPrefix: 'pi',
-            state: { status: paymentIntentStatus },
-            notState: ['cancellation_reason', 'capture_method', 'confirmation_method', 'setup_future_usage'],
+            idPrefix: 'pi', ...states["payment_intent"],
             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'] },
+        // next_invoice_sequence, "The suffix of the customer's next invoice number" (docs.stripe.com/api/customers/object): one
+        // past its numbered invoices (a finalized invoice is never deleted)
+        customer: { idPrefix: 'cus', update: 'replace', ...states["customer"], filters: ['email'], counts: { next_invoice_sequence: { of: 'invoice', by: 'customer', present: 'number', plus: 1 } } },
+        tax_id: { idPrefix: 'txi', ...states["tax_id"], filters: ['customer'] },
+        customer_balance_transaction: { idPrefix: 'cbtxn', ...states["customer_balance_transaction"], },
+        customer_cash_balance_transaction: { storedAs: 'cash_balance_transaction', idPrefix: 'ccsbtxn', ...states["customer_cash_balance_transaction"], },
         // 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
@@ -595,69 +288,46 @@ export const manifest = {
         // 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'],
+            idPrefix: 'src', ...states["payment_source"],
         },
         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'],
+            idPrefix: 'src', ...states["source"],
         },
+        // Connect OAuth's authorization codes: the row's id minted, the code's value drawn from the World's secret
+        _oauth_code: { idPrefix: '', ids: '{n}' },
         charge: {
-            idPrefix: 'ch',
-            state: { status: chargeStatus, captured: chargeCaptured, paid: chargePaid, refunded: chargeRefunded },
+            idPrefix: 'ch', ...states["charge"],
             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'],
+            update: 'replace', ...states["refund"],
             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'],
+            update: 'replace', ...states["setup_intent"],
             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'] },
+        payment_method: { idPrefix: 'pm', ...states["payment_method"], embeds: { customer: 'customer' }, filters: ['customer', 'type'] },
         subscription: {
-            idPrefix: 'sub',
-            state: { status: subscriptionStatus },
-            notState: ['collection_method'],
+            idPrefix: 'sub', ...states["subscription"],
             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'],
+            idPrefix: 'in', ...states["invoice"],
             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'],
+            idPrefix: 'cs', ...states["checkout.session"],
             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' },
@@ -665,120 +335,61 @@ export const manifest = {
         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'],
+            idPrefix: 'mandate', ...states["mandate"],
         },
-        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' } },
+        dispute: { idPrefix: 'dp', update: 'replace', ...states["dispute"], embeds: { charge: 'charge', payment_intent: 'payment_intent' }, filters: ['charge', 'payment_intent'] },
+        payout: { idPrefix: 'po', ...states["payout"], 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'],
+            idPrefix: 'txn', ...states["balance_transaction"],
             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."')] } },
+            idPrefix: 'coupon', update: 'replace', ...states["coupon"],
         },
         // 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'),
-                    ],
-                },
-            },
+            notFound: "No such promotion code: '{id}'", ...states["promotion_code"],
         },
-        credit_note: { idPrefix: 'cn', state: { status: creditNoteStatus }, notState: ['reason', 'type'], embeds: { customer: 'customer', invoice: 'invoice' }, filters: ['invoice', 'customer'] },
+        credit_note: { idPrefix: 'cn', ...states["credit_note"], embeds: { customer: 'customer', invoice: 'invoice' }, filters: ['invoice', 'customer'] },
         subscription_schedule: {
             idPrefix: 'sub_sched',
-            update: 'replace',
-            state: { status: scheduleStatus },
-            notState: ['end_behavior'],
+            update: 'replace', ...states["subscription_schedule"],
             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."') } },
+            storedAs: 'entitlements_feature', idPrefix: 'feat', notFound: "No such feature: '{id}'", ...states["entitlements.feature"],
         },
-        // an advance answers advancing and the clock is ready once it has reached the time (semantics/test-clocks.ts)
+        // an advance answers advancing and the clock is ready once it has reached the time (./engine/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)
-                    ],
-                },
-            },
+            notFound: "No such test clock: '{id}'", ...states["test_helpers.test_clock"],
         },
         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: '*', to, source: 'https://docs.stripe.com/api/webhook_endpoints/update#update_webhook_endpoint-disabled' })),
-                    ],
-                },
-            },
+            notFound: "No such webhook endpoint: '{id}'", ...states["webhook_endpoint"],
         },
-        account: { idPrefix: 'acct', notState: ['business_type', 'type'] },
-        person: { idPrefix: 'person', notState: ['political_exposure'], parent: { param: 'account', field: 'account', resource: 'account' } },
+        account: { idPrefix: 'acct', ...states["account"], },
+        person: { idPrefix: 'person', ...states["person"], 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: '*', 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'),
-                    ],
-                },
-            },
+            idPrefix: 'cap', ...states["capability"],
         },
         // 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'],
+            idPrefix: 'ba', ...states["external_account"],
         },
         account_link: { idPrefix: 'acctlink' },
         account_session: { idPrefix: 'accts' },
@@ -786,285 +397,148 @@ export const manifest = {
         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' })),
-                    ] } },
+            idPrefix: 'fee', notFound: "No such application fee: '{id}'", filters: ['charge'], ...states["application_fee"],
         },
         fee_refund: { idPrefix: 'fr' },
         'apps.secret': { storedAs: 'apps_secret', idPrefix: 'apmc' },
         token: { idPrefix: 'tok' },
-        file: { idPrefix: 'file', notState: ['purpose'], filters: ['purpose'] },
+        file: { idPrefix: 'file', ...states["file"], 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'],
+            notFound: "No such VerificationSession: '{id}'", ...states["identity.verification_session"],
         },
-        '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'] },
+        'identity.verification_report': { storedAs: 'verification_report', idPrefix: 'vr', notFound: "No such verification report: '{id}'", ...states["identity.verification_report"], filters: ['verification_session', 'type'] },
+        'billing_portal.session': { storedAs: 'billing_portal_session', idPrefix: 'bps', ...states["billing_portal.session"], },
         // 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'],
+            storedAs: 'billing_portal_configuration', idPrefix: 'bpc', notFound: "No such configuration: '{id}'", ...states["billing_portal.configuration"],
         },
         // `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'],
+            idPrefix: 'txr', notFound: "No such tax rate: '{id}'", ...states["tax_rate"],
         },
         // 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.settings': { storedAs: 'tax_settings', idPrefix: 'taxset', ...states["tax.settings"], },
         '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: [] },
-            },
+            storedAs: 'tax_registration', idPrefix: 'taxreg', notFound: "No such tax registration: '{id}'", filters: ['status'], ...states["tax.registration"],
         },
-        'tax.transaction': { storedAs: 'tax_transaction', idPrefix: 'tax', notFound: "No such tax transaction: '{id}'", notState: ['type'] },
+        'tax.transaction': { storedAs: 'tax_transaction', idPrefix: 'tax', notFound: "No such tax transaction: '{id}'", ...states["tax.transaction"], },
         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'],
+            update: 'replace', notFound: "No such payment link: '{id}'", ...states["payment_link"],
         },
-        quote: { idPrefix: 'qt', state: { status: quoteStatus }, notState: ['collection_method'], filters: ['customer', 'status'] },
+        quote: { idPrefix: 'qt', ...states["quote"], 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'],
+            idPrefix: 'prv', ...states["review"],
         },
-        'radar.value_list': { storedAs: 'radar_value_list', idPrefix: 'rsl', notFound: "No such radar value list: '{id}'", notState: ['item_type'], filters: ['alias'] },
+        'radar.value_list': { storedAs: 'radar_value_list', idPrefix: 'rsl', notFound: "No such radar value list: '{id}'", ...states["radar.value_list"], 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'],
+            notFound: "No such cardholder: '{id}'", ...states["issuing.cardholder"],
             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'],
+            notFound: "No such card: '{id}'", ...states["issuing.card"],
             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.authorization': { storedAs: 'issuing_authorization', idPrefix: 'iauth', ...states["issuing.authorization"], },
+        'issuing.transaction': { storedAs: 'issuing_transaction', idPrefix: 'ipi', notFound: "No such transaction: '{id}'", ...states["issuing.transaction"], 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'],
+            notFound: "No such dispute: '{id}'", ...states["issuing.dispute"],
             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'],
+            notFound: "No such issuing token: '{id}'", ...states["issuing.token"],
             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)
-                    ],
-                },
-            },
+            notFound: "No such personalization design: '{id}'", ...states["issuing.personalization_design"],
         },
         '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: [] } },
+            storedAs: 'terminal_reader', idPrefix: 'tmr', notFound: "No such reader: '{id}'", ...states["terminal.reader"], filters: ['location', 'status'],
         },
-        'terminal.configuration': { storedAs: 'terminal_configuration', idPrefix: 'tmc', notFound: "No such configuration: '{id}'", notState: ['is_account_default'] },
+        'terminal.configuration': { storedAs: 'terminal_configuration', idPrefix: 'tmc', notFound: "No such configuration: '{id}'", ...states["terminal.configuration"], },
         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'],
+            idPrefix: 'tu', ...states["topup"],
             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.financial_account': { storedAs: 'financial_account', idPrefix: 'fa', notFound: "No such financial account: '{id}'", ...states["treasury.financial_account"], 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')) },
+            notFound: "No such outbound payment: '{id}'", ...states["treasury.outbound_payment"],
             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')) },
+            notFound: "No such outbound transfer: '{id}'", ...states["treasury.outbound_transfer"],
             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' },
-                ]) },
+            notFound: "No such inbound transfer: '{id}'", ...states["treasury.inbound_transfer"],
             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'] },
+        'treasury.received_credit': { storedAs: 'received_credit', idPrefix: 'rc', notFound: "No such received credit: '{id}'", ...states["treasury.received_credit"], filters: ['financial_account', 'status'] },
+        'treasury.received_debit': { storedAs: 'received_debit', idPrefix: 'rd', notFound: "No such received debit: '{id}'", ...states["treasury.received_debit"], 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' },
-                    ] } },
+            storedAs: 'treasury_transaction', idPrefix: 'trxn', notFound: "No such treasury transaction: '{id}'", ...states["treasury.transaction"],
         },
-        'treasury.transaction_entry': { storedAs: 'treasury_transaction_entry', idPrefix: 'trxne', notFound: "No such transaction entry: '{id}'", notState: ['flow_type', 'type'] },
+        'treasury.transaction_entry': { storedAs: 'treasury_transaction_entry', idPrefix: 'trxne', notFound: "No such transaction entry: '{id}'", ...states["treasury.transaction_entry"], },
         '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'],
+            notFound: "No such order: '{id}'", ...states["climate.order"],
         },
         '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'],
+            notFound: "No such account: '{id}'", ...states["financial_connections.account"],
         },
         // 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: [] } },
+            storedAs: 'fc_transaction', idPrefix: 'fctxn', ...states["financial_connections.transaction"],
         },
         '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')] } },
+            storedAs: 'report_run', idPrefix: 'frr', notFound: "No such report run: '{id}'", ...states["reporting.report_run"],
         },
         // 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: { idPrefix: 'prod', update: 'replace', ...states["product"], },
         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' }] } },
+            update: 'replace', ...states["price"], embeds: { product: 'product' },
         },
     },
-    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);
-    },
+    // the webhooks Stripe's writes send (./semantics/shared.ts), each event's data and account rendered by ./semantics/events.ts
+    events: { ...STRIPE_EVENTS, render: data, values },
 };