@volter/twin-stripe 2.0.38 → 3.0.0

package/spec/sources.json

@@ -0,0 +1,378 @@
+{
+  "https://docs.stripe.com/api/authentication": {
+    "status": 200,
+    "checked": "2026-09-30",
+    "quotes": {
+      "API requests without authentication also fail.": true
+    }
+  },
+  "https://docs.stripe.com/api/balance_transactions/object#balance_transaction_object-status": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/billing/alert/activate": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/billing/alert/archive": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/billing/alert/deactivate": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/billing/meter/deactivate": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/billing/meter/reactivate": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/capabilities/update": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/charges/capture": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/charges/object#charge_object-refunded": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/checkout/sessions/expire": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/checkout/sessions/object#checkout_session_object-payment_status": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/checkout/sessions/object#checkout_session_object-status": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/climate/order/cancel": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/credit_notes/void": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/customer_portal/configurations/update": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/disputes/close": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/disputes/update#update_dispute-submit": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/fee_refunds/create": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/financial_connections/accounts/disconnect": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/invoices/delete": {
+    "status": 200,
+    "checked": "2026-10-02"
+  },
+  "https://docs.stripe.com/api/invoices/finalize": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/invoices/mark_uncollectible": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/invoices/pay": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/invoices/send": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/invoices/void": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/issuing/authorizations/decline": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/issuing/authorizations/test_mode_capture": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/issuing/cardholders/update": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/issuing/cards/update": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/issuing/tokens/update": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/mandates/object": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/payment_intents/apply_customer_balance": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/payment_intents/cancel": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/payment_intents/capture": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/payment_intents/confirm": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/payment_intents/increment_authorization": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/payment_links/payment_links/update": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/payouts/cancel": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/plans/delete": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/prices/update#update_price-active": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/products/update#update_product-active": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/promotion_codes/update": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/quotes/accept": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/quotes/cancel": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/quotes/finalize": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/radar/reviews/approve": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/refunds/cancel": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/refunds/create#create_refund-refund_application_fee": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/setup_intents/cancel": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/setup_intents/confirm": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/setup_intents/verify_microdeposits": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/subscription_schedules/cancel": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/subscription_schedules/release": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/subscriptions/cancel": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/subscriptions/update#update_subscription-trial_end": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/tax_rates/update": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/terminal/readers/present_payment_method": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/test_clocks/advance": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/topups/cancel": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/treasury": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/treasury/inbound_transfers": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/treasury/transactions/object": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/webhook_endpoints/update#update_webhook_endpoint-disabled": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/billing/subscriptions/build-subscriptions": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/billing/subscriptions/cancel#cancel-at-end-of-cycle": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/billing/subscriptions/overview#payment-status": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/billing/subscriptions/trials": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/billing/subscriptions/trials/free-trials": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/billing/subscriptions/trials/free-trials#adding-a-new-trial-to-a-subscription-previously-in-a-trial": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/billing/subscriptions/upgrade-downgrade#immediate-payment": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/connect/account-capabilities#capability-status": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/connect/top-ups": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/customer-management": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/identity/how-sessions-work": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/invoicing/integration": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/invoicing/integration/workflow-transitions#finalized": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/issuing/cards/physical/create-design.md?testing-method=with-code": {
+    "status": 200,
+    "checked": "2026-09-30",
+    "quotes": {
+      "Use the [Files API](https://docs.stripe.com/api/files/create.md) to upload a .PNG file of your card logo, and specify the purpose as `issuing_logo`.": true
+    }
+  },
+  "https://docs.stripe.com/issuing/controls/real-time-authorizations": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/issuing/purchases/authorizations": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/keys": {
+    "status": 200,
+    "checked": "2026-09-30",
+    "quotes": {
+      "Publishable keys": true
+    }
+  },
+  "https://docs.stripe.com/payments/ach-direct-debit/accept-a-payment?payment-ui=direct-api": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/payments/checkout/how-checkout-works": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/payments/customer-balance/reconciliation": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/payments/paymentintents/lifecycle": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/payouts#payout-statuses": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/refunds": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/reports/api": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/testing#evidence": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/webhooks": {
+    "status": 200,
+    "checked": "2026-09-30",
+    "quotes": {
+      "register a webhook endpoint, Stripe pushes real-time data to it when": true
+    }
+  }
+}

package/src/cli.ts

@@ -1,36 +1,22 @@
 #!/usr/bin/env node
-import { keepProcessAlive } from '@volter/world-core/lifecycle';
-// world-stripe CLI: serve the Stripe API twin, the mirror UI, or run conformance.
+// world-stripe: serve the stripe twin.
 import { hasFlag, optionValue } from '@volter/world-core/args';
-import { createStripeTwinServer } from './stripe-server.ts';
-import { createStripeMirrorServer } from './stripe-mirror-ui.ts';
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { createStripeTwinServer } from './server.ts';
 
 const [cmd, ...rest] = process.argv.slice(2);
 const port = Number(optionValue(rest, '--port', '0')) || undefined;
 const root = optionValue(rest, '--root') || undefined;
-const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+const readOnly = hasFlag(rest, '--read-only');
+// the World's managed Postgres, which the runtime binds a pack declaring managedDatabase to
+const database = optionValue(rest, '--database') || undefined;
+// the World's scenario file, for a model vendor's turns
+const scenarioPath = optionValue(rest, '--scenario') || undefined;
 
-if (cmd === 'serve') {
-  const s = await createStripeTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
-  process.stdout.write(`stripe twin (spec-correct API)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
-  await keepProcessAlive();
-} else if (cmd === 'mirror') {
-  const s = await createStripeMirrorServer({ ...(root ? { root } : {}), ...(port ? { port } : {}) });
-  process.stdout.write(`stripe mirror UI (dashboard) at http://127.0.0.1:${s.port}\n`);
+if (cmd === 'serve' || cmd === undefined) {
+  const s = await createStripeTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(database ? { database } : {}), ...(scenarioPath ? { scenarioPath } : {}) });
+  process.stdout.write(`stripe twin${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
   await keepProcessAlive();
-} else if (cmd === 'emit') {
-  // DELIVER: fire a signed, vendor-shaped event synthesized from twin state at the app's
-  // registered webhook endpoint(s). `emit --list` shows what's emittable right now.
-  const { runEmitCli } = await import('@volter/world-core');
-  const { stripeEmitter } = await import('./stripe-emit.ts');
-  process.exit(await runEmitCli(stripeEmitter, rest));
-} else if (cmd === 'conformance') {
-  // dev-only; lazy so the bin runs without @volter/world-tooling
-  const { checkStripeConformance, loadStripeKnownDeviations, loadStripeSchemas, stripeCoverage } = await import('./stripe-conformance.ts');
-  const [schemas, known] = await Promise.all([loadStripeSchemas(), loadStripeKnownDeviations()]);
-  const report = checkStripeConformance(schemas, { ...(root ? { root } : {}), known });
-  process.stdout.write(`${JSON.stringify({ ...report, coverage: stripeCoverage(schemas, { ...(root ? { root } : {}) }) }, null, 2)}\n`);
-  if (!report.ok) process.exitCode = 1;
 } else {
-  process.stdout.write('Usage: world-stripe serve|mirror|emit|conformance [--port N] [--root DIR] [--read-only]\n       world-stripe emit --list [--root DIR] | emit <event.type> <subject-id> [--root DIR] [--endpoint URL|we_id] [--json]\n');
+  process.stdout.write('Usage: world-stripe serve [--port N] [--root DIR] [--read-only] [--database URL] [--scenario FILE]\n');
 }

package/src/engine/after-payment.ts

@@ -0,0 +1,31 @@
+// What Stripe does itself once a payment succeeds, which no API call asks for:
+// - a test card that is disputed opens a dispute on its charge (docs.stripe.com/testing#disputes: 4000000000000259
+//   "charge succeeds, then disputed as fraudulent", 4000000000002685 disputed as product not received,
+//   4000000000001976 an inquiry), and Stripe debits the disputed
+//   amount and its dispute fee from the balance (docs.stripe.com/disputes/how-disputes-work);
+// - a test card Radar scores as elevated risk opens a review of its charge (docs.stripe.com/testing#fraud-prevention:
+//   4000000000009235, "elevated risk", which Radar places in review; docs.stripe.com/radar/reviews);
+// - a charge a platform makes with `application_fee_amount` earns the platform an application fee, from the connected
+//   account it pays (a destination charge's `transfer_data.destination`, or the account a direct charge is made on;
+//   docs.stripe.com/connect/destination-charges, docs.stripe.com/connect/direct-charges);
+// - a bank account verified by micro-deposits for a payment or a setup carries a mandate, the customer's acceptance
+//   of debits (docs.stripe.com/payments/ach-direct-debit/accept-a-payment, docs.stripe.com/api/mandates).
+//
+// Where the documentation stops and the twin decides: evidence is due seven days after a dispute opens (Stripe's
+// deadline depends on the card network); the dispute fee is 1500 cents in any currency (Stripe's US fee is $15); an
+// elevated-risk review's risk score is 67 (Radar's elevated band); the application is `ca_twin`.
+import { BYPASS_PENDING_CARDS } from './test-cards.ts';
+
+export type Outcome = 'dispute' | 'dispute_not_received' | 'inquiry' | 'review' | 'available';
+export const DAY = 86_400;
+
+/** The test cards whose success Stripe follows with its own act, by number and by their documented test names. */
+export const AFTER_SUCCESS_CARDS: Record<string, { brand: string; number: string; outcome: Outcome }> = {
+  pm_card_createDispute: { brand: 'visa', number: '4000000000000259', outcome: 'dispute' },
+  pm_card_createDisputeProductNotReceived: { brand: 'visa', number: '4000000000002685', outcome: 'dispute_not_received' },
+  pm_card_createDisputeInquiry: { brand: 'visa', number: '4000000000001976', outcome: 'inquiry' },
+  pm_card_riskLevelElevated: { brand: 'visa', number: '4000000000009235', outcome: 'review' },
+  // its funds go straight to the available balance (ledger.ts reads it; no act follows here)
+  ...Object.fromEntries(Object.entries(BYPASS_PENDING_CARDS).map(([name, c]) => [name, { ...c, outcome: 'available' as const }])),
+};
+export const BY_NUMBER: Record<string, Outcome> = Object.fromEntries(Object.values(AFTER_SUCCESS_CARDS).map((c) => [c.number, c.outcome]));

package/src/engine/apps-secrets.ts

@@ -0,0 +1,4 @@
+// Apps secret-store semantics: a secret is named within a scope (the account, or one user); setting
+// the same name in the same scope overwrites it. The scope is kept as a bookkeeping key.
+
+export const SECRET = 'apps.secret';

package/src/engine/balance.ts

@@ -0,0 +1,33 @@
+// Balance and payout semantics. The balance is computed from the balance-transaction ledger (./ledger.ts), never
+// stored: funds past their available_on are available, the rest pending, and Issuing funds their own section. The
+// balance, the payouts and the ledger are the acting account's: the platform's, or a connected account's under the
+// Stripe-Account header. A payout comes out of what that account has available and goes to its bank account, which a
+// connected account must have (docs.stripe.com/connect/payouts-connected-accounts). A pending payout can be canceled,
+// which returns its money; a connected account's paid payout can be reversed, which debits its bank account back
+// into its balance (docs.stripe.com/api/payouts/reverse). The machine in ../manifest.ts says how a payout's status
+// moves.
+//
+// Stripe also pays each account out on its own schedule (settings.payouts.schedule: daily by default, weekly or monthly
+// on an anchor, or manual): an automatic payout takes what has become available since the last one, and the ledger
+// lists the entries it paid (docs.stripe.com/payouts#payout-schedule, docs.stripe.com/connect/manage-payout-schedule).
+// A connected account is paid out once it can be (payouts_enabled, with a bank account).
+//
+// Where the documentation stops and the twin decides: a payout arrives two days after it is made (Stripe's standard
+// US schedule counts business days) and reads paid from then on; an automatic payout is made at midnight UTC on the
+// first scheduled day on or after its funds become available, only when what it would pay is positive.
+import type { Row } from './common.ts';
+
+export const DAY = 86_400;
+
+export const DAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+/** The first scheduled payout time on or after `from`: midnight UTC of a day the schedule pays out on. */
+export function payoutDay(from: number, schedule: Row): number {
+  const first = Math.ceil(from / DAY) * DAY;
+  const pays = (day: number): boolean => {
+    const d = new Date(day * 1000);
+    if (schedule.interval === 'weekly') return DAYS[d.getUTCDay()] === String(schedule.weekly_anchor ?? 'monday');
+    if (schedule.interval === 'monthly') return d.getUTCDate() === Math.min(Number(schedule.monthly_anchor ?? 1), new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0)).getUTCDate());
+    return true;
+  };
+  return Array.from({ length: 62 }, (_, i) => first + i * DAY).find(pays) ?? first;
+}

package/src/engine/billing.ts

@@ -0,0 +1,16 @@
+// Billing semantics: meters (how usage events aggregate), the meter events that report usage and
+// the summaries that aggregate them, prepaid credit grants and the balance they leave, and usage
+// alerts. The machines in ../manifest.ts say how a meter and an alert move. Lists and retrieves
+// with no scoping of their own are the derived core's.
+import type { Row } from './common.ts';
+
+export const METER = 'billing.meter';
+export const objectOf = (v: unknown): Row => (v && typeof v === 'object' ? (v as Row) : {});
+
+// ── credit grants: a customer's prepaid credit, paid or promotional, in a monetary amount ──
+
+export const GRANT = 'billing.credit_grant';
+
+// ── alerts: a usage threshold on a meter ──
+
+export const ALERT = 'billing.alert';

package/src/engine/charges.ts

@@ -0,0 +1,19 @@
+// Charge semantics. The machine in ../manifest.ts says a charge is captured once; these handlers
+// compute the money: a charge's `refunds` sub-list is derived on every read from the refunds that
+// point at it, never a stored snapshot, while the cumulative `amount_refunded` / `refunded` stay
+// stored (a partial capture moves them for a reason that is also a Refund row).
+import type { Row } from './common.ts';
+
+// A charge is written as the event Stripe sends for it (docs.stripe.com/api/events/types; Stripe has no
+// `charge.created`): charge.succeeded, "Occurs whenever a charge is successful", for one made or authorized
+// (capture=false: its status is succeeded, captured false), and charge.failed, "Occurs whenever a failed charge attempt
+// occurs", for a declined attempt. The twin makes no pending charge (charge.pending, "Occurs whenever a pending charge is
+// created"): its charges settle when made.
+/** The create's parameters as the charge keeps them: without `card`, the request's card details ("A token, like the ones
+ *  returned by Stripe.js", or a hash of the number, expiry and CVC). The Charge object has no `card` property (served
+ *  spec, charge); the card it was made with is its payment_method_details. Kept, it answered the card's full number and
+ *  CVC back on every read of the charge. */
+export function withoutCard(params: Row): Row {
+  const { card: _card, ...rest } = params;
+  return rest;
+}

package/src/engine/checkout.ts

@@ -0,0 +1,40 @@
+// Checkout Session semantics. The machine in ../manifest.ts says an open session expires or
+// completes and nothing else does. Stripe completes a session when the customer pays on its hosted
+// page (src/screens/checkout.tsx, the session's url), which has no API verb; completing links what
+// the payment made: a succeeded PaymentIntent, an active (or
+// trialing) subscription, or a succeeded SetupIntent. List and retrieve are the derived core's.
+import type { Row } from './common.ts';
+
+export const CS = 'checkout.session';
+
+/** The payment method types a session takes: the list a caller pinned to an earlier version gives as
+ *  payment_method_types ("A list of the types of payment methods (e.g., `card`) this Checkout Session can accept", the
+ *  parameter the served version's allowed_payment_method_types is described against: "Unlike `payment_method_types`,
+ *  this acts as a filter on the dynamically computed set of eligible payment methods", docs.stripe.com/api/checkout/
+ *  sessions/create), else the allowed_payment_method_types of the served one, else card. Where the documentation stops
+ *  and the twin decides: an allowed list is answered whole (the twin does not compute eligibility), and without one the
+ *  session takes card (the account's enabled methods are not modelled). */
+export function sessionMethodTypes(params: Row): string[] {
+  const given = Array.isArray(params.payment_method_types) ? params.payment_method_types : params.allowed_payment_method_types;
+  return Array.isArray(given) && given.length ? given.map(String) : ['card'];
+}
+
+/** Metadata passed on to what a session makes (payment_intent_data[metadata], subscription_data[metadata]) as a
+ *  create's own is kept: "Individual keys can be unset by posting an empty value to them. All keys can be unset by
+ *  posting an empty value to `metadata`" (every metadata parameter, docs.stripe.com/api/metadata), so a key posted
+ *  empty is not set, and metadata posted empty is {} (./front.ts createMetadata, the top-level case). */
+export function nestedMetadata(given: unknown): Row | undefined {
+  if (given === '') return {};
+  if (!given || typeof given !== 'object' || Array.isArray(given)) return undefined;
+  return Object.fromEntries(Object.entries(given as Row).filter(([, v]) => v !== ''));
+}
+
+/** The card the customer entered on the page. */
+export type EnteredCard = { number: string; exp_month: number; exp_year: number };
+
+/** A line item of a one-time Price: a stored Price, or an inline `price_data`, without `recurring` ("Line items with
+ *  one-time Prices will be on the initial invoice only", docs.stripe.com/api/checkout/sessions/create). */
+export function isOneTime(item: Row, priceData?: Row | null): boolean {
+  if (priceData) return !priceData.recurring;
+  return !!item.price && typeof item.price === 'object' && !(item.price as Row).recurring;
+}

package/src/engine/common.ts

@@ -0,0 +1,47 @@
+// Stripe's shared computation over rows already read: the fields each object's spec gives, a row as Stripe answers it,
+// and the list and refund shapes (the handlers' shared behaviour is ../semantics/shared.ts).
+import { view } from './stripe.ts';
+
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+
+export type Row = Record<string, unknown>;
+
+
+/** A removed discount as Stripe answers it: the discount, marked deleted (docs.stripe.com/api/discounts/delete). */
+export function deletedDiscount(d: Row, now: unknown): Row {
+  const coupon = d.coupon && typeof d.coupon === 'object' ? String((d.coupon as Row).id) : typeof d.coupon === 'string' ? d.coupon : null;
+  return {
+    id: d.id ?? `di_${coupon ?? 'twin'}`, object: 'discount', deleted: true, checkout_session: d.checkout_session ?? null, customer: d.customer ?? null,
+    invoice: d.invoice ?? null, invoice_item: d.invoice_item ?? null, promotion_code: d.promotion_code ?? null, subscription: d.subscription ?? null,
+    subscription_item: d.subscription_item ?? null, source: d.source ?? { type: 'coupon', coupon }, start: d.start ?? now,
+  };
+}
+
+/** Keep the rows whose field equals the request's parameter of the same name, for each name given. */
+/** A list's range filter on a unix time (`created[gte]=…&created[lt]=…`, or one exact time). */
+export function inRange(t: unknown, v: unknown): boolean {
+  const at = Number(t);
+  const r = (v && typeof v === 'object' ? v : { gte: v, lte: v }) as Row;
+  return (r.gt === undefined || at > Number(r.gt)) && (r.gte === undefined || at >= Number(r.gte)) && (r.lt === undefined || at < Number(r.lt)) && (r.lte === undefined || at <= Number(r.lte));
+}
+
+export const SPEC_FIELDS = new Map((surface.resources as Array<{ name: string; fields: Array<{ name: string }> }>).map((r) => [r.name, new Set(r.fields.map((f) => f.name))]));
+
+/** A stored subject of any stored type, tombstones included, in the pack's view: what the pack's
+ *  shared helpers look a price, a payment method or a card up by, read from the context's tree. */
+export type Find = (storedType: string, id: string) => Row | undefined;
+
+/** A refund's destination_details for a card charge: "If this is a `card` refund, this hash contains the transaction
+ *  specific details" and its `type` "can be `refund`, `reversal`, or `pending`" — a reversal, where "The original charge
+ *  will drop off the bank statement altogether", for an authorization released uncaptured, else a refund, "a credit entry
+ *  on the bank statement" (docs.stripe.com/api/refunds/object). The network's reference number the twin never has. A
+ *  charge not paid by card answers none. */
+export function refundDestination(charge: Row, type: 'refund' | 'reversal'): Row {
+  const pmd = charge.payment_method_details as Row | null | undefined;
+  if (pmd && pmd.type !== 'card') return {};
+  return { destination_details: { type: 'card', card: { reference: null, reference_status: null, reference_type: null, type } } };
+}
+
+/** An account's external_accounts, "External accounts (bank accounts and debit cards) currently attached to this
+ *  account" (docs.stripe.com/api/accounts/object), as the list its example answers. */
+export const externalList = (account: string, data: Row[]): Row => ({ object: 'list', data, has_more: false, total_count: data.length, url: `/v1/accounts/${account}/external_accounts` });

package/src/engine/connect-settings.ts

@@ -0,0 +1,23 @@
+// The platform's Connect OAuth settings (its client_id, whether OAuth is on, its redirect URIs), which the Dashboard's
+// settings page saves (../screens/dashboard.tsx) and connect.stripe.com/oauth/authorize reads (../screens/connect-oauth.tsx).
+
+/** The platform's test client_id: the World's one platform (acct_twin_self) is the application it names. */
+export const PLATFORM_CLIENT_ID = 'ca_twin_self';
+export const SETTINGS_URL = 'https://dashboard.stripe.com/settings/connect/onboarding-options/oauth';
+/** The page's addresses: the docs' own, its test-mode link, and Connect's settings root. */
+export const CONNECT_SETTINGS_PATH = /^\/(test\/)?settings\/connect(\/onboarding-options\/oauth)?\/?$/;
+export const SETTINGS = '_connect_oauth_settings';
+
+export type ConnectOAuthSettings = { oauth_enabled: boolean; redirect_uris: string[] };
+
+/** The redirect URIs a form's field names, or the first one refused and why. */
+export function redirectUris(field: string): { uris: string[] } | { refused: string } {
+  const uris = [...new Set(field.split(/[\n,]/).map((s) => s.trim()).filter(Boolean))];
+  for (const uri of uris) {
+    let url: URL;
+    try { url = new URL(uri); } catch { return { refused: `${uri} is not a valid URL.` }; }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') return { refused: `${uri} must use http or https.` };
+    if (uri.includes('#')) return { refused: `${uri} must not contain a fragment.` };
+  }
+  return { uris };
+}