@volter/twin-stripe 3.0.0 → 3.0.1

package/dist/src/manifest.js

@@ -6,71 +6,119 @@ export const manifest = {
     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',
@@ -82,57 +130,156 @@ export const manifest = {
         '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}' } },
@@ -144,6 +291,10 @@ export const manifest = {
         pattern: '^\\d{4}-\\d{2}-\\d{2}(\\.[a-z_]+)?$',
         error: { status: 400, kind: 'invalid_request_error', code: 'invalid_api_version', message: 'Invalid Stripe version: {value}. Check the API version reference: https://stripe.com/docs/api/versioning' },
     },
+    // source: https://github.com/stripe/stripe-mock/issues/31 "Unrecognized request URL (GET: /v1/test)."
+    // source: spec:/components/schemas/api_errors/properties/type "invalid_request_error"
+    // Stripe's published API answer, shown by its maintainer for an unknown URL.
+    gap: { status: 404, kind: 'invalid_request_error', message: 'Unrecognized request URL ({method}: {path}). Please see https://stripe.com/docs or we can help at https://support.stripe.com/.' },
     notFound: { status: 404, kind: 'invalid_request_error', code: 'resource_missing', message: "No such {object}: '{id}'" },
     list: {
         style: 'envelope',
@@ -164,8 +315,12 @@ export const manifest = {
         },
     },
     // 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,
@@ -203,16 +358,16 @@ export const manifest = {
         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: [
@@ -222,31 +377,26 @@ export const manifest = {
         { 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',
@@ -255,20 +405,21 @@ export const manifest = {
         },
         {
             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'],
@@ -277,268 +428,245 @@ export const manifest = {
         // 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' },
+        },
+    },
 };