@volter/twin-stripe 0.1.2 → 2.0.1

package/src/stripe-conformance.ts

@@ -10,10 +10,12 @@
 // 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';
+import { INCLUDABLE_FIELDS, render } from './stripe-version.ts';
 
 type JsonSchema = specConformance.JsonSchema;
 type KnownDeviation = specConformance.KnownDeviation;
@@ -42,6 +44,8 @@ export type StripeConformanceReport = {
   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('_');
@@ -50,21 +54,27 @@ const fixturePath = (name: string): string => new URL(`../test-fixtures/${name}`
 // 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;
-  return out;
+  // 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 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;
 }
 
@@ -78,6 +88,7 @@ export function checkStripeConformance(schemas: StripeSchemas, opts: { root?: st
   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;
@@ -85,10 +96,11 @@ export function checkStripeConformance(schemas: StripeSchemas, opts: { root?: st
     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 };
+  return { ok: violations.length === 0, resourcesChecked: resources.length, fieldsChecked, violations, knownIgnored, fieldsByType };
 }
 
 export type StripeCoverageReport = specConformance.SpecCoverageReport & { object: string };

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, worldNow, 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(
@@ -125,7 +127,11 @@ export const stripeEmitter: TwinEmitter = {
     const endpointRow = liveEndpointRows(root).find((w) => String(w.id) === endpoint.id || String(w.url) === endpoint.url);
     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);
+    const created = occurredAt ? Math.floor(Date.parse(occurredAt) / 1000) : Math.floor(Date.parse(worldNow()) / 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,8 @@
+import { nodeBuiltin, worldNow } from '@volter/world-core';
+import { appDestination, appFetch } from '@volter/world-core/app-route';
+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 +15,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 +24,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 +42,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. */
@@ -43,7 +52,8 @@ export function computeStripeSignature(payload: string, secret: string, timestam
 
 /** Build a `Stripe-Signature` header value for `payload` (mirrors generateTestHeaderString). */
 export function generateTestHeaderString(opts: { payload: string; secret: string; timestamp?: number; scheme?: string }): string {
-  const timestamp = opts.timestamp ?? Math.floor(Date.now() / 1000);
+  // signed at the World's time, as its application reads the time (a moved World clock; the app keeps it too)
+  const timestamp = opts.timestamp ?? Math.floor(Date.parse(worldNow()) / 1000);
   const scheme = opts.scheme ?? 'v1';
   const signature = computeStripeSignature(opts.payload, opts.secret, timestamp);
   return `t=${timestamp},${scheme}=${signature}`;
@@ -93,7 +103,7 @@ export function constructEvent(payload: string, header: string, secret: string,
     throw new StripeSignatureVerificationError('No signatures found matching the expected signature for payload.');
   }
   if (opts.tolerance !== undefined) {
-    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    const now = opts.now ?? Math.floor(Date.parse(worldNow()) / 1000);
     if (now - timestamp > opts.tolerance) {
       throw new StripeSignatureVerificationError('Timestamp outside the tolerance zone');
     }
@@ -102,15 +112,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 +155,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 +166,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 +201,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 +217,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,14 +257,24 @@ 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; the application's own hostnames
+  // reach it inside the World
+  const refusal = appDestination(url) ? null : 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 {
       const header = generateTestHeaderString({ payload, secret });
-      await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', 'stripe-signature': header }, body: payload });
+      await appFetch(url, { method: 'POST', headers: { 'content-type': 'application/json', 'stripe-signature': header }, body: payload });
       return;
     } catch (error) {
       last = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
@@ -241,16 +282,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,9 +325,18 @@ 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 });
-  const res = await fetch(url, {
+  // the World's egress rule: a refused endpoint is an unreachable one (the caller's timeout fallback); the
+  // application's own hostnames reach it inside the World
+  const refusal = appDestination(url) ? null : 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 appFetch(url, {
     method: 'POST',
     headers: { 'content-type': 'application/json', 'stripe-signature': header },
     body: payload,
@@ -304,16 +355,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 +403,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;