@volter/twin-stripe 2.0.38 → 3.0.1

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

@@ -1,28 +1,15 @@
-// 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';
+import { digest } from '@volter/world-core';
+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 +21,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 +118,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 {
@@ -237,8 +167,6 @@ export function threeDsNextAction(): Record<string, unknown> {
 // a `descriptor_code` (the test value `SM11AA`). We model that exact pair so the verify
 // can FAIL with the wrong amounts. The well-known token that triggers this flow:
 const MICRODEPOSIT_TOKENS = new Set(['pm_usBankAccount_requiresVerification', 'pm_us_bank_account']);
-const MICRODEPOSIT_AMOUNTS = [32, 45];
-const MICRODEPOSIT_DESCRIPTOR = 'SM11AA';
 export function requiresMicrodeposits(...paramSets: Array<Record<string, unknown>>): boolean {
   for (const params of paramSets) {
     const ref = resolveCardRef(params);
@@ -255,31 +183,6 @@ export function microdepositsNextAction(): Record<string, unknown> {
     },
   };
 }
-/** The two deposits' amounts as sent: the test values (docs.stripe.com/payments/ach-direct-debit/accept-a-payment). */
-function amountsMatch(params: Record<string, unknown>): boolean {
-  const got = (params.amounts as unknown[]).map((a) => Math.trunc(Number(a) || 0));
-  return got.length === 2 && got[0] === MICRODEPOSIT_AMOUNTS[0] && got[1] === MICRODEPOSIT_AMOUNTS[1];
-}
-/** The deposit's descriptor code as sent: the test value. */
-function descriptorMatches(params: Record<string, unknown>): boolean {
-  return String(params.descriptor_code) === MICRODEPOSIT_DESCRIPTOR;
-}
-/** Stripe's refusal of deposits that do not match what was sent. */
-function depositMismatch(byAmounts: boolean): StripeResponse {
-  return byAmounts
-    ? err('The amounts provided do not match the amounts that were sent to the bank account.', 400, 'payment_intent_microdeposit_verification_amounts_mismatch')
-    : err('The descriptor code provided does not match the one that was sent to the bank account.', 400, 'payment_intent_microdeposit_verification_descriptor_code_mismatch');
-}
-// Validate the submitted micro-deposit verification params against the modeled test values.
-// Returns a vendor 400 on missing/both/wrong inputs, or null when the verification matches.
-export function verifyMicrodeposits(params: Record<string, unknown>, _existing: Record<string, unknown>): StripeResponse | null {
-  const hasAmounts = Array.isArray(params.amounts);
-  const hasDescriptor = typeof params.descriptor_code === 'string' && params.descriptor_code !== '';
-  if (hasAmounts === hasDescriptor) return err('You must pass exactly one of `amounts` and `descriptor_code`.', 400, 'parameter_missing');
-  const matches = hasAmounts ? amountsMatch(params) : descriptorMatches(params);
-  return matches ? null : depositMismatch(hasAmounts);
-}
-
 // Build the real Stripe card-error envelope (HTTP 402). `param` is 'card' for card
 // errors; charge/payment_intent ids are attached when known so SDK error objects carry
 // them (Stripe does this for confirm/charge failures).
@@ -304,19 +207,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 +214,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 +282,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 +321,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';
@@ -556,7 +334,7 @@ export function asBool(v: unknown): boolean {
 // resource view. This is the vendor's OWN per-field semantics (A4: not a cross-vendor query
 // engine — it lives in the Stripe pack and speaks Stripe's language only). Unsupported
 // constructs cause the clause to not match (safe), never a fabricated hit.
-type SearchClause = { field: string; op: ':' | '>' | '<' | '>=' | '<='; value: string };
+type SearchClause = { field: string; op: ':' | '~' | '>' | '<' | '>=' | '<='; value: string };
 // Tokenize on top-level AND/OR (we treat the whole query as either all-AND or all-OR; mixed
 // precedence is uncommon in practice and Stripe groups with parens we don't model — kept simple).
 function parseSearchQuery(query: string): { clauses: SearchClause[]; disjunction: boolean } | null {
@@ -565,12 +343,13 @@ function parseSearchQuery(query: string): { clauses: SearchClause[]; disjunction
   const disjunction = / OR /i.test(trimmed) && !/ AND /i.test(trimmed);
   const parts = trimmed.split(disjunction ? / OR /i : / AND /i);
   const clauses: SearchClause[] = [];
-  const re = /^\s*([A-Za-z0-9_]+(?:\[[^\]]+\])?)\s*(>=|<=|>|<|:)\s*(.+?)\s*$/;
+  const re = /^\s*([A-Za-z0-9_]+(?:\[[^\]]+\])?)\s*(>=|<=|>|<|:|~)\s*(.+?)\s*$/;
   for (const part of parts) {
     const m = re.exec(part);
     if (!m) return null;
     let value = m[3]!.trim();
     if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) value = value.slice(1, -1);
+    if (m[2] === '~' && (!['email', 'name'].includes(m[1]!) || value.length < 3)) return null;
     clauses.push({ field: m[1]!, op: m[2] as SearchClause['op'], value });
   }
   return { clauses, disjunction };
@@ -588,22 +367,19 @@ function searchFieldValue(item: Record<string, unknown>, field: string): unknown
 }
 /** A search's numeric comparison other than `>=` (docs.stripe.com/search#search-query-language). */
 function otherComparison(op: string, a: number, n: number): boolean {
-  switch (op) {
-    case '>': return a > n;
-    case '<': return a < n;
-    case '<=': return a <= n;
-  }
-  return false;
+  return op === '>' ? a > n : op === '<' ? a < n : a <= n;
 }
 
 function evalSearchClause(item: Record<string, unknown>, c: SearchClause): boolean {
   const actual = searchFieldValue(item, c.field);
+  // source: https://docs.stripe.com/search "Substring match operator (substrings must be a minimum of 3 characters)"
+  if (c.op === '~') return actual != null && String(actual).toLowerCase().includes(c.value.toLowerCase());
   if (c.op === ':') {
     if (c.value === 'null') return actual === null || actual === undefined;
     // numeric exact when both look numeric; else string-equality (case-sensitive, like Stripe tokens)
     if (typeof actual === 'number' && /^-?\d+(\.\d+)?$/.test(c.value)) return actual === Number(c.value);
-    if (typeof actual === 'boolean') return String(actual) === c.value;
-    return String(actual) === c.value;
+    if (typeof actual === 'boolean') return String(actual).toLowerCase() === c.value.toLowerCase();
+    return String(actual).toLowerCase() === c.value.toLowerCase();
   }
   const n = Number(c.value);
   const a = Number(actual);
@@ -662,23 +438,6 @@ export function buildDiscount(coupon: Record<string, unknown>, customer: string,
   };
 }
 
-// The (price id, quantity) pairs a subscription bills, normalized across the shapes the
-// twin stores items in (the create form array items:[{price,quantity}], or the canonical
-// items:{data:[{price}]} list). Used to compute upcoming-invoice lines.
-export function subscriptionItemPairs(sub: Record<string, unknown>): Array<{ price: string; quantity: number }> {
-  const items = sub.items as { data?: unknown } | undefined;
-  const data = Array.isArray(items?.data) ? items!.data : Array.isArray(sub.items) ? (sub.items as unknown[]) : [];
-  const out: Array<{ price: string; quantity: number }> = [];
-  for (const it of data as Array<Record<string, unknown>>) {
-    const p = it?.price;
-    const id = typeof p === 'string' ? p : (p && typeof p === 'object' ? String((p as Record<string, unknown>).id ?? '') : '');
-    if (id) out.push({ price: id, quantity: Math.max(1, Math.trunc(Number(it.quantity) || 1)) });
-  }
-  // a bare `price` field (the connector's flattened shape) counts as one item.
-  if (out.length === 0 && typeof sub.price === 'string' && sub.price) out.push({ price: sub.price, quantity: 1 });
-  return out;
-}
-
 // The raw item entries a subscription/checkout-derived-subscription create sent,
 // normalized to an ordered array. The form reader already turns the bracket form
 // items[0][price]=… into an array of objects (see lineItemEntries() above for the
@@ -740,18 +499,13 @@ export function addBillingInterval(atUnix: number, interval: BillingInterval, co
 // response includes the actual items, mirroring what was requested.
 /** What a subscription item carries of its price: the Price itself and its plan view (a subscription item answers both,
  *  docs.stripe.com/api/subscription_items/object), by the price's id or an already-resolved Price. */
+// source: https://docs.stripe.com/api/plans/create "It replaces the Plans API and is backwards compatible to simplify your migration."
+// source: spec:/components/schemas/plan "amount_decimal"
+
 export function subscriptionItemPrice(p: unknown, find: FindStored): { price: Record<string, unknown> | string | null; plan: Record<string, unknown> | null } {
   const priceId = typeof p === 'string' ? p : (p && typeof p === 'object' ? String((p as Record<string, unknown>).id ?? '') : '');
   const price = priceId ? find('price', priceId) : undefined;
-  const recurring = price?.recurring as Record<string, unknown> | undefined;
-  const plan = price ? {
-    id: price.id, object: 'plan', active: price.active ?? true, amount: price.unit_amount ?? null,
-    amount_decimal: price.unit_amount_decimal ?? null, billing_scheme: price.billing_scheme ?? 'per_unit',
-    currency: price.currency ?? 'usd', interval: recurring?.interval ?? null,
-    interval_count: recurring?.interval_count ?? 1, livemode: false,
-    metadata: price.metadata ?? {}, nickname: price.nickname ?? null,
-    product: price.product ?? null, tiers_mode: price.tiers_mode ?? null, usage_type: 'licensed',
-  } : null;
+  const plan = price ? planView(price) : null;
   return { price: price ?? (priceId || null), plan };
 }
 
@@ -804,41 +558,6 @@ 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> {
-  if (typeof body.card === 'string') {
-    const cardRow = getOne('issuing_card', body.card, root);
-    if (cardRow !== undefined) body.card = cardRow;
-  }
-  return body;
-}
-
 // The closed interval set for spending_controls[spending_limits][][interval]
 // (stripe@22.3.0 Issuing/Cards.d.ts SpendingLimit.Interval — a documented closed enum).
 const SPENDING_LIMIT_INTERVALS = new Set(['all_time', 'daily', 'monthly', 'per_authorization', 'weekly', 'yearly']);
@@ -869,10 +588,10 @@ function controlsRefused(what: 'dictionary' | 'categories' | 'countries' | 'limi
 // Vendor rules enforced: interval must be in the closed enum; a spending limit amount is a
 // positive integer; allowed_categories "Cannot be set with blocked_categories" (and the
 // merchant-country pair likewise) — both restrictions verbatim from the SDK's field docs.
-export function normalizeSpendingControls(raw: unknown, currency: string | null): { controls?: Record<string, unknown>; error?: StripeResponse } {
+export function normalizeSpendingControls(raw: unknown, currency: string | null, previous?: Record<string, unknown>): { controls?: Record<string, unknown>; error?: StripeResponse } {
   if (raw === undefined) return {};
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return controlsRefused('dictionary');
-  const sc = raw as Record<string, unknown>;
+  const sc = { ...previous, ...(raw as Record<string, unknown>) };
   const strArr = (v: unknown): string[] | undefined => (Array.isArray(v) ? v.map(String) : undefined);
   const allowedCats = strArr(sc.allowed_categories);
   const blockedCats = strArr(sc.blocked_categories);
@@ -894,6 +613,9 @@ export function normalizeSpendingControls(raw: unknown, currency: string | null)
   const arrOrNull = (v: string[] | undefined) => (v === undefined ? undefined : v.length ? v : null);
   const controls: Record<string, unknown> = {
     ...emptySpendingControls(),
+    // source: spec:/paths/~1v1~1issuing~1cards~1{card}/post/requestBody/content/application~1x-www-form-urlencoded/schema/properties/spending_controls "Rules that control spending for this card."
+    // Keep every documented control, including allowed_card_presences and blocked_card_presences.
+    ...sc,
     spending_limits: limits,
     ...(limits.length ? { spending_limits_currency: typeof sc.spending_limits_currency === 'string' ? sc.spending_limits_currency : currency } : {}),
   };
@@ -1002,6 +724,9 @@ function cardSubObject(params: Params): Params {
     brand: 'visa', last4: number ? number.slice(-4) : '4242',
     exp_month: Number(c.exp_month) || 12, exp_year: Number(c.exp_year) || 2034,
     funding: 'credit', country: 'US',
+    // source: spec:/components/schemas/payment_method_card/properties/fingerprint/description "Uniquely identifies this particular card number."
+    // The synthetic fingerprint is stable for a number; Stripe's opaque fingerprint algorithm is not published.
+    fingerprint: digest('sha256', number || '4242424242424242').slice(0, 16),
     checks: { address_line1_check: null, address_postal_code_check: null, cvc_check: 'pass' },
     networks: { available: ['visa'], preferred: null },
     three_d_secure_usage: { supported: true }, wallet: null,
@@ -1202,19 +927,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 +949,20 @@ 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).
 
+
+export function planView(price: Record<string, unknown>): Record<string, unknown> {
+  const recurring = price.recurring as Record<string, unknown> | undefined;
+  return {
+    id: price.id, object: 'plan', active: price.active ?? true, amount: price.unit_amount ?? null,
+    amount_decimal: price.unit_amount_decimal ?? (price.unit_amount == null ? null : String(price.unit_amount)),
+    billing_scheme: price.billing_scheme ?? 'per_unit', created: price.created, currency: price.currency,
+    interval: recurring?.interval ?? null, interval_count: recurring?.interval_count ?? 1,
+    livemode: price.livemode ?? false, metadata: price.metadata ?? {}, nickname: price.nickname ?? null,
+    product: price.product ?? null, tiers_mode: price.tiers_mode ?? null,
+    meter: recurring?.meter ?? null, trial_period_days: recurring?.trial_period_days ?? null,
+    transform_usage: price.transform_quantity ?? null, usage_type: recurring?.usage_type ?? 'licensed',
+  };
+}