@volter/twin-stripe 2.0.38 → 3.0.0

package/src/{stripe-twin.ts → engine/stripe.ts}

@@ -1,28 +1,18 @@
-// Stripe twin REQUEST HANDLER — the canonical Stripe API surface for the twin and
-// the QA stack's authoritative Stripe (it replaced the old hand-made in-process
-// mock). Contract: handleStripeTwinRequest({method, path, body, mode}) -> {status,
-// body}. The whole point: this is backed by the event/action-log kernel and its
-// response SHAPES are conformant to real Stripe (see stripe-conformance), instead
-// of being invented — so the SDK/API call shapes the app relies on actually match
-// Stripe. HTTP wrapper: stripe-server.ts → createStripeTwinServer.
-//
-// State lives in the action log (R18): writes are local actions, reads are the
-// projection. No real Stripe is ever called.
-import { applyTwinWrite } from '@volter/world-core';
-import { projectResources } from '@volter/world-core';
-import { createStripeTwinFetch } from './stripe-server.ts';
-import { emitStripeEvent, eventTypeFor, type StripeWebhookTarget } from './stripe-events.ts';
-import { SERVED_VERSION } from './stripe-version.ts';
-import { planOf } from './semantics/plans.ts';
-import { platformAccountDefault } from './semantics/connect.ts';
-import { OAUTH_CONNECTIONS } from './stripe-shared.ts';
-
-const SERVICE = 'stripe';
+// Stripe's own computation that its handlers share (docs/contributing/architecture.md, "Pack layout": the engine): money
+// and its declines, 3-D Secure and micro-deposits, the list page and the search grammar, a subscription's items, billing
+// intervals and discounts, Issuing's spending controls, a payment method's sub-object, a Connect account's settings and a
+// Checkout Session's line items. None of it reads or writes state: a caller hands it what it looked up (FindStored).
+import { ownFields, type TwinResource } from '@volter/world-core';
+import { SERVED_VERSION } from './version.ts';
 
-export type StripeRequest = { method: string; path: string; body?: string; occurredAt?: string; root?: string; readOnly?: boolean; idempotencyKey?: string; apiVersion?: string; stripeAccount?: string };
 export type StripeResponse = { status: number; body: unknown };
 
-// The Stripe API version a request that pins none is served in: the vendored spec's (stripe-version.ts renders
+/** Stripe's error body: an invalid_request_error with the message, and the code when there is one. */
+export function err(message: string, status = 404, code?: string): StripeResponse {
+  return { status, body: { error: { type: 'invalid_request_error', message, ...(code ? { code } : {}) } } };
+}
+
+// The Stripe API version a request that pins none is served in: the vendored spec's (./version.ts renders
 // every answer in it). A request may override it via the `Stripe-Version` header (apiVersion);
 // the value is echoed onto every event the request produces, exactly like real Stripe,
 // whose stored Event.api_version reflects the version in force when the event was created.
@@ -34,63 +24,6 @@ export function isValidApiVersion(v: string): boolean {
   return API_VERSION_RE.test(v);
 }
 
-// resource type → id prefix (Stripe's conventions).
-const PREFIX: Record<string, string> = {
-  charge: 'ch', customer: 'cus', payment_intent: 'pi', setup_intent: 'seti', payment_method: 'pm',
-  subscription: 'sub', price: 'price', product: 'prod', invoice: 'in', invoiceitem: 'ii',
-  refund: 're', verification_session: 'vs', ephemeral_key: 'ephkey', file_link: 'link',
-  dispute: 'dp', payout: 'po', balance_transaction: 'txn', event: 'evt',
-  checkout_session: 'cs', billing_portal_session: 'bps', billing_portal_configuration: 'bpc',
-  account: 'acct', transfer: 'tr',
-  tax_rate: 'txr', tax_calculation: 'taxcalc', tax_registration: 'taxreg',
-  credit_note: 'cn', tax_id: 'txi', customer_balance_transaction: 'cbtxn',
-  coupon: 'coupon', promotion_code: 'promo', payment_link: 'plink', quote: 'qt',
-  webhook_endpoint: 'we',
-  subscription_schedule: 'sub_sched', billing_meter: 'mtr', billing_meter_event: 'mtr_evt',
-  usage_record: 'mbur', test_clock: 'clock',
-  token: 'tok', mandate: 'mandate', application_fee: 'fee', fee_refund: 'fr',
-  transfer_reversal: 'trr', account_link: 'acctlink', person: 'person',
-  external_account: 'ba', file: 'file',
-  subscription_item: 'si', tax_transaction: 'tax', radar_review: 'prv',
-  radar_value_list: 'rsl', radar_value_list_item: 'rsli', radar_rule: 'rule',
-  // Issuing family (vendor-faithful Stripe id prefixes).
-  issuing_cardholder: 'ich', issuing_card: 'ic', issuing_authorization: 'iauth',
-  issuing_transaction: 'ipi', issuing_dispute: 'idp',
-  // Terminal family.
-  terminal_location: 'tml', terminal_reader: 'tmr', terminal_configuration: 'tmc',
-  // Top-ups, identity reports, reporting runs.
-  topup: 'tu', verification_report: 'vr', report_run: 'frr',
-  // Customer cash balance ledger + legacy sources.
-  cash_balance_transaction: 'ccsbtxn', source: 'src',
-  // Billing: prepaid credit grants + usage alerts.
-  credit_grant: 'credgr', billing_alert: 'alert',
-  // Entitlements: account-level features + per-customer active entitlements.
-  entitlements_feature: 'feat', active_entitlement: 'ent',
-  // Connect: embedded account sessions + apps secret store.
-  account_session: 'accts', apps_secret: 'apmc',
-  // Issuing: network tokens + card personalization designs.
-  issuing_token: 'iss_tok', personalization_design: 'pd',
-  // Treasury: financial accounts + money-movement flows + ledger.
-  financial_account: 'fa',
-  outbound_payment: 'obp', outbound_transfer: 'obt', inbound_transfer: 'ibt',
-  received_credit: 'rc', received_debit: 'rd',
-  treasury_transaction: 'trxn', treasury_transaction_entry: 'trxne',
-  // Climate (carbon removal): orders. (products/suppliers are a fixed read-only catalog.)
-  climate_order: 'climorder',
-  // Financial Connections: sessions + linked accounts + account transactions.
-  fc_session: 'fcsess', fc_account: 'fca', fc_transaction: 'fctxn',
-  // Forwarding (PAN forwarding) requests + Crypto onramp sessions.
-  forwarding_request: 'fwdr', onramp_session: 'cos',
-  // Entitlements: a product↔feature grant.
-  product_feature: 'prodft',
-  // Tax settings singleton.
-  tax_settings: 'taxset',
-};
-
-function err(message: string, status = 404, code?: string): StripeResponse {
-  return { status, body: { error: { type: status === 404 ? 'invalid_request_error' : 'invalid_request_error', message, ...(code ? { code } : {}) } } };
-}
-
 // Fidelity: real Stripe rejects a charge/payment_intent missing or with a non-positive
 // amount, or missing currency, before any state change.
 export function validateMoney(params: Record<string, unknown>): StripeResponse | null {
@@ -188,7 +121,7 @@ function resolveCardRef(params: Record<string, unknown>): string | undefined {
 // that references it purely by id (the normal shape for a saved-card/off-session charge,
 // e.g. an invoice retry) could never reproduce the decline.
 /** A stored subject by stored type and id, in the pack's view (tombstones included): how the
- *  semantics hand these helpers the tree they read (semantics/shared.ts `finder`). */
+ *  semantics hand these helpers the tree they read (./common.ts `finder`). */
 export type FindStored = (storedType: string, id: string) => Record<string, unknown> | undefined;
 
 export function declineFor(find: FindStored, ...paramSets: Array<Record<string, unknown>>): DeclineOutcome | null | undefined {
@@ -304,19 +237,6 @@ export function cardError(outcome: DeclineOutcome, attach: { charge?: string; pa
 export function nowUnix(occurredAt?: string): number {
   return Math.floor((occurredAt ? Date.parse(occurredAt) : 0) / 1000);
 }
-
-function rows(type: string, root?: string) {
-  return projectResources(SERVICE, root).filter((r) => r.type === type);
-}
-function nextId(type: string, root?: string): string {
-  const prefix = PREFIX[type] ?? type;
-  let max = 0;
-  for (const r of rows(type, root)) {
-    const m = new RegExp(`^${prefix}_twin_(\\d+)$`).exec(r.id);
-    if (m) max = Math.max(max, Number(m[1]));
-  }
-  return `${prefix}_twin_${max + 1}`;
-}
 // Real Stripe embeds the resource's OWN id inside its client_secret (format
 // `<id>_secret_<random>`) — Stripe.js's confirmPayment/confirmSetup parse the id back
 // out of the client_secret (splitting on `_secret`) to build the same-origin confirm
@@ -324,25 +244,14 @@ function nextId(type: string, root?: string): string {
 // A secret that doesn't carry the real id breaks that round trip: a browser Stripe.js
 // call would try to confirm a resource whose id it invented from the string
 // (`'pi_twin_secret'` → `'pi_twin'`, which was never actually created). Every PI/SI a
-// caller might confirm CLIENT-SIDE (real Stripe.js — see the QA proxy's browserRouting
-// in packages/twin/stripe/src/index.ts) must mint a secret this way.
-export function mintClientSecret(id: string): string {
-  return `${id}_secret_twin`;
-}
-// Stripe resource view: inject `object` + `id`, drop kernel meta.
-//
-// The kernel reserves the field name `type` as its resource-type discriminator, so a
-// stored vendor field literally named `type` is dropped on projection (see actions.ts
-// META). Several Stripe objects (payout.type, balance_transaction.type, event.type,
-// dispute uses `reason` not `type`) DO have a vendor `type`, so the create path stashes
-// it under the reserved key `_stripe_type` (a `_`-prefixed twin-internal field that the
-// conformance gate exempts) and we restore it to `type` here. This keeps the vendor
-// field faithful without touching the kernel discriminator. (price.type stays a declared
-// deviation — its create path predates this and one_time/recurring is derivable.)
-// A few Stripe objects have a DOTTED `object` value that differs from the twin's
-// (identifier-safe) resource type — e.g. type 'checkout_session' emits object
-// 'checkout.session'. Map them on emit so the `object` field is vendor-faithful.
-// (stripe-conformance.ts emitted() mirrors this map.)
+// caller might confirm CLIENT-SIDE (real Stripe.js) must mint a secret this way.
+/** An intent's client secret: its id, `_secret_`, and a secret the World holds for it (ctx.secret, passed in), so no one
+ *  derives it from the intent's id; Stripe.js confirms an intent with it and the publishable key. */
+export function mintClientSecret(id: string, secret: string): string {
+  return `${id}_secret_${secret.replace(/[^A-Za-z0-9]/g, '').slice(0, 24)}`;
+}
+// A few Stripe objects have a DOTTED `object` value that differs from the twin's (identifier-safe) resource type: type
+// 'checkout_session' is object 'checkout.session'.
 export const OBJECT_NAME: Record<string, string> = {
   checkout_session: 'checkout.session',
   billing_portal_session: 'billing_portal.session',
@@ -403,17 +312,11 @@ export const OBJECT_NAME: Record<string, string> = {
   // Forwarding + Crypto onramp.
   forwarding_request: 'forwarding.request', onramp_session: 'crypto.onramp_session',
 };
-// Exported for the pack's own modules that must render the SAME vendor view of a stored
-// resource (stripe-emit.ts synthesizes `data.object` for emitted events from it) — one
-// projection, no drift. Not a public API for consumers.
-export function view(type: string, r: Record<string, unknown>): Record<string, unknown> {
-  // `_subscription_data` is twin-internal (a Checkout Session's create-only
-  // subscription_data, held for the completion transition to copy onto the created
-  // subscription) — real Stripe never returns it on the Session, so strip it here.
-  const { type: _t, updatedAt: _u, _stripe_type, _subscription_data, ...rest } = r;
-  const out: Record<string, unknown> = { object: OBJECT_NAME[type] ?? type, ...rest, id: r.id };
-  if (_stripe_type !== undefined) out.type = _stripe_type;
-  return out;
+/** A stored row as Stripe answers it: its `object`, its own fields (the vendor's `type` among them, which the tree's
+ *  shadows: world-core ownFields) without the twin's `_` bookkeeping, and its id. */
+export function view(type: string, r: TwinResource): Record<string, unknown> {
+  const own = Object.fromEntries(Object.entries(ownFields(r)).filter(([k]) => !k.startsWith('_') && k !== 'updatedAt'));
+  return { object: OBJECT_NAME[type] ?? type, ...own, id: r.id };
 }
 // Real Stripe list pagination. Honors limit (default 10, max 100, min 1),
 // starting_after (cursor: exclude up to & including that id), ending_before
@@ -448,101 +351,6 @@ export function paginate(items: Array<Record<string, unknown>>, params: Record<s
   const page = items.slice(from, from + limit);
   return { page, hasMore: from + limit < items.length };
 }
-
-async function writeResource(
-  type: string,
-  id: string,
-  fields: Record<string, unknown>,
-  op: string,
-  root?: string,
-  occurredAt?: string,
-  apiVersion?: string,
-): Promise<Record<string, unknown>> {
-  const { resource } = await applyTwinWrite(SERVICE, { operation: op, subjectType: type, subjectId: id, fields, ...(occurredAt ? { occurredAt } : {}), actor: { kind: 'agent' } }, root);
-  const out = view(type, resource);
-  await afterStripeWrite(type, op, out, root, occurredAt, apiVersion);
-  return out;
-}
-
-/** What follows every stored Stripe write: the webhook for the state change and the stored Event
- *  the Events API lists. The derived pack's write hook (manifest.ts) is this same function. */
-export async function afterStripeWrite(type: string, op: string, out: Record<string, unknown>, root?: string, occurredAt?: string, apiVersion?: string, stripeAccount?: string): Promise<void> {
-  // R17: fire the Stripe event/webhook for this state change (no-op if none registered). An event is a connected
-  // account's when its resource lives in one (a request made as it, the Stripe-Account header) or is a connected
-  // account itself (its account.updated): docs.stripe.com/connect/webhooks, "Connected accounts" scope.
-  // A write with no header is still a connected account's when the row it wrote is kept on that account's books (a
-  // payout or ledger entry's `_account`: an automatic payout time makes for it, semantics/balance.ts).
-  const account = stripeAccount ?? (type === 'account' && typeof out.id === 'string' && out.id !== PLATFORM_ACCOUNT_ID ? out.id : undefined) ?? ownerOf(type, out.id, root);
-  // a plan is stored as the recurring price it is; its own events carry the plan object (semantics/plans.ts)
-  const object = type === 'price' && op.startsWith('plan.') ? planOf(out) : out;
-  // events.full_types: the Stripe `event` envelope for this state change is also stored, so it appears in GET
-  // /v1/events (independent of webhook registration), exactly like real Stripe's stored Events API. Skip when the op
-  // has no mapped event type, and never for event/_idempotency writes themselves (no recursion / no meta-events). The
-  // event's id is minted once and is the delivered webhook's id and the stored event's alike: one event, one id, which
-  // a consumer deduplicates by and retrieves by.
-  const eventType = type !== 'event' && type !== IDEMPOTENCY_TYPE ? eventTypeFor(op) : null;
-  const id = eventType ? nextStripeEventId(root) : undefined;
-  // stored before it is delivered: a consumer that looks its webhook's event up finds it
-  if (eventType) await persistStripeEvent(eventType, object, root, occurredAt, apiVersion, account, id);
-  // a connected account whose OAuth connection was revoked "can't be accessed by your platform" (docs.stripe.com/connect/
-  // oauth-reference): its events (a payout time makes, a renewal) are its own and no longer reach the platform's Connect
-  // endpoints, except the account.application.deauthorized that says so (screens/connect-oauth.tsx)
-  if (account && eventType !== 'account.application.deauthorized' && rows(OAUTH_CONNECTIONS, root).some((c) => (c as Record<string, unknown>).id === account && (c as Record<string, unknown>).revoked === true)) return;
-  await emitStripeEvent(op, object, { occurredAt: occurredAt ?? '1970-01-01T00:00:00.000Z', endpoints: webhookTargets(root), ...(account ? { account } : {}), ...(id ? { id } : {}) });
-}
-
-/** Event numbers taken in this process, per root, before their events are stored: two writes whose events overlap
- *  (a webhook handler calling back in, concurrent requests) never take the same number. */
-const takenEventNumbers = new Map<string, number>();
-/** The id the World's next event takes: its place in the World's events, so it is deterministic and never repeats
- *  within a World (a Balance has no id of its own, so nothing about the object can tell two events apart). The number
- *  is taken synchronously — the count of stored events, or the last number taken, whichever is higher. */
-export function nextStripeEventId(root?: string): string {
-  const key = root ?? '';
-  const n = Math.max(rows('event', root).length, takenEventNumbers.get(key) ?? 0) + 1;
-  takenEventNumbers.set(key, n);
-  return `evt_twin_${n}`;
-}
-
-/** The connected account whose books a stored row is kept on (its `_account`), if any. */
-function ownerOf(type: string, id: unknown, root?: string): string | undefined {
-  if (typeof id !== 'string') return undefined;
-  const owner = (rows(type, root).find((r) => r.id === id) as Record<string, unknown> | undefined)?._account;
-  return typeof owner === 'string' ? owner : undefined;
-}
-
-// Persist a Stripe `event` resource (object 'event') for a state change into the action
-// log so the Events API (GET /v1/events) lists/retrieves it. Deterministic id derived
-// from the per-root event count; data.object carries the resource snapshot. Written via
-// applyTwinWrite directly (NOT writeResource) to avoid re-emitting an event for the event.
-export async function persistStripeEvent(eventType: string, resource: Record<string, unknown>, root?: string, occurredAt?: string, apiVersion?: string, account?: string, id?: string): Promise<void> {
-  const eventId = id ?? nextStripeEventId(root);
-  const fields = {
-    object: 'event', _stripe_type: eventType, created: nowUnix(occurredAt), livemode: false,
-    pending_webhooks: 0, api_version: apiVersion && isValidApiVersion(apiVersion) ? apiVersion : TWIN_API_VERSION,
-    request: { id: null, idempotency_key: null },
-    data: { object: resource },
-    // a connected account's event names it, and is listed to requests made as it (semantics/webhook-endpoints.ts)
-    ...(account ? { account } : {}),
-  };
-  await applyTwinWrite(SERVICE, { operation: 'event.record', subjectType: 'event', subjectId: eventId, fields, ...(occurredAt ? { occurredAt } : {}), actor: { kind: 'system' } }, root);
-}
-function getOne(type: string, id: string, root?: string): Record<string, unknown> | undefined {
-  const r = rows(type, root).find((x) => x.id === id);
-  return r ? view(type, r) : undefined;
-}
-
-// Stripe list order: newest first by `created` (or `date` for invoiceitem), ties
-// broken by id descending so the order is stable for cursor pagination.
-/** The World's live webhook endpoints, from its tree: delivery survives a restart and belongs to
- *  this World alone. A disabled or deleted endpoint receives nothing, like the vendor. */
-function webhookTargets(root: string | undefined): StripeWebhookTarget[] {
-  // `connect` is a create parameter the endpoint object does not answer, so it is read off the stored row
-  return rows('webhook_endpoint', root)
-    .map((r) => ({ w: view('webhook_endpoint', r), connect: asBool((r as Record<string, unknown>).connect) }))
-    .filter(({ w }) => !w.deleted && w.status !== 'disabled' && typeof w.url === 'string')
-    .map(({ w, connect }) => ({ url: String(w.url), ...(typeof w.secret === 'string' ? { secret: w.secret } : {}), ...(Array.isArray(w.enabled_events) ? { enabledEvents: w.enabled_events.map(String) } : {}), connect }));
-}
 // Stripe's `active=true|false` filters arrive as strings/booleans; normalize.
 export function asBool(v: unknown): boolean {
   return v === true || v === 'true' || v === 1 || v === '1';
@@ -804,36 +612,15 @@ export function resolveTrial(params: Record<string, unknown>, at: number): { sta
   return undefined;
 }
 
-// Create a resource from form params, stamping object + id + created + the given
-// defaults. Only real Stripe field names are emitted (conformance-checked).
-// A vendor `type` field (a price's one_time or recurring, a payout's bank_account) always collides with the kernel's
-// row type, so it is stashed under `_stripe_type` and restored by view().
-export function stashVendorType(_type: string, fields: Record<string, unknown>): Record<string, unknown> {
-  if (!('type' in fields)) return fields;
-  const { type: vt, ...rest } = fields;
-  return { ...rest, _stripe_type: vt };
-}
-
-async function create(type: string, params: Record<string, unknown>, defaults: Record<string, unknown>, req: StripeRequest, opts: { timeField?: string } = {}): Promise<StripeResponse> {
-  // honor a caller-provided id (seeding uses the catalog's real prod_*/price_* ids);
-  // otherwise assign one. The id is identity, not a stored field.
-  const { id: providedId, ...rest } = params as { id?: unknown } & Record<string, unknown>;
-  const id = typeof providedId === 'string' && providedId ? providedId : nextId(type, req.root);
-  // Most Stripe objects stamp `created`; a few (invoiceitem) use a differently-named
-  // timestamp instead (`date`) and have NO `created` field — honor that, don't fabricate.
-  const fields = stashVendorType(type, { object: OBJECT_NAME[type] ?? type, [opts.timeField ?? 'created']: nowUnix(req.occurredAt), ...defaults, ...rest });
-  return { status: 200, body: await writeResource(type, id, fields, `${type}.create`, req.root, req.occurredAt, req.apiVersion) };
-}
-
 // ── ISSUING helpers: spending controls, real-time-auth shapes ─────────────────────────
 // Authorization.card is the FULL Card object in every vendor egress (API responses and
 // webhook payloads) — it is not expandable (stripe@22.3.0 Issuing.Authorization.card:
 // Stripe.Issuing.Card). The twin stores the id internally and embeds at the boundary;
 // cardholder stays an id string (expandable, unexpanded default). Caught live: the
 // issuing-bridge reads event.data.object.card.id and refused every twin presentment.
-export function embedIssuingAuthorizationCard(body: Record<string, unknown>, root?: string): Record<string, unknown> {
+export function embedIssuingAuthorizationCard(body: Record<string, unknown>, find: FindStored): Record<string, unknown> {
   if (typeof body.card === 'string') {
-    const cardRow = getOne('issuing_card', body.card, root);
+    const cardRow = find('issuing_card', body.card);
     if (cardRow !== undefined) body.card = cardRow;
   }
   return body;
@@ -1202,19 +989,6 @@ export function lineItemEntries(params: Record<string, unknown>): Array<Record<s
   return Array.isArray(li) ? (li.filter((x) => x && typeof x === 'object') as Array<Record<string, unknown>>) : [];
 }
 
-// ---- IDEMPOTENCY KEYS (vendor-faithful) ----
-// Real Stripe honors the `Idempotency-Key` header on POST: the first request with a
-// key executes and the (status + body) response is stored against the key; a replay
-// with the SAME key returns the SAME stored response WITHOUT re-applying the write.
-// We persist the stored response as an `_idempotency` resource in the action log
-// (per-root, so a fork has its own keyspace). `_idempotency` is a twin-internal type
-// (never served as a Stripe object), so it does not affect spec conformance.
-//
-// Note: real Stripe only persists idempotency for responses it considers "completed"
-// (2xx and most 4xx, including card 402s) and scopes the key to the account; here we
-// store every executed POST response (success and error alike), keyed per-root.
-const IDEMPOTENCY_TYPE = '_idempotency';
-
 // ── THE MONEY MODEL: a charge and the refunds taken out of it ──────────────────────────
 //
 // The rule this section exists to hold: A FACT RECORDED ON ONE MONEY OBJECT IS VISIBLE FROM
@@ -1237,75 +1011,6 @@ export function chargeDefaults(chargeId: string, amount: number, captured: boole
   };
 }
 
-/**
- * Public entry: honors the Idempotency-Key (replay → stored response, no re-write)
- * then delegates to the router. Only POSTs are idempotent (matches Stripe; GET/DELETE
- * pass straight through). A read-only twin never stores (it cannot write).
- */
-/** Stripe's API as one call: the request goes through the pack's own dispatch (the derived dispatch over
- *  its semantics, its derived core and the hand-written routes below), so a caller that holds no
- *  HTTP server reaches exactly what an SDK does. `occurredAt` pins the World instant. */
-export async function handleStripeTwinRequest(req: StripeRequest): Promise<StripeResponse> {
-  const twin = createStripeTwinFetch({ ...(req.root !== undefined ? { root: req.root } : {}), readOnly: req.readOnly ?? false, ...(req.occurredAt ? { clock: () => req.occurredAt! } : {}) });
-  const method = req.method.toUpperCase();
-  const headers: Record<string, string> = { 'content-type': 'application/x-www-form-urlencoded' };
-  if (req.idempotencyKey) headers['idempotency-key'] = req.idempotencyKey;
-  if (req.apiVersion !== undefined) headers['stripe-version'] = req.apiVersion;
-  if (req.stripeAccount) headers['stripe-account'] = req.stripeAccount;
-  // a GET carries its parameters in the query; a caller that handed them as a body keeps them
-  let path = req.path.startsWith('/') ? req.path : `/${req.path}`;
-  if ((method === 'GET' || method === 'HEAD') && req.body) path += (path.includes('?') ? '&' : '?') + req.body;
-  const response = await twin(new Request(`http://stripe.test${path}`, { method, headers, ...(method !== 'GET' && method !== 'HEAD' && req.body ? { body: req.body } : {}) }));
-  const text = await response.text();
-  return { status: response.status, body: text ? JSON.parse(text) : null };
-}
-
-/**
- * The twin's doors: what stands in for an act Stripe's API does not have, each under `/_twin/`. The
- * platform's own account settings (its payout schedule) change on Stripe's Dashboard, which has no API:
- * POST /_twin/account stands in for that page. Answers nothing for any other path.
- */
-export async function handleStripeDoor(req: StripeRequest, params: Record<string, unknown>): Promise<StripeResponse | undefined> {
-  const method = req.method.toUpperCase();
-  const path = (req.path.split('?')[0] ?? '/').replace(/\/+$/, '') || '/';
-  const seg = path.replace(/^\/+/, '').split('/');
-  if (seg[0] !== '_twin') return undefined;
-  if (req.readOnly) return err('twin is read-only; omit readOnly to accept writes', 405);
-  if (path === '/_twin/account' && method === 'POST') {
-    const ex = getOne('account', PLATFORM_ACCOUNT_ID, req.root);
-    const { type: _t, settings: rawSettings, business_profile: rawProfile, ...rest } = params as Record<string, unknown>;
-    // the platform's account is Stripe's default until the page first changes it (semantics/connect.ts, the same
-    // default GET /v1/account answers and the Public details page stores)
-    const fields = {
-      ...(ex ? {} : (({ id: _id, ...base }) => base)(platformAccountDefault())),
-      ...rest,
-      settings: accountSettings(rawSettings, ex?.settings as Record<string, unknown> | undefined),
-      // a hash is merged into what the account holds, as an update merges it (the name the Public details page saved stays)
-      ...(rawProfile && typeof rawProfile === 'object' ? { business_profile: { ...((ex?.business_profile as Record<string, unknown> | undefined) ?? {}), ...(rawProfile as Record<string, unknown>) } } : {}),
-    };
-    return { status: 200, body: await writeResource('account', PLATFORM_ACCOUNT_ID, stashVendorType('account', fields), 'account.update', req.root, req.occurredAt) };
-  }
-  // Issuing network tokens are minted by the card network when a cardholder adds the card to a
-  // phone's wallet (docs.stripe.com/issuing/cards/digital-wallets): there is no API create, and the
-  // act happens in the phone's wallet app, not on a Stripe page. POST /_twin/issuing/cards/:card/wallets
-  // stands in for that act ({wallet_provider, network}); the API reads the token and moves its status.
-  // Where the documentation stops and the twin decides: the network approves at once (the token is active).
-  if (seg[0] === '_twin' && seg[1] === 'issuing' && seg[2] === 'cards' && seg[3] && seg[4] === 'wallets' && seg.length === 5 && method === 'POST') {
-    const card = decodeURIComponent(seg[3]);
-    const c = getOne('issuing_card', card, req.root);
-    if (!c) return err(`No such card: '${card}'`, 400, 'resource_missing');
-    const wallet = typeof params.wallet_provider === 'string' && ['apple_pay', 'google_pay', 'samsung_pay'].includes(params.wallet_provider)
-      ? params.wallet_provider : 'apple_pay';
-    const network = typeof params.network === 'string' && ['visa', 'mastercard'].includes(params.network) ? params.network : 'visa';
-    const last4 = typeof c.last4 === 'string' ? c.last4 : '0000';
-    return create('issuing_token', { card, cardholder: typeof c.cardholder === 'string' ? c.cardholder : ((c.cardholder as Record<string, unknown> | undefined)?.id ?? null) }, {
-      status: 'active', wallet_provider: wallet, network, last4, livemode: false,
-      device_fingerprint: null, network_data: null, network_updated_at: nowUnix(req.occurredAt),
-    }, req);
-  }
-  return undefined;
-}
-
 // collection path segment → resource type, for the generic list of a collection Stripe does not
 // list at that path (the twin's test clocks, which Stripe lists under /v1/test_helpers).
 

package/src/engine/subscription-schedules.ts

@@ -0,0 +1,10 @@
+// Subscription schedule semantics: a schedule drives a subscription through phases (items for a
+// duration). One made for a customer starts its subscription at once on the first phase's items. Cancel and
+// release end it, the machine's moves in ../manifest.ts. List and update are the derived core's.
+//
+// Where the documentation stops and the twin decides: the subscription a schedule starts raises no first invoice.
+import { addBillingInterval } from './stripe.ts';
+
+export const SS = 'subscription_schedule';
+
+export type Interval = Parameters<typeof addBillingInterval>[1];

package/src/engine/subscriptions.ts

@@ -0,0 +1,40 @@
+// Subscription and SubscriptionItem semantics. A subscription is created with its items, its
+// billing period and, under payment_behavior=default_incomplete, its first invoice and that
+// invoice's PaymentIntent; canceling it is the machine's move in ../manifest.ts. Retrieve of a
+// subscription and of an item are the derived core's.
+import type { Row } from './common.ts';
+
+export const SUB = 'subscription';
+
+// pause_collection pauses billing (the subscription stays active; the paused event fires) and
+// clearing it resumes; cancel_at_period_end schedules or withdraws a cancel; a coupon replaces the
+// discount and an empty one clears it
+/** pause_collection pauses billing (the paused event fires) and clearing it resumes
+ *  (docs.stripe.com/billing/subscriptions/pause-payment); answers the event, or nothing for a value it does not take. */
+export function pauseCollection(pc: unknown, fields: Row): string | undefined {
+  const isClear = pc === '' || pc === null || (typeof pc === 'object' && pc !== null && Object.keys(pc as object).length === 0);
+  if (isClear) {
+    fields.pause_collection = null;
+    return 'customer.subscription.resumed';
+  }
+  if (!pc || typeof pc !== 'object') return undefined;
+  const p = pc as Row;
+  fields.pause_collection = { behavior: typeof p.behavior === 'string' ? p.behavior : 'void', resumes_at: p.resumes_at !== undefined ? Number(p.resumes_at) : null };
+  return 'customer.subscription.paused';
+}
+
+/** The longest trial Stripe takes: `trial_end` "Can be at most two years from `billing_cycle_anchor`"
+ *  (docs.stripe.com/api/subscriptions/update#update_subscription-trial_end); "The trial period must be 730 days (2 years)
+ *  or less" (docs.stripe.com/billing/subscriptions/trials/free-trials). */
+export const MAX_TRIAL = 730 * 86400;
+
+/** A trial moved to end at `end`, or a new one to `end` on a subscription out of its trial (applyTrialEnd). */
+export function movedTrial(sub: Row, fields: Row, end: number, now: number): undefined {
+  Object.assign(fields, {
+    status: 'trialing', trial_end: end, trial_start: sub.trial_start ?? now, billing_cycle_anchor: end,
+    current_period_end: end, ...(sub.status !== 'trialing' ? { current_period_start: now } : {}),
+  });
+  return undefined;
+}
+
+export const ITEM_ATTRIBUTES = new Set(['billing_thresholds', 'discounts', 'metadata', 'price', 'quantity', 'tax_rates']);

package/src/engine/tax.ts

@@ -0,0 +1,39 @@
+// Stripe Tax semantics: tax rates, the account's tax settings (a singleton), calculations,
+// registrations, and the transactions that commit a calculation or reverse one. A calculation's
+// tax comes from one flat default rate so its amounts are stable (Stripe derives it from the
+// customer's jurisdiction and the account's registrations). Rate, calculation, registration and
+// transaction retrieves and the registration list are the derived core's.
+import type { Row } from './common.ts';
+
+export const TWIN_TAX_RATE_PCT = 10;
+
+// ── settings: active once a head office is set; the answer has no id ──
+
+// the defaults' provider: "The tax calculation provider this account uses. Defaults to `stripe` when not using a
+// third-party provider" (the served spec's tax settings defaults); the head office's address answers each line, the
+// lines not given null (the served spec's address: each "(string, nullable)"; the settings page's example answers
+// line2 null)
+export const ADDRESS_LINES = ['city', 'country', 'line1', 'line2', 'postal_code', 'state'];
+export function settingsBody(stored: Row | undefined): Row {
+  const given = (stored?.head_office ?? null) as Row | null;
+  const address = given && typeof given.address === 'object' && given.address ? (given.address as Row) : undefined;
+  const headOffice = given ? { ...given, ...(address ? { address: Object.fromEntries(ADDRESS_LINES.map((k) => [k, address[k] ?? null])) } : {}) } : null;
+  const active = !!headOffice;
+  return {
+    object: 'tax.settings', livemode: false,
+    defaults: { provider: 'stripe', ...((stored?.defaults as Row) ?? { tax_behavior: null, tax_code: null }) }, head_office: headOffice,
+    status: active ? 'active' : 'pending',
+    status_details: active ? { active: {} } : { pending: { missing_fields: ['head_office'] } },
+  };
+}
+
+// ── transactions: committing a calculation, or reversing a transaction with negated amounts ──
+
+export const TX = 'tax.transaction';
+export const txLine = (id: string, i: number, l: Row, sign: 1 | -1, reversal: Row | null, type: string): Row => ({
+  object: 'tax.transaction_line_item', id: `tax_li_${id}_${i + 1}`,
+  amount: sign === 1 ? l.amount : -(Number(l.amount) || 0), amount_tax: sign === 1 ? l.amount_tax : -(Number(l.amount_tax) || 0),
+  reference: l.reference ?? null, tax_behavior: l.tax_behavior ?? 'exclusive', tax_code: l.tax_code ?? 'txcd_99999999',
+  quantity: l.quantity ?? 1, reversal, type, livemode: false, metadata: {},
+});
+export const linesOf = (holder: Row): Row[] => (holder.line_items as { data?: Row[] } | undefined)?.data ?? [];

package/src/engine/terminal.ts

@@ -0,0 +1,23 @@
+// Terminal and top-up semantics: in-person locations, readers (handed a PaymentIntent to process)
+// and their configurations, the reader SDK's connection tokens, and top-ups that fund the balance
+// (a test top-up succeeds at once; only a pending one cancels, the machine in ../manifest.ts). In test mode a
+// simulated reader is presented a card by a test helper: the PaymentIntent the reader is processing is paid with a
+// card_present payment method (succeeded, or requires_capture under manual capture) and the reader's action succeeds
+// (docs.stripe.com/terminal/references/testing#simulated-test-cards,
+// docs.stripe.com/api/terminal/readers/present_payment_method). Where the documentation stops and the twin decides:
+// the presented card is the simulated reader's default Visa, and the reader answers at once.
+// Lists and retrieves are the derived core's.
+
+export const LOC = 'terminal.location';
+export const READER = 'terminal.reader';
+export const CONF = 'terminal.configuration';
+
+// ── top-ups ──
+
+// a top-up adds money to the balance it names, through the ledger, once its funds arrive: "USA (USD) ACH Debit Transfer
+// 5 days" (docs.stripe.com/connect/top-ups), and to the Issuing balance alike: "Top-ups debit your bank account. Your
+// top-ups can take up to 5 business days to become available. While they're pending, they won't be added to your
+// Issuing balance" (docs.stripe.com/issuing/funding/balance). It is pending until its expected_availability_date, then
+// settled by settleTopups. Where the documentation stops and the twin decides: every top-up takes exactly five days,
+// whatever its currency and balance, and succeeds.
+export const TOPUP_DAYS = 5;

package/src/engine/test-clocks.ts

@@ -0,0 +1,11 @@
+// Test clock semantics. A test clock is Stripe's own door for a transition no API verb makes: the
+// passage of time. Advancing it moves the subscriptions of the clock's customers as a real clock tick does:
+// trials that ended end, and periods that ended renew (./renewals.ts advanceBilling). List, retrieve and delete are
+// the derived core's.
+
+export const CLOCK = 'test_helpers.test_clock';
+
+/** How long an advance takes: "it takes a few seconds to advance to the specified time"
+ *  (docs.stripe.com/billing/testing/test-clocks/api-advanced-usage). Where the documentation stops and the twin decides:
+ *  five seconds of World time from the advance. */
+export const ADVANCE_SECONDS = 5;

package/src/engine/tokens.ts

@@ -0,0 +1,22 @@
+// Token semantics: the older integrations' single-use tokens for a card, a bank account or PII. A
+// token carries only the safe fields of its instrument, never the card or account number. Retrieve
+// is the derived core's.
+import { paymentMethodSubObject } from './stripe.ts';
+import type { Row } from './common.ts';
+
+/** The Card object a card token carries, as the served spec's `card` describes it: its brand as a name ("Card brand.
+ *  Can be `American Express`, ... `MasterCard`, `UnionPay`, `Visa`, or `Unknown`"), the holder's name and address as
+ *  given ("Cardholder name"), and the CVC's check when one was given ("If a CVC was provided, results of the check:
+ *  pass, fail, unavailable, or unchecked"). Where the documentation stops and the twin decides: a test card's CVC passes. */
+export const BRAND_NAMES: Record<string, string> = { amex: 'American Express', cartes_bancaires: 'Cartes Bancaires', diners: 'Diners Club', discover: 'Discover', eftpos_au: 'Eftpos Australia', girocard: 'Girocard', jcb: 'JCB', mastercard: 'MasterCard', unionpay: 'UnionPay', visa: 'Visa' };
+export function legacyCard(id: string, card: Row): Row {
+  const pm = paymentMethodSubObject('card', { card }).card as Row;
+  const given = (k: string): unknown => (typeof card[k] === 'string' && card[k] !== '' ? card[k] : null);
+  return {
+    id, object: 'card', brand: BRAND_NAMES[String(pm.brand)] ?? 'Unknown', last4: pm.last4, exp_month: pm.exp_month, exp_year: pm.exp_year,
+    funding: pm.funding ?? 'credit', country: pm.country ?? null, fingerprint: pm.fingerprint ?? null, name: given('name'),
+    address_line1: given('address_line1'), address_line2: given('address_line2'), address_city: given('address_city'), address_state: given('address_state'),
+    address_zip: given('address_zip'), address_country: given('address_country'), address_line1_check: null, address_zip_check: null,
+    cvc_check: card.cvc !== undefined && card.cvc !== '' ? 'pass' : null, dynamic_last4: null, tokenization_method: null, metadata: {}, customer: null,
+  };
+}

package/src/engine/transfers.ts

@@ -0,0 +1,23 @@
+// Transfer and application-fee semantics: money the platform moves to a connected account and
+// claws back (reversals), and the platform's fee on a connected charge and its refunds. A
+// reversal or fee refund never exceeds what is left, and lands on its parent's totals and list.
+// A transfer goes only to an account whose transfers capability is active, comes out of the
+// platform's available balance, and lands in the destination's (docs.stripe.com/connect/separate-
+// charges-and-transfers); a reversal moves it back.
+// A transfer tied to a charge (`source_transaction`, "Transfer availability" in the same guide) "returns success
+// regardless of your available balance if the related charge hasn't settled yet", but "the funds don't become
+// available in the destination account until the funds from the associated charge are available"; a charge whose funds
+// are already available by the World's clock is no exception, and the transfer is held to the available balance as any
+// other. "The amount of the transfer must not exceed the amount of the source charge", several transfers may share one
+// charge while "the sum of the transfers doesn't exceed the source charge", and the charge's balance currency must
+// match. "If the source charge has a `transfer_group` value, Stripe assigns the same value to the transfer's
+// `transfer_group`. If it doesn't, then Stripe generates a string in the format `group_` plus the associated
+// PaymentIntent ID ... It assigns that string as the `transfer_group` for both the charge and the transfer."
+// Where the documentation stops and the twin decides: the sum from one charge counts each transfer less what was
+// reversed of it; a transfer_group the request names is kept only when the charge has none and no PaymentIntent to
+// name one after; an uncaptured charge (an authorization, docs silent) is refused as a source_transaction until it is
+// captured; the refusals' wording is the twin's.
+// Transfer list, retrieve and update and application-fee list and retrieve are the derived core's.
+import type { Row } from './common.ts';
+
+export const emptyList = (url: string): Row => ({ object: 'list', data: [], has_more: false, total_count: 0, url });