@volter/twin-stripe 2.0.38 → 3.0.1

package/dist/src/manifest.js

@@ -1,491 +1,285 @@
-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',
     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',
+        'DeleteAccountsAccountExternalAccountsId',
         'DeleteAccountsAccountPeoplePerson',
+        'DeleteAccountsAccountPersonsPerson',
+        'DeleteCouponsCoupon',
+        'DeleteCustomersCustomerSourcesId',
         'DeleteCustomersCustomerSubscriptionsSubscriptionExposedId',
+        'DeleteCustomersCustomerTaxIdsId',
+        'DeleteEphemeralKeysKey',
+        'DeleteInvoiceitemsInvoiceitem',
+        'DeleteInvoicesInvoice',
+        'DeleteProductsId',
+        'DeleteProductsProductFeaturesId',
+        'DeleteRadarValueListItemsItem',
+        'DeleteRadarValueListsValueList',
+        'DeleteSubscriptionItemsItem',
         'DeleteTaxIdsId',
+        'DeleteTerminalConfigurationsConfiguration',
+        'DeleteTerminalLocationsLocation',
+        'DeleteTerminalReadersReader',
+        'DeleteTestHelpersTestClocksTestClock',
+        'DeleteWebhookEndpointsWebhookEndpoint',
         'GetAccountsAccountBankAccountsId',
+        'GetAccountsAccountCapabilities',
+        'GetAccountsAccountCapabilitiesCapability',
+        'GetAccountsAccountExternalAccountsId',
         'GetAccountsAccountPeople',
         'GetAccountsAccountPeoplePerson',
+        'GetAccountsAccountPersonsPerson',
         'GetApplicationFeesFeeRefundsId',
+        'GetApplicationFeesId',
+        'GetAppsSecrets',
         'GetBalanceHistory',
         'GetBalanceHistoryId',
+        'GetBalanceTransactionsId',
+        'GetBillingAlertsId',
+        'GetBillingCreditGrantsId',
+        'GetBillingMetersId',
+        'GetBillingPortalConfigurationsConfiguration',
         'GetChargesChargeDispute',
+        'GetChargesChargeRefunds',
+        'GetChargesChargeRefundsRefund',
+        'GetClimateOrdersOrder',
+        'GetCreditNotesId',
+        'GetCreditNotesPreview',
+        'GetCustomersCustomerBalanceTransactionsTransaction',
+        'GetCustomersCustomerCashBalanceTransactionsTransaction',
+        'GetCustomersCustomerPaymentMethods',
+        'GetCustomersCustomerPaymentMethodsPaymentMethod',
+        'GetCustomersCustomerSourcesId',
         'GetCustomersCustomerSubscriptions',
         'GetCustomersCustomerSubscriptionsSubscriptionExposedId',
-        'GetFileLinks',
+        'GetCustomersCustomerTaxIds',
+        'GetCustomersCustomerTaxIdsId',
+        'GetDisputesDispute',
+        'GetEntitlementsActiveEntitlements',
+        'GetEntitlementsFeaturesId',
+        'GetEventsId',
         'GetFileLinksLink',
+        'GetFilesFile',
+        'GetFinancialConnectionsAccountsAccount',
+        'GetFinancialConnectionsSessionsSession',
+        'GetFinancialConnectionsTransactions',
         'GetFinancialConnectionsTransactionsTransaction',
-        'GetIdentityVerificationSessions',
+        'GetIdentityVerificationReportsReport',
+        'GetIdentityVerificationSessionsSession',
+        'GetInvoiceitemsInvoiceitem',
+        'GetInvoicesInvoiceLines',
+        'GetIssuingAuthorizationsAuthorization',
+        'GetIssuingCardholdersCardholder',
+        'GetIssuingDisputesDispute',
+        'GetIssuingPersonalizationDesignsPersonalizationDesign',
+        'GetIssuingTransactionsTransaction',
         'GetLinkAccountSessionsSession',
         'GetLinkedAccounts',
         'GetLinkedAccountsAccount',
+        'GetMandatesMandate',
+        'GetPaymentIntentsIntent',
+        'GetPaymentIntentsSearch',
+        'GetPaymentLinksPaymentLink',
+        'GetPayoutsPayout',
+        'GetProductsId',
+        'GetProductsProductFeaturesId',
+        'GetProductsSearch',
+        'GetQuotesQuote',
+        'GetRadarValueListItems',
+        'GetRadarValueListItemsItem',
+        'GetRadarValueListsValueList',
+        'GetRefundsRefund',
+        'GetReportingReportRunsReportRun',
+        'GetReviewsReview',
+        'GetSetupIntentsIntent',
+        'GetSourcesSource',
+        'GetSubscriptionItems',
+        'GetSubscriptionItemsItem',
+        'GetSubscriptionSchedulesSchedule',
+        'GetSubscriptionsSearch',
+        'GetTaxCalculationsCalculation',
         'GetTaxIdsId',
+        'GetTaxRatesTaxRate',
+        'GetTaxRegistrationsId',
+        'GetTaxTransactionsTransaction',
+        'GetTerminalConfigurationsConfiguration',
+        'GetTerminalLocationsLocation',
+        'GetTerminalReadersReader',
+        'GetTestHelpersTestClocks',
+        'GetTestHelpersTestClocksTestClock',
+        'GetTokensToken',
+        'GetTopups',
+        'GetTopupsTopup',
+        'GetTransfersTransfer',
         'GetTransfersTransferReversalsId',
+        'GetTreasuryFinancialAccountsFinancialAccount',
+        'GetTreasuryInboundTransfers',
+        'GetTreasuryInboundTransfersId',
+        'GetTreasuryOutboundPayments',
+        'GetTreasuryOutboundPaymentsId',
+        'GetTreasuryOutboundTransfers',
+        'GetTreasuryOutboundTransfersOutboundTransfer',
+        'GetTreasuryReceivedCredits',
+        'GetTreasuryReceivedCreditsId',
+        'GetTreasuryReceivedDebits',
+        'GetTreasuryReceivedDebitsId',
+        'GetTreasuryTransactionEntries',
+        'GetTreasuryTransactionEntriesId',
+        'GetTreasuryTransactions',
+        'GetTreasuryTransactionsId',
+        'GetWebhookEndpointsWebhookEndpoint',
+        'PostAccountsAccount',
         'PostAccountsAccountBankAccounts',
         'PostAccountsAccountBankAccountsId',
+        'PostAccountsAccountCapabilitiesCapability',
+        'PostAccountsAccountExternalAccounts',
         'PostAccountsAccountExternalAccountsId',
         'PostAccountsAccountPeople',
         'PostAccountsAccountPeoplePerson',
+        'PostAccountsAccountPersons',
+        'PostAccountsAccountPersonsPerson',
         'PostApplicationFeesFeeRefundsId',
+        'PostApplicationFeesIdRefunds',
+        'PostBillingAlerts',
+        'PostBillingAlertsIdActivate',
+        'PostBillingAlertsIdArchive',
+        'PostBillingAlertsIdDeactivate',
+        'PostBillingCreditGrants',
+        'PostBillingCreditGrantsId',
+        'PostBillingMeters',
         'PostBillingMetersId',
+        'PostBillingMetersIdDeactivate',
+        'PostBillingMetersIdReactivate',
+        'PostBillingPortalConfigurationsConfiguration',
+        'PostCharges',
+        'PostChargesCharge',
+        'PostChargesChargeCapture',
+        'PostChargesChargeRefunds',
+        'PostChargesChargeRefundsRefund',
+        'PostCheckoutSessionsSession',
+        'PostCheckoutSessionsSessionExpire',
+        'PostClimateOrders',
+        'PostClimateOrdersOrder',
+        'PostClimateOrdersOrderCancel',
+        'PostCouponsCoupon',
+        'PostCreditNotes',
+        'PostCreditNotesId',
+        'PostCreditNotesIdVoid',
+        'PostCustomersCustomerBalanceTransactions',
         'PostCustomersCustomerBalanceTransactionsTransaction',
+        'PostCustomersCustomerSources',
         'PostCustomersCustomerSubscriptions',
         'PostCustomersCustomerSubscriptionsSubscriptionExposedId',
+        'PostCustomersCustomerTaxIds',
+        'PostDisputesDispute',
+        'PostDisputesDisputeClose',
+        'PostEntitlementsFeatures',
+        'PostEntitlementsFeaturesId',
+        'PostFileLinks',
         'PostFileLinksLink',
+        'PostFiles',
+        'PostFinancialConnectionsAccountsAccountDisconnect',
+        'PostFinancialConnectionsSessions',
+        'PostIdentityVerificationSessions',
         'PostIdentityVerificationSessionsSession',
+        'PostInvoiceitems',
+        'PostInvoiceitemsInvoiceitem',
         'PostInvoicesInvoice',
+        'PostInvoicesInvoiceFinalize',
+        'PostInvoicesInvoiceMarkUncollectible',
+        'PostInvoicesInvoiceSend',
+        'PostIssuingAuthorizationsAuthorization',
+        'PostIssuingCardholdersCardholder',
+        'PostIssuingDisputes',
+        'PostIssuingDisputesDispute',
+        'PostIssuingDisputesDisputeSubmit',
+        'PostIssuingPersonalizationDesigns',
+        'PostIssuingPersonalizationDesignsPersonalizationDesign',
+        'PostIssuingTransactionsTransaction',
         'PostLinkAccountSessions',
+        'PostPaymentIntentsIntent',
+        'PostPaymentIntentsIntentApplyCustomerBalance',
+        'PostPaymentIntentsIntentCapture',
+        'PostPaymentIntentsIntentConfirm',
+        'PostPaymentIntentsIntentIncrementAuthorization',
+        'PostPaymentIntentsIntentVerifyMicrodeposits',
+        'PostPaymentLinks',
+        'PostPaymentLinksPaymentLink',
+        'PostPaymentMethods',
         'PostPaymentMethodsPaymentMethod',
+        'PostPaymentMethodsPaymentMethodAttach',
         'PostPayoutsPayout',
+        'PostPayoutsPayoutCancel',
+        'PostPlans',
+        'PostPricesPrice',
+        'PostProductsId',
+        'PostProductsProductFeatures',
+        'PostQuotes',
         'PostQuotesQuote',
+        'PostQuotesQuoteAccept',
+        'PostQuotesQuoteCancel',
+        'PostQuotesQuoteFinalize',
+        'PostRadarValueLists',
+        'PostRadarValueListsValueList',
+        'PostRefundsRefund',
+        'PostRefundsRefundCancel',
+        'PostReportingReportRuns',
+        'PostReviewsReviewApprove',
+        'PostSetupIntents',
+        'PostSetupIntentsIntent',
+        'PostSetupIntentsIntentCancel',
+        'PostSetupIntentsIntentConfirm',
+        'PostSetupIntentsIntentVerifyMicrodeposits',
+        'PostSources',
+        'PostSourcesSource',
+        'PostSubscriptionItems',
+        'PostSubscriptionItemsItem',
+        'PostSubscriptionSchedules',
+        'PostSubscriptionSchedulesSchedule',
+        'PostSubscriptionSchedulesScheduleCancel',
+        'PostSubscriptionSchedulesScheduleRelease',
+        'PostSubscriptions',
+        'PostTaxCalculations',
+        'PostTaxIds',
+        'PostTaxRates',
+        'PostTaxRatesTaxRate',
+        'PostTaxRegistrations',
         'PostTaxRegistrationsId',
+        'PostTerminalConfigurations',
+        'PostTerminalConfigurationsConfiguration',
+        'PostTerminalLocations',
+        'PostTerminalLocationsLocation',
+        'PostTerminalReaders',
+        'PostTerminalReadersReader',
+        'PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignActivate',
+        'PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignDeactivate',
+        'PostTestHelpersIssuingPersonalizationDesignsPersonalizationDesignReject',
+        'PostTestHelpersTestClocks',
+        'PostTestHelpersTestClocksTestClockAdvance',
+        'PostTestHelpersTreasuryInboundTransfersIdSucceed',
+        'PostTokens',
+        'PostTopups',
+        'PostTopupsTopup',
+        'PostTopupsTopupCancel',
+        'PostTransfersIdReversals',
+        'PostTransfersTransfer',
         'PostTransfersTransferReversalsId',
+        'PostTreasuryFinancialAccounts',
+        'PostTreasuryFinancialAccountsFinancialAccount',
+        'PostTreasuryInboundTransfers',
+        'PostTreasuryInboundTransfersInboundTransferCancel',
+        'PostTreasuryOutboundPayments',
+        'PostTreasuryOutboundPaymentsIdCancel',
+        'PostTreasuryOutboundTransfers',
+        'PostTreasuryOutboundTransfersOutboundTransferCancel',
+        'PostWebhookEndpointsWebhookEndpoint',
     ],
     time: 'unix',
     error: { error: { type: '{kind}', message: '{message}', code: '{code}', param: '{param}' } },
@@ -497,6 +291,10 @@ export const manifest = {
         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' },
     },
+    // source: https://github.com/stripe/stripe-mock/issues/31 "Unrecognized request URL (GET: /v1/test)."
+    // source: spec:/components/schemas/api_errors/properties/type "invalid_request_error"
+    // Stripe's published API answer, shown by its maintainer for an unknown URL.
+    gap: { status: 404, kind: 'invalid_request_error', message: 'Unrecognized request URL ({method}: {path}). Please see https://stripe.com/docs or we can help at https://support.stripe.com/.' },
     notFound: { status: 404, kind: 'invalid_request_error', code: 'resource_missing', message: "No such {object}: '{id}'" },
     list: {
         style: 'envelope',
@@ -516,555 +314,359 @@ 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), inside its sandbox
+    // allowance
+    // source: https://docs.stripe.com/rate-limits "25 requests per second"
+    rateBudget: {
+        // the vendor's documented allowance this budget stays inside (cited above)
+        allowance: { perMinute: 1500, source: 'https://docs.stripe.com/rate-limits' },
+        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/' },
+            { host: 'dashboard.stripe.com', pathPattern: '^/radar/lists(?:/[^/]+)?/?$|^/test/issuing/balance/?$|^/settings/public/?$' },
+            { host: 'verify.stripe.com', pathPattern: '^/start/' },
+            { host: 'js.stripe.com', pathPattern: '^/v3/?$|^/(v3|[a-z]+)/stripe\\.js$' },
+        ],
+    },
+    // what GET /twin says this twin is
+    discovery: {
+        twinOf: 'the Stripe REST API, Checkout, the customer portal, Connect onboarding, and Stripe.js',
+        stores: 'customers, payment objects, checkout sessions, products and prices, subscriptions and invoices, Connect accounts, Issuing, and 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.
+    // applications' code that sends a customer to the page (journeys/demand.json).
     screens: [
+        { id: 'checkout-js', kind: 'content', host: 'api.stripe.com', path: '/v1/payment_pages/{session}', takes: ['POST'], status: 'done', source: 'https://docs.stripe.com/payments/advanced', demand: 'Postiz CheckoutProvider: the published Stripe.js contract over the session store; the private wire is authored (screens/checkout-js.ts).' },
         {
             id: 'checkout', kind: 'flow', host: 'checkout.stripe.com', path: '/c/pay/{session}', status: 'done',
-            demand: '16 of 85 applications send customers to Checkout',
+            demand: 'Dub, Rallly, Postiz and Twenty send customers to Checkout (journeys/demand.json)',
             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}'],
+            demand: 'Cal.com, Dub, Postiz, Rallly and Twenty 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'],
+            // 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: "Dub onboards its partners' 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',
-            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',
+            // 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: '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; /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',
-            controls: ['Business name', 'Save', 'Enable OAuth for Standard accounts', 'Redirect URIs'], source: 'https://docs.stripe.com/dashboard/basics',
+            id: 'dashboard', kind: 'workspace', host: 'dashboard.stripe.com', path: '/', status: 'done',
+            demand: 'Operator setup for the cited application calls: Public details; Radar lists for Dub add-to-stripe-fraud-value-lists.ts:3-7; sandbox funding for Open Autonomy world/model/scenario.ts:60,62',
+            controls: ['Business name', 'Save', 'New list', 'Name', 'Alias', 'List type', 'Add', 'Add test funds', 'Amount'], 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'],
+        'billing.meter': { refresh: { list: 'GetBillingMeters' },
+            // source: spec:/components/schemas/billing.meter/properties/status "active"
+            assigned: { object: { value: 'billing.meter' }, created: { now: true }, updated: { now: true }, livemode: { value: false }, status: { value: 'active' }, status_transitions: { value: { deactivated_at: null } },
+                // source: https://docs.stripe.com/api/billing/meter/create "stripe_customer_id"
+                // Where the page stops: omitted mappings use the creation example’s customer/value payload keys.
+                customer_mapping: { value: { type: 'by_id', event_payload_key: 'stripe_customer_id' } }, value_settings: { value: { event_payload_key: 'value' } } },
+            storedAs: 'billing_meter', idPrefix: 'mtr', notFound: "No such meter: '{id}'", ...states["billing.meter"], filters: ['status'],
+        },
+        'billing.meter_event': { refresh: { none: 'a meter event is written, never read: the API reads back only its meter’s summaries (GET /v1/billing/meters/{id}/event_summaries)' }, storedAs: 'billing_meter_event', idPrefix: 'mtr_evt' },
+        payment_intent: { refresh: { list: 'GetPaymentIntents' },
+            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: { refresh: { list: 'GetCustomers' }, idPrefix: 'cus', update: 'replace', ...states["customer"], filters: ['email'], counts: { next_invoice_sequence: { of: 'invoice', by: 'customer', present: 'number', plus: 1 } } },
+        customer_balance_transaction: { refresh: { list: 'GetCustomersCustomerBalanceTransactions' }, parent: { param: 'customer', field: 'customer', resource: 'customer' }, idPrefix: 'cbtxn', ...states["customer_balance_transaction"], },
+        customer_cash_balance_transaction: { refresh: { list: 'GetCustomersCustomerCashBalanceTransactions' }, parent: { param: 'customer', field: 'customer', resource: 'customer' }, 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
         // 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: {
+        payment_source: { refresh: { none: 'a customer’s sources are listed only per customer, cards, bank accounts and Sources together (GET /v1/customers/{customer}/sources); the twin keeps them among the Sources, which no list reads' },
             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'],
+        source: { refresh: { none: 'Stripe lists no Sources: each is read by its id (GET /v1/sources/{source})' },
+            idPrefix: 'src', ...states["source"],
         },
-        charge: {
-            idPrefix: 'ch',
-            state: { status: chargeStatus, captured: chargeCaptured, paid: chargePaid, refunded: chargeRefunded },
+        // 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: { refresh: { list: 'GetCharges' },
+            idPrefix: 'ch', ...states["charge"],
             embeds: { customer: 'customer', payment_intent: 'payment_intent', invoice: 'invoice', balance_transaction: 'balance_transaction' },
             filters: ['customer', 'payment_intent'],
         },
-        refund: {
+        refund: { refresh: { list: 'GetRefunds' },
             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: {
+        setup_intent: { refresh: { list: 'GetSetupIntents' },
             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'] },
-        subscription: {
-            idPrefix: 'sub',
-            state: { status: subscriptionStatus },
-            notState: ['collection_method'],
+        payment_method: { refresh: { list: 'GetPaymentMethods' }, idPrefix: 'pm', ...states["payment_method"], embeds: { customer: 'customer' }, filters: ['customer', 'type'] },
+        subscription: { refresh: { list: 'GetSubscriptions', complete: false },
+            idPrefix: 'sub', ...states["subscription"],
             embeds: { customer: 'customer', latest_invoice: 'invoice', default_payment_method: 'payment_method', schedule: 'subscription_schedule' },
+            // source: spec:/components/schemas/subscription/properties/items/description "List of subscription items, each with an attached price."
+            // source: https://docs.stripe.com/api/subscriptions/object "subscription_items?subscription="
+            collections: { items: { resource: 'subscription_item', by: 'subscription', list: { object: 'list', has_more: false, url: '/v1/subscription_items?subscription={id}' } } },
             filters: ['customer'],
         },
-        subscription_item: { idPrefix: 'si' },
-        invoice: {
-            idPrefix: 'in',
-            state: { status: invoiceStatus },
-            notState: ['billing_reason', 'collection_method', 'customer_tax_exempt'],
+        subscription_item: { refresh: { none: 'subscription items are listed only per subscription (the list requires subscription), and each subscription answers its items in full (subscription.items)' }, idPrefix: 'si',
+            // source: spec:/components/schemas/subscription_item/properties/price "price"
+            embeds: { price: 'price' }, alwaysEmbedded: ['price'] },
+        invoice: { refresh: { list: 'GetInvoices' },
+            idPrefix: 'in', ...states["invoice"],
             embeds: { customer: 'customer', subscription: 'subscription', charge: 'charge', payment_intent: 'payment_intent' },
-            filters: ['customer', 'status', 'subscription'],
+            filters: ['customer', 'status', 'subscription', 'collection_method'],
         },
-        invoiceitem: { idPrefix: 'ii', embeds: { customer: 'customer', price: 'price' }, filters: ['customer', 'invoice'], order: { field: 'date', direction: 'desc' } },
-        'checkout.session': {
+        invoiceitem: { refresh: { list: 'GetInvoiceitems' }, idPrefix: 'ii', embeds: { customer: 'customer', price: 'price' }, filters: ['customer', 'invoice'], order: { field: 'date', direction: 'desc' } },
+        'checkout.session': { refresh: { list: 'GetCheckoutSessions' },
             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' },
         },
-        ephemeral_key: { idPrefix: 'ephkey' },
+        ephemeral_key: { refresh: { none: 'an ephemeral key is answered once, by its create: the API has no read of one' }, 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'],
+        mandate: { refresh: { none: 'a mandate is read by its id (GET /v1/mandates/{mandate}): the API lists none' },
+            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: { refresh: { list: 'GetDisputes' }, idPrefix: 'dp', update: 'replace', ...states["dispute"], embeds: { charge: 'charge', payment_intent: 'payment_intent' }, filters: ['charge', 'payment_intent'] },
+        payout: { refresh: { list: 'GetPayouts' }, 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'],
+        balance_transaction: { refresh: { list: 'GetBalanceTransactions' },
+            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."')] } },
+        coupon: { refresh: { list: 'GetCoupons' },
+            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: {
+        // source: https://docs.stripe.com/changelog/clover/2025-09-30/polymorphic-coupon "When you retrieve Promotion Codes, they don’t auto-expand the promotion.coupon field"
+        // Before Clover the top-level coupon auto-expands; Clover omits that field in its view.
+        promotion_code: { embeds: { coupon: 'coupon' }, alwaysEmbedded: ['coupon'], refresh: { list: 'GetPromotionCodes' },
             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'] },
-        subscription_schedule: {
+        subscription_schedule: { refresh: { list: 'GetSubscriptionSchedules' },
             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."') } },
+        'entitlements.feature': { refresh: { list: 'GetEntitlementsFeatures' },
+            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)
-        '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'] },
+        // an advance answers advancing and the clock is ready once it has reached the time (./engine/test-clocks.ts)
+        event: { refresh: { list: 'GetEvents', complete: false }, 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: {
+        webhook_endpoint: { refresh: { list: 'GetWebhookEndpoints' },
             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: {
+            // source: spec:/components/schemas/account/properties/individual "person"
+            embeds: { individual: 'person' }, alwaysEmbedded: ['individual'], refresh: { list: 'GetAccounts', complete: false }, idPrefix: 'acct', ...states["account"],
         },
-        account: { idPrefix: 'acct', notState: ['business_type', 'type'] },
-        person: { idPrefix: 'person', notState: ['political_exposure'], parent: { param: 'account', field: 'account', resource: 'account' } },
+        person: { refresh: { list: 'GetAccountsAccountPersons' }, 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'),
-                    ],
-                },
-            },
+        capability: { refresh: { none: 'the twin keeps a capability in its account’s capabilities, which the accounts’ list reads back (GET /v1/accounts)' },
+            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'],
+        external_account: { refresh: { none: 'an account answers its external accounts (account.external_accounts), which the accounts’ list reads back (GET /v1/accounts)' },
+            idPrefix: 'ba', ...states["external_account"],
         },
-        account_link: { idPrefix: 'acctlink' },
-        account_session: { idPrefix: 'accts' },
-        transfer: { idPrefix: 'tr', update: 'replace', filters: ['destination'] },
-        transfer_reversal: { idPrefix: 'trr' },
+        account_link: { refresh: { none: 'an account link is answered once, by its create: the API has no read of one' }, idPrefix: 'acctlink' },
+        account_session: { refresh: { none: 'an account session is answered once, by its create: the API has no read of one' }, idPrefix: 'accts' },
+        transfer: { refresh: { list: 'GetTransfers' }, idPrefix: 'tr', update: 'replace', filters: ['destination'] },
+        transfer_reversal: { refresh: { list: 'GetTransfersIdReversals' }, parent: { param: 'id', field: 'transfer', resource: 'transfer' }, 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'],
+        application_fee: { refresh: { list: 'GetApplicationFees' },
+            idPrefix: 'fee', notFound: "No such application fee: '{id}'", filters: ['charge'], ...states["application_fee"],
         },
-        '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'] },
+        fee_refund: { refresh: { list: 'GetApplicationFeesIdRefunds' }, parent: { param: 'id', field: 'fee', resource: 'application_fee' }, idPrefix: 'fr' },
+        'apps.secret': { refresh: { none: 'secrets are listed only per scope (the list requires scope), which a root does not name' }, storedAs: 'apps_secret', idPrefix: 'apmc' },
+        'billing_portal.session': { refresh: { none: 'a portal session is answered once, by its create: the API has no read of one' }, 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'],
-        },
-        // `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'],
+        'billing_portal.configuration': { refresh: { list: 'GetBillingPortalConfigurations' },
+            storedAs: 'billing_portal_configuration', idPrefix: 'bpc', notFound: "No such configuration: '{id}'", ...states["billing_portal.configuration"],
         },
-        quote: { idPrefix: 'qt', state: { status: quoteStatus }, notState: ['collection_method'], filters: ['customer', 'status'] },
+        'tax.calculation': { refresh: { none: 'a calculation is read by its id (GET /v1/tax/calculations/{calculation}): the API lists none' }, storedAs: 'tax_calculation', idPrefix: 'taxcalc', notFound: "No such tax calculation: '{id}'" },
+        'tax.transaction': { refresh: { none: 'a tax transaction is read by its id (GET /v1/tax/transactions/{transaction}): the API lists none' }, storedAs: 'tax_transaction', idPrefix: 'tax', notFound: "No such tax transaction: '{id}'", ...states["tax.transaction"], },
         // a review is open until it is closed; approving closes it, once
-        review: {
+        review: { refresh: { list: 'GetReviews', complete: false },
             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': {
+            idPrefix: 'prv', ...states["review"],
+        },
+        'radar.value_list': { refresh: { list: 'GetRadarValueLists' }, storedAs: 'radar_value_list', idPrefix: 'rsl', notFound: "No such radar value list: '{id}'", ...states["radar.value_list"],
+            // source: spec:/components/schemas/radar.value_list/properties/created/description "Time at which the object was created."
+            assigned: { created: { now: true }, object: { value: 'radar.value_list' }, livemode: { value: false }, metadata: { value: {} },
+                // source: spec:/components/schemas/radar.value_list/properties/created_by/description "The name or email address of the user who created this value list."
+                // Where documentation stops: local API-key creates identify their synthetic account operator as twin.
+                created_by: { value: 'twin' }, list_items: { value: { object: 'list', data: [], has_more: false, url: '/v1/radar/value_list_items' } } }, filters: ['alias'] },
+        'radar.value_list_item': { refresh: { none: 'value list items are listed only per value list (the list requires value_list), and each list answers its items (radar.value_list.list_items)' }, storedAs: 'radar_value_list_item', idPrefix: 'rsli', notFound: "No such radar value list item: '{id}'" },
+        'issuing.cardholder': { refresh: { list: 'GetIssuingCardholders' },
             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'],
+            // source: spec:/components/schemas/issuing.cardholder/properties/created/description "Time at which the object was created."
+            assigned: { created: { now: true }, object: { value: 'issuing.cardholder' }, livemode: { value: false }, metadata: { value: {} },
+                // source: spec:/components/schemas/issuing_cardholder_requirements/properties/past_due/description "Array of fields that need to be collected"
+                requirements: { value: { disabled_reason: null, past_due: [] } } },
+            notFound: "No such cardholder: '{id}'", ...states["issuing.cardholder"],
             filters: ['status', 'type', 'email'],
         },
-        'issuing.card': {
+        'issuing.card': { refresh: { list: 'GetIssuingCards' },
             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"],
+            // source: spec:/components/schemas/issuing.card/properties/cardholder "issuing.cardholder"
+            embeds: { cardholder: 'issuing.cardholder' }, alwaysEmbedded: ['cardholder'],
             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': {
+        'issuing.authorization': { refresh: { list: 'GetIssuingAuthorizations' }, storedAs: 'issuing_authorization', idPrefix: 'iauth', ...states["issuing.authorization"],
+            // source: spec:/components/schemas/issuing.authorization/properties/card "issuing.card"
+            embeds: { card: 'issuing.card', cardholder: 'issuing.cardholder' }, alwaysEmbedded: ['card'], filters: ['card', 'cardholder', 'status'], },
+        'issuing.transaction': { refresh: { list: 'GetIssuingTransactions' }, storedAs: 'issuing_transaction', idPrefix: 'ipi', notFound: "No such transaction: '{id}'", ...states["issuing.transaction"], filters: ['card', 'cardholder'] },
+        'treasury.outbound_payment': { refresh: { none: 'outbound payments are listed only per financial account (the list requires financial_account)' },
             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': {
+        'treasury.outbound_transfer': { refresh: { none: 'outbound transfers are listed only per financial account (the list requires financial_account)' },
             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': {
+        'treasury.inbound_transfer': { refresh: { none: 'inbound transfers are listed only per financial account (the list requires financial_account)' },
             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': { refresh: { none: 'received credits are listed only per financial account (the list requires financial_account)' }, storedAs: 'received_credit', idPrefix: 'rc', notFound: "No such received credit: '{id}'", ...states["treasury.received_credit"], filters: ['financial_account', 'status'] },
+        'treasury.received_debit': { refresh: { none: 'received debits are listed only per financial account (the list requires financial_account)' }, 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' },
-                    ] } },
-        },
-        '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'],
+        'treasury.transaction': { refresh: { none: 'Treasury transactions are listed only per financial account (the list requires financial_account)' },
+            storedAs: 'treasury_transaction', idPrefix: 'trxn', notFound: "No such treasury transaction: '{id}'", ...states["treasury.transaction"],
         },
+        'treasury.transaction_entry': { refresh: { none: 'transaction entries are listed only per financial account (the list requires financial_account)' }, storedAs: 'treasury_transaction_entry', idPrefix: 'trxne', notFound: "No such transaction entry: '{id}'", ...states["treasury.transaction_entry"], },
+        'financial_connections.session': { refresh: { none: 'a session is read by its id (GET /v1/financial_connections/sessions/{session}): the API lists none' }, storedAs: 'fc_session', idPrefix: 'fcsess' },
         // 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')] } },
+        'financial_connections.transaction': { refresh: { none: 'transactions are listed only per linked account (the list requires account)' },
+            storedAs: 'fc_transaction', idPrefix: 'fctxn', ...states["financial_connections.transaction"],
         },
         // 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: {
+        product: { refresh: { list: 'GetProducts' }, idPrefix: 'prod', update: 'replace', ...states["product"], },
+        product_feature: {
+            // source: spec:/components/schemas/product_feature/properties/entitlement_feature "entitlements.feature"
+            embeds: { entitlement_feature: 'entitlements.feature' }, alwaysEmbedded: ['entitlement_feature'], refresh: { list: 'GetProductsProductFeatures' }, parent: { param: 'product', field: '_product', resource: 'product' }, idPrefix: 'prodft'
+        },
+        price: { refresh: { list: 'GetPrices', complete: false },
             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 },
+    // a vendor-backed World's root: Stripe's webhooks sent to the World's ingest door, signed as Stripe signs every event
+    // (Stripe-Signature: t=<seconds>,v1=<HMAC-SHA256 of "<t>.<body>">, docs.stripe.com/webhooks#verify-manually), the
+    // event's type in its body and its object at data.object (docs.stripe.com/api/events/object); the types whose
+    // resource neither the events' write names nor <resource>.created|updated|deleted say
+    ingest: {
+        scheme: { kind: 'timestamp-v1', header: 'Stripe-Signature' },
+        type: { body: 'type' },
+        object: 'data.object',
+        types: {
+            'checkout.session.completed': { resource: 'checkout.session' },
+            'checkout.session.expired': { resource: 'checkout.session' },
+            'charge.succeeded': { resource: 'charge' },
+            'charge.failed': { resource: 'charge' },
+            'charge.refunded': { resource: 'charge' },
+            'payment_intent.requires_action': { resource: 'payment_intent' },
+            'payment_intent.canceled': { resource: 'payment_intent' },
+            'payment_method.automatically_updated': { resource: 'payment_method' },
+            'invoice.payment_succeeded': { resource: 'invoice' },
+            'invoice.payment_failed': { resource: 'invoice' },
+            'invoice.voided': { resource: 'invoice' },
+            'transfer.reversed': { resource: 'transfer' },
+            'account.external_account.updated': { resource: 'external_account' },
+            'account.external_account.created': { resource: 'external_account' },
+            'account.external_account.deleted': { resource: 'external_account', deleted: true },
+            'payout.paid': { resource: 'payout' },
+            'payout.failed': { resource: 'payout' },
+            'issuing_authorization.request': { resource: 'issuing.authorization' },
+        },
     },
 };