@volter/twin-stripe 2.0.38 → 3.0.1

package/src/manifest.ts

@@ -1,523 +1,290 @@
 // Stripe's manifest: the vendor facts its published spec does not carry, and the resources the
 // derived core serves (docs/contributing/architecture.md, "Protocol 3"). The surface itself is
 // generated (./generated/surface.gen.json, from ../spec by scripts/derive-pack.ts).
-import type { DerivedManifest, StateField, Transition } from '@volter/world-core';
-import { afterStripeWrite, embedIssuingAuthorizationCard, isValidApiVersion, view } from './stripe-twin.ts';
-
-const unexpected = (verb: string, allowed: string) => ({
-  status: 400,
-  code: 'payment_intent_unexpected_state',
-  message: `This PaymentIntent could not be ${verb} because it has a status of {from}. ${allowed}`,
-});
-const OPEN = ['requires_payment_method', 'requires_confirmation', 'requires_action', 'requires_capture', 'processing'];
-
-/** A move no API call makes: Stripe's own (`vendor`), the clock's (`time`), or the person on a
- *  Stripe-hosted page (`external`: Checkout, the billing portal, a hosted invoice or 3DS page). */
-const by = (actor: 'vendor' | 'time' | 'external', from: string[], to: string, source: string): Transition => ({ actor, from, to, source });
-/** A bank account's `status` as a payout or payment destination. Stripe validates its routing number,
- *  verifies it (micro-deposits, or instantly) and marks it errored when a payout or debit to it fails
- *  (the page each machine cites); no call the twin serves does any of that (the customer-source verify is
- *  a gap), so no move of it is the twin's. */
-const bankAccountStatus = (_doc: string): StateField => ({ initial: 'new', transitions: [] });
-
-/** A flag an update sets either way. */
-const flag = (operation: string, source: string): Transition[] => ['true', 'false'].map((to) => ({ operation, from: '*' as const, to, source }));
-
-/** A PaymentIntent's `status`: which operation may move it from where, and what Stripe answers otherwise. */
-const paymentIntentStatus: StateField = {
-  // "After you create the PaymentIntent, its status is `requires_payment_method` until you attach a payment method"
-  // (docs.stripe.com/payments/paymentintents/lifecycle)
-  initial: 'requires_payment_method',
-  transitions: [
-    // created with its payment method, it "enters the `requires_confirmation` status and is ready to confirm" (the same page)
-    { operation: 'PostPaymentIntents', from: ['requires_payment_method'], to: 'requires_confirmation', source: 'https://docs.stripe.com/payments/paymentintents/lifecycle' },
-    // confirm lands on one of its outcomes, decided by the payment method and the capture method
-    ...['requires_payment_method', 'requires_action', 'requires_capture', 'succeeded'].map((to) => ({
-      operation: 'PostPaymentIntentsIntentConfirm',
-      from: ['requires_payment_method', 'requires_confirmation', 'requires_action'],
-      to,
-      refusal: { status: 400, code: 'payment_intent_unexpected_state', message: 'You cannot confirm this PaymentIntent because it has a status of {from}.' },
-      source: 'https://docs.stripe.com/api/payment_intents/confirm',
-    })),
-    // a bank debit confirmed (created with `confirm`, confirmed, or verified by micro-deposits) is submitted and
-    // processes: "The PaymentIntent you create initially has a status of `processing`"; "When the bank account is
-    // successfully verified, Stripe returns the PaymentIntent object with a status of `processing`"
-    ...['PostPaymentIntents', 'PostPaymentIntentsIntentConfirm'].map((operation) => ({
-      operation, from: ['requires_payment_method', 'requires_confirmation', 'requires_action'], to: 'processing',
-      source: 'https://docs.stripe.com/payments/ach-direct-debit/accept-a-payment?payment-ui=direct-api',
-    })),
-    // and succeeds: "After the payment has succeeded, the PaymentIntent status is updated from `processing`
-    // to `succeeded`" (semantics/payment-intents.ts settleBankDebits)
-    by('vendor', ['processing'], 'succeeded', 'https://docs.stripe.com/payments/ach-direct-debit/accept-a-payment?payment-ui=direct-api'),
-    // creating one with `confirm` confirms it at once, landing where a confirm lands
-    ...['requires_payment_method', 'requires_action', 'requires_capture', 'succeeded'].map((to) => ({
-      operation: 'PostPaymentIntents',
-      from: ['requires_payment_method', 'requires_confirmation'],
-      to,
-      source: 'spec:PostPaymentIntents "Set to `true` to attempt to [confirm this PaymentIntent](https://docs.stripe.com/api/payment_intents/confirm) immediately."',
-    })),
-    {
-      operation: 'PostPaymentIntentsIntentCapture',
-      from: ['requires_capture'],
-      to: 'succeeded',
-      refusal: unexpected('captured', 'Only a PaymentIntent with one of the following statuses may be captured: requires_capture.'),
-      source: 'https://docs.stripe.com/api/payment_intents/capture',
-    },
-    {
-      operation: 'PostPaymentIntentsIntentIncrementAuthorization',
-      from: ['requires_capture'],
-      to: 'requires_capture',
-      refusal: unexpected('incremented', 'Only a PaymentIntent with a status of requires_capture may be incremented.'),
-      source: 'https://docs.stripe.com/api/payment_intents/increment_authorization',
-    },
-    {
-      operation: 'PostPaymentIntentsIntentCancel',
-      from: OPEN,
-      to: 'canceled',
-      refusal: unexpected('canceled', 'Only a PaymentIntent with one of the following statuses may be canceled: requires_payment_method, requires_capture, requires_confirmation, requires_action, processing.'),
-      source: 'https://docs.stripe.com/api/payment_intents/cancel',
-    },
-    {
-      operation: 'PostPaymentIntentsIntentVerifyMicrodeposits',
-      from: ['requires_action'],
-      to: 'processing',
-      refusal: { status: 400, code: 'payment_intent_unexpected_state', message: 'This PaymentIntent could not be verified because it has a status of {from}.' },
-      source: 'https://docs.stripe.com/payments/ach-direct-debit/accept-a-payment?payment-ui=direct-api',
-    },
-    {
-      // paying the invoice an intent collects for settles the intent
-      operation: 'PostInvoicesInvoicePay',
-      from: OPEN,
-      to: 'succeeded',
-      source: 'https://docs.stripe.com/api/invoices/pay',
-    },
-    ...['succeeded', 'requires_action'].map((to) => ({
-      operation: 'PostPaymentIntentsIntentApplyCustomerBalance',
-      from: OPEN,
-      to,
-      refusal: { status: 400, code: 'payment_intent_unexpected_state', message: 'This PaymentIntent could not be updated because it has a status of {from}.' },
-      source: 'https://docs.stripe.com/api/payment_intents/apply_customer_balance',
-    })),
-    // a card presented to the Terminal reader processing an intent pays it (held, under manual capture)
-    ...['succeeded', 'requires_capture'].map((to) => ({
-      operation: 'PostTestHelpersTerminalReadersReaderPresentPaymentMethod', from: ['requires_payment_method', 'requires_confirmation'], to,
-      source: 'https://docs.stripe.com/api/terminal/readers/present_payment_method',
-    })),
-    // the customer pays, in the billing portal, the invoice an intent collects for after its charge was declined
-    by('external', ['requires_payment_method'], 'succeeded', 'https://docs.stripe.com/customer-management'),
-    // Stripe also fails a bank debit back to needing a payment method, completes 3-D Secure on the bank's page and
-    // cancels a hold left uncaptured; the twin's bank debits succeed unless their test account stays processing, it has no 3-D Secure page, and it keeps
-    // holds until they are captured or canceled
-  ],
-};
-
-/** A charge's `captured`: an authorization (capture=false) is captured once. */
-const chargeCaptured: StateField = {
-  initial: true,
-  transitions: [
-    {
-      operation: 'PostChargesChargeCapture',
-      from: ['false'],
-      to: 'true',
-      refusal: { status: 400, code: 'charge_already_captured', message: 'Charge ch_xxx has already been captured.' },
-      source: 'https://docs.stripe.com/api/charges/capture',
-    },
-    // a manual-capture intent's capture captures the charge its confirm authorized
-    { operation: 'PostPaymentIntentsIntentCapture', from: ['false'], to: 'true', source: 'https://docs.stripe.com/api/payment_intents/capture' },
-  ],
-};
-
-/** A charge's `refunded`: true once refunds take its whole amount, false again when a refund that made it so is
- *  canceled. A capture or a cancel never makes it so: "`refunded` will no longer be `true` for payment cancellation
- *  flows", and a partial capture makes no Refund (docs.stripe.com/changelog/basil/2025-03-31/remove-refund-from-partial-
- *  capture-and-payment-cancellation-flow). */
-const chargeRefunded: StateField = {
-  initial: false,
-  transitions: [
-    ...['PostRefunds', 'PostChargesChargeRefunds', 'PostCreditNotes'].map((operation) => ({ operation, from: ['false'], to: 'true', source: 'https://docs.stripe.com/api/charges/object#charge_object-refunded' })),
-    { operation: 'PostRefundsRefundCancel', from: ['true'], to: 'false', source: 'https://docs.stripe.com/api/refunds/cancel' },
-    // (an authorization left uncaptured is canceled after seven days, "Uncaptured PaymentIntents are cancelled a set
-    // number of days (7 by default) after their creation", docs.stripe.com/api/payment_intents/capture; the twin keeps it)
-  ],
-};
-
-/** A charge's `status`: the twin settles a charge when it is made (a declined one is never
- *  stored); an asynchronous one settles later, on the network's word. */
-const chargeStatus: StateField = {
-  initial: 'succeeded',
-  transitions: [
-    // (an asynchronous charge is pending at Stripe until it settles or fails; the twin's settle when made)
-  ],
-};
-
-/** A charge's `paid`: true once it succeeded or was authorized; a pending one becomes paid when it settles. */
-const chargePaid: StateField = {
-  initial: true,
-  // (a charge is paid when it settles; the twin's settle when made)
-  transitions: [],
-};
-
-/** A refund's `status`: only one waiting on the customer (requires_action) may be canceled; the
- *  rest is the network's. */
-const refundStatus: StateField = {
-  initial: 'succeeded',
-  transitions: [
-    {
-      operation: 'PostRefundsRefundCancel',
-      from: ['requires_action'],
-      to: 'canceled',
-      refusal: { status: 400, code: 'refund_status_invalid', message: 'Refund {id} cannot be canceled because its status is {from}.' },
-      source: 'https://docs.stripe.com/api/refunds/cancel',
-    },
-    // a card refund the available balance does not cover is held pending, and made once the balance covers it: "Stripe
-    // holds the refund as pending for card transactions ... until your Stripe balance becomes sufficient"
-    // (docs.stripe.com/refunds; semantics/refunds.ts)
-    // (a paid invoice's credit note makes its refund as a refund call does: "Refunds: create a new refund (using
-    // refund_amount)", docs.stripe.com/api/credit_notes/create)
-    ...['PostRefunds', 'PostChargesChargeRefunds', 'PostCreditNotes'].map((operation) => ({ operation, from: ['succeeded'], to: 'pending', source: 'https://docs.stripe.com/refunds' })),
-    by('vendor', ['pending'], 'succeeded', 'https://docs.stripe.com/refunds'),
-    // a bank-transfer payment's refund waits in requires_action for the customer's bank details, and is made so
-    // (semantics/refunds.ts); (Stripe also fails some refunds; the twin's do not fail)
-  ],
-};
-
-const SETUP_OPEN = ['requires_payment_method', 'requires_confirmation', 'requires_action'];
-const setupUnexpected = (verb: string) => ({ status: 400, code: 'setup_intent_unexpected_state', message: `You cannot ${verb} this SetupIntent because it has a status of {from}.` });
-
-/** A SetupIntent's `status`: confirm settles it (or leaves a bank account awaiting micro-deposits),
- *  cancel ends an open one, and verification completes the micro-deposit wait. */
-const setupIntentStatus: StateField = {
-  // "After you create the SetupIntent, it has a status of `requires_payment_method` until you attach a payment method"
-  // (docs.stripe.com/payments/paymentintents/lifecycle)
-  initial: 'requires_payment_method',
-  transitions: [
-    // created with its payment method, it "enters the `requires_confirmation` status and is ready to confirm" (the same page)
-    { operation: 'PostSetupIntents', from: ['requires_payment_method'], to: 'requires_confirmation', source: 'https://docs.stripe.com/payments/paymentintents/lifecycle' },
-    ...['requires_action', 'succeeded'].map((to) => ({
-      operation: 'PostSetupIntentsIntentConfirm',
-      from: SETUP_OPEN,
-      to,
-      refusal: setupUnexpected('confirm'),
-      source: 'https://docs.stripe.com/api/setup_intents/confirm',
-    })),
-    {
-      operation: 'PostSetupIntentsIntentCancel',
-      from: SETUP_OPEN,
-      to: 'canceled',
-      refusal: setupUnexpected('cancel'),
-      source: 'https://docs.stripe.com/api/setup_intents/cancel',
-    },
-    {
-      operation: 'PostSetupIntentsIntentVerifyMicrodeposits',
-      from: ['requires_action'],
-      to: 'succeeded',
-      refusal: { status: 400, code: 'setup_intent_unexpected_state', message: 'This SetupIntent could not be verified because it has a status of {from}.' },
-      source: 'https://docs.stripe.com/api/setup_intents/verify_microdeposits',
-    },
-    // (Stripe completes 3-D Secure on the bank's page and settles an asynchronous method from processing; the
-    // twin has no such page and settles every method at once)
-  ],
-};
-
-const invoiceRefusal = (message: string) => ({ status: 400, code: 'invoice_not_editable', message });
-
-/** An invoice's `status`: a draft is finalized (or sent, which finalizes it) into open, an open one
- *  is paid, written off or voided. Sending leaves any other status where it is. */
-const invoiceStatus: StateField = {
-  initial: 'draft',
-  transitions: [
-    {
-      operation: 'PostInvoicesInvoiceFinalize',
-      from: ['draft'],
-      to: 'open',
-      refusal: invoiceRefusal('This invoice cannot be finalized because it has status {from}.'),
-      source: 'https://docs.stripe.com/api/invoices/finalize',
-    },
-    // docs.stripe.com/invoicing/integration: "To finalize a draft invoice, use the Dashboard, send it to the customer, or pay it."
-    { operation: 'PostInvoicesInvoiceSend', from: ['draft'], to: 'open', source: 'https://docs.stripe.com/invoicing/integration' },
-    { operation: 'PostInvoicesInvoiceSend', from: ['open', 'paid', 'uncollectible', 'void'], source: 'https://docs.stripe.com/api/invoices/send' },
-    {
-      operation: 'PostInvoicesInvoicePay',
-      from: ['open', 'uncollectible'],
-      to: 'paid',
-      refusal: invoiceRefusal('This invoice cannot be paid because it has status {from}.'),
-      refusals: { paid: { status: 400, code: 'invoice_payment_intent_requires_action', message: 'This invoice has already been paid.' } },
-      source: 'https://docs.stripe.com/api/invoices/pay',
-    },
-    {
-      operation: 'PostInvoicesInvoiceMarkUncollectible',
-      from: ['open'],
-      to: 'uncollectible',
-      refusal: invoiceRefusal('Only open invoices can be marked uncollectible (this one is {from}).'),
-      source: 'https://docs.stripe.com/api/invoices/mark_uncollectible',
-    },
-    {
-      // only a finalized invoice is voided; a draft is deleted
-      operation: 'PostInvoicesInvoiceVoid',
-      from: ['open', 'uncollectible'],
-      to: 'void',
-      refusal: invoiceRefusal('This invoice cannot be voided because it has status {from}.'),
-      source: 'https://docs.stripe.com/api/invoices/void',
-    },
-    // confirming or capturing the PaymentIntent an invoice collects through pays the invoice
-    ...['PostPaymentIntentsIntentConfirm', 'PostPaymentIntentsIntentCapture'].map((operation) => ({
-      operation, from: ['draft', 'open', 'uncollectible'], to: 'paid', source: 'https://docs.stripe.com/billing/subscriptions/build-subscriptions',
-    })),
-    // as does its bank debit succeeding once submitted (semantics/payment-intents.ts settleBankDebits)
-    by('vendor', ['draft', 'open', 'uncollectible'], 'paid', 'https://docs.stripe.com/billing/subscriptions/build-subscriptions'),
-    // a bank transfer that arrives in the customer's cash balance pays an open invoice that takes transfers
-    // (automatic reconciliation; in test mode the funding helper stands in for the transfer)
-    { operation: 'PostTestHelpersCustomersCustomerFundCashBalance', from: ['open'], to: 'paid', source: 'https://docs.stripe.com/payments/customer-balance/reconciliation' },
-    // a subscription's first invoice is paid on the Checkout page that started it
-    by('external', ['draft'], 'paid', 'https://docs.stripe.com/payments/checkout/how-checkout-works'),
-    // a subscription's renewal, drafted at its period's end, is finalized about an hour later and charged: paid, or
-    // open when the charge is declined (semantics/renewals.ts)
-    by('time', ['draft'], 'paid', 'https://docs.stripe.com/invoicing/integration/workflow-transitions#finalized'),
-    by('time', ['draft'], 'open', 'https://docs.stripe.com/billing/subscriptions/overview#payment-status'),
-    // an update that ends a subscription's trial invoices its new period and attempts payment at once: paid, or open
-    // when the charge is declined or not attempted (semantics/subscriptions.ts applyTrialEnd)
-    { operation: 'PostSubscriptionsSubscriptionExposedId', from: ['draft'], to: 'paid', source: 'https://docs.stripe.com/billing/subscriptions/upgrade-downgrade#immediate-payment' },
-    // a trialing subscription's first invoice, for nothing, is paid as it is made ("An immediate invoice is still
-    // created, but the amount is 0", docs.stripe.com/billing/subscriptions/trials/free-trials)
-    { operation: 'PostSubscriptions', from: ['draft'], to: 'paid', source: 'https://docs.stripe.com/billing/subscriptions/trials/free-trials' },
-    { operation: 'PostSubscriptionsSubscriptionExposedId', from: ['draft'], to: 'open', source: 'https://docs.stripe.com/billing/subscriptions/upgrade-downgrade#immediate-payment' },
-    // the customer pays an open invoice in the billing portal
-    by('external', ['open'], 'paid', 'https://docs.stripe.com/customer-management'),
-    // (Stripe also finalizes any other auto-advancing draft after an hour, retries an open invoice on its schedule
-    // and, retries exhausted, may write it off, and takes payment on the hosted invoice page; the twin's other
-    // invoices move only by the calls above)
-  ],
-};
-
-/** A subscription's `status` as the twin's own operations move it; canceling ends any subscription. */
-const subscriptionStatus: StateField = {
-  initial: 'active',
-  transitions: [
-    { operation: 'DeleteSubscriptionsSubscriptionExposedId', from: '*', to: 'canceled', source: 'https://docs.stripe.com/api/subscriptions/cancel' },
-    // (a test clock's advance moves no subscription itself: when the clock reaches its target, a trial that ended there
-    // ends by time's move below, on the next request; semantics/test-clocks.ts finishClockAdvances)
-    // "Deleting the simulation also deletes the test customers associated with the clock and cancels their
-    // subscriptions" (docs.stripe.com/billing/testing/test-clocks/api-advanced-usage)
-    { operation: 'DeleteTestHelpersTestClocksTestClock', from: '*', to: 'canceled', source: 'https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage' },
-    // "Cancels a subscription schedule and its associated subscription immediately" (docs.stripe.com/api/subscription_schedules/cancel)
-    { operation: 'PostSubscriptionSchedulesScheduleCancel', from: ['active', 'trialing', 'past_due', 'incomplete'], to: 'canceled', source: 'https://docs.stripe.com/api/subscription_schedules/cancel' },
-    // confirming or capturing the first invoice's PaymentIntent, or paying the invoice itself, pays it and
-    // activates the subscription
-    ...['PostPaymentIntentsIntentConfirm', 'PostPaymentIntentsIntentCapture'].map((operation) => ({
-      operation, from: ['incomplete'], to: 'active', source: 'https://docs.stripe.com/billing/subscriptions/build-subscriptions',
-    })),
-    // or when its bank debit succeeds once submitted (semantics/payment-intents.ts settleBankDebits)
-    by('vendor', ['incomplete'], 'active', 'https://docs.stripe.com/billing/subscriptions/build-subscriptions'),
-    // paying the invoice a subscription waits on (its first, or a renewal that failed) makes it active
-    { operation: 'PostInvoicesInvoicePay', from: ['incomplete', 'past_due'], to: 'active', source: 'https://docs.stripe.com/billing/subscriptions/overview#payment-status' },
-    // an update's `trial_end`: `now` ends a trial at once and charges the new period, active when paid and past_due when
-    // not; a future timestamp starts a trial on a subscription out of one (semantics/subscriptions.ts applyTrialEnd)
-    { operation: 'PostSubscriptionsSubscriptionExposedId', from: ['trialing'], to: 'active', source: 'https://docs.stripe.com/api/subscriptions/update#update_subscription-trial_end' },
-    { operation: 'PostSubscriptionsSubscriptionExposedId', from: ['trialing'], to: 'past_due', source: 'https://docs.stripe.com/billing/subscriptions/upgrade-downgrade#immediate-payment' },
-    {
-      operation: 'PostSubscriptionsSubscriptionExposedId', from: ['active', 'past_due'], to: 'trialing',
-      // (Where the documentation stops and the twin decides: the wording of the refusal for a subscription neither
-      // active nor past_due; a canceled one answers what Stripe answers any update of a canceled subscription.)
-      refusal: { status: 400, message: 'A trial can only be added to an active or past_due subscription; this one is {from}.' },
-      refusals: { canceled: { status: 400, message: 'A canceled subscription can only update its cancellation_details and metadata.' } },
-      source: 'https://docs.stripe.com/billing/subscriptions/trials/free-trials#adding-a-new-trial-to-a-subscription-previously-in-a-trial',
-    },
-    // a trial ends on its own clock (Stripe pauses one that ends with no payment method to bill; the twin's
-    // trials end active), and a renewal whose charge is declined leaves the subscription past_due
-    // (semantics/renewals.ts)
-    by('time', ['trialing'], 'active', 'https://docs.stripe.com/billing/subscriptions/trials'),
-    by('time', ['active'], 'past_due', 'https://docs.stripe.com/billing/subscriptions/overview#payment-status'),
-    // one set to cancel at its period's end is canceled when the period ends
-    by('time', ['active', 'trialing', 'past_due'], 'canceled', 'https://docs.stripe.com/billing/subscriptions/cancel#cancel-at-end-of-cycle'),
-    // the customer pays the invoice it waits on in the billing portal
-    by('external', ['past_due'], 'active', 'https://docs.stripe.com/customer-management'),
-    // (Stripe also expires an incomplete subscription after 23 hours, and retries a failed renewal on its schedule,
-    // the settings ending the retries unpaid or canceled; the twin makes no retry)
-    // the customer cancels in the billing portal
-    by('external', ['active', 'trialing', 'past_due', 'unpaid', 'paused'], 'canceled', 'spec:/components/schemas/portal_subscription_cancel "Whether to cancel subscriptions immediately or at the end of the billing period."'),
-  ],
-};
-
-const notOpen = (verb: string) => ({ status: 400, code: 'checkout_session_not_open', message: `You may only ${verb} a Checkout Session that is currently in the \`open\` state.` });
-
-/** A Checkout Session's `status`: an open session expires (asked to, or 24 hours on), or completes
- *  when the customer pays on the hosted page. Completion is the external actor's move, the one the
- *  hosted Checkout page (src/screens/checkout.tsx) performs. */
-const checkoutStatus: StateField = {
-  initial: 'open',
-  transitions: [
-    { operation: 'PostCheckoutSessionsSessionExpire', from: ['open'], to: 'expired', refusal: notOpen('expire'), source: 'https://docs.stripe.com/api/checkout/sessions/expire' },
-    { actor: 'external', from: ['open'], to: 'complete', refusal: notOpen('complete'), source: 'https://docs.stripe.com/api/checkout/sessions/object#checkout_session_object-status' },
-    // (Stripe expires an open session at expires_at; the twin keeps it open until asked)
-  ],
-};
-
-/** A Checkout Session's `payment_status`: the customer completing a payment or subscription session
- *  pays it; a delayed payment method settles later. */
-const checkoutPaymentStatus: StateField = {
-  initial: 'unpaid',
-  transitions: [
-    { actor: 'external', from: '*', to: 'paid', source: 'https://docs.stripe.com/api/checkout/sessions/object#checkout_session_object-payment_status' },
-    // (a delayed method settles a session later at Stripe; the twin's settle on the page)
-  ],
-};
-
-/** A dispute's `status`: closing concedes it; the bank decides the rest, and an unanswered one is
- *  lost when its evidence is due. */
-const disputeStatus: StateField = {
-  initial: 'warning_needs_response',
-  transitions: [
-    { operation: 'PostDisputesDisputeClose', from: '*', to: 'lost', source: 'https://docs.stripe.com/api/disputes/close' },
-    // submitting evidence puts a dispute (or an inquiry) under review; in test mode the evidence decides it
-    { operation: 'PostDisputesDispute', from: ['needs_response'], to: 'under_review', source: 'https://docs.stripe.com/api/disputes/update#update_dispute-submit' },
-    { operation: 'PostDisputesDispute', from: ['warning_needs_response'], to: 'warning_under_review', source: 'https://docs.stripe.com/api/disputes/update#update_dispute-submit' },
-    by('vendor', ['under_review'], 'won', 'https://docs.stripe.com/testing#evidence'),
-    by('vendor', ['under_review'], 'lost', 'https://docs.stripe.com/testing#evidence'),
-    // (the bank decides a dispute under review, escalates an inquiry and loses one left unanswered; the twin
-    // decides none)
-    // Stripe also closes an inquiry the bank drops (warning_closed); no inquiry the twin holds is dropped
-  ],
-};
-
-/** A payout's `status`: cancel ends it; reversing cancels it and pays a reversal, never twice. */
-const payoutStatus: StateField = {
-  initial: 'pending',
-  transitions: [
-    // only a pending payout can be canceled (docs.stripe.com/api/payouts/cancel); reversing a paid one makes a new
-    // payout and leaves the original paid (semantics/balance.ts)
-    { operation: 'PostPayoutsPayoutCancel', from: ['pending'], to: 'canceled', source: 'https://docs.stripe.com/api/payouts/cancel' },
-    // it arrives in the bank on its arrival date
-    by('time', ['pending'], 'paid', 'https://docs.stripe.com/payouts#payout-statuses'),
-    // (a bank may fail a payout at Stripe; the twin's arrive)
-  ],
-};
-
-/** A credit note's `status`: issued, then voided once. */
-const creditNoteStatus: StateField = {
-  initial: 'issued',
-  transitions: [
-    {
-      operation: 'PostCreditNotesIdVoid',
-      from: ['issued'],
-      to: 'void',
-      refusal: { status: 400, code: 'credit_note_already_voided', message: 'This credit note has already been voided.' },
-      source: 'https://docs.stripe.com/api/credit_notes/void',
-    },
-  ],
-};
-
-const scheduleEnded = (verb: string) => ({ status: 400, code: 'subscription_schedule_status_invalid', message: `This subscription schedule has status {from} and cannot be ${verb}.` });
-
-/** A subscription schedule's `status`: canceling or releasing ends it; an ended one refuses both. */
-const scheduleStatus: StateField = {
-  initial: 'active',
-  transitions: [
-    // "A subscription schedule can only be canceled if its status is not_started or active"; "A schedule can only be
-    // released if its status is not_started or active" (the cancel and release pages)
-    { operation: 'PostSubscriptionSchedulesScheduleCancel', from: ['active', 'not_started'], to: 'canceled', refusal: scheduleEnded('canceled'), source: 'https://docs.stripe.com/api/subscription_schedules/cancel' },
-    { operation: 'PostSubscriptionSchedulesScheduleRelease', from: ['active', 'not_started'], to: 'released', refusal: scheduleEnded('released'), source: 'https://docs.stripe.com/api/subscription_schedules/release' },
-    // its phases run on the clock: it starts at its start date and ends with its last phase
-    // (a schedule whose end_behavior is cancel completes at its end at Stripe; the twin's release)
-    // (Stripe starts a schedule at its start date and ends it with its last phase; the twin's start at once
-    // and end when canceled or released)
-  ],
-};
-
-const quoteRefusal = (verb: string) => ({ status: 400, code: 'quote_invalid_status', message: `This quote cannot be ${verb} because it has status {from}.` });
-
-/** A quote's `status`: a draft is finalized into open, an open one accepted, and either canceled. */
-const quoteStatus: StateField = {
-  initial: 'draft',
-  transitions: [
-    { operation: 'PostQuotesQuoteFinalize', from: ['draft'], to: 'open', refusal: quoteRefusal('finalized'), source: 'https://docs.stripe.com/api/quotes/finalize' },
-    { operation: 'PostQuotesQuoteAccept', from: ['open'], to: 'accepted', refusal: quoteRefusal('accepted'), source: 'https://docs.stripe.com/api/quotes/accept' },
-    { operation: 'PostQuotesQuoteCancel', from: ['draft', 'open'], to: 'canceled', refusal: quoteRefusal('canceled'), source: 'https://docs.stripe.com/api/quotes/cancel' },
-    // an open quote not accepted by its expires_at is canceled
-    // (Stripe cancels an open quote at its expires_at; the twin keeps it open)
-  ],
-};
-
-const setBy = (operation: string, values: string[], source: string): Transition[] => values.map((to) => ({ operation, from: '*' as const, to, source }));
-
-/** An Issuing authorization's `status`: approve and decline close a pending one, once; a capture
- *  closes it, or leaves it pending when told not to close. */
-const issuingAuthorizationStatus: StateField = {
-  initial: 'pending',
-  transitions: [
-    // approving keeps it pending (approved) until the merchant captures; declining closes it
-    { operation: 'PostIssuingAuthorizationsAuthorizationApprove', from: ['pending'], refusal: { status: 400, code: 'authorization_already_finalized', message: 'This authorization has already been finalized (status {from}).' }, source: 'https://docs.stripe.com/issuing/purchases/authorizations' },
-    { operation: 'PostIssuingAuthorizationsAuthorizationDecline', from: ['pending'], to: 'closed', refusal: { status: 400, code: 'authorization_already_finalized', message: 'This authorization has already been finalized (status {from}).' }, source: 'https://docs.stripe.com/api/issuing/authorizations/decline' },
-    { operation: 'PostTestHelpersIssuingAuthorizationsAuthorizationCapture', from: ['pending'], to: 'closed', source: 'https://docs.stripe.com/api/issuing/authorizations/test_mode_capture' },
-    { operation: 'PostTestHelpersIssuingAuthorizationsAuthorizationCapture', from: ['pending'], source: 'https://docs.stripe.com/api/issuing/authorizations/test_mode_capture' },
-    // a real-time request no one answered is decided when its window ends: "If Stripe doesn't receive your approve or
-    // decline response within 2 seconds, the Authorization is automatically approved or declined based on your timeout
-    // settings" (semantics/issuing.ts lapseRealtimeRequests)
-    by('time', ['pending'], 'closed', 'https://docs.stripe.com/issuing/controls/real-time-authorizations'),
-    // (Stripe also closes, reverses and expires one as the merchant and the clock act; in test mode the
-    // capture helper above closes it, and the twin serves no other)
-  ],
-};
-
-/** A Treasury flow's `status` as the twin's own operations move it: only a processing flow cancels. */
-const flowCancel = (operation: string, code: string, name: string, network: Transition[]): StateField => ({
-  initial: 'processing',
-  transitions: [
-    { operation, from: ['processing'], to: 'canceled', refusal: { status: 400, code, message: `This ${name} cannot be canceled because it is no longer processing.` }, source: 'https://docs.stripe.com/api/treasury' },
-    ...network,
-  ],
-});
-/** An outbound flow on the network: Stripe posts or fails it and a posted one may come back returned (in
- *  test mode by test helpers the twin does not serve), so none of those moves is the twin's. */
-const outbound = (_doc: string): Transition[] => [];
+import type { DerivedManifest } from '@volter/world-core';
+import { data, values } from './semantics/events.ts';
+import { STRIPE_EVENTS } from './semantics/shared.ts';
+import { states } from './semantics/states.ts';
 
 export const manifest: DerivedManifest = {
   vendor: 'stripe',
   service: 'stripe',
   body: { form: { coerce: true } },
   ids: { template: '{prefix}_twin_{n}', acceptProvided: true },
-  // on declared resources, but never served by the twin: Stripe's unknown-URL answer
   unmodeled: [
     'DeleteAccountsAccountBankAccountsId',
+    '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}' } },
@@ -529,6 +296,10 @@ export const manifest: DerivedManifest = {
     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',
@@ -548,555 +319,360 @@ export const manifest: DerivedManifest = {
       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',
-    },
-    {
-      id: 'identity-verification', kind: 'flow', host: 'verify.stripe.com', path: '/start/{verification_session}', status: 'done',
-      demand: 'a verification report is written only when a person completes this page', controls: ['Verify', 'Fail verification'],
-      source: 'https://docs.stripe.com/identity/how-sessions-work',
-    },
-    {
-      id: 'financial-connections', kind: 'flow', host: 'js.stripe.com', path: '/v3/financial-connections/{client_secret}', status: 'done',
-      demand: 'a linked bank account exists only once its holder links it here', controls: ['Link accounts', 'Cancel'],
-      source: 'https://docs.stripe.com/js/financial_connections/collect_financial_connections_accounts',
+      // Stripe.js, the client library an application's page loads: /v3/, /v3/stripe.js and /<release train>/stripe.js
+      id: 'stripe-js', kind: 'content', host: 'js.stripe.com', path: '/', status: 'done',
+      demand: "Dub's upgrade button loads Stripe.js and calls redirectToCheckout",
+      source: 'https://docs.stripe.com/js',
     },
     {
-      id: 'dashboard', kind: 'workspace', host: 'dashboard.stripe.com', path: '/test/{section}; /settings/public; /settings/connect/onboarding-options/oauth', status: 'done',
-      demand: 'testers and agents inspect payments, customers and subscriptions; an operator sets the business name Checkout shows (Public details) and a Connect platform its OAuth client_id and redirect URIs',
-      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: '*' as const, to, source: 'https://docs.stripe.com/api/webhook_endpoints/update#update_webhook_endpoint-disabled' })),
-          ],
-        },
-      },
+      notFound: "No such webhook endpoint: '{id}'", ...states["webhook_endpoint"],
     },
-    account: { idPrefix: 'acct', notState: ['business_type', 'type'] },
-    person: { idPrefix: 'person', notState: ['political_exposure'], parent: { param: 'account', field: 'account', resource: 'account' } },
+    account: {
+      // source: spec:/components/schemas/account/properties/individual "person"
+      embeds: { individual: 'person' }, alwaysEmbedded: ['individual'], refresh: { list: 'GetAccounts', complete: false }, idPrefix: 'acct', ...states["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: '*' as const, to, source: 'https://docs.stripe.com/api/capabilities/update' })),
-            // Stripe reviews the account's requirements
-            by('vendor', ['pending', 'inactive'], 'active', 'https://docs.stripe.com/connect/account-capabilities#capability-status'),
-            by('vendor', ['active', 'pending'], 'inactive', 'https://docs.stripe.com/connect/account-capabilities#capability-status'),
-          ],
-        },
-      },
+    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'],
+    'billing_portal.configuration': { refresh: { list: 'GetBillingPortalConfigurations' },
+      storedAs: 'billing_portal_configuration', idPrefix: 'bpc', notFound: "No such configuration: '{id}'", ...states["billing_portal.configuration"],
     },
-    // `state` is a US state code, not a lifecycle
-    tax_rate: {
-      idPrefix: 'txr', notFound: "No such tax rate: '{id}'",
-      state: { active: { initial: true, transitions: flag('PostTaxRatesTaxRate', 'https://docs.stripe.com/api/tax_rates/update') } },
-      notState: ['jurisdiction_level', 'rate_type', 'state', 'tax_type'],
-    },
-    // its status is derived on every read from whether a head office is set; nothing stores it
-    'tax.settings': { storedAs: 'tax_settings', idPrefix: 'taxset', notState: ['status'] },
-    'tax.calculation': { storedAs: 'tax_calculation', idPrefix: 'taxcalc', notFound: "No such tax calculation: '{id}'" },
-    // a registration is active from creation here; its dates move it on the clock
-    'tax.registration': {
-      storedAs: 'tax_registration', idPrefix: 'taxreg', notFound: "No such tax registration: '{id}'", filters: ['status'],
-      state: {
-        // Stripe schedules a registration with a future active_from and expires one at expires_at; the twin's
-        // are active from the start and never expire
-        status: { initial: 'active', transitions: [] },
-      },
-    },
-    'tax.transaction': { storedAs: 'tax_transaction', idPrefix: 'tax', notFound: "No such tax transaction: '{id}'", notState: ['type'] },
-    payment_link: {
-      idPrefix: 'plink',
-      update: 'replace', notFound: "No such payment link: '{id}'",
-      state: { active: { initial: true, transitions: flag('PostPaymentLinksPaymentLink', 'https://docs.stripe.com/api/payment_links/payment_links/update') } },
-      notState: ['billing_address_collection', 'customer_creation', 'payment_method_collection', 'submit_type'],
-    },
-    quote: { idPrefix: 'qt', state: { status: quoteStatus }, notState: ['collection_method'], filters: ['customer', 'status'] },
+    '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' },
+    },
   },
 };
-