@volter/twin-stripe 2.0.38 → 3.0.1

package/spec/sources.json

@@ -0,0 +1,306 @@
+{
+  "archive:https://registry.npmjs.org/@stripe/stripe-js/-/stripe-js-8.6.0.tgz#sha256=13e61419e9076ab440cc636e34d3ea5df3fc62bbf2d6a80d3fd718e8cd47f0a2!/package/dist/stripe-js/checkout.d.ts": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "sha256": "13e61419e9076ab440cc636e34d3ea5df3fc62bbf2d6a80d3fd718e8cd47f0a2",
+    "quotes": {
+      "export interface StripeCheckoutSession": true,
+      "loadActions: () => Promise<StripeCheckoutLoadActionsResult>": true
+    }
+  },
+  "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/meter/create": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "stripe_customer_id": true
+    }
+  },
+  "https://docs.stripe.com/api/charges/object#charge_object-refunded": {
+    "status": 200,
+    "checked": "2026-10-03"
+  },
+  "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/invoices/create_preview.md?query=subscription_details": {
+    "status": 200,
+    "checked": "2026-10-04",
+    "quotes": {
+      "The default value is": true,
+      "forces the proration to be calculated as though the update was done at the specified time.": true,
+      "The time given must be within the current subscription period": true,
+      "cannot be set to": true,
+      "Disable creating prorations in this request.": true,
+      "Always invoice immediately for prorations.": true
+    }
+  },
+  "https://docs.stripe.com/api/invoices/pay": {
+    "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/cards/create": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "Whether authorizations can be approved on this card. May be blocked from activating cards depending on past-due Cardholder requirements. Defaults to inactive.": true,
+      "Defaults to inactive": true
+    }
+  },
+  "https://docs.stripe.com/api/issuing/cards/update": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/payment_intents/cancel": {
+    "status": 200,
+    "checked": "2026-10-03"
+  },
+  "https://docs.stripe.com/api/payment_intents/confirm": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/api/plans/create": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "It replaces the Plans API and is backwards compatible to simplify your migration.": true
+    }
+  },
+  "https://docs.stripe.com/api/promotion_codes/update": {
+    "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/object": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "subscription_items?subscription=": true
+    }
+  },
+  "https://docs.stripe.com/api/subscriptions/update#update_subscription-trial_end": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/billing/customer/balance": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "Represents the starting value of the customer invoice balance when a customer is created using the API with a non-zero invoice balance.": true,
+      "All modifications to the invoice balance are recorded as Transactions": true,
+      "All Transactions created with the API or in the Dashboard have a type value of adjustment": true
+    }
+  },
+  "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/prorations": {
+    "status": 200,
+    "checked": "2026-10-04",
+    "quotes": {
+      "Unused time on original 10 USD plan (credit)": true,
+      "Remaining time on new 20 USD plan (debit)": true,
+      "The current billing period’s start and end times are used to calculate the cost of the subscription before and after the change.": true,
+      "By default, Stripe calculates prorations down to the second.": true,
+      "When calculating proration credits or debits, Stripe uses the subscription’s discounted price, not the original price.": true,
+      "The prorated amount is calculated as soon as the API updates the subscription.": true,
+      "creates a non-proration debit, even when the debit covers a partial billing period.": true,
+      "no additional discounts are applied to the proration line items themselves": true
+    }
+  },
+  "https://docs.stripe.com/billing/subscriptions/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/changelog/clover/2025-09-30/polymorphic-coupon": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "Moves the top-level coupon field on Promotion Codes to promotion.coupon": true,
+      "When you retrieve Promotion Codes, they don’t auto-expand the promotion.coupon field": true
+    }
+  },
+  "https://docs.stripe.com/connect/account-capabilities": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "If a connected account has both card_payments and transfers": true
+    }
+  },
+  "https://docs.stripe.com/connect/authentication": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "Stripe-Account header": true
+    }
+  },
+  "https://docs.stripe.com/connect/destination-charges#issue-refunds": {
+    "status": 200,
+    "checked": "2026-10-03"
+  },
+  "https://docs.stripe.com/customer-management": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/invoicing/integration": {
+    "status": 200,
+    "checked": "2026-10-02",
+    "quotes": {
+      "To finalize a draft invoice, use the Dashboard, send it to the customer, or pay it.": true
+    }
+  },
+  "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/issuing/testing": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "Before you create test transactions, you must add test funds to the Issuing balance on your account.": true,
+      "You can create test top-ups in the Dashboard, or with the Top-ups API": true
+    }
+  },
+  "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/paymentintents/lifecycle": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/payouts": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "paid": true
+    }
+  },
+  "https://docs.stripe.com/payouts#payout-statuses": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/radar/lists": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "Use the Dashboard or the API to create lists.": true,
+      "Enter a name for the list": true,
+      "Select the type of list to create.": true,
+      "Click Add to save your new list.": true
+    }
+  },
+  "https://docs.stripe.com/rate-limits": {
+    "status": 200,
+    "checked": "2026-10-01",
+    "quotes": {
+      "25 requests per second": true
+    }
+  },
+  "https://docs.stripe.com/refunds": {
+    "status": 200,
+    "checked": "2026-09-30"
+  },
+  "https://docs.stripe.com/search": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "Substring match operator (substrings must be a minimum of 3 characters)": true
+    }
+  },
+  "https://docs.stripe.com/testing": {
+    "status": 200,
+    "checked": "2026-10-02",
+    "quotes": {
+      "Generic decline 4000 0000 0000 0002": true,
+      "This card requires authentication on all transactions, regardless of how the card is set up.": true
+    }
+  },
+  "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
+    }
+  },
+  "https://github.com/stripe/stripe-mock/issues/31": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "Unrecognized request URL (GET: /v1/test).": true
+    }
+  }
+}

package/src/cli.ts

@@ -1,36 +1,19 @@
-#!/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.
 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,29 @@
+// 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';
+
+/** 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,32 @@
+// 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/checkout.ts

@@ -0,0 +1,39 @@
+// 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,49 @@
+// 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 surface from '../generated/surface.gen.json' with { type: 'json' };
+
+export type Row = Record<string, unknown>;
+
+/** 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;
+
+/** 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` });
+
+
+
+
+/** 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,
+  };
+}
+
+
+
+/** 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 } } };
+}

package/src/engine/connect.ts

@@ -0,0 +1,106 @@
+// Connect semantics: connected accounts (and the platform's own account), their persons,
+// capabilities, external (payout) accounts, login links, onboarding links and embedded-component
+// sessions. A new connected account is not yet active: charges and payouts are off and its
+// requirements are outstanding, as on Stripe before onboarding. Account retrieve and delete and
+// the person list are the derived core's.
+import { accountRequirements, accountSettings, PLATFORM_ACCOUNT_ID } from './stripe.ts';
+import { currentlyDue, kindOf } from './onboarding.ts';
+import { externalList, type Row } from './common.ts';
+// the platform's own account: stored once it is written, otherwise Stripe's default. It "controls itself" (controller
+// type `account`, docs.stripe.com/api/accounts/object), is fully onboarded with nothing due, and takes card payments
+// and transfers. Where the documentation stops and the twin decides: it was created as the World began (2026-01-01),
+// and its bank account, which its automatic payouts reach, is not modelled, so it lists none.
+export const PLATFORM_CREATED = 1_767_225_600;
+/** The platform's own account as Stripe's default has it, before anything is written to it. */
+export const platformAccountDefault = (): Row => ({
+  object: 'account', id: PLATFORM_ACCOUNT_ID, type: 'standard', country: 'US', default_currency: 'usd', created: PLATFORM_CREATED,
+  charges_enabled: true, payouts_enabled: true, details_submitted: true, email: null, metadata: {},
+  capabilities: { card_payments: 'active', transfers: 'active' }, controller: { type: 'account' },
+  requirements: { alternatives: [], current_deadline: null, currently_due: [], disabled_reason: null, errors: [], eventually_due: [], past_due: [], pending_verification: [] },
+  future_requirements: { alternatives: [], current_deadline: null, currently_due: [], disabled_reason: null, errors: [], eventually_due: [], past_due: [], pending_verification: [] },
+  external_accounts: externalList(PLATFORM_ACCOUNT_ID, []), tos_acceptance: { date: null, ip: null, user_agent: null }, business_profile: {},
+  settings: accountSettings(undefined), livemode: false,
+});
+
+/** A new Express account owes what its hosted onboarding will ask for (screens/connect-onboarding.tsx; the US sets
+ *  docs.stripe.com/connect/required-verification-information lists), or, where the twin does not model the set, the
+ *  generic list. */
+export function expressRequirements(params: Row): Row {
+  const kind = kindOf({ country: params.country ?? 'US', business_type: params.business_type ?? 'individual' });
+  const base = accountRequirements();
+  return kind ? { ...base, currently_due: currentlyDue(kind), eventually_due: currentlyDue(kind) } : base;
+}
+
+/** The controller an account made with a `type` has: "Each of the three account types maps to values in the
+ *  `controller` hash", Standard to losses.payments `stripe`, fees.payer `account`, requirement_collection `stripe` and
+ *  a `full` dashboard, Express to `application`, `application_express`, `stripe` and `express`, Custom to
+ *  `application`, `application_custom`, `application` and `none`; each "type": "application", "is_controller": true
+ *  (docs.stripe.com/connect/migrate-to-controller-properties). */
+export function controllerOf(type: string): Row {
+  const [losses, payer, collection, dashboard] = type === 'express' ? ['application', 'application_express', 'stripe', 'express']
+    : type === 'custom' ? ['application', 'application_custom', 'application', 'none'] : ['stripe', 'account', 'stripe', 'full'];
+  return { type: 'application', is_controller: true, losses: { payments: losses }, fees: { payer }, requirement_collection: collection, stripe_dashboard: { type: dashboard } };
+}
+
+/** What a Custom account still owes, from what the platform has given for it, as Stripe's requirements endpoint lists it
+ *  for a US account with no Stripe Dashboard and the full service agreement
+ *  (docs.stripe.com/_endpoint/get-requirements-for-setups, the data behind
+ *  docs.stripe.com/connect/required-verification-information). With transfers alone, a company owes business_profile.url,
+ *  company.name, an external account and tos_acceptance.date and .ip at once (capability_limit_amount -1: paused until
+ *  given) and company.tax_id before $3,000 of payouts (payout_limit_amount 300000); an individual owes the url, its
+ *  first and last name, the bank account and the terms at once, and its date of birth and ssn_last_4 before $3,000 of
+ *  payouts. Requesting card_payments adds business_profile.mcc and the entity's address at once (and an individual's
+ *  email and ssn_last_4). A company with card_payments owes, at once, business_profile.mcc, its address, that its owners
+ *  are provided, each owner's name and email, and its representative's name, email, address, title and ssn_last_4; and
+ *  in time its phone, its statement descriptor and its representative's date of birth and phone (the endpoint's answer
+ *  for US / dashboard none / full terms / company / card_payments and transfers, saved in scratch as
+ *  req-custom-company-cards-transfers.json: capability_limit_amount -1 for the first, none for the second). The
+ *  representative and the owners are the account's persons (relationship.representative, relationship.owner).
+ *  Where the documentation stops and the twin decides: what has no limit, or is owed before $3,000 of payouts, is
+ *  eventually_due and blocks nothing (the twin keeps no payout total against it); an owner field is met when every
+ *  person marked owner has it (none marked: met). */
+export const at_path = (a: Row, path: string): unknown => path.split('.').reduce<unknown>((v, k) => (v && typeof v === 'object' ? (v as Row)[k] : undefined), a);
+export const CARD_COMPANY_NOW = ['business_profile.mcc', 'company.address.line1', 'company.address.city', 'company.address.state', 'company.address.postal_code', 'company.owners_provided', 'owners.first_name', 'owners.last_name', 'owners.email', 'representative.first_name', 'representative.last_name', 'representative.email', 'representative.address.line1', 'representative.address.city', 'representative.address.state', 'representative.address.postal_code', 'representative.relationship.title', 'representative.ssn_last_4'];
+export const CARD_COMPANY_LATER = ['company.phone', 'settings.payments.statement_descriptor', 'representative.dob.day', 'representative.dob.month', 'representative.dob.year', 'representative.phone'];
+export const CARD_INDIVIDUAL_NOW = ['business_profile.mcc', 'individual.address.line1', 'individual.address.city', 'individual.address.state', 'individual.address.postal_code', 'individual.email', 'individual.ssn_last_4'];
+export const personHas = (p: Row, field: string): boolean => {
+  if (field === 'ssn_last_4') return p.ssn_last_4_provided === true;
+  const v = at_path(p, field);
+  return v !== undefined && v !== null && v !== '';
+};
+export const met = (a: Row, bank: boolean, field: string, persons: Row[] = []): boolean => {
+  if (field === 'external_account') return bank;
+  if (field.startsWith('representative.')) {
+    const rep = persons.find((p) => (p.relationship as Row | undefined)?.representative === true);
+    return !!rep && personHas(rep, field.slice('representative.'.length));
+  }
+  if (field.startsWith('owners.')) return persons.filter((p) => (p.relationship as Row | undefined)?.owner === true).every((p) => personHas(p, field.slice('owners.'.length)));
+  if (field === 'company.tax_id') return at_path(a, 'company.tax_id_provided') === true;
+  if (field === 'individual.ssn_last_4') return at_path(a, 'individual.ssn_last_4_provided') === true;
+  const v = at_path(a, field);
+  return v !== undefined && v !== null && v !== '';
+};
+export function customRequirements(a: Row, bank: boolean, persons: Row[] = []): { now: string[]; later: string[] } {
+  const company = a.business_type === 'company';
+  const cards = Object.keys((a.capabilities as Row | undefined) ?? {}).includes('card_payments');
+  const now = ['business_profile.url', ...(company ? ['company.name'] : ['individual.first_name', 'individual.last_name']), 'external_account', 'tos_acceptance.date', 'tos_acceptance.ip'];
+  if (cards) now.push(...(company ? CARD_COMPANY_NOW : CARD_INDIVIDUAL_NOW));
+  const later = [...(company ? ['company.tax_id'] : ['individual.dob.day', 'individual.dob.month', 'individual.dob.year', 'individual.ssn_last_4']), ...(cards && company ? CARD_COMPANY_LATER : [])].filter((f) => !now.includes(f));
+  return { now: now.filter((f) => !met(a, bank, f, persons)), later: later.filter((f) => !met(a, bank, f, persons)) };
+}
+
+/** A request's company or individual as Stripe keeps it: a tax id or SSN given is kept only as provided (the Account
+ *  object answers company.tax_id_provided and individual.ssn_last_4_provided, never the numbers;
+ *  docs.stripe.com/api/accounts/object). */
+export function keptKyc(params: Row): Row {
+  const out: Row = { ...params };
+  if (params.company && typeof params.company === 'object') {
+    const { tax_id, ...company } = params.company as Row;
+    out.company = { ...company, ...(tax_id !== undefined && tax_id !== '' ? { tax_id_provided: true } : {}) };
+  }
+  if (params.individual && typeof params.individual === 'object') {
+    const { ssn_last_4, id_number, ...individual } = params.individual as Row;
+    out.individual = { ...individual, ...(ssn_last_4 !== undefined && ssn_last_4 !== '' ? { ssn_last_4_provided: true } : {}), ...(id_number !== undefined && id_number !== '' ? { id_number_provided: true } : {}) };
+  }
+  return out;
+}

package/src/engine/customers.ts

@@ -0,0 +1,10 @@
+// Customer semantics: the customer and what hangs off it (tax ids, the credit-balance ledger, the
+// cash balance, legacy sources, attached payment methods) and the top-level Source object. List,
+// update and delete of a customer, retrieve of a Source and the flat tax-id list are the derived core's.
+import { invoicePrefix } from './invoices.ts';
+import type { Row } from './common.ts';
+/** What a new customer answers before any invoice: its invoice_prefix and a next_invoice_sequence of 1, a zero balance,
+ *  no metadata (docs.stripe.com/api/customers/object). */
+export const newCustomer = (id: string): Row => ({ invoice_prefix: invoicePrefix(id), next_invoice_sequence: 1, balance: 0, metadata: {}, invoice_settings: {} });
+
+// ── tax ids: a customer's, keyed under it; `type` and `value` are required ──