@volter/twin-polar 0.1.0

package/src/polar-twin.ts

@@ -0,0 +1,828 @@
+// Polar API twin REQUEST HANDLER — the canonical api.polar.sh surface for the twin, backed by
+// the event/action-log kernel (@volter/twin). Contract:
+//   handlePolarTwinRequest({ method, path, body, root, readOnly }) -> { status, body }
+// Response SHAPES mirror real Polar (UUID4 ids, `{ items, pagination }` list envelopes, the
+// FastAPI-style error envelopes) so the real `@polar-sh/sdk` works unmodified. HTTP wrapper:
+// polar-server.ts → createPolarTwinServer.
+//
+// State lives ENTIRELY in the kernel action log: writes go through `applyTwinWrite`, reads are
+// the projection (`projectResources`). There is NO Map/array side-store — the projection over
+// the append-only log is the single source of truth (D1). No real Polar is ever contacted.
+//
+// Honesty (D2): an unmodeled route/op returns Polar's REAL error envelope (ResourceNotFound /
+// HTTPValidationError), never a fabricated `{ ok: true }`. readOnly rejects writes with 405.
+//
+// Kernel SUBJECT ids are type-prefixed (`customer:<uuid>`) — a pack convention that keeps
+// subject ids self-describing (the kernel resolves writes by (type, id), so the prefix is not
+// required for correctness) — while the PUBLIC `id` emitted to clients is the bare UUID4 that
+// Polar returns. `kid()` builds the subject id; rows() strips the prefix back off for the view.
+import { createHash } from 'node:crypto';
+import { applyTwinWrite, projectResources, worldNow } from '@volter/twin';
+
+const SERVICE = 'polar';
+const ORG_ID = '00000000-0000-4000-8000-0000000000a1'; // the twin's single organization id
+
+export type PolarRequest = {
+  method: string;
+  path: string;
+  body?: string;
+  occurredAt?: string;
+  root?: string;
+  readOnly?: boolean;
+};
+export type PolarResponse = { status: number; body: unknown; headers?: Record<string, string> };
+
+// Resource types the twin serves (kernel subject `type`s). The PUBLIC ids are bare UUIDs; the
+// kernel subject id is `${type}:${uuid}` (collision-safe).
+export const POLAR_RESOURCE_TYPES = [
+  'customer', 'product', 'subscription', 'order', 'checkout', 'benefit',
+  'discount', 'customer_session', 'event', 'meter', 'webhook_endpoint',
+] as const;
+export type PolarResourceType = typeof POLAR_RESOURCE_TYPES[number];
+
+// ── error envelopes (Polar / FastAPI shapes, D2) ─────────────────────────────────────
+// Polar returns `{ type: 'ResourceNotFound', detail: '... not found.' }` for 404 and a
+// FastAPI `HTTPValidationError` (`{ detail: [{ type, loc, msg }] }`) for 422.
+function notFound(detail: string): PolarResponse {
+  return { status: 404, body: { type: 'ResourceNotFound', detail } };
+}
+function validationError(loc: (string | number)[], msg: string, type = 'value_error'): PolarResponse {
+  return { status: 422, body: { detail: [{ type, loc: ['body', ...loc], msg, input: null }] } };
+}
+function notPermitted(detail: string): PolarResponse {
+  return { status: 403, body: { type: 'NotPermitted', detail } };
+}
+
+// ── body / time / id helpers ─────────────────────────────────────────────────────────
+function parseBody(body?: string): Record<string, unknown> {
+  if (!body) return {};
+  try {
+    const v = JSON.parse(body);
+    return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+/** The instant this request happened at: the caller's `occurredAt` (the kernel fetch adapter
+ *  stamps it from the world clock) or, for a direct in-process call that supplies none, the WORLD
+ *  clock — never `new Date()`. Every stored/served timestamp and every minted id derives from it. */
+function nowIso(occurredAt?: string): string {
+  return occurredAt ?? worldNow();
+}
+function laterIso(occurredAt?: string): string {
+  return new Date(Date.parse(nowIso(occurredAt)) + 30 * 24 * 60 * 60 * 1000).toISOString();
+}
+
+// ── ids: DERIVED FROM THE WRITE, never drawn ─────────────────────────────────────────
+// Polar's public ids are bare UUID4s, so the SHAPE is a uuid4 (version nibble `4`, variant
+// nibble `8`-`b`). The BITS are a SHA-256 of the write — the subject type, the world instant the
+// request occurred at, and the ordinal the subject takes among its type — never `Math.random`.
+//
+// That is invariant R9 at the resource level: a served id must be a function of (request, stored
+// state) and of nothing else, so two identical worlds replaying the same writes serve the same
+// bytes. The earlier version drew every id from `Math.random` and called collisions the only
+// risk; the real cost was that a replay could never be compared at all, and one `Math.random`
+// sat on a READ path (`/customers/:id/state`'s `active_meters[].id`), so the same GET differed
+// between two serves of unchanged state.
+//
+// The ordinal is the count of live rows of that type BEFORE the insert, which is what keeps two
+// subjects created in the SAME millisecond apart; every call site mints and then AWAITS its
+// write, so the next mint of that type sees a count one larger.
+function digest(kind: string, seed: string): string {
+  return createHash('sha256').update(`polar-twin-id:${kind}:${seed}`).digest('hex');
+}
+function uuidFrom(kind: string, seed: string): string {
+  const h = digest(kind, seed);
+  const variant = ((parseInt(h[16]!, 16) & 0x3) | 0x8).toString(16);
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-${variant}${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+/** The public id for a NEW subject of `type`, derived from this request and the ordinal it takes. */
+function mintId(type: string, req: PolarRequest, extra = ''): string {
+  return uuidFrom(type, `${nowIso(req.occurredAt)}:${rows(type, req.root).length}:${extra}`);
+}
+/** A 32-hex secret (session token, checkout client secret), derived the same way. */
+function mintSecret(kind: string, req: PolarRequest, extra = ''): string {
+  return digest(kind, `${nowIso(req.occurredAt)}:${extra}`).slice(0, 32);
+}
+// Kernel subject id (type-prefixed → collision-safe across types).
+function kid(type: string, id: string): string {
+  return `${type}:${id}`;
+}
+
+// ── projection helpers ──────────────────────────────────────────────────────────────
+// Live (non-soft-deleted) rows of a type, with the kernel subject prefix stripped back to the
+// bare public id. `_deleted` is the twin-internal soft-delete overlay (the log is append-only).
+function rows(type: string, root?: string): Array<Record<string, unknown>> {
+  const prefix = `${type}:`;
+  return projectResources(SERVICE, root)
+    .filter((r) => r.type === type && r.id.startsWith(prefix) && (r as Record<string, unknown>)._deleted !== true)
+    .map((r) => ({ ...r, id: r.id.slice(prefix.length) }));
+}
+function getRow(type: string, id: string, root?: string): Record<string, unknown> | undefined {
+  return rows(type, root).find((r) => r.id === id);
+}
+// The client view: drop kernel meta (`type`, `updatedAt`) + twin-internal `_`-prefixed fields.
+function view(r: Record<string, unknown>): Record<string, unknown> {
+  const { type: _t, updatedAt: _u, ...rest } = r;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(rest)) if (!k.startsWith('_')) out[k] = v;
+  return out;
+}
+
+async function write(
+  type: string,
+  id: string,
+  fields: Record<string, unknown>,
+  op: string,
+  req: PolarRequest,
+): Promise<Record<string, unknown>> {
+  const { resource } = await applyTwinWrite(
+    SERVICE,
+    { operation: op, subjectType: type, subjectId: kid(type, id), fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } },
+    req.root,
+  );
+  return view({ ...resource, id });
+}
+
+// Polar's list envelope: `{ items: [...], pagination: { total_count, max_page } }`.
+function listEnvelope(items: unknown[]): { items: unknown[]; pagination: { total_count: number; max_page: number } } {
+  return { items, pagination: { total_count: items.length, max_page: items.length > 0 ? 1 : 0 } };
+}
+
+// ── object shapes (mirror real Polar response bodies) ────────────────────────────────
+function customerView(r: Record<string, unknown>): Record<string, unknown> {
+  const v = view(r);
+  return {
+    id: v.id,
+    created_at: v.created_at,
+    modified_at: v.modified_at ?? null,
+    metadata: v.metadata ?? {},
+    external_id: v.external_id ?? null,
+    email: v.email ?? null,
+    email_verified: v.email_verified ?? false,
+    type: v.customer_type ?? 'individual',
+    name: v.name ?? null,
+    billing_name: v.billing_name ?? null,
+    billing_address: v.billing_address ?? null,
+    tax_id: v.tax_id ?? null,
+    locale: v.locale ?? 'en',
+    organization_id: ORG_ID,
+    default_payment_method_id: null,
+    deleted_at: null,
+    avatar_url: `https://www.gravatar.com/avatar?d=blank`,
+  };
+}
+
+function productView(r: Record<string, unknown>): Record<string, unknown> {
+  const v = view(r);
+  return {
+    id: v.id,
+    created_at: v.created_at,
+    modified_at: v.modified_at ?? null,
+    name: v.name ?? null,
+    description: v.description ?? null,
+    recurring_interval: v.recurring_interval ?? null,
+    is_recurring: v.recurring_interval != null,
+    is_archived: v.is_archived ?? false,
+    organization_id: ORG_ID,
+    metadata: v.metadata ?? {},
+    prices: Array.isArray(v.prices) ? v.prices : [],
+    benefits: Array.isArray(v.benefits) ? v.benefits : [],
+    medias: [],
+    attached_custom_fields: [],
+  };
+}
+
+function subscriptionView(r: Record<string, unknown>, root?: string): Record<string, unknown> {
+  const v = view(r);
+  const cust = v.customer_id ? getRow('customer', String(v.customer_id), root) : undefined;
+  return {
+    id: v.id,
+    created_at: v.created_at,
+    modified_at: v.modified_at ?? null,
+    amount: v.amount ?? 0,
+    currency: v.currency ?? 'usd',
+    recurring_interval: v.recurring_interval ?? 'month',
+    status: v.status ?? 'active',
+    current_period_start: v.current_period_start ?? v.created_at,
+    current_period_end: v.current_period_end ?? null,
+    cancel_at_period_end: v.cancel_at_period_end ?? false,
+    canceled_at: v.canceled_at ?? null,
+    started_at: v.started_at ?? v.created_at,
+    ends_at: v.ends_at ?? null,
+    ended_at: v.ended_at ?? null,
+    customer_id: v.customer_id ?? null,
+    product_id: v.product_id ?? null,
+    discount_id: v.discount_id ?? null,
+    checkout_id: v.checkout_id ?? null,
+    metadata: v.metadata ?? {},
+    customer: cust ? customerView(cust) : null,
+    prices: [],
+  };
+}
+
+function orderView(r: Record<string, unknown>): Record<string, unknown> {
+  const v = view(r);
+  return {
+    id: v.id,
+    created_at: v.created_at,
+    modified_at: v.modified_at ?? null,
+    status: v.status ?? 'paid',
+    paid: v.status === 'refunded' ? false : (v.paid ?? true),
+    subtotal_amount: v.subtotal_amount ?? v.amount ?? 0,
+    discount_amount: v.discount_amount ?? 0,
+    net_amount: v.net_amount ?? v.amount ?? 0,
+    tax_amount: v.tax_amount ?? 0,
+    total_amount: v.total_amount ?? v.amount ?? 0,
+    refunded_amount: v.refunded_amount ?? 0,
+    currency: v.currency ?? 'usd',
+    billing_reason: v.billing_reason ?? 'purchase',
+    customer_id: v.customer_id ?? null,
+    product_id: v.product_id ?? null,
+    subscription_id: v.subscription_id ?? null,
+    checkout_id: v.checkout_id ?? null,
+    metadata: v.metadata ?? {},
+  };
+}
+
+function checkoutView(r: Record<string, unknown>): Record<string, unknown> {
+  const v = view(r);
+  return {
+    id: v.id,
+    created_at: v.created_at,
+    modified_at: v.modified_at ?? null,
+    payment_processor: 'stripe',
+    status: v.status ?? 'open',
+    client_secret: v.client_secret,
+    url: v.url,
+    expires_at: v.expires_at,
+    success_url: v.success_url ?? null,
+    embed_origin: v.embed_origin ?? null,
+    amount: v.amount ?? 0,
+    discount_amount: 0,
+    net_amount: v.amount ?? 0,
+    tax_amount: 0,
+    total_amount: v.amount ?? 0,
+    currency: v.currency ?? 'usd',
+    product_id: v.product_id ?? null,
+    products: Array.isArray(v.products) ? v.products : [],
+    discount_id: v.discount_id ?? null,
+    customer_id: v.customer_id ?? null,
+    customer_email: v.customer_email ?? null,
+    customer_name: v.customer_name ?? null,
+    subscription_id: v.subscription_id ?? null,
+    organization_id: ORG_ID,
+    metadata: v.metadata ?? {},
+    customer_metadata: {},
+  };
+}
+
+function benefitView(r: Record<string, unknown>): Record<string, unknown> {
+  const v = view(r);
+  return {
+    id: v.id,
+    created_at: v.created_at,
+    modified_at: v.modified_at ?? null,
+    type: v.benefit_type ?? 'custom',
+    description: v.description ?? null,
+    selectable: v.selectable ?? true,
+    deletable: v.deletable ?? true,
+    organization_id: ORG_ID,
+    properties: v.properties ?? {},
+    metadata: v.metadata ?? {},
+  };
+}
+
+function discountView(r: Record<string, unknown>): Record<string, unknown> {
+  const v = view(r);
+  return {
+    id: v.id,
+    created_at: v.created_at,
+    modified_at: v.modified_at ?? null,
+    name: v.name ?? null,
+    code: v.code ?? null,
+    type: v.discount_type ?? 'percentage',
+    basis_points: v.basis_points ?? null,
+    amount: v.amount ?? null,
+    currency: v.currency ?? null,
+    duration: v.duration ?? 'once',
+    max_redemptions: v.max_redemptions ?? null,
+    redemptions_count: v.redemptions_count ?? 0,
+    organization_id: ORG_ID,
+    metadata: v.metadata ?? {},
+  };
+}
+
+function meterView(r: Record<string, unknown>): Record<string, unknown> {
+  const v = view(r);
+  return {
+    id: v.id,
+    created_at: v.created_at,
+    modified_at: v.modified_at ?? null,
+    name: v.name ?? null,
+    aggregation: v.aggregation ?? { func: 'count' },
+    filter: v.filter ?? { conjunction: 'and', clauses: [] },
+    organization_id: ORG_ID,
+    metadata: v.metadata ?? {},
+  };
+}
+
+function eventView(r: Record<string, unknown>): Record<string, unknown> {
+  const v = view(r);
+  return {
+    id: v.id,
+    timestamp: v.timestamp ?? v.created_at,
+    organization_id: ORG_ID,
+    customer_id: v.customer_id ?? null,
+    external_customer_id: v.external_customer_id ?? null,
+    name: v.name ?? null,
+    source: v.source ?? 'user',
+    metadata: v.metadata ?? {},
+  };
+}
+
+function webhookView(r: Record<string, unknown>): Record<string, unknown> {
+  const v = view(r);
+  return {
+    id: v.id,
+    created_at: v.created_at,
+    modified_at: v.modified_at ?? null,
+    url: v.url ?? null,
+    format: v.format ?? 'raw',
+    events: Array.isArray(v.events) ? v.events : [],
+    organization_id: ORG_ID,
+  };
+}
+
+// ── customer state (meter balances) ──────────────────────────────────────────────────
+function customerState(customerId: string, root?: string): Record<string, unknown> {
+  const cust = getRow('customer', customerId, root);
+  const subs = rows('subscription', root)
+    .filter((s) => s.customer_id === customerId && s.status === 'active')
+    .map((s) => subscriptionView(s, root));
+  const meters = rows('event', root)
+    .filter((e) => e.customer_id === customerId)
+    .reduce<{ consumed: number; credited: number }>((acc, e) => {
+      const cost = Number((e.metadata as Record<string, unknown>)?.cost_usd ?? 0);
+      if (Number.isFinite(cost)) { if (cost < 0) acc.credited += Math.abs(cost); else acc.consumed += cost; }
+      return acc;
+    }, { consumed: 0, credited: 0 });
+  return {
+    ...(cust ? customerView(cust) : { id: customerId }),
+    active_subscriptions: subs,
+    granted_benefits: [],
+    active_meters: [{
+      id: uuidFrom('customer_meter', customerId),
+      meter_id: '00000000-0000-4000-8000-0000000000b1',
+      consumed_units: meters.consumed,
+      credited_units: meters.credited,
+      balance: meters.credited - meters.consumed,
+    }],
+  };
+}
+
+// ── route handler ────────────────────────────────────────────────────────────────────
+export async function handlePolarTwinRequest(req: PolarRequest): Promise<PolarResponse> {
+  const method = req.method.toUpperCase();
+  const [rawPath, rawQuery] = req.path.split('?');
+  const path = (rawPath ?? '/').replace(/\/+$/, '') || '/';
+  const query = Object.fromEntries(new URLSearchParams(rawQuery ?? ''));
+  const body = parseBody(req.body);
+  // segments after the /v1 prefix, e.g. /v1/customers/abc → ["customers","abc"]
+  const all = path.replace(/^\/+/, '').split('/').filter(Boolean);
+  const seg = all[0] === 'v1' ? all.slice(1) : all;
+  const idAt = (i: number) => decodeURIComponent(seg[i] ?? '');
+
+  if (req.readOnly && method !== 'GET') {
+    return { status: 405, body: { type: 'NotPermitted', detail: 'twin is read-only; omit readOnly to accept writes' } };
+  }
+
+  if (path === '/' || seg.length === 0) {
+    return { status: 200, body: { service: 'polar', object: 'twin', organization_id: ORG_ID } };
+  }
+
+  // ── CUSTOMERS ──
+  if (seg[0] === 'customers') {
+    if (seg.length === 1 && method === 'POST') {
+      if (!body.email && (body.type ?? 'individual') === 'individual') {
+        return validationError(['email'], 'Field required', 'missing');
+      }
+      const email = body.email ? String(body.email) : null;
+      if (email && rows('customer', req.root).some((c) => c.email === email)) {
+        return { status: 422, body: { type: 'PolarRequestValidationError', detail: [{ type: 'value_error', loc: ['body', 'email'], msg: 'A customer with this email address already exists.' }] } };
+      }
+      const id = mintId('customer', req);
+      const c = await write('customer', id, {
+        created_at: nowIso(req.occurredAt), modified_at: null,
+        email, name: body.name ?? null, external_id: body.external_id ?? null,
+        customer_type: body.type ?? 'individual', email_verified: false,
+        billing_name: body.billing_name ?? null, billing_address: body.billing_address ?? null,
+        tax_id: body.tax_id ?? null, locale: body.locale ?? 'en',
+        metadata: body.metadata ?? {},
+      }, 'customer.create', req);
+      return { status: 201, body: customerView({ ...c, type: 'customer' }) };
+    }
+    if (seg.length === 1 && method === 'GET') {
+      const email = query.email;
+      const extId = query.external_id;
+      const items = rows('customer', req.root)
+        .filter((c) => (!email || c.email === email) && (!extId || c.external_id === extId))
+        .map((c) => customerView({ ...c, type: 'customer' }));
+      return { status: 200, body: listEnvelope(items) };
+    }
+    // GET /customers/:id/state
+    if (seg.length === 3 && seg[2] === 'state' && method === 'GET') {
+      if (!getRow('customer', idAt(1), req.root)) return notFound('Customer not found.');
+      return { status: 200, body: customerState(idAt(1), req.root) };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      const c = getRow('customer', idAt(1), req.root);
+      return c ? { status: 200, body: customerView({ ...c, type: 'customer' }) } : notFound('Customer not found.');
+    }
+    if (seg.length === 2 && method === 'PATCH') {
+      const c = getRow('customer', idAt(1), req.root);
+      if (!c) return notFound('Customer not found.');
+      const patch: Record<string, unknown> = { modified_at: nowIso(req.occurredAt) };
+      for (const k of ['email', 'name', 'external_id', 'billing_name', 'billing_address', 'tax_id', 'locale', 'metadata']) if (k in body) patch[k] = body[k];
+      const updated = await write('customer', idAt(1), patch, 'customer.update', req);
+      return { status: 200, body: customerView({ ...updated, type: 'customer' }) };
+    }
+    if (seg.length === 2 && method === 'DELETE') {
+      const c = getRow('customer', idAt(1), req.root);
+      if (!c) return notFound('Customer not found.');
+      await write('customer', idAt(1), { _deleted: true }, 'customer.delete', req);
+      return { status: 204, body: null };
+    }
+  }
+
+  // ── PRODUCTS ──
+  if (seg[0] === 'products') {
+    if (seg.length === 1 && method === 'POST') {
+      if (!body.name) return validationError(['name'], 'Field required', 'missing');
+      const prices = Array.isArray(body.prices)
+        ? (body.prices as Array<Record<string, unknown>>).map((p, i) => ({ id: uuidFrom('price', `${nowIso(req.occurredAt)}:${rows('product', req.root).length}:${i}`), ...p }))
+        : [];
+      const id = mintId('product', req);
+      const p = await write('product', id, {
+        created_at: nowIso(req.occurredAt), modified_at: null,
+        name: body.name, description: body.description ?? null,
+        recurring_interval: body.recurring_interval ?? null,
+        is_archived: false, prices, benefits: [], metadata: body.metadata ?? {},
+      }, 'product.create', req);
+      return { status: 201, body: productView({ ...p, type: 'product' }) };
+    }
+    if (seg.length === 1 && method === 'GET') {
+      let items = rows('product', req.root);
+      if (query.is_archived !== undefined) items = items.filter((p) => Boolean(p.is_archived) === (query.is_archived === 'true'));
+      return { status: 200, body: listEnvelope(items.map((p) => productView({ ...p, type: 'product' }))) };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      const p = getRow('product', idAt(1), req.root);
+      return p ? { status: 200, body: productView({ ...p, type: 'product' }) } : notFound('Product not found.');
+    }
+    if (seg.length === 2 && method === 'PATCH') {
+      const p = getRow('product', idAt(1), req.root);
+      if (!p) return notFound('Product not found.');
+      const patch: Record<string, unknown> = { modified_at: nowIso(req.occurredAt) };
+      for (const k of ['name', 'description', 'recurring_interval', 'is_archived', 'metadata']) if (k in body) patch[k] = body[k];
+      const updated = await write('product', idAt(1), patch, 'product.update', req);
+      return { status: 200, body: productView({ ...updated, type: 'product' }) };
+    }
+  }
+
+  // ── BENEFITS ──
+  if (seg[0] === 'benefits') {
+    if (seg.length === 1 && method === 'POST') {
+      if (!body.type) return validationError(['type'], 'Field required', 'missing');
+      const id = mintId('benefit', req);
+      const b = await write('benefit', id, {
+        created_at: nowIso(req.occurredAt), modified_at: null,
+        benefit_type: body.type, description: body.description ?? null,
+        properties: body.properties ?? {}, metadata: body.metadata ?? {},
+      }, 'benefit.create', req);
+      return { status: 201, body: benefitView({ ...b, type: 'benefit' }) };
+    }
+    if (seg.length === 1 && method === 'GET') {
+      return { status: 200, body: listEnvelope(rows('benefit', req.root).map((b) => benefitView({ ...b, type: 'benefit' }))) };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      const b = getRow('benefit', idAt(1), req.root);
+      return b ? { status: 200, body: benefitView({ ...b, type: 'benefit' }) } : notFound('Benefit not found.');
+    }
+    if (seg.length === 2 && method === 'DELETE') {
+      const b = getRow('benefit', idAt(1), req.root);
+      if (!b) return notFound('Benefit not found.');
+      await write('benefit', idAt(1), { _deleted: true }, 'benefit.delete', req);
+      return { status: 204, body: null };
+    }
+  }
+
+  // ── DISCOUNTS ──
+  if (seg[0] === 'discounts') {
+    if (seg.length === 1 && method === 'POST') {
+      if (!body.name) return validationError(['name'], 'Field required', 'missing');
+      if (!body.type) return validationError(['type'], 'Field required', 'missing');
+      const id = mintId('discount', req);
+      const d = await write('discount', id, {
+        created_at: nowIso(req.occurredAt), modified_at: null,
+        name: body.name, code: body.code ?? null, discount_type: body.type,
+        basis_points: body.basis_points ?? null, amount: body.amount ?? null,
+        currency: body.currency ?? null, duration: body.duration ?? 'once',
+        max_redemptions: body.max_redemptions ?? null, redemptions_count: 0,
+        metadata: body.metadata ?? {},
+      }, 'discount.create', req);
+      return { status: 201, body: discountView({ ...d, type: 'discount' }) };
+    }
+    if (seg.length === 1 && method === 'GET') {
+      return { status: 200, body: listEnvelope(rows('discount', req.root).map((d) => discountView({ ...d, type: 'discount' }))) };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      const d = getRow('discount', idAt(1), req.root);
+      return d ? { status: 200, body: discountView({ ...d, type: 'discount' }) } : notFound('Discount not found.');
+    }
+    if (seg.length === 2 && method === 'PATCH') {
+      const d = getRow('discount', idAt(1), req.root);
+      if (!d) return notFound('Discount not found.');
+      const patch: Record<string, unknown> = { modified_at: nowIso(req.occurredAt) };
+      for (const k of ['name', 'code', 'basis_points', 'amount', 'duration', 'max_redemptions', 'metadata']) if (k in body) patch[k] = body[k];
+      const updated = await write('discount', idAt(1), patch, 'discount.update', req);
+      return { status: 200, body: discountView({ ...updated, type: 'discount' }) };
+    }
+    if (seg.length === 2 && method === 'DELETE') {
+      const d = getRow('discount', idAt(1), req.root);
+      if (!d) return notFound('Discount not found.');
+      await write('discount', idAt(1), { _deleted: true }, 'discount.delete', req);
+      return { status: 204, body: null };
+    }
+  }
+
+  // ── METERS ──
+  if (seg[0] === 'meters') {
+    if (seg.length === 1 && method === 'POST') {
+      if (!body.name) return validationError(['name'], 'Field required', 'missing');
+      const id = mintId('meter', req);
+      const m = await write('meter', id, {
+        created_at: nowIso(req.occurredAt), modified_at: null,
+        name: body.name, aggregation: body.aggregation ?? { func: 'count' },
+        filter: body.filter ?? { conjunction: 'and', clauses: [] }, metadata: body.metadata ?? {},
+      }, 'meter.create', req);
+      return { status: 201, body: meterView({ ...m, type: 'meter' }) };
+    }
+    if (seg.length === 1 && method === 'GET') {
+      return { status: 200, body: listEnvelope(rows('meter', req.root).map((m) => meterView({ ...m, type: 'meter' }))) };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      const m = getRow('meter', idAt(1), req.root);
+      return m ? { status: 200, body: meterView({ ...m, type: 'meter' }) } : notFound('Meter not found.');
+    }
+  }
+
+  // ── EVENTS ──
+  if (seg[0] === 'events') {
+    // POST /events/ingest
+    if (seg.length === 2 && seg[1] === 'ingest' && method === 'POST') {
+      const events = Array.isArray(body.events) ? (body.events as Array<Record<string, unknown>>) : null;
+      if (!events) return validationError(['events'], 'Field required', 'missing');
+      let inserted = 0;
+      for (const e of events) {
+        if (!e.name) return validationError(['events', 'name'], 'Field required', 'missing');
+        const id = mintId('event', req);
+        await write('event', id, {
+          timestamp: e.timestamp ?? nowIso(req.occurredAt), created_at: nowIso(req.occurredAt),
+          name: e.name, customer_id: e.customer_id ?? null,
+          external_customer_id: e.external_customer_id ?? null,
+          source: 'user', metadata: e.metadata ?? {},
+        }, 'event.ingest', req);
+        inserted += 1;
+      }
+      return { status: 200, body: { inserted, duplicates: 0 } };
+    }
+    if (seg.length === 1 && method === 'GET') {
+      const customerId = query.customer_id;
+      const name = query.name;
+      const items = rows('event', req.root)
+        .filter((e) => (!customerId || e.customer_id === customerId) && (!name || e.name === name))
+        .map((e) => eventView({ ...e, type: 'event' }));
+      return { status: 200, body: listEnvelope(items) };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      const e = getRow('event', idAt(1), req.root);
+      return e ? { status: 200, body: eventView({ ...e, type: 'event' }) } : notFound('Event not found.');
+    }
+  }
+
+  // ── CUSTOMER SESSIONS ──
+  if (seg[0] === 'customer-sessions') {
+    if (seg.length === 1 && method === 'POST') {
+      const customerId = body.customer_id ? String(body.customer_id) : null;
+      const extId = body.external_customer_id ? String(body.external_customer_id) : null;
+      let cust = customerId ? getRow('customer', customerId, req.root) : undefined;
+      if (!cust && extId) cust = rows('customer', req.root).find((c) => c.external_id === extId);
+      if (!cust) return notFound('Customer not found.');
+      const id = mintId('customer_session', req, String(cust.id));
+      const token = `polar_cst_${mintSecret('customer_session_token', req, String(cust.id))}`;
+      const s = await write('customer_session', id, {
+        created_at: nowIso(req.occurredAt), modified_at: null,
+        token, expires_at: laterIso(req.occurredAt), customer_id: cust.id,
+        customer_portal_url: `https://polar.sh/twin/portal?customer_session_token=${token}`,
+      }, 'customer_session.create', req);
+      const v = view({ ...s, type: 'customer_session' });
+      return { status: 201, body: { ...v, customer: customerView({ ...cust, type: 'customer' }) } };
+    }
+  }
+
+  // ── CHECKOUTS ──
+  if (seg[0] === 'checkouts') {
+    if (seg.length === 1 && method === 'POST') {
+      const products = Array.isArray(body.products) ? (body.products as string[]) : (body.product_id ? [String(body.product_id)] : []);
+      if (products.length === 0) return validationError(['products'], 'Field required', 'missing');
+      const productId = products[0]!;
+      const product = getRow('product', productId, req.root);
+      const amount = product && Array.isArray(product.prices) && product.prices[0]
+        ? Number((product.prices[0] as Record<string, unknown>).price_amount ?? 1000)
+        : Number(body.amount ?? 1000);
+      const id = mintId('checkout', req);
+      const c = await write('checkout', id, {
+        created_at: nowIso(req.occurredAt), modified_at: null,
+        status: 'open', client_secret: `polar_checkout_${mintSecret('checkout_client_secret', req, id)}`,
+        url: `https://polar.sh/twin/checkout/${id}`, expires_at: laterIso(req.occurredAt),
+        success_url: body.success_url ?? null, embed_origin: body.embed_origin ?? null,
+        amount, currency: 'usd', product_id: productId, products,
+        customer_id: body.customer_id ?? null, customer_email: body.customer_email ?? null,
+        customer_name: body.customer_name ?? null, discount_id: body.discount_id ?? null,
+        metadata: body.metadata ?? {},
+      }, 'checkout.create', req);
+      return { status: 201, body: checkoutView({ ...c, type: 'checkout' }) };
+    }
+    if (seg.length === 1 && method === 'GET') {
+      return { status: 200, body: listEnvelope(rows('checkout', req.root).map((c) => checkoutView({ ...c, type: 'checkout' }))) };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      const c = getRow('checkout', idAt(1), req.root);
+      return c ? { status: 200, body: checkoutView({ ...c, type: 'checkout' }) } : notFound('Checkout not found.');
+    }
+    // POST /checkouts/:id/confirm — confirm the checkout: create customer (if needed),
+    // subscription/order, and flip the checkout to confirmed (the twin "completes" payment).
+    if (seg.length === 3 && seg[2] === 'confirm' && method === 'POST') {
+      const c = getRow('checkout', idAt(1), req.root);
+      if (!c) return notFound('Checkout not found.');
+      if (c.status !== 'open') return notPermitted('This checkout has already been confirmed.');
+      // Resolve / create the customer.
+      let customerId = c.customer_id ? String(c.customer_id) : null;
+      const email = body.customer_email ?? c.customer_email ?? null;
+      if (!customerId && email) {
+        const existing = rows('customer', req.root).find((x) => x.email === email);
+        if (existing) customerId = String(existing.id);
+        else {
+          const cid = mintId('customer', req);
+          await write('customer', cid, {
+            created_at: nowIso(req.occurredAt), modified_at: null, email,
+            name: body.customer_name ?? c.customer_name ?? null, external_id: null,
+            customer_type: 'individual', email_verified: false, locale: 'en', metadata: {},
+          }, 'customer.create', req);
+          customerId = cid;
+        }
+      }
+      const product = c.product_id ? getRow('product', String(c.product_id), req.root) : undefined;
+      const recurring = product?.recurring_interval ?? null;
+      const at = nowIso(req.occurredAt);
+      let subscriptionId: string | null = null;
+      if (recurring) {
+        subscriptionId = mintId('subscription', req);
+        await write('subscription', subscriptionId, {
+          created_at: at, modified_at: null, status: 'active',
+          amount: c.amount ?? 0, currency: 'usd', recurring_interval: recurring,
+          current_period_start: at, current_period_end: laterIso(req.occurredAt),
+          started_at: at, cancel_at_period_end: false, canceled_at: null,
+          customer_id: customerId, product_id: c.product_id, checkout_id: c.id, metadata: {},
+        }, 'subscription.create', req);
+      }
+      const orderId = mintId('order', req);
+      await write('order', orderId, {
+        created_at: at, modified_at: null, status: 'paid', paid: true,
+        amount: c.amount ?? 0, currency: 'usd', billing_reason: recurring ? 'subscription_create' : 'purchase',
+        customer_id: customerId, product_id: c.product_id, subscription_id: subscriptionId,
+        checkout_id: c.id, metadata: {},
+      }, 'order.create', req);
+      await write('checkout', idAt(1), { status: 'confirmed', modified_at: at, customer_id: customerId, subscription_id: subscriptionId }, 'checkout.confirm', req);
+      const updated = getRow('checkout', idAt(1), req.root)!;
+      return { status: 200, body: checkoutView({ ...updated, type: 'checkout' }) };
+    }
+  }
+
+  // ── SUBSCRIPTIONS ──
+  if (seg[0] === 'subscriptions') {
+    if (seg.length === 1 && method === 'GET') {
+      const customerId = query.customer_id;
+      const items = rows('subscription', req.root)
+        .filter((s) => !customerId || s.customer_id === customerId)
+        .map((s) => subscriptionView(s, req.root));
+      return { status: 200, body: listEnvelope(items) };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      const s = getRow('subscription', idAt(1), req.root);
+      return s ? { status: 200, body: subscriptionView(s, req.root) } : notFound('Subscription not found.');
+    }
+    if (seg.length === 2 && method === 'PATCH') {
+      const s = getRow('subscription', idAt(1), req.root);
+      if (!s) return notFound('Subscription not found.');
+      const patch: Record<string, unknown> = { modified_at: nowIso(req.occurredAt) };
+      if ('product_id' in body) patch.product_id = body.product_id;
+      if ('cancel_at_period_end' in body) {
+        patch.cancel_at_period_end = Boolean(body.cancel_at_period_end);
+        patch.canceled_at = body.cancel_at_period_end ? nowIso(req.occurredAt) : null;
+      }
+      if ('metadata' in body) patch.metadata = body.metadata;
+      if ('discount_id' in body) patch.discount_id = body.discount_id;
+      const updated = await write('subscription', idAt(1), patch, 'subscription.update', req);
+      return { status: 200, body: subscriptionView({ ...updated, customer_id: s.customer_id }, req.root) };
+    }
+    // DELETE /subscriptions/:id — cancel (immediately, or revoke). Polar returns the canceled sub.
+    if (seg.length === 2 && method === 'DELETE') {
+      const s = getRow('subscription', idAt(1), req.root);
+      if (!s) return notFound('Subscription not found.');
+      const at = nowIso(req.occurredAt);
+      const updated = await write('subscription', idAt(1), { status: 'canceled', canceled_at: at, ended_at: at, ends_at: at, modified_at: at }, 'subscription.cancel', req);
+      return { status: 200, body: subscriptionView({ ...updated, customer_id: s.customer_id }, req.root) };
+    }
+  }
+
+  // ── ORDERS ──
+  if (seg[0] === 'orders') {
+    if (seg.length === 1 && method === 'GET') {
+      const customerId = query.customer_id;
+      const subscriptionId = query.subscription_id;
+      const items = rows('order', req.root)
+        .filter((o) => (!customerId || o.customer_id === customerId) && (!subscriptionId || o.subscription_id === subscriptionId))
+        .map((o) => orderView({ ...o, type: 'order' }));
+      return { status: 200, body: listEnvelope(items) };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      const o = getRow('order', idAt(1), req.root);
+      return o ? { status: 200, body: orderView({ ...o, type: 'order' }) } : notFound('Order not found.');
+    }
+    // POST /orders/:id/refund — refund an order (the twin marks it refunded offline)
+    if (seg.length === 3 && seg[2] === 'refund' && method === 'POST') {
+      const o = getRow('order', idAt(1), req.root);
+      if (!o) return notFound('Order not found.');
+      const amount = Number(body.amount ?? o.total_amount ?? o.amount ?? 0);
+      const updated = await write('order', idAt(1), { status: 'refunded', paid: false, refunded_amount: amount, modified_at: nowIso(req.occurredAt) }, 'order.refund', req);
+      return { status: 200, body: orderView({ ...updated, type: 'order' }) };
+    }
+  }
+
+  // ── WEBHOOK ENDPOINTS ──
+  if (seg[0] === 'webhooks' && seg[1] === 'endpoints') {
+    if (seg.length === 2 && method === 'POST') {
+      if (!body.url) return validationError(['url'], 'Field required', 'missing');
+      const id = mintId('webhook_endpoint', req);
+      const w = await write('webhook_endpoint', id, {
+        created_at: nowIso(req.occurredAt), modified_at: null,
+        url: body.url, format: body.format ?? 'raw', events: Array.isArray(body.events) ? body.events : [],
+      }, 'webhook_endpoint.create', req);
+      return { status: 201, body: webhookView({ ...w, type: 'webhook_endpoint' }) };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      return { status: 200, body: listEnvelope(rows('webhook_endpoint', req.root).map((w) => webhookView({ ...w, type: 'webhook_endpoint' }))) };
+    }
+    if (seg.length === 3 && method === 'GET') {
+      const w = getRow('webhook_endpoint', idAt(2), req.root);
+      return w ? { status: 200, body: webhookView({ ...w, type: 'webhook_endpoint' }) } : notFound('Webhook endpoint not found.');
+    }
+    if (seg.length === 3 && method === 'DELETE') {
+      const w = getRow('webhook_endpoint', idAt(2), req.root);
+      if (!w) return notFound('Webhook endpoint not found.');
+      await write('webhook_endpoint', idAt(2), { _deleted: true }, 'webhook_endpoint.delete', req);
+      return { status: 204, body: null };
+    }
+  }
+
+  // Unmodeled route → Polar's ResourceNotFound envelope (D2 — never fabricated success).
+  return notFound(`Cannot ${method} ${path}`);
+}
+
+export type PolarTwinSnapshot = {
+  resourceTypes: readonly PolarResourceType[];
+  implementedEndpoints: readonly string[];
+};
+
+// Endpoint inventory used by the conformance snapshot.
+export function polarTwinSnapshot(): PolarTwinSnapshot {
+  return {
+    resourceTypes: POLAR_RESOURCE_TYPES,
+    implementedEndpoints: [
+      'POST /v1/customers/', 'GET /v1/customers/', 'GET /v1/customers/:id',
+      'PATCH /v1/customers/:id', 'DELETE /v1/customers/:id', 'GET /v1/customers/:id/state',
+      'POST /v1/products/', 'GET /v1/products/', 'GET /v1/products/:id', 'PATCH /v1/products/:id',
+      'POST /v1/benefits/', 'GET /v1/benefits/', 'GET /v1/benefits/:id', 'DELETE /v1/benefits/:id',
+      'POST /v1/discounts/', 'GET /v1/discounts/', 'GET /v1/discounts/:id', 'PATCH /v1/discounts/:id', 'DELETE /v1/discounts/:id',
+      'POST /v1/meters/', 'GET /v1/meters/', 'GET /v1/meters/:id',
+      'POST /v1/events/ingest', 'GET /v1/events/', 'GET /v1/events/:id',
+      'POST /v1/customer-sessions/',
+      'POST /v1/checkouts/', 'GET /v1/checkouts/', 'GET /v1/checkouts/:id', 'POST /v1/checkouts/:id/confirm',
+      'GET /v1/subscriptions/', 'GET /v1/subscriptions/:id', 'PATCH /v1/subscriptions/:id', 'DELETE /v1/subscriptions/:id',
+      'GET /v1/orders/', 'GET /v1/orders/:id', 'POST /v1/orders/:id/refund',
+      'POST /v1/webhooks/endpoints/', 'GET /v1/webhooks/endpoints/', 'GET /v1/webhooks/endpoints/:id', 'DELETE /v1/webhooks/endpoints/:id',
+    ],
+  };
+}