@volter/twin-stripe 2.0.38 → 3.0.1

package/src/stripe-conformance.ts

@@ -1,124 +0,0 @@
-// Stripe twin conformance (scorecard R2) — spec-conformance against Stripe's
-// PUBLISHED OpenAPI, offline (no API key). Stripe is the twin we CANNOT dual-run
-// against a live sandbox, so the published spec carries the most weight here.
-//
-// For every resource the twin emits, validate its REST body against the vendored
-// per-object schema (test-fixtures/stripe-schemas.json) via the shared
-// specConformance harness: declared TYPES, REQUIRED fields (omission), and ENUMS.
-// Polymorphic Stripe fields (anyOf/$ref — `customer` may be id|object|null) are
-// left untyped in the projection and so are not type-checked, avoiding false
-// positives. Fields the twin deliberately does not model are DECLARED in
-// stripe-known-deviations.json with reasons; an undeclared missing-required field,
-// a wrong type, an enum violation, or a fabricated field all fail CI.
-import { readFile } from 'node:fs/promises';
-import { twinResources } from '@volter/world-core';
-import { specConformance } from '@volter/world-tooling';
-import type { TwinResource } from '@volter/world-core';
-import { OBJECT_NAME } from './stripe-twin.ts';
-import { INCLUDABLE_FIELDS, render } from './stripe-version.ts';
-
-type JsonSchema = specConformance.JsonSchema;
-type KnownDeviation = specConformance.KnownDeviation;
-type SpecViolation = specConformance.SpecViolation;
-
-// twin resource type -> Stripe OpenAPI object name (the resources the twin serves)
-const TYPE_TO_OBJECT: Record<string, string> = {
-  charge: 'charge', customer: 'customer', payment_intent: 'payment_intent', refund: 'refund',
-  subscription: 'subscription', setup_intent: 'setup_intent', payment_method: 'payment_method',
-  price: 'price', product: 'product', invoice: 'invoice', invoiceitem: 'invoiceitem',
-  dispute: 'dispute', payout: 'payout', balance_transaction: 'balance_transaction', event: 'event',
-  checkout_session: 'checkout.session', billing_portal_session: 'billing_portal.session',
-  billing_portal_configuration: 'billing_portal.configuration',
-  account: 'account', transfer: 'transfer',
-  tax_rate: 'tax_rate', tax_calculation: 'tax.calculation', tax_registration: 'tax.registration',
-  credit_note: 'credit_note', tax_id: 'tax_id', customer_balance_transaction: 'customer_balance_transaction',
-  issuing_authorization: 'issuing.authorization', issuing_card: 'issuing.card',
-  issuing_cardholder: 'issuing.cardholder', issuing_transaction: 'issuing.transaction',
-};
-
-export type StripeSchemas = Record<string, JsonSchema>;
-export type StripeViolation = SpecViolation & { object: string; id: string };
-export type StripeConformanceReport = {
-  ok: boolean;
-  resourcesChecked: number;
-  fieldsChecked: number;
-  violations: StripeViolation[];
-  knownIgnored: number;
-  /** fields checked per twin resource type: a type the check skipped (no schema) is absent */
-  fieldsByType: Record<string, number>;
-};
-
-const isTwinExtra = (k: string): boolean => k.startsWith('_');
-const fixturePath = (name: string): string => new URL(`../test-fixtures/${name}`, import.meta.url).pathname;
-
-// The emitted REST body == the twin's view(): strip internal fields, add object + id.
-// Mirrors stripe-twin.ts view(): a vendor `type` field collides with the kernel
-// discriminator, so it is stored under `_stripe_type` and restored to `type` on emit.
-// ...and then rendered in the version a caller that pins none is served (stripe-version.ts render): since 24e757f60
-// the twin KEEPS objects in the 2024-06-20 shape its rules were written against and answers them in the served
-// version's (basil onward moved an invoice's subscription and charge, a charge's source, ...), so the stored row is
-// not what any client receives. The schemas are projected from a post-basil spec, so the answer is what is checked.
-function emitted(r: TwinResource): Record<string, unknown> {
-  const { type, updatedAt, _stripe_type, ...rest } = r as TwinResource & { _stripe_type?: unknown };
-  const out: Record<string, unknown> = { object: OBJECT_NAME[type] ?? type, ...rest, id: r.id };
-  if (_stripe_type !== undefined) out.type = _stripe_type;
-  // expanded: an includable field (a session's line_items, a charge's refunds) is answered only when a request asks, and
-  // the check reads the answer that carries it so its shape is still checked
-  return render(out, undefined, INCLUDABLE_FIELDS) as Record<string, unknown>;
-}
-
-/** Load the vendored per-object Stripe JSON Schemas (type+required+enum from OpenAPI). */
-export async function loadStripeSchemas(): Promise<StripeSchemas> {
-  return JSON.parse(await readFile(fixturePath('stripe-schemas.json'), 'utf8')) as StripeSchemas;
-}
-
-/** Load the declared scope (Stripe fields the twin does not model, + reasons). */
-export async function loadStripeKnownDeviations(): Promise<KnownDeviation[]> {
-  const doc = JSON.parse(await readFile(fixturePath('stripe-known-deviations.json'), 'utf8')) as { deviations: KnownDeviation[] };
-  return doc.deviations;
-}
-
-/**
- * Validate every Stripe resource the twin serves (in `root`) against the published
- * schema. A wrong type, an undeclared missing-required field, an enum violation, or
- * a fabricated field fails the report.
- */
-export function checkStripeConformance(schemas: StripeSchemas, opts: { root?: string; known?: KnownDeviation[] } = {}): StripeConformanceReport {
-  const resources = twinResources('stripe', opts.root);
-  const violations: StripeViolation[] = [];
-  let fieldsChecked = 0;
-  let knownIgnored = 0;
-  const fieldsByType: Record<string, number> = {};
-  for (const r of resources) {
-    const objectName = TYPE_TO_OBJECT[r.type];
-    if (!objectName) continue;
-    const schema = schemas[objectName];
-    if (!schema) continue;
-    const rep = specConformance.checkSpecConformance(emitted(r), schema, { exemptKey: isTwinExtra, known: opts.known ?? [] });
-    fieldsChecked += rep.fieldsChecked;
-    fieldsByType[r.type] = (fieldsByType[r.type] ?? 0) + rep.fieldsChecked;
-    knownIgnored += rep.knownIgnored;
-    for (const v of rep.violations) violations.push({ ...v, object: objectName, id: r.id });
-  }
-  return { ok: violations.length === 0, resourcesChecked: resources.length, fieldsChecked, violations, knownIgnored, fieldsByType };
-}
-
-export type StripeCoverageReport = specConformance.SpecCoverageReport & { object: string };
-
-/**
- * Per-object coverage: of the fields each Stripe object declares, which does the
- * twin emit? Computed over one representative resource of each type present in
- * `root` — the "what we emulate / what we're missing" report, from the spec.
- */
-export function stripeCoverage(schemas: StripeSchemas, opts: { root?: string } = {}): StripeCoverageReport[] {
-  const byType = new Map<string, TwinResource>();
-  for (const r of twinResources('stripe', opts.root)) if (!byType.has(r.type)) byType.set(r.type, r);
-  const out: StripeCoverageReport[] = [];
-  for (const [type, r] of byType) {
-    const objectName = TYPE_TO_OBJECT[type];
-    const schema = objectName ? schemas[objectName] : undefined;
-    if (!objectName || !schema) continue;
-    out.push({ object: objectName, ...specConformance.specCoverage(schema, emitted(r), { exemptKey: isTwinExtra }) });
-  }
-  return out;
-}

package/src/stripe-connector.ts

@@ -1,462 +0,0 @@
-// Stripe CONNECTOR — the live-vendor pull/push path that gives the Stripe twin the
-// full "git for SaaS" lifecycle (the piece every other connector pack already had,
-// and Stripe was missing entirely).
-//
-// PULL  (real → twin):  fetch real Stripe objects, map snake_case → SyncResource[],
-//                       fold into the tree through the kernel's observe (its own diff, so a
-//                       re-pull of identical state appends nothing).
-// PUSH  (twin → real):  for every PENDING local action, call the real Stripe REST API
-//                       and the head confirms on success — which records the confirmed
-//                       fields as an observed event and suppresses the local
-//                       projection (the change is counted exactly once).
-//
-// The vendor I/O is an INJECTED executor (the auth-boundary, hard-problem #6): the
-// kernel and this pack hold NO Stripe key and import NO network client.
-//   - offline/tests pass a fake executor (deterministic, no network),
-//   - live runs pass `liveStripeExecute(apiKey)` (the user's own secret key).
-// Same code path either way, so the connector is fully exercisable offline AND
-// runnable against a real account.
-import { assertBudgetGuardIntact, observeResources } from '@volter/world-core';
-import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
-import { StripeBudget, StripeBudgetError, stripeCallWeight, type StripeBudgetOptions } from './stripe-budget.ts';
-
-const SERVICE = 'stripe';
-
-// Subject types that are twin-internal and are NEVER pushed to real Stripe: the recorded
-// Stripe `event` envelopes (the local Events-API store) and idempotency bookkeeping.
-export const INTERNAL_SUBJECT_TYPES = new Set(['event', '_idempotency']);
-
-/**
- * The injected real-Stripe boundary. `request` issues ONE Stripe REST call:
- *   method  — 'GET' | 'POST' | 'DELETE'
- *   path    — e.g. '/v1/customers' or '/v1/customers/cus_123'
- *   params  — form params (POST) or query filters (GET); omitted for plain GETs
- * It returns the parsed JSON body (a Stripe object or `{ object: 'list', data }`) or
- * a Stripe `{ error }` envelope. A real client (the `stripe` SDK or a raw fetch
- * wrapper) is structurally assignable; tests pass a fake.
- */
-export type StripeExecute = (
-  method: 'GET' | 'POST' | 'DELETE',
-  path: string,
-  params?: Record<string, unknown>,
-) => Promise<{ object?: string; data?: any; error?: { message?: string; type?: string }; [k: string]: unknown }>;
-
-/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
-export type LiveStripeOptions = {
-  /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
-  fetchImpl?: typeof fetch;
-  /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
-  budget?: StripeBudget;
-  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
-  budgetOptions?: StripeBudgetOptions;
-};
-
-/**
- * A live executor against the real Stripe REST API (secret key = the user's own).
- * Form-encodes POST params; sends GET filters as a query string. Never imported by
- * the pack's own code path — only constructed by a caller that opts into real I/O.
- *
- * THIS IS THE ONE PLACE this pack issues a live `api.stripe.com` request, and therefore the one
- * place the rate budget has to be enforced — and Stripe is the pack where a runaway loop does not
- * merely annoy a vendor, it MOVES MONEY. EVERY call is guarded: the budget is charged BEFORE the
- * request goes out (`checkBudget`, which THROWS `StripeBudgetError` instead of returning when the
- * ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a `Retry-After` /
- * 429 signal becomes a persisted cooldown that makes every later call fail fast WITHOUT touching
- * Stripe. There is deliberately no OPTION to disable the guard, and no
- * value a caller can pass for `budget` that yields an unguarded client. That is NOT immunity from
- * a caller who WANTS one: a fresh `budgetOptions.path` per construction, or an injected clock,
- * restores the allowance, because the seam tests need cannot be denied to a determined caller in
- * the same process. The kernel header states that limit and this does not upgrade it. See `stripe-budget.ts` for why,
- * and for the limits of the guarantee.
- */
-export function liveStripeExecute(
-  apiKey: string,
-  base = 'https://api.stripe.com',
-  opts: LiveStripeOptions = {},
-): StripeExecute {
-  // `null`/`undefined` (or omitting it) build the default budget. Anything else must be an
-  // UNMODIFIED StripeBudget: a duck-typed stand-in, a SUBCLASS that overrides `checkBudget`, and a
-  // Proxy that traps it are all refused, because all three are one-liners that would otherwise
-  // hand back a client with no ceiling at all (§9 finding, 2026-07-26 — `instanceof` alone was
-  // not a check). What this cannot stop is deliberate sabotage from inside the process (an
-  // injected clock, a throwaway ledger path); the kernel's header says so rather than pretending
-  // otherwise, and this guards the accident and the one-liner, which are the shapes that happen.
-  const doFetch = opts.fetchImpl ?? fetch;
-  // The default ledger is keyed by a hash of THIS key — Stripe's limits attach to the account
-  // behind it, so a cwd-scoped ledger would hand it a fresh allowance per checkout/worktree/CI leg.
-  // A live key and a test key hash differently, which matches Stripe's separate 100/s and 25/s.
-  // ONE expression decides which budget is used, so there is no second, weaker test that could
-  // disagree with the first. `null`/`undefined` (or omitting it) build the default; anything else
-  // must be an UNMODIFIED StripeBudget — a duck-typed stand-in, a SUBCLASS overriding
-  // `checkBudget`, and a Proxy trapping it are ALL refused, because each is a one-liner that
-  // would otherwise hand back a client with no ceiling (§9 finding, 2026-07-26: `instanceof`
-  // alone was not a check — a subclass satisfied it). What this cannot stop is deliberate
-  // sabotage from inside the process (an injected clock, a throwaway ledger path); the kernel
-  // header states that limit rather than pretending otherwise. This closes the accident and the
-  // one-liner, which are the shapes that actually happen.
-  const budget = opts.budget !== undefined && opts.budget !== null
-    ? assertBudgetGuardIntact(opts.budget, StripeBudget, 'liveStripeExecute')
-    : new StripeBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
-  return async (method, path, params) => {
-    const headers: Record<string, string> = { Authorization: `Bearer ${apiKey}` };
-    let url = `${base}${path}`;
-    const form = encodeForm(params ?? {});
-    const init: { method: string; headers: Record<string, string>; body?: string } = { method, headers };
-    if (method === 'GET') {
-      if (form) url += `?${form}`;
-    } else if (form) {
-      headers['Content-Type'] = 'application/x-www-form-urlencoded';
-      init.body = form;
-    }
-    const weight = stripeCallWeight(method, path);
-    // THROWS instead of calling. Nothing below this line runs when the budget refuses.
-    const reservation = budget.checkBudget(weight);
-    const res = await doFetch(url, init);
-    const resHeaders: Record<string, string> = {};
-    res.headers.forEach((v: string, k: string) => { resHeaders[k.toLowerCase()] = v; });
-    const parsed = (await res.json()) as { object?: string; data?: any; error?: { message?: string } };
-    // Settles the reservation and, on a back-off signal, arms the cooldown. May itself throw (a
-    // `Retry-After` beyond the cap is not something to sleep off) — the cooldown is persisted
-    // first either way, so the refusal survives the throw.
-    // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
-    // call that louder refusal wins; an answer Stripe ACCEPTED is kept, so a write that landed is
-    // never recorded as failed and performed again on retry.
-    try {
-      budget.recordCall(weight, resHeaders, { status: res.status, reservation });
-    } catch (error) {
-      if (!(error instanceof StripeBudgetError) || !res.ok) throw error;
-    }
-    return parsed;
-  };
-}
-
-// Stripe's nested form encoding (a[b]=c). Only the shapes the connector pushes
-// (flat scalars + one level of object nesting, e.g. metadata) are handled.
-function encodeForm(params: Record<string, unknown>, prefix = ''): string {
-  const parts: string[] = [];
-  for (const [key, value] of Object.entries(params)) {
-    if (value === undefined) continue;
-    const name = prefix ? `${prefix}[${key}]` : key;
-    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
-      const nested = encodeForm(value as Record<string, unknown>, name);
-      if (nested) parts.push(nested);
-    } else {
-      parts.push(`${encodeURIComponent(name)}=${encodeURIComponent(value === null ? '' : String(value))}`);
-    }
-  }
-  return parts.join('&');
-}
-
-function listOf(res: { data?: unknown }): any[] {
-  return Array.isArray(res.data) ? res.data : [];
-}
-function throwIfError(res: { error?: { message?: string } }, ctx: string): void {
-  if (res.error) throw new Error(`stripe ${ctx} failed: ${res.error.message ?? 'unknown error'}`);
-}
-
-// ── PULL ────────────────────────────────────────────────────────────────────
-
-/**
- * Map a real-Stripe customer (snake_case) → a twin sync resource. Only the stable
- * scalar fields the twin tracks are carried; absent fields become null so the diff
- * is faithful (an unset email reads as null, not missing).
- */
-export function mapCustomer(c: Record<string, unknown>): SyncResource {
-  return {
-    type: 'customer',
-    id: String(c.id),
-    fields: {
-      email: (c.email as string) ?? null,
-      name: (c.name as string) ?? null,
-      description: (c.description as string) ?? null,
-      phone: (c.phone as string) ?? null,
-      currency: (c.currency as string) ?? null,
-      delinquent: typeof c.delinquent === 'boolean' ? c.delinquent : null,
-      created: typeof c.created === 'number' ? c.created : null,
-      livemode: typeof c.livemode === 'boolean' ? c.livemode : null,
-    },
-  };
-}
-
-/**
- * Map a real-Stripe subscription (snake_case) → a twin sync resource. The single
- * subscribed price id is lifted out of items.data[0].price.id (Stripe's nested list
- * shape) so the twin tracks a flat, diffable `price`.
- */
-export function mapSubscription(s: Record<string, unknown>): SyncResource {
-  const items = s.items as { data?: Array<{ price?: { id?: unknown } }> } | undefined;
-  const firstPrice = items?.data?.[0]?.price?.id;
-  return {
-    type: 'subscription',
-    id: String(s.id),
-    fields: {
-      customer: (s.customer as string) ?? null,
-      status: (s.status as string) ?? null,
-      currency: (s.currency as string) ?? null,
-      cancel_at_period_end: typeof s.cancel_at_period_end === 'boolean' ? s.cancel_at_period_end : null,
-      price: typeof firstPrice === 'string' ? firstPrice : null,
-      created: typeof s.created === 'number' ? s.created : null,
-      livemode: typeof s.livemode === 'boolean' ? s.livemode : null,
-    },
-  };
-}
-
-/**
- * A GENERIC scalar mapper for the collections that don't need special id-lifting like
- * subscriptions do. We carry the stable, diffable scalar fields a twin tracks (anything
- * that is a string/number/boolean), dropping nested objects/arrays (which the twin either
- * synthesizes or doesn't diff on). This keeps every collection's pull faithful without a
- * bespoke mapper per type — vendor-SPECIFIC lifting (subscription.price) stays explicit.
- */
-export function mapScalarResource(type: string, r: Record<string, unknown>): SyncResource {
-  const fields: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(r)) {
-    if (k === 'id' || k === 'object') continue;
-    if (v === null || typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') fields[k] = v ?? null;
-  }
-  return { type, id: String(r.id), fields };
-}
-
-// The full set of collections a full sync pulls, mapped to the REST list path + the twin
-// resource type. Customers + subscriptions keep their bespoke mappers (id-lifting); the
-// rest use the generic scalar mapper.
-const PULL_COLLECTIONS: Array<{ path: string; type: string; map?: (r: Record<string, unknown>) => SyncResource; params?: Record<string, unknown> }> = [
-  { path: '/v1/customers', type: 'customer', map: mapCustomer },
-  { path: '/v1/subscriptions', type: 'subscription', map: mapSubscription, params: { status: 'all' } },
-  { path: '/v1/products', type: 'product' },
-  { path: '/v1/prices', type: 'price' },
-  { path: '/v1/charges', type: 'charge' },
-  { path: '/v1/payment_intents', type: 'payment_intent' },
-  { path: '/v1/invoices', type: 'invoice' },
-  { path: '/v1/refunds', type: 'refund' },
-  { path: '/v1/payouts', type: 'payout' },
-  { path: '/v1/disputes', type: 'dispute' },
-  { path: '/v1/coupons', type: 'coupon' },
-];
-
-/** Pull real Stripe customers via the executor and map them to twin sync resources. */
-export async function pullStripeCustomers(execute: StripeExecute, opts: { limit?: number } = {}): Promise<SyncResource[]> {
-  const res = await execute('GET', '/v1/customers', { limit: opts.limit ?? 100 });
-  throwIfError(res, 'pull customers');
-  return listOf(res).map(mapCustomer);
-}
-
-/** Pull real Stripe subscriptions via the executor and map them to twin sync resources. */
-export async function pullStripeSubscriptions(execute: StripeExecute, opts: { limit?: number } = {}): Promise<SyncResource[]> {
-  const res = await execute('GET', '/v1/subscriptions', { status: 'all', limit: opts.limit ?? 100 });
-  throwIfError(res, 'pull subscriptions');
-  return listOf(res).map(mapSubscription);
-}
-
-/**
- * Pull from real Stripe (customers + subscriptions) and fold into the twin (mirror
- * seeding). The fold makes a re-pull of identical state a no-op.
- */
-/** One fold onto the head: protocol 2's observe, one batch, one instant. */
-function fold(resources: SyncResource[], opts: { root?: string; occurredAt: string }) {
-  return observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), {
-    ...(opts.root !== undefined ? { root: opts.root } : {}), at: opts.occurredAt, batch: `obs:${SERVICE}:${opts.occurredAt}`,
-  });
-}
-
-export async function syncStripeFromReal(
-  execute: StripeExecute,
-  opts: { root?: string; occurredAt: string; limit?: number },
-): Promise<{ observed: number; deltasAppended: number }> {
-  const customers = await pullStripeCustomers(execute, { ...(opts.limit ? { limit: opts.limit } : {}) });
-  const subscriptions = await pullStripeSubscriptions(execute, { ...(opts.limit ? { limit: opts.limit } : {}) });
-  const resources = [...customers, ...subscriptions];
-  const result = fold(resources, opts);
-  return { observed: result.observed, deltasAppended: result.appended };
-}
-
-// ── PUSH ────────────────────────────────────────────────────────────────────
-
-// Stripe resource type → REST collection segment, for building create paths.
-// (Pluralization isn't uniform — e.g. `dispute`→`disputes` is fine but several types
-// the twin writes need an explicit mapping so the path matches real Stripe exactly.)
-const COLLECTION: Record<string, string> = {
-  customer: 'customers',
-  subscription: 'subscriptions',
-  charge: 'charges',
-  product: 'products',
-  price: 'prices',
-  invoice: 'invoices',
-  payment_intent: 'payment_intents',
-  setup_intent: 'setup_intents',
-  payment_method: 'payment_methods',
-  refund: 'refunds',
-  dispute: 'disputes',
-  payout: 'payouts',
-};
-
-// Verb-style twin operations that map to a real-Stripe SUB-ACTION endpoint
-// (POST /v1/<collection>/:id/<verb>) rather than a plain resource update. The twin
-// records these verbs verbatim as the operation's suffix (see stripe-twin.ts:
-// payment_intent.confirm, setup_intent.confirm, payment_method.detach,
-// invoice.finalize|pay|void, dispute.close, payout.cancel). The verb here IS the
-// real Stripe path segment, so this stays faithful as the twin grows.
-const SUBACTION_VERBS = new Set(['confirm', 'detach', 'finalize', 'pay', 'void', 'close']);
-
-// `cancel` is resource-specific in real Stripe: a subscription is canceled with
-// DELETE /v1/subscriptions/:id, but a payout is canceled with POST
-// /v1/payouts/:id/cancel. Anything else canceled via DELETE on the resource is a safe
-// default (no other type the twin emits a `.cancel` for uses a sub-action path).
-const CANCEL_VIA_SUBACTION = new Set(['payout']);
-
-/**
- * Resolve the REST (method, path) for ONE pending action — faithful to the real
- * Stripe REST surface for EVERY write operation the twin records. The action carries
- * the twin operation (`<type>.<verb>`) plus its subject:
- *   - `<type>.create`              → POST   /v1/<collection>
- *   - `subscription.cancel`        → DELETE /v1/subscriptions/:id
- *   - `payout.cancel`              → POST   /v1/payouts/:id/cancel  (sub-action)
- *   - `payment_intent.confirm`     → POST   /v1/payment_intents/:id/confirm
- *   - `setup_intent.confirm`       → POST   /v1/setup_intents/:id/confirm
- *   - `payment_method.detach`      → POST   /v1/payment_methods/:id/detach
- *   - `invoice.finalize|pay|void`  → POST   /v1/invoices/:id/<verb>
- *   - `dispute.close`              → POST   /v1/disputes/:id/close
- *   - `<type>.update` (or any other verb) → POST /v1/<collection>/:id
- *
- * Unknown/unsupported operations must FAIL LOUDLY at push time (see pushStripeAction),
- * never be silently dropped — so this resolver always returns a concrete request and
- * the caller validates the operation is one the twin is allowed to push.
- */
-export function stripeRequestForAction(action: Pick<TwinAction, 'operation' | 'subject'>): { method: 'POST' | 'DELETE'; path: string } {
-  const op = action.operation ?? `${action.subject.type}.update`;
-  const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
-  const collection = COLLECTION[action.subject.type] ?? `${action.subject.type}s`;
-  const base = `/v1/${collection}`;
-  if (verb === 'create') return { method: 'POST', path: base };
-  if (verb === 'cancel') {
-    return CANCEL_VIA_SUBACTION.has(action.subject.type)
-      ? { method: 'POST', path: `${base}/${action.subject.id}/cancel` }
-      : { method: 'DELETE', path: `${base}/${action.subject.id}` };
-  }
-  // confirm / detach / finalize / pay / void / close → /:id/<verb>
-  if (SUBACTION_VERBS.has(verb)) return { method: 'POST', path: `${base}/${action.subject.id}/${verb}` };
-  // update (and any other plain mutation) → POST the resource itself.
-  return { method: 'POST', path: `${base}/${action.subject.id}` };
-}
-
-// The twin operations this connector knows how to push to real Stripe. Anything not
-// here (a new/unmodeled write op) must FAIL LOUDLY rather than be silently dropped —
-// pushing an unrecognized op risks hitting the wrong real endpoint or no-op'ing a
-// real change. New twin write ops must be deliberately added here.
-const PUSHABLE_VERBS = new Set(['create', 'update', 'cancel', ...SUBACTION_VERBS]);
-
-/** Throw if `op` is not a write operation this connector can faithfully push. */
-/** Whether this operation is one the connector can faithfully send to Stripe. */
-export function isPushable(op: string): boolean {
-  const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
-  return PUSHABLE_VERBS.has(verb);
-}
-function assertPushable(op: string): void {
-  const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
-  if (!PUSHABLE_VERBS.has(verb)) {
-    throw new Error(`stripe push: unsupported operation '${op}' — refusing to silently drop a local write`);
-  }
-}
-
-/**
- * Push ONE pending action to REAL Stripe via the injected executor. Returns the real
- * external id (the Stripe object id from the response — for a create that is a freshly
- * minted id; for an update it echoes the subject). WRITES TO THE REAL ACCOUNT.
- */
-export async function pushStripeAction(
-  execute: StripeExecute,
-  action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>,
-): Promise<{ externalId: string }> {
-  assertPushable(action.operation ?? `${action.subject.type}.update`);
-  const { method, path } = stripeRequestForAction(action);
-  const res = await execute(method, path, method === 'DELETE' ? undefined : (action.fields ?? {}));
-  throwIfError(res, `push ${action.subject.type}`);
-  const id = (res as { id?: unknown }).id;
-  return { externalId: typeof id === 'string' && id ? id : action.subject.id };
-}
-
-// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
-/** The pack's executor over the kernel's: the same Stripe REST call, carried by the head. Stripe's API is
- *  form-encoded, which is what `stripeExecute` already speaks — this only carries it. */
-export function stripeExecuteOver(execute: RemoteExecute): StripeExecute {
-  return async (method, path, params) => {
-    const body = params === undefined ? undefined : encodeForm(params);
-    const res = await execute({
-      method, path,
-      headers: { accept: 'application/json', ...(body === undefined ? {} : { 'content-type': 'application/x-www-form-urlencoded' }) },
-      ...(body === undefined ? {} : { body }),
-    });
-    if (res.body === '') return {};
-    try { return JSON.parse(res.body) as Record<string, unknown>; } catch { return { error: { type: 'api_error', message: res.body.slice(0, 200) } }; }
-  };
-}
-/** The refresh adapter: pull every modeled collection and the webhook endpoints through the executor. */
-export async function syncStripeFromRemote(execute: RemoteExecute, opts: { root?: string; origin?: string; occurredAt?: string } = {}): Promise<{ observed: number; deltasAppended: number }> {
-  const at = opts.occurredAt ?? new Date().toISOString();
-  const wire = stripeExecuteOver(execute);
-  const resources = [
-    ...await pullStripeAll(wire),
-    ...await pullStripeWebhookEndpoints(wire),
-  ];
-  const report = fold(resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), occurredAt: at });
-  return { observed: report.observed, deltasAppended: report.appended };
-}
-/** The perform adapter: one entry crosses to Stripe, or settles with the reason it never could. The twin's
- *  own subject types — the recorded `event` envelopes the write path persists for the Events API, and the
- *  idempotency bookkeeping — are local state and must never be sent. */
-export async function performStripeAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome> {
-  const op = action.operation ?? `${action.subject.type}.update`;
-  if (INTERNAL_SUBJECT_TYPES.has(action.subject.type) || !isPushable(op)) {
-    return { externalId: action.subject.id, data: { performed: false, reason: `${op} is the twin's own record — nothing at Stripe to write` } };
-  }
-  return pushStripeAction(stripeExecuteOver(execute), { operation: op, subject: action.subject, fields: action.fields ?? {} });
-}
-
-// ── FULL SYNC (all collections + webhooks, bi-directional) ───────────────────
-
-/** Pull a single REST list collection and map each row to a twin sync resource. */
-async function pullCollection(execute: StripeExecute, spec: { path: string; type: string; map?: (r: Record<string, unknown>) => SyncResource; params?: Record<string, unknown> }, limit: number): Promise<SyncResource[]> {
-  const res = await execute('GET', spec.path, { ...(spec.params ?? {}), limit });
-  throwIfError(res, `pull ${spec.type}`);
-  const map = spec.map ?? ((r: Record<string, unknown>) => mapScalarResource(spec.type, r));
-  return listOf(res).map(map);
-}
-
-/**
- * Pull EVERY tracked collection from real Stripe (not just customers + subscriptions) in
- * one pass and return the combined sync resources. This is the read half of a full sync.
- */
-export async function pullStripeAll(execute: StripeExecute, opts: { limit?: number } = {}): Promise<SyncResource[]> {
-  const limit = opts.limit ?? 100;
-  const all: SyncResource[] = [];
-  for (const spec of PULL_COLLECTIONS) all.push(...await pullCollection(execute, spec, limit));
-  return all;
-}
-
-/** Pull the account's registered webhook endpoints (so the twin mirrors them too). */
-export async function pullStripeWebhookEndpoints(execute: StripeExecute, opts: { limit?: number } = {}): Promise<SyncResource[]> {
-  const res = await execute('GET', '/v1/webhook_endpoints', { limit: opts.limit ?? 100 });
-  throwIfError(res, 'pull webhook_endpoints');
-  return listOf(res).map((w: Record<string, unknown>) => mapScalarResource('webhook_endpoint', w));
-}
-
-/**
- * FULL bi-directional sync over the injected client: (1) PUSH every pending local action to
- * real Stripe and confirm it, then (2) PULL all collections + webhook endpoints back and
- * fold them into the event log. Pushing first means the pull observes the twin's own writes
- * as confirmed external state (no double-count). Returns per-direction counts. Same code
- * path offline (fake executor) and live (real key) — D4-faithful.
- */
-export async function fullSyncStripe(
-  execute: StripeExecute,
-  opts: { root?: string; occurredAt: string; limit?: number },
-): Promise<{ observed: number; deltasAppended: number; collections: number }> {
-  // protocol 2: this is the PULL half only. The push half is the head's — it performs each entry through
-  // `performStripeAction` and confirms it — so a refresh no longer reconciles both directions at once.
-  const resources = [
-    ...await pullStripeAll(execute, { ...(opts.limit ? { limit: opts.limit } : {}) }),
-    ...await pullStripeWebhookEndpoints(execute, { ...(opts.limit ? { limit: opts.limit } : {}) }),
-  ];
-  const pull = fold(resources, opts);
-  return { observed: pull.observed, deltasAppended: pull.appended, collections: PULL_COLLECTIONS.length + 1 };
-}