@volter/twin-stripe 3.0.0 → 3.0.2

package/src/manifest.ts

@@ -11,71 +11,119 @@ export const manifest: DerivedManifest = {
   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: [
-    // served by the core on a declared resource, but no application's demand (../journeys/demand.json) names them: the gap
+    'DeleteAccountsAccountBankAccountsId',
+    'DeleteAccountsAccountExternalAccountsId',
+    'DeleteAccountsAccountPeoplePerson',
+    'DeleteAccountsAccountPersonsPerson',
+    'DeleteCouponsCoupon',
+    'DeleteCustomersCustomerSourcesId',
+    'DeleteCustomersCustomerSubscriptionsSubscriptionExposedId',
+    'DeleteCustomersCustomerTaxIdsId',
+    'DeleteEphemeralKeysKey',
+    'DeleteInvoiceitemsInvoiceitem',
+    'DeleteInvoicesInvoice',
+    'DeleteProductsId',
+    'DeleteProductsProductFeaturesId',
+    'DeleteRadarValueListItemsItem',
+    'DeleteRadarValueListsValueList',
+    'DeleteSubscriptionItemsItem',
+    'DeleteTaxIdsId',
+    'DeleteTerminalConfigurationsConfiguration',
+    'DeleteTerminalLocationsLocation',
+    'DeleteTerminalReadersReader',
+    'DeleteTestHelpersTestClocksTestClock',
     'DeleteWebhookEndpointsWebhookEndpoint',
-    'GetAccountsAccountPersons',
-    'GetApplicationFees',
+    'GetAccountsAccountBankAccountsId',
+    'GetAccountsAccountCapabilities',
+    'GetAccountsAccountCapabilitiesCapability',
+    'GetAccountsAccountExternalAccountsId',
+    'GetAccountsAccountPeople',
+    'GetAccountsAccountPeoplePerson',
+    'GetAccountsAccountPersonsPerson',
+    'GetApplicationFeesFeeRefundsId',
     'GetApplicationFeesId',
+    'GetAppsSecrets',
+    'GetBalanceHistory',
+    'GetBalanceHistoryId',
+    'GetBalanceTransactionsId',
     'GetBillingAlertsId',
-    'GetBillingCreditGrants',
     'GetBillingCreditGrantsId',
+    'GetBillingMetersId',
     'GetBillingPortalConfigurationsConfiguration',
-    'GetClimateOrders',
+    'GetChargesChargeDispute',
+    'GetChargesChargeRefunds',
+    'GetChargesChargeRefundsRefund',
     'GetClimateOrdersOrder',
-    'GetCoupons',
-    'GetCreditNotes',
+    'GetCreditNotesId',
+    'GetCreditNotesPreview',
+    'GetCustomersCustomerBalanceTransactionsTransaction',
+    'GetCustomersCustomerCashBalanceTransactionsTransaction',
+    'GetCustomersCustomerPaymentMethods',
+    'GetCustomersCustomerPaymentMethodsPaymentMethod',
+    'GetCustomersCustomerSourcesId',
+    'GetCustomersCustomerSubscriptions',
+    'GetCustomersCustomerSubscriptionsSubscriptionExposedId',
+    'GetCustomersCustomerTaxIds',
+    'GetCustomersCustomerTaxIdsId',
+    'GetDisputesDispute',
+    'GetEntitlementsActiveEntitlements',
     'GetEntitlementsFeaturesId',
-    'GetFiles',
+    'GetEventsId',
+    'GetFileLinksLink',
     'GetFilesFile',
     'GetFinancialConnectionsAccountsAccount',
-    'GetForwardingRequests',
-    'GetForwardingRequestsId',
-    'GetIdentityVerificationReports',
+    'GetFinancialConnectionsSessionsSession',
+    'GetFinancialConnectionsTransactions',
+    'GetFinancialConnectionsTransactionsTransaction',
     'GetIdentityVerificationReportsReport',
     'GetIdentityVerificationSessionsSession',
-    'GetIssuingCardholders',
+    'GetInvoiceitemsInvoiceitem',
+    'GetInvoicesInvoiceLines',
+    'GetIssuingAuthorizationsAuthorization',
     'GetIssuingCardholdersCardholder',
-    'GetIssuingCardsCard',
-    'GetIssuingDisputes',
     'GetIssuingDisputesDispute',
     'GetIssuingPersonalizationDesignsPersonalizationDesign',
-    'GetIssuingTokens',
-    'GetIssuingTokensToken',
-    'GetIssuingTransactions',
     'GetIssuingTransactionsTransaction',
+    'GetLinkAccountSessionsSession',
+    'GetLinkedAccounts',
+    'GetLinkedAccountsAccount',
     'GetMandatesMandate',
+    'GetPaymentIntentsIntent',
+    'GetPaymentIntentsSearch',
     'GetPaymentLinksPaymentLink',
-    'GetQuotes',
+    'GetPayoutsPayout',
+    'GetProductsId',
+    'GetProductsProductFeaturesId',
+    'GetProductsSearch',
     'GetQuotesQuote',
+    'GetRadarValueListItems',
     'GetRadarValueListItemsItem',
-    'GetRadarValueLists',
     'GetRadarValueListsValueList',
-    'GetReportingReportRuns',
+    'GetRefundsRefund',
     'GetReportingReportRunsReportRun',
-    'GetReviews',
     'GetReviewsReview',
     'GetSetupIntentsIntent',
     'GetSourcesSource',
-    'GetSubscriptionSchedules',
+    'GetSubscriptionItems',
+    'GetSubscriptionItemsItem',
+    'GetSubscriptionSchedulesSchedule',
+    'GetSubscriptionsSearch',
     'GetTaxCalculationsCalculation',
+    'GetTaxIdsId',
     'GetTaxRatesTaxRate',
-    'GetTaxRegistrations',
     'GetTaxRegistrationsId',
     'GetTaxTransactionsTransaction',
-    'GetTerminalConfigurations',
     'GetTerminalConfigurationsConfiguration',
-    'GetTerminalLocations',
     'GetTerminalLocationsLocation',
-    'GetTerminalReaders',
     'GetTerminalReadersReader',
     'GetTestHelpersTestClocks',
+    'GetTestHelpersTestClocksTestClock',
     'GetTokensToken',
     'GetTopups',
     'GetTopupsTopup',
     'GetTransfersTransfer',
-    'GetTreasuryFinancialAccounts',
+    'GetTransfersTransferReversalsId',
     'GetTreasuryFinancialAccountsFinancialAccount',
     'GetTreasuryInboundTransfers',
     'GetTreasuryInboundTransfersId',
@@ -87,57 +135,156 @@ export const manifest: DerivedManifest = {
     'GetTreasuryReceivedCreditsId',
     'GetTreasuryReceivedDebits',
     'GetTreasuryReceivedDebitsId',
+    'GetTreasuryTransactionEntries',
     'GetTreasuryTransactionEntriesId',
+    'GetTreasuryTransactions',
     'GetTreasuryTransactionsId',
-    'GetWebhookEndpoints',
     'GetWebhookEndpointsWebhookEndpoint',
-    'PostCouponsCoupon',
-    'PostPaymentIntentsIntent',
-    'PostPaymentLinksPaymentLink',
-    'PostRefundsRefund',
-    'PostSetupIntentsIntent',
-    'PostTransfersTransfer',
-    'DeleteAccountsAccountBankAccountsId',
-    'DeleteAccountsAccountPeoplePerson',
-    'DeleteCustomersCustomerSubscriptionsSubscriptionExposedId',
-    'DeleteTaxIdsId',
-    'GetAccountsAccountBankAccountsId',
-    'GetAccountsAccountPeople',
-    'GetAccountsAccountPeoplePerson',
-    'GetApplicationFeesFeeRefundsId',
-    'GetBalanceHistory',
-    'GetBalanceHistoryId',
-    'GetChargesChargeDispute',
-    'GetCustomersCustomerSubscriptions',
-    'GetCustomersCustomerSubscriptionsSubscriptionExposedId',
-    'GetFileLinks',
-    'GetFileLinksLink',
-    'GetFinancialConnectionsTransactionsTransaction',
-    'GetIdentityVerificationSessions',
-    'GetLinkAccountSessionsSession',
-    'GetLinkedAccounts',
-    'GetLinkedAccountsAccount',
-    'GetTaxIdsId',
-    'GetTransfersTransferReversalsId',
+    '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}' } },
@@ -149,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',
@@ -169,8 +320,12 @@ export const manifest: DerivedManifest = {
     },
   },
   // 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)
+  // 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,
@@ -209,16 +364,16 @@ export const manifest: DerivedManifest = {
     credentialDoor: { path: '/_twin/app-credentials', body: {}, fill: { STRIPE_SECRET_KEY: 'secret_key', STRIPE_API_KEY: 'secret_key', STRIPE_PRIVATE_KEY: 'secret_key', BILLING_STRIPE_API_KEY: 'secret_key', STRIPE_PUBLISHABLE_KEY: 'publishable_key', NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: 'publishable_key', NEXT_PUBLIC_STRIPE_PUBLIC_KEY: 'publishable_key', NEXT_PUBLIC_STRIPE_KEY: 'publishable_key', STRIPE_WEBHOOK_SECRET: 'webhook_secret', STRIPE_WEBHOOK_SIGNING_SECRET: 'webhook_secret', STRIPE_ENDPOINT_SECRET: 'webhook_secret', STRIPE_WEBHOOK_SECRET_KEY: 'webhook_secret', NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET: 'webhook_secret', BILLING_STRIPE_WEBHOOK_SECRET: 'webhook_secret', STRIPE_CONNECT_WEBHOOK_SECRET: 'connect_webhook_secret', STRIPE_WEBHOOK_SECRET_CONNECT: 'connect_webhook_secret', STRIPE_CONNECT_WEBHOOK_SIGNING_SECRET: 'connect_webhook_secret' } },
     hosts: [
       { host: 'api.stripe.com' }, { host: 'checkout.stripe.com', pathPattern: '^/c/pay/' }, { host: 'billing.stripe.com', pathPattern: '^/p/session/' },
-      { host: 'connect.stripe.com', pathPattern: '^/setup/|^/oauth/(authorize|token|deauthorize)/?$' },
-      { host: 'dashboard.stripe.com', pathPattern: '^/settings/public/?$|^/(test/)?settings/connect(/onboarding-options/oauth)?/?$' },
+      { host: '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/financial-connections/|^/v3/?$|^/(v3|[a-z]+)/stripe\\.js$' },
+      { host: 'js.stripe.com', pathPattern: '^/v3/?$|^/(v3|[a-z]+)/stripe\\.js$' },
     ],
   },
   // what GET /twin says this twin is
   discovery: {
-    twinOf: 'the Stripe REST API, its hosted pages (Checkout, the customer portal, Connect onboarding and OAuth, Identity, Financial Connections) and Stripe.js',
-    stores: 'customers, payment objects, checkout sessions, products and prices, subscriptions and invoices, Connect accounts, Issuing, Treasury, and webhook endpoints (signed events)',
+    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: [
@@ -228,31 +383,26 @@ export const manifest: DerivedManifest = {
     { 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',
     },
     {
       // an Account Link's url (/setup/{account_link}) opens the onboarding session the page is (/setup/s/{session})
       id: 'connect-onboarding', kind: 'flow', host: 'connect.stripe.com', path: '/setup', status: 'done',
-      demand: '3 of 85 applications onboard connected accounts with Account Links', controls: ['Agree and submit', '← Return to platform'],
+      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',
     },
-    {
-      // the authorize page, and the token and deauthorize endpoints the platform's server calls (not in Stripe's spec)
-      id: 'connect-oauth', kind: 'flow', host: 'connect.stripe.com', path: '/oauth', status: 'done',
-      demand: "Cal.com's Stripe app connects each organizer's Standard account through Connect OAuth", controls: ['Skip this form', 'Deny access'],
-      source: 'https://docs.stripe.com/connect/oauth-reference',
-    },
     {
       // 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',
@@ -261,20 +411,21 @@ export const manifest: DerivedManifest = {
     },
     {
       id: 'dashboard', kind: 'workspace', host: 'dashboard.stripe.com', path: '/', status: 'done',
-      demand: 'an operator sets the business name Checkout shows (Public details: /settings/public) and a Connect platform its OAuth client_id and redirect URIs (/settings/connect/onboarding-options/oauth)',
-      controls: ['Business name', 'Save', 'Enable OAuth for Standard accounts', 'Redirect URIs'], source: 'https://docs.stripe.com/dashboard/basics',
+      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': {
+    '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': { storedAs: 'billing_meter_event', idPrefix: 'mtr_evt' },
-    'billing.credit_grant': { storedAs: 'credit_grant', idPrefix: 'credgr', ...states["billing.credit_grant"], filters: ['customer'], notFound: "No such credit grant: '{id}'" },
-    'billing.alert': {
-      storedAs: 'billing_alert', idPrefix: 'alert', notFound: "No such alert: '{id}'", ...states["billing.alert"],
-    },
-    payment_intent: {
+    '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'],
@@ -283,268 +434,245 @@ export const manifest: DerivedManifest = {
     // metadata keys; `update: 'replace'` keeps the twin's answer)
     // next_invoice_sequence, "The suffix of the customer's next invoice number" (docs.stripe.com/api/customers/object): one
     // past its numbered invoices (a finalized invoice is never deleted)
-    customer: { idPrefix: 'cus', update: 'replace', ...states["customer"], filters: ['email'], counts: { next_invoice_sequence: { of: 'invoice', by: 'customer', present: 'number', plus: 1 } } },
-    tax_id: { idPrefix: 'txi', ...states["tax_id"], filters: ['customer'] },
-    customer_balance_transaction: { idPrefix: 'cbtxn', ...states["customer_balance_transaction"], },
-    customer_cash_balance_transaction: { storedAs: 'cash_balance_transaction', idPrefix: 'ccsbtxn', ...states["customer_cash_balance_transaction"], },
+    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', ...states["payment_source"],
     },
-    source: {
+    source: { refresh: { none: 'Stripe lists no Sources: each is read by its id (GET /v1/sources/{source})' },
       idPrefix: 'src', ...states["source"],
     },
     // Connect OAuth's authorization codes: the row's id minted, the code's value drawn from the World's secret
     _oauth_code: { idPrefix: '', ids: '{n}' },
-    charge: {
+    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', ...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', ...states["setup_intent"],
       embeds: { customer: 'customer', payment_method: 'payment_method' },
       filters: ['customer', 'payment_method'],
     },
-    payment_method: { idPrefix: 'pm', ...states["payment_method"], embeds: { customer: 'customer' }, filters: ['customer', 'type'] },
-    subscription: {
+    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: {
+    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', ...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: {
+    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', ...states["dispute"], embeds: { charge: 'charge', payment_intent: 'payment_intent' }, filters: ['charge', 'payment_intent'] },
-    payout: { idPrefix: 'po', ...states["payout"], embeds: { balance_transaction: 'balance_transaction', destination: 'account' } },
+    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: {
+    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: {
+    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}'", ...states["promotion_code"],
     },
-    credit_note: { idPrefix: 'cn', ...states["credit_note"], embeds: { customer: 'customer', invoice: 'invoice' }, filters: ['invoice', 'customer'] },
-    subscription_schedule: {
+    subscription_schedule: { refresh: { list: 'GetSubscriptionSchedules' },
       idPrefix: 'sub_sched',
       update: 'replace', ...states["subscription_schedule"],
       embeds: { customer: 'customer', subscription: 'subscription' },
       filters: ['customer', 'subscription'],
     },
-    'entitlements.feature': {
+    '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 (./engine/test-clocks.ts)
-    'test_helpers.test_clock': {
-      storedAs: 'test_clock',
-      idPrefix: 'clock',
-      notFound: "No such test clock: '{id}'", ...states["test_helpers.test_clock"],
-    },
-    event: { idPrefix: 'evt', filters: ['type'] },
+
+    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}'", ...states["webhook_endpoint"],
     },
-    account: { idPrefix: 'acct', ...states["account"], },
-    person: { idPrefix: 'person', ...states["person"], 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: {
+    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: {
+    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: {
+    application_fee: { refresh: { list: 'GetApplicationFees' },
       idPrefix: 'fee', notFound: "No such application fee: '{id}'", filters: ['charge'], ...states["application_fee"],
     },
-    fee_refund: { idPrefix: 'fr' },
-    'apps.secret': { storedAs: 'apps_secret', idPrefix: 'apmc' },
-    token: { idPrefix: 'tok' },
-    file: { idPrefix: 'file', ...states["file"], filters: ['purpose'] },
-    file_link: { idPrefix: 'link' },
-    // the user submits on Stripe's hosted verification page and Stripe checks it (the twin's own helper
-    // outside Stripe's surface, POST …/verify, stands in for both at once)
-    'identity.verification_session': {
-      storedAs: 'verification_session',
-      idPrefix: 'vs',
-      notFound: "No such VerificationSession: '{id}'", ...states["identity.verification_session"],
-    },
-    'identity.verification_report': { storedAs: 'verification_report', idPrefix: 'vr', notFound: "No such verification report: '{id}'", ...states["identity.verification_report"], filters: ['verification_session', 'type'] },
-    'billing_portal.session': { storedAs: 'billing_portal_session', idPrefix: 'bps', ...states["billing_portal.session"], },
+    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': {
+    '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}'", ...states["tax_rate"],
-    },
-    // its status is derived on every read from whether a head office is set; nothing stores it
-    'tax.settings': { storedAs: 'tax_settings', idPrefix: 'taxset', ...states["tax.settings"], },
-    'tax.calculation': { storedAs: 'tax_calculation', idPrefix: 'taxcalc', notFound: "No such tax calculation: '{id}'" },
-    // a registration is active from creation here; its dates move it on the clock
-    'tax.registration': {
-      storedAs: 'tax_registration', idPrefix: 'taxreg', notFound: "No such tax registration: '{id}'", filters: ['status'], ...states["tax.registration"],
-    },
-    'tax.transaction': { storedAs: 'tax_transaction', idPrefix: 'tax', notFound: "No such tax transaction: '{id}'", ...states["tax.transaction"], },
-    payment_link: {
-      idPrefix: 'plink',
-      update: 'replace', notFound: "No such payment link: '{id}'", ...states["payment_link"],
-    },
-    quote: { idPrefix: 'qt', ...states["quote"], 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', ...states["review"],
     },
-    'radar.value_list': { storedAs: 'radar_value_list', idPrefix: 'rsl', notFound: "No such radar value list: '{id}'", ...states["radar.value_list"], filters: ['alias'] },
-    'radar.value_list_item': { storedAs: 'radar_value_list_item', idPrefix: 'rsli', notFound: "No such radar value list item: '{id}'" },
-    'issuing.cardholder': {
+    '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',
+      // 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}'", ...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', ...states["issuing.authorization"], },
-    'issuing.transaction': { storedAs: 'issuing_transaction', idPrefix: 'ipi', notFound: "No such transaction: '{id}'", ...states["issuing.transaction"], filters: ['card', 'cardholder'] },
-    'issuing.dispute': {
-      storedAs: 'issuing_dispute',
-      idPrefix: 'idp',
-      notFound: "No such dispute: '{id}'", ...states["issuing.dispute"],
-      filters: ['status', 'transaction'],
-    },
-    'issuing.token': {
-      storedAs: 'issuing_token',
-      idPrefix: 'iss_tok',
-      notFound: "No such issuing token: '{id}'", ...states["issuing.token"],
-      filters: ['card', 'status'],
-    },
-    // a design waits in review (inactive) until the review test helpers decide it
-    'issuing.personalization_design': {
-      storedAs: 'personalization_design',
-      idPrefix: 'pd',
-      notFound: "No such personalization design: '{id}'", ...states["issuing.personalization_design"],
-    },
-    'terminal.location': { storedAs: 'terminal_location', idPrefix: 'tml', notFound: "No such location: '{id}'" },
-    // a simulated reader is online from registration; a real one drops off and comes back
-    'terminal.reader': {
-      storedAs: 'terminal_reader', idPrefix: 'tmr', notFound: "No such reader: '{id}'", ...states["terminal.reader"], filters: ['location', 'status'],
-    },
-    'terminal.configuration': { storedAs: 'terminal_configuration', idPrefix: 'tmc', notFound: "No such configuration: '{id}'", ...states["terminal.configuration"], },
-    topup: {
-      idPrefix: 'tu', ...states["topup"],
-      filters: ['status'],
-    },
-    // closing an account (POST …/close) is not modeled here; is_default is Stripe's
-    'treasury.financial_account': { storedAs: 'financial_account', idPrefix: 'fa', notFound: "No such financial account: '{id}'", ...states["treasury.financial_account"], 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}'", ...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}'", ...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}'", ...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}'", ...states["treasury.received_credit"], filters: ['financial_account', 'status'] },
-    'treasury.received_debit': { storedAs: 'received_debit', idPrefix: 'rd', notFound: "No such received debit: '{id}'", ...states["treasury.received_debit"], filters: ['financial_account', 'status'] },
+    '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': {
+    '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': { storedAs: 'treasury_transaction_entry', idPrefix: 'trxne', notFound: "No such transaction entry: '{id}'", ...states["treasury.transaction_entry"], },
-    'climate.order': {
-      storedAs: 'climate_order',
-      idPrefix: 'climorder',
-      notFound: "No such order: '{id}'", ...states["climate.order"],
-    },
-    'financial_connections.session': { storedAs: 'fc_session', idPrefix: 'fcsess' },
-    'financial_connections.account': {
-      storedAs: 'fc_account',
-      idPrefix: 'fca',
-      notFound: "No such account: '{id}'", ...states["financial_connections.account"],
-    },
+    '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': {
+    '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"],
     },
-    '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}'", ...states["reporting.report_run"],
-    },
     // archived (active=false) and restored by an update
-    product: { idPrefix: 'prod', update: 'replace', ...states["product"], },
-    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', ...states["price"], embeds: { product: 'product' },
     },
   },
   // 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' },
+    },
+  },
 };