@volter/twin-stripe 0.1.1 → 2.0.0

package/src/stripe-conformance.ts

@@ -10,9 +10,10 @@
 // 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 { twinResources } from '@volter/twin';
-import { specConformance } from '@volter/twin-tooling';
-import type { TwinResource } from '@volter/twin';
+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';
 
 type JsonSchema = specConformance.JsonSchema;
@@ -59,12 +60,12 @@ function emitted(r: TwinResource): 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 Bun.file(fixturePath('stripe-schemas.json')).text()) as 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 Bun.file(fixturePath('stripe-known-deviations.json')).text()) as { deviations: KnownDeviation[] };
+  const doc = JSON.parse(await readFile(fixturePath('stripe-known-deviations.json'), 'utf8')) as { deviations: KnownDeviation[] };
   return doc.deviations;
 }
 

package/src/stripe-connector.ts

@@ -3,10 +3,10 @@
 // and Stripe was missing entirely).
 //
 // PULL  (real → twin):  fetch real Stripe objects, map snake_case → SyncResource[],
-//                       fold into the event log via syncPull (shadow-diff dedup, so a
+//                       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 confirmAction on success — which records the confirmed
+//                       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).
 //
@@ -16,15 +16,15 @@
 //   - 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, confirmAction, pendingActions, syncPull } from '@volter/twin';
-import type { SyncResource, TwinAction } from '@volter/twin';
-import { StripeBudget, stripeCallWeight, type StripeBudgetOptions } from './stripe-budget.ts';
+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.
-const INTERNAL_SUBJECT_TYPES = new Set(['event', '_idempotency']);
+export const INTERNAL_SUBJECT_TYPES = new Set(['event', '_idempotency']);
 
 /**
  * The injected real-Stripe boundary. `request` issues ONE Stripe REST call:
@@ -118,7 +118,14 @@ export function liveStripeExecute(
     // 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.
-    budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+    // 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;
   };
 }
@@ -243,8 +250,15 @@ export async function pullStripeSubscriptions(execute: StripeExecute, opts: { li
 
 /**
  * Pull from real Stripe (customers + subscriptions) and fold into the twin (mirror
- * seeding). syncPull's shadow-diff makes a re-pull of identical state a no-op.
+ * 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 },
@@ -252,8 +266,8 @@ export async function syncStripeFromReal(
   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 = syncPull({ service: SERVICE, resources, occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
-  return { observed: result.observed, deltasAppended: result.deltasAppended };
+  const result = fold(resources, opts);
+  return { observed: result.observed, deltasAppended: result.appended };
 }
 
 // ── PUSH ────────────────────────────────────────────────────────────────────
@@ -332,6 +346,11 @@ export function stripeRequestForAction(action: Pick<TwinAction, 'operation' | 's
 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)) {
@@ -356,31 +375,41 @@ export async function pushStripeAction(
   return { externalId: typeof id === 'string' && id ? id : action.subject.id };
 }
 
-/**
- * Push the twin's PENDING local actions to real Stripe and CONFIRM each (R18): for
- * every pending `set` action, call the real API; on success, `confirmAction` records
- * the confirmed fields as an observed event and maps action → event (suppressing the
- * local projection). Idempotency: a confirmed action is no longer pending, so a
- * re-push enacts NOTHING — the executor is never called twice for the same change.
- * `execute` is injected (fake offline / live key).
- */
-export async function pushPendingStripeActions(
-  execute: StripeExecute,
-  opts: { root?: string; occurredAt: string },
-): Promise<{ pushed: number; confirmed: string[]; externalIds: Record<string, string> }> {
-  const confirmed: string[] = [];
-  const externalIds: Record<string, string> = {};
-  for (const action of pendingActions(SERVICE, opts.root)) {
-    // Twin-internal subject types (the recorded Stripe `event` envelopes the write path
-    // persists for the Events API, and idempotency bookkeeping) are NOT real-Stripe writes —
-    // they are local-only state and must never be pushed. Skip them (not an error).
-    if (INTERNAL_SUBJECT_TYPES.has(action.subject.type)) continue;
-    const { externalId } = await pushStripeAction(execute, action);
-    confirmAction({ service: SERVICE, actionId: action.id, subject: action.subject, fields: action.fields ?? {}, occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
-    confirmed.push(action.id);
-    externalIds[action.id] = externalId;
+// ── 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 { pushed: confirmed.length, confirmed, externalIds };
+  return pushStripeAction(stripeExecuteOver(execute), { operation: op, subject: action.subject, fields: action.fields ?? {} });
 }
 
 // ── FULL SYNC (all collections + webhooks, bi-directional) ───────────────────
@@ -421,14 +450,13 @@ export async function pullStripeWebhookEndpoints(execute: StripeExecute, opts: {
 export async function fullSyncStripe(
   execute: StripeExecute,
   opts: { root?: string; occurredAt: string; limit?: number },
-): Promise<{ pushed: number; observed: number; deltasAppended: number; collections: number }> {
-  // 1. PUSH pending local changes to real Stripe (and confirm each).
-  const push = await pushPendingStripeActions(execute, { occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
-  // 2. PULL all collections + webhooks back into the twin.
+): 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 = syncPull({ service: SERVICE, resources, occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
-  return { pushed: push.pushed, observed: pull.observed, deltasAppended: pull.deltasAppended, collections: PULL_COLLECTIONS.length + 1 };
+  const pull = fold(resources, opts);
+  return { observed: pull.observed, deltasAppended: pull.appended, collections: PULL_COLLECTIONS.length + 1 };
 }

package/src/stripe-emit.ts

@@ -1,6 +1,6 @@
 // The Stripe DELIVER verb — `world-stripe emit` (feature-sweep friction: hand-constructing
 // checkout.session.completed / invoice.paid envelopes + HMAC signing to poke an app's webhook
-// handler). This is the pack side of the kernel's emit seam (@volter/twin emit.ts): the
+// handler). This is the pack side of the kernel's emit seam (@volter/world-core emit.ts): the
 // catalog of emittable event types, endpoint registrations read FROM TWIN STATE AT REST
 // (webhook_endpoint rows minted by POST /v1/webhook_endpoints — the CLI runs in its own
 // process, so the in-memory delivery registry in stripe-events.ts does not apply), and
@@ -11,9 +11,10 @@
 // DELIVER does not transition state: it snapshots the subject AS IT IS in the twin and fires
 // the named event about it. Completing a checkout session / paying an invoice is the twin
 // API's job; this verb answers "my app's webhook handler needs to SEE the event, now."
-import { projectResources, type EmitEndpoint, type EmittableEvent, type SynthesizedDelivery, type TwinEmitter } from '@volter/twin';
-import { OBJECT_NAME, TWIN_API_VERSION, view } from './stripe-twin.ts';
+import { projectResources, type EmitEndpoint, type EmittableEvent, type SynthesizedDelivery, type TwinEmitter } from '@volter/world-core';
+import { OBJECT_NAME, PLATFORM_ACCOUNT_ID, TWIN_API_VERSION, view } from './stripe-twin.ts';
 import { STRIPE_WEBHOOK_FALLBACK_SECRET, generateTestHeaderString } from './stripe-events.ts';
+import { render } from './stripe-version.ts';
 
 const SERVICE = 'stripe';
 
@@ -31,6 +32,7 @@ const EMITTABLE: Record<string, string> = {
   'payment_intent.canceled': 'payment_intent',
   // charges + disputes
   'charge.succeeded': 'charge',
+  'charge.failed': 'charge',
   'charge.captured': 'charge',
   'charge.refunded': 'charge',
   'charge.dispute.created': 'dispute',
@@ -86,7 +88,7 @@ function rows(type: string, root?: string): Array<Record<string, unknown>> {
 }
 
 function liveEndpointRows(root?: string): Array<Record<string, unknown>> {
-  return rows('webhook_endpoint', root).filter((w) => w._deleted !== true);
+  return rows('webhook_endpoint', root).filter((w) => w.deleted !== true);
 }
 
 let emitSeq = 0;
@@ -107,13 +109,13 @@ export const stripeEmitter: TwinEmitter = {
   },
 
   subjects(subjectType: string, root?: string): string[] {
-    return rows(subjectType, root).filter((r) => r._deleted !== true).map((r) => String(r.id));
+    return rows(subjectType, root).filter((r) => r.deleted !== true).map((r) => String(r.id));
   },
 
   synthesize({ type, subjectId, endpoint, root, occurredAt }): SynthesizedDelivery {
     const subjectType = EMITTABLE[type];
     if (!subjectType) throw new Error(`emit: the stripe pack cannot synthesize "${type}".`);
-    const row = rows(subjectType, root).find((r) => String(r.id) === subjectId && r._deleted !== true);
+    const row = rows(subjectType, root).find((r) => String(r.id) === subjectId && r.deleted !== true);
     if (!row) {
       const have = stripeEmitter.subjects(subjectType, root);
       throw new Error(
@@ -126,6 +128,10 @@ export const stripeEmitter: TwinEmitter = {
     const secret = typeof endpointRow?.secret === 'string' && endpointRow.secret ? endpointRow.secret : STRIPE_WEBHOOK_FALLBACK_SECRET;
 
     const created = occurredAt ? Math.floor(Date.parse(occurredAt) / 1000) : Math.floor(Date.now() / 1000);
+    // a connected account's object is its event's, as the write path scopes it (stripe-twin.ts afterStripeWrite): the
+    // account itself, or a row kept on its books (`_account`). "Each event for a connected account contains a top-level
+    // `account` property that identifies the connected account" (docs.stripe.com/connect/webhooks).
+    const account = typeof row._account === 'string' ? row._account : subjectType === 'account' && String(row.id) !== PLATFORM_ACCOUNT_ID ? String(row.id) : undefined;
     // Same envelope persistStripeEvent stores for GET /v1/events; `evt_twin_emit_*` marks it
     // operator-fired (never colliding with the write path's organic `evt_twin_<n>` ids).
     const event: Record<string, unknown> = {
@@ -138,8 +144,9 @@ export const stripeEmitter: TwinEmitter = {
       pending_webhooks: 1,
       request: { id: null, idempotency_key: null },
       type,
+      ...(account ? { account } : {}),
     };
-    const payload = JSON.stringify(event);
+    const payload = JSON.stringify(render(event, TWIN_API_VERSION));
     const header = generateTestHeaderString({ payload, secret, ...(occurredAt ? { timestamp: created } : {}) });
     return {
       payload,

package/src/stripe-events.ts

@@ -1,3 +1,7 @@
+import { nodeBuiltin } from '@volter/world-core';
+import { worldEgressRefusal } from '@volter/world-core/network-policy';
+import vendorEvents from './generated/events.gen.json' with { type: 'json' };
+import { render } from './stripe-version.ts';
 // Stripe event/webhook emission (scorecard R17). Real Stripe fires `event`
 // objects (and webhooks) on state changes — payment_intent.succeeded,
 // customer.subscription.created, invoice.paid, … — so an app's webhook handler
@@ -10,6 +14,8 @@ export type StripeEvent = {
   type: string;
   created: number;
   livemode: false;
+  /** the connected account a Connect event is from */
+  account?: string;
   data: { object: Record<string, unknown> };
 };
 // A deliverer MAY return the endpoint's raw HTTP response. Ordinary (asynchronous) event
@@ -17,7 +23,9 @@ export type StripeEvent = {
 // (issuing_authorization.request) reads it to honor the endpoint's approve/decline. A
 // fire-and-forget deliverer returning void stays valid for the asynchronous path.
 export type StripeWebhookEndpointResponse = { status: number; body: string };
-export type StripeEventDelivery = (url: string, event: StripeEvent) => Promise<void | StripeWebhookEndpointResponse> | void | StripeWebhookEndpointResponse;
+export type StripeEventDelivery = (url: string, event: StripeEvent, secret?: string) => Promise<void | StripeWebhookEndpointResponse> | void | StripeWebhookEndpointResponse;
+/** A webhook endpoint a World holds in its tree: where to POST, what to sign with, what it subscribed to. */
+export type StripeWebhookTarget = { url: string; secret?: string; enabledEvents?: string[]; /** a Connect endpoint (`connect: true`): events from connected accounts */ connect?: boolean };
 
 // ── Webhook signature verification (Stripe's scheme) ────────────────────────────
 // Real Stripe signs each webhook delivery with an HMAC-SHA256 over `${timestamp}.${payload}`
@@ -33,7 +41,7 @@ export type StripeEventDelivery = (url: string, event: StripeEvent) => Promise<v
 type NodeCrypto = typeof import('node:crypto');
 function nodeCrypto(): NodeCrypto {
   // eslint-disable-next-line @typescript-eslint/no-require-imports
-  return require('node:crypto') as NodeCrypto;
+  return nodeBuiltin('node:crypto') as NodeCrypto;
 }
 
 /** HMAC-SHA256(secret, `${timestamp}.${payload}`) as lowercase hex — Stripe's v1 signature. */
@@ -102,15 +110,13 @@ export function constructEvent(payload: string, header: string, secret: string,
 }
 
 const registry: string[] = [];
-// Endpoint signing secrets by URL. POST /v1/webhook_endpoints mints a `whsec_twin_*`
-// secret on the WebhookEndpoint object and registers it here so live HTTP delivery
-// signs each POST with THAT endpoint's secret (real Stripe signs per-endpoint). A
-// URL registered without a secret (test seam) is signed with the fallback below so
-// the header is still a real, verifiable signature — never a placeholder.
+// URLs a HOST registered directly (registerStripeWebhook), with the secret to sign with and the
+// enabled_events to filter on. A World's own endpoints are not here: POST /v1/webhook_endpoints
+// writes the WebhookEndpoint to the tree, and every emit reads the tree (the caller passes them as
+// `endpoints`), so delivery survives a restart and belongs to one World. A URL registered here
+// without a secret is signed with the fallback below, so the header is still a real, verifiable
+// signature; one registered without a list receives every event, equivalent to ['*'].
 const secrets = new Map<string, string>();
-// Subscriptions by URL: the endpoint's enabled_events, carried through registration so the
-// organic fan-out filters like the vendor. A URL registered WITHOUT a list (test seam)
-// receives every event — equivalent to ['*'].
 const subscriptions = new Map<string, string[]>();
 export const STRIPE_WEBHOOK_FALLBACK_SECRET = 'whsec_twin_default';
 export function registerStripeWebhook(url: string, secret?: string, enabledEvents?: string[]): void {
@@ -147,6 +153,8 @@ export function listStripeWebhooks(): string[] {
 // twin write operation → Stripe event type (the ones an app's webhooks care about).
 // Returns null when an operation has no event (e.g. a plain create/retrieve we
 // don't model an event for).
+const VENDOR_EVENT_TYPES = new Set((vendorEvents as { types: string[] }).types);
+
 export function eventTypeFor(operation: string): string | null {
   // Several twin write operations ARE already the Stripe event type (we record the
   // op as `<resource>.<event>` so it maps 1:1): payment_intent.amount_capturable_updated,
@@ -156,6 +164,11 @@ export function eventTypeFor(operation: string): string | null {
     'payment_intent.payment_failed', 'payment_intent.created', 'payment_intent.processing',
     'payment_intent.requires_action',
     'charge.succeeded', 'charge.captured', 'charge.refunded', 'charge.dispute.created',
+    // A refund fires TWO real Stripe events: `refund.created` carrying the Refund, and
+    // `charge.refunded` carrying the CHARGE with its new totals. The twin records the charge's
+    // own write as `charge.refunded`, so the event a consumer receives is the charge — which is
+    // the whole point of that event and the reason a reconciler subscribes to it.
+    'refund.created', 'refund.updated',
     'customer.updated', 'customer.deleted', 'invoice.created', 'invoice.finalized',
     'invoice.paid', 'invoice.payment_failed', 'invoice.voided', 'invoice.marked_uncollectible', 'invoice.sent',
     'customer.subscription.updated', 'customer.subscription.paused', 'customer.subscription.resumed',
@@ -186,7 +199,7 @@ export function eventTypeFor(operation: string): string | null {
     case 'invoice.finalize': return 'invoice.finalized';
     case 'invoice.pay': return 'invoice.paid';
     case 'invoice.void': return 'invoice.voided';
-    case 'refund.create': return 'charge.refunded';
+    case 'refund.create': return 'refund.created';
     case 'dispute.create': return 'charge.dispute.created';
     case 'payout.create': return 'payout.created';
     case 'product.create': return 'product.created';
@@ -202,11 +215,27 @@ export function eventTypeFor(operation: string): string | null {
     case 'issuing_card.create': return 'issuing_card.created';
     case 'issuing_cardholder.create': return 'issuing_cardholder.created';
     case 'issuing_transaction.create': return 'issuing_transaction.created';
-    default: return null;
+    default: return vendorEventType(operation);
   }
 }
 
-let counter = 0;
+/** Any other write records the event Stripe sends for it, when Stripe sends one: the operation itself, or its
+ *  resource's create/update/delete as `<resource>.created|updated|deleted` (the types Stripe's spec enumerates). */
+function vendorEventType(operation: string): string | null {
+  if (VENDOR_EVENT_TYPES.has(operation)) return operation;
+  const verb = /^(.+)\.(create|update|delete)$/.exec(operation);
+  return verb && VENDOR_EVENT_TYPES.has(`${verb[1]}.${verb[2]}d`) ? `${verb[1]}.${verb[2]}d` : null;
+}
+
+/** An event's id, DERIVED from the event itself — the operation, the resource it carries and the instant —
+ *  never a process counter (protocol 2: two identical worlds deliver identically, and a replay of the same
+ *  write raises the same event id rather than one that drifts with process uptime). */
+function eventId(operation: string, resource: Record<string, unknown>, occurredAt: string, account?: string): string {
+  let h = 0x811c9dc5;
+  const seed = `${operation}|${String((resource as { id?: unknown }).id ?? '')}|${occurredAt}|${account ?? ''}`;
+  for (let i = 0; i < seed.length; i += 1) { h ^= seed.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; }
+  return `evt_twin_${h.toString(16).padStart(8, '0')}`;
+}
 // Live HTTP delivery signs exactly like real Stripe: HMAC-SHA256 over
 // `${timestamp}.${payload}` keyed by the ENDPOINT'S OWN signing secret (the
 // `whsec_twin_*` minted by POST /v1/webhook_endpoints and registered alongside the
@@ -226,9 +255,18 @@ let counter = 0;
 // A delivery that still fails after the re-attempts is DROPPED, and says so: silent loss is
 // the one outcome a twin must never have, because it makes every consumer look flaky.
 const DELIVERY_ATTEMPTS = 3;
-const httpDelivery: StripeEventDelivery = async (url, event) => {
-  const payload = JSON.stringify(event);
-  const secret = secrets.get(url) ?? STRIPE_WEBHOOK_FALLBACK_SECRET;
+const httpDelivery: StripeEventDelivery = async (url, event, endpointSecret) => {
+  // the event as its API version renders it (stripe-version.ts)
+  const payload = JSON.stringify(render(event, (event as { api_version?: string }).api_version));
+  const secret = endpointSecret ?? secrets.get(url) ?? STRIPE_WEBHOOK_FALLBACK_SECRET;
+  // the World's egress rule: an endpoint it refuses is not delivered to, and says so
+  const refusal = worldEgressRefusal(url);
+  if (refusal !== null) console.error(`[twin:stripe] webhook delivery DROPPED — ${event.type} ${event.id} -> ${url}: ${refusal}`);
+  return refusal !== null ? undefined : postEvent(url, event, payload, secret);
+};
+
+/** The HTTP POST of a signed event to an endpoint the World lets it reach, re-attempted on a transport failure. */
+async function postEvent(url: string, event: StripeEvent, payload: string, secret: string): Promise<void> {
   let last = '';
   for (let attempt = 1; attempt <= DELIVERY_ATTEMPTS; attempt += 1) {
     try {
@@ -241,16 +279,17 @@ const httpDelivery: StripeEventDelivery = async (url, event) => {
     }
   }
   console.error(`[twin:stripe] webhook delivery DROPPED after ${DELIVERY_ATTEMPTS} attempts — ${event.type} ${event.id} -> ${url}: ${last}`);
-};
+}
 
 // Default deliverer override (a TEST SEAM). The twin's write path emits events without
 // threading a per-call deliverer, so to drive event delivery fully OFFLINE/deterministically
 // — no real sockets — a test installs a fake sink here. When unset, real HTTP POST is used
 // (prod behavior). This keeps D5 honest: verify() exercises the twin's own emission, in-process.
-let defaultDelivery: StripeEventDelivery | null = null;
+// a slot, not module truth (protocol 2): WHERE a delivery goes, set once by the host that mounts the twin
+const defaultDelivery: { current: StripeEventDelivery | null } = { current: null };
 /** Install a default deliverer used by the write path when no per-call `deliver` is passed. */
 export function setStripeEventDelivery(deliver: StripeEventDelivery | null): void {
-  defaultDelivery = deliver;
+  defaultDelivery.current = deliver;
 }
 
 // ── Real-time authorization (issuing_authorization.request) — the SYNCHRONOUS leg ────────
@@ -283,8 +322,16 @@ export type StripeAuthRequestOutcome =
 // the 2s window. Signs with the enrolled endpoint's own whsec (passed by the caller, read
 // from the endpoint's state row) — never a placeholder.
 async function httpAuthRequestDelivery(url: string, event: StripeEvent, secret: string): Promise<StripeWebhookEndpointResponse> {
-  const payload = JSON.stringify(event);
+  // the event as its API version renders it (stripe-version.ts)
+  const payload = JSON.stringify(render(event, (event as { api_version?: string }).api_version));
   const header = generateTestHeaderString({ payload, secret });
+  // the World's egress rule: a refused endpoint is an unreachable one (the caller's timeout fallback)
+  const refusal = worldEgressRefusal(url);
+  return refusal !== null ? Promise.reject(new Error(refusal)) : postAuthRequest(url, payload, header);
+}
+
+/** The HTTP POST of a real-time authorization request, cut off at the window, and the endpoint's answer. */
+async function postAuthRequest(url: string, payload: string, header: string): Promise<StripeWebhookEndpointResponse> {
   const res = await fetch(url, {
     method: 'POST',
     headers: { 'content-type': 'application/json', 'stripe-signature': header },
@@ -304,16 +351,20 @@ async function httpAuthRequestDelivery(url: string, event: StripeEvent, secret:
 export async function requestAuthorizationDecision(url: string, event: StripeEvent, secret: string): Promise<StripeAuthRequestOutcome> {
   let res: void | StripeWebhookEndpointResponse;
   try {
-    res = defaultDelivery ? await defaultDelivery(url, event) : await httpAuthRequestDelivery(url, event, secret);
+    res = defaultDelivery.current ? await defaultDelivery.current(url, event) : await httpAuthRequestDelivery(url, event, secret);
   } catch (e) {
-    const name = e instanceof Error ? e.name : '';
-    if (name === 'TimeoutError' || name === 'AbortError') {
-      return { kind: 'timeout', message: 'Webhook endpoint did not respond within the real-time authorization window.' };
-    }
-    // No response ever reached us (connection refused, DNS, socket reset) — like an
-    // endpoint that never answered inside the window: a timeout, not an invalid response.
-    return { kind: 'timeout', message: 'Webhook endpoint was unreachable within the real-time authorization window.' };
+    // no answer inside the window: cut off (TimeoutError, AbortError), or never reached (refused, DNS, reset), alike
+    return (e instanceof Error && (e.name === 'TimeoutError' || e.name === 'AbortError')) ? TIMED_OUT : UNREACHED;
   }
+  return readDecision(res);
+}
+
+const TIMED_OUT: StripeAuthRequestOutcome = { kind: 'timeout', message: 'Webhook endpoint did not respond within the real-time authorization window.' };
+const UNREACHED: StripeAuthRequestOutcome = { kind: 'timeout', message: 'Webhook endpoint was unreachable within the real-time authorization window.' };
+
+/** The endpoint's synchronous answer read as the decision: `approved` (and an optional `amount`), or an error for an
+ *  answer Stripe cannot read. */
+function readDecision(res: void | StripeWebhookEndpointResponse): StripeAuthRequestOutcome {
   if (!res || typeof res !== 'object') {
     return { kind: 'error', message: 'Webhook endpoint returned no response body.' };
   }
@@ -348,24 +399,31 @@ export async function requestAuthorizationDecision(url: string, event: StripeEve
 export async function emitStripeEvent(
   operation: string,
   resource: Record<string, unknown>,
-  opts: { occurredAt: string; deliver?: StripeEventDelivery } = { occurredAt: '1970-01-01T00:00:00.000Z' },
+  opts: { occurredAt: string; deliver?: StripeEventDelivery; endpoints?: StripeWebhookTarget[]; account?: string; /** the id the stored event takes (afterStripeWrite) */ id?: string } = { occurredAt: '1970-01-01T00:00:00.000Z' },
 ): Promise<StripeEvent[]> {
   const type = eventTypeFor(operation);
-  if (!type || registry.length === 0) return [];
-  const deliver = opts.deliver ?? defaultDelivery ?? httpDelivery;
+  // the World's own endpoints (its tree is the record), then any URL a host registered directly
+  const targets: StripeWebhookTarget[] = [...(opts.endpoints ?? [])];
+  for (const url of registry) if (!targets.some((t) => t.url === url)) targets.push({ url, ...(secrets.has(url) ? { secret: secrets.get(url)! } : {}), ...(subscriptions.has(url) ? { enabledEvents: subscriptions.get(url)! } : {}) });
+  if (!type || targets.length === 0) return [];
+  const deliver = opts.deliver ?? defaultDelivery.current ?? httpDelivery;
   const event: StripeEvent = {
-    id: `evt_twin_${++counter}`,
+    id: opts.id ?? eventId(operation, resource, opts.occurredAt, opts.account),
     object: 'event',
     type,
     created: Math.floor(Date.parse(opts.occurredAt) / 1000) || 0,
     livemode: false,
     data: { object: resource },
+    // "Each event for a connected account contains a top-level `account` property that identifies the connected account"
+    ...(opts.account ? { account: opts.account } : {}),
   };
   const out: StripeEvent[] = [];
-  for (const url of registry) {
-    const enabled = subscriptions.get(url);
-    if (enabled && !stripeEventMatches(enabled, type)) continue;
-    await deliver(url, event);
+  for (const target of targets) {
+    if (target.enabledEvents && !stripeEventMatches(target.enabledEvents, type)) continue;
+    // an endpoint's scope (docs.stripe.com/connect/webhooks): `connect: true` receives the Connected accounts scope,
+    // `connect: false` Your account; a URL registered without a scope (a host's seam) receives both
+    if (target.connect !== undefined && target.connect !== Boolean(opts.account)) continue;
+    await deliver(target.url, event, target.secret);
     out.push(event);
   }
   return out;

package/src/stripe-js.ts

@@ -0,0 +1,70 @@
+// STRIPE.JS — the client library an application's page loads from js.stripe.com (docs/contributing/architecture.md,
+// "Screens": a widget the vendor ships into the application's own page "is not a screen: it is a client library,
+// twinned from its published types as an SDK surface is"). Written from @stripe/stripe-js's published loader and types
+// (7.x: dist/index.mjs, dist/stripe-js/stripe.d.ts, dist/stripe-js/hosted-checkout.d.ts), nothing of Stripe's script
+// copied:
+//   - the loader injects https://js.stripe.com/<release train>/stripe.js (or /v3/), and accepts a script already on the
+//     page whose src matches `/^https:\/\/js\.stripe\.com\/(v3|[a-z]+)\/stripe\.js(\?.*)?$/` (so /v3/stripe.js too);
+//     it resolves `window.Stripe`, reads `Stripe.version` (3 is the v3 URL, otherwise the train's name) and calls the
+//     instance's `_registerWrapper` when it has one;
+//   - `stripe.redirectToCheckout({ sessionId })` sends the customer to that Checkout Session's page (hosted-checkout.d.ts,
+//     RedirectToCheckoutServerOptions), which this twin serves at checkout.stripe.com/c/pay/{id} (screens/checkout.tsx),
+//     and its promise settles only on failure (`Promise<never | {error}>`);
+//   - `stripe.collectFinancialConnectionsAccounts({ clientSecret })` loads the Financial Connections authentication
+//     flow for the session whose client_secret it is (stripe.d.ts; docs.stripe.com/js/financial_connections/
+//     collect_financial_connections_accounts: "it will load the Authentication Flow, an on-page modal UI"). Where the
+//     twin decides: it navigates to the flow's page, js.stripe.com/v3/financial-connections/{client_secret}
+//     (screens/financial-connections.tsx), instead of a modal, so its promise does not settle; the flow returns the
+//     holder to the session's return_url, where the application reads the session's accounts.
+// Demand: Dub's upgrade button (apps/web/ui/workspaces/upgrade-plan-button.tsx) creates a session on its server and
+// calls redirectToCheckout. Every other member of the library throws, naming itself, when called: an application
+// reaching one finds the gap instead of a silent no-op.
+
+/** The release train a script path names: `/v3`, `/v3/` or `/v3/stripe.js` → 3, `/<train>/stripe.js` → the train. */
+export function stripeJsTrain(pathname: string): 3 | string | undefined {
+  if (/^\/v3(\/|\/stripe\.js)?$/.test(pathname)) return 3;
+  return /^\/([a-z]+)\/stripe\.js$/.exec(pathname)?.[1];
+}
+
+function script(version: 3 | string): string {
+  return `(function () {
+  var version = ${JSON.stringify(version)};
+  function gap(name) {
+    return function () { throw new Error("Stripe.js (Volter twin): stripe." + name + " is not modelled by this twin yet"); };
+  }
+  function Stripe(publishableKey) {
+    if (typeof publishableKey !== "string" || !publishableKey) throw new Error("Stripe.js (Volter twin): Stripe() needs a publishable key");
+    var known = {
+      _registerWrapper: function () {},
+      redirectToCheckout: function (options) {
+        if (!options || typeof options.sessionId !== "string" || !options.sessionId) return gap("redirectToCheckout without a sessionId")();
+        window.location.assign("https://checkout.stripe.com/c/pay/" + encodeURIComponent(options.sessionId));
+        return new Promise(function () {});
+      },
+      collectFinancialConnectionsAccounts: function (options) {
+        if (!options || typeof options.clientSecret !== "string" || !options.clientSecret) return gap("collectFinancialConnectionsAccounts without a clientSecret")();
+        window.location.assign("https://js.stripe.com/v3/financial-connections/" + encodeURIComponent(options.clientSecret));
+        return new Promise(function () {});
+      }
+    };
+    return new Proxy(known, {
+      get: function (target, name) {
+        if (name in target) return target[name];
+        if (typeof name === "symbol" || name === "then") return undefined;
+        return gap(String(name));
+      }
+    });
+  }
+  Stripe.version = version;
+  window.Stripe = Stripe;
+})();
+`;
+}
+
+/** js.stripe.com's script for a GET of its path, or undefined for any other request. */
+export function stripeJs(request: Request): Response | undefined {
+  if (request.method !== 'GET') return undefined;
+  const train = stripeJsTrain(new URL(request.url).pathname);
+  if (train === undefined) return undefined;
+  return new Response(script(train), { headers: { 'content-type': 'application/javascript; charset=utf-8', 'access-control-allow-origin': '*' } });
+}