@volter/twin-polar 0.1.0

package/src/polar-capabilities.ts

@@ -0,0 +1,413 @@
+// Polar capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored
+// top-down from what Polar (polar.sh) actually does — NOT from what this twin has built. The
+// honest denominator: most entries start as `todo`. `verify()` (required to count as done) is
+// ground truth and drives the KERNEL-BACKED `handlePolarTwinRequest` against a FRESH temp root
+// (no spawned mock; no in-memory side-store) — create → read → assert VALUES + a negative 4xx
+// in Polar's error shape, so every claim is failable.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkCapabilities, type CapabilityReport, type CapabilitySpec, verifyBoundary } from '@volter/twin-tooling';
+import { checkPolarConformance } from './polar-conformance.ts';
+import { syncPolarFromReal, pushPendingPolarActions, type PolarLikeClient } from './polar-connector.ts';
+import { handlePolarTwinRequest, type PolarResponse } from './polar-twin.ts';
+
+const done = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier'], verify: CapabilitySpec['verify']): CapabilitySpec =>
+  ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier']): CapabilitySpec =>
+  ({ id, area, title, dimension, tier, expected: 'todo' });
+const outOfScope = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier'], reason: string): CapabilitySpec =>
+  ({ id, area, title, dimension, tier, expected: 'todo', outOfScope: reason });
+
+// ── API verify: drive REAL requests against a fresh isolated root, then assert status/shape ──
+type Step = { m: string; p: string; b?: unknown };
+type Body = Record<string, unknown>;
+
+/** Run a sequence of real Polar requests against an isolated kernel root; return all responses. */
+async function withRoot(steps: (h: (s: Step) => Promise<PolarResponse>) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'polar-cap-'));
+  const h = (s: Step) => handlePolarTwinRequest({ method: s.m, path: s.p, body: s.b === undefined ? undefined : JSON.stringify(s.b), root });
+  try {
+    return await verifyBoundary('polar.withRoot', () => steps(h));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+const ok = (r: PolarResponse) => r.status >= 200 && r.status < 300;
+const id = (r: PolarResponse) => (r.body as Body)?.id as string;
+const field = (r: PolarResponse, k: string) => (r.body as Body)?.[k];
+const items = (r: PolarResponse) => (r.body as Body)?.items as Body[];
+/** A Polar ResourceNotFound 404 (the real error envelope). */
+const isNotFound = (r: PolarResponse) => r.status === 404 && (r.body as Body)?.type === 'ResourceNotFound';
+/** A FastAPI/Polar 422 validation envelope. */
+const isValidation = (r: PolarResponse) => r.status === 422 && Array.isArray((r.body as Body)?.detail);
+
+export const POLAR_CAPABILITIES: CapabilitySpec[] = [
+  // ── Customers ─────────────────────────────────────────────────────────────────────
+  done('polar.customers.create', 'customers', 'Create customer with email/name/external_id', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/customers/', b: { email: 'a@example.test', name: 'A', external_id: 'ext-1' } });
+      return c.status === 201 && typeof id(c) === 'string' && field(c, 'email') === 'a@example.test' && field(c, 'name') === 'A' && field(c, 'external_id') === 'ext-1' && field(c, 'organization_id') != null;
+    })),
+  done('polar.customers.create_requires_email', 'customers', 'Creating an individual customer without email → 422', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/customers/', b: { name: 'No Email' } });
+      return isValidation(c);
+    })),
+  done('polar.customers.duplicate_email', 'customers', 'Duplicate email → 422 (not a fabricated success)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ m: 'POST', p: '/v1/customers/', b: { email: 'dup@example.test' } });
+      const c = await h({ m: 'POST', p: '/v1/customers/', b: { email: 'dup@example.test' } });
+      return c.status === 422;
+    })),
+  done('polar.customers.get', 'customers', 'Retrieve a customer by id; unknown id → 404', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/customers/', b: { email: 'get@example.test' } });
+      const g = await h({ m: 'GET', p: `/v1/customers/${id(c)}` });
+      const miss = await h({ m: 'GET', p: '/v1/customers/00000000-0000-4000-8000-000000000999' });
+      return ok(g) && id(g) === id(c) && field(g, 'email') === 'get@example.test' && isNotFound(miss);
+    })),
+  done('polar.customers.list_filter_email', 'customers', 'List customers and filter by email', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await h({ m: 'POST', p: '/v1/customers/', b: { email: 'list@example.test' } });
+      await h({ m: 'POST', p: '/v1/customers/', b: { email: 'other@example.test' } });
+      const r = await h({ m: 'GET', p: '/v1/customers/?email=list@example.test' });
+      return ok(r) && items(r).length === 1 && items(r)[0]!.email === 'list@example.test' && (field(r, 'pagination') as Body).total_count === 1;
+    })),
+  done('polar.customers.update', 'customers', 'Update (PATCH) customer name/metadata; unknown → 404', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/customers/', b: { email: 'patch@example.test', name: 'Old' } });
+      const u = await h({ m: 'PATCH', p: `/v1/customers/${id(c)}`, b: { name: 'New', metadata: { tier: 'pro' } } });
+      const miss = await h({ m: 'PATCH', p: '/v1/customers/nope', b: { name: 'x' } });
+      return ok(u) && field(u, 'name') === 'New' && (field(u, 'metadata') as Body).tier === 'pro' && isNotFound(miss);
+    })),
+  done('polar.customers.delete', 'customers', 'Delete (soft) a customer → 204, then 404 on read', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/customers/', b: { email: 'del@example.test' } });
+      const d = await h({ m: 'DELETE', p: `/v1/customers/${id(c)}` });
+      const g = await h({ m: 'GET', p: `/v1/customers/${id(c)}` });
+      return d.status === 204 && isNotFound(g);
+    })),
+  done('polar.customers.state_meter_balance', 'customers', 'Customer state returns active meter balance shape', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/customers/', b: { email: 'state@example.test' } });
+      const s = await h({ m: 'GET', p: `/v1/customers/${id(c)}/state` });
+      const meters = field(s, 'active_meters') as Body[];
+      return ok(s) && Array.isArray(meters) && typeof meters[0]?.balance === 'number' && Array.isArray(field(s, 'active_subscriptions'));
+    })),
+
+  // ── Products ──────────────────────────────────────────────────────────────────────
+  done('polar.products.create', 'products', 'Create a recurring product; retrieve round-trips', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const p = await h({ m: 'POST', p: '/v1/products/', b: { name: 'Pro', recurring_interval: 'month', prices: [{ price_amount: 1500, price_currency: 'usd' }] } });
+      const g = await h({ m: 'GET', p: `/v1/products/${id(p)}` });
+      return p.status === 201 && field(p, 'name') === 'Pro' && field(p, 'is_recurring') === true && ok(g) && (field(g, 'prices') as unknown[]).length === 1;
+    })),
+  done('polar.products.create_requires_name', 'products', 'Create product without name → 422', 'api', 'common', () =>
+    withRoot(async (h) => isValidation(await h({ m: 'POST', p: '/v1/products/', b: {} })))),
+  done('polar.products.list_and_archive', 'products', 'List products + archive via PATCH is_archived', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const p = await h({ m: 'POST', p: '/v1/products/', b: { name: 'Arch' } });
+      const u = await h({ m: 'PATCH', p: `/v1/products/${id(p)}`, b: { is_archived: true } });
+      const l = await h({ m: 'GET', p: '/v1/products/?is_archived=true' });
+      return field(u, 'is_archived') === true && items(l).some((x) => x.id === id(p));
+    })),
+
+  // ── Checkouts + confirm → subscription/order ────────────────────────────────────────
+  done('polar.checkouts.create', 'checkouts', 'Create checkout with client secret + hosted url', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const prod = await h({ m: 'POST', p: '/v1/products/', b: { name: 'CO', recurring_interval: 'month', prices: [{ price_amount: 2000 }] } });
+      const c = await h({ m: 'POST', p: '/v1/checkouts/', b: { products: [id(prod)] } });
+      return c.status === 201 && String(field(c, 'client_secret')).startsWith('polar_checkout_') && String(field(c, 'url')).includes('/checkout/') && field(c, 'status') === 'open' && field(c, 'amount') === 2000;
+    })),
+  done('polar.checkouts.requires_product', 'checkouts', 'Checkout without products → 422', 'api', 'common', () =>
+    withRoot(async (h) => isValidation(await h({ m: 'POST', p: '/v1/checkouts/', b: {} })))),
+  done('polar.checkouts.confirm_creates_subscription', 'checkouts', 'Confirm a recurring checkout → active subscription + paid order + customer', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const prod = await h({ m: 'POST', p: '/v1/products/', b: { name: 'Sub', recurring_interval: 'month', prices: [{ price_amount: 1000 }] } });
+      const c = await h({ m: 'POST', p: '/v1/checkouts/', b: { products: [id(prod)], customer_email: 'buyer@example.test' } });
+      const conf = await h({ m: 'POST', p: `/v1/checkouts/${id(c)}/confirm`, b: { customer_email: 'buyer@example.test' } });
+      if (!ok(conf) || field(conf, 'status') !== 'confirmed' || !field(conf, 'subscription_id')) return false;
+      const subs = await h({ m: 'GET', p: '/v1/subscriptions/' });
+      const orders = await h({ m: 'GET', p: '/v1/orders/' });
+      return items(subs).length === 1 && items(subs)[0]!.status === 'active' && items(orders).length === 1 && items(orders)[0]!.paid === true;
+    })),
+  done('polar.checkouts.confirm_twice_rejected', 'checkouts', 'Confirming an already-confirmed checkout → 403', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const prod = await h({ m: 'POST', p: '/v1/products/', b: { name: 'Once', recurring_interval: 'month', prices: [{ price_amount: 500 }] } });
+      const c = await h({ m: 'POST', p: '/v1/checkouts/', b: { products: [id(prod)], customer_email: 'x@example.test' } });
+      await h({ m: 'POST', p: `/v1/checkouts/${id(c)}/confirm`, b: { customer_email: 'x@example.test' } });
+      const again = await h({ m: 'POST', p: `/v1/checkouts/${id(c)}/confirm`, b: {} });
+      return again.status === 403;
+    })),
+
+  // ── Subscriptions ───────────────────────────────────────────────────────────────────
+  done('polar.subscriptions.list_get', 'subscriptions', 'List + retrieve subscriptions; unknown → 404', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const prod = await h({ m: 'POST', p: '/v1/products/', b: { name: 'S', recurring_interval: 'month', prices: [{ price_amount: 100 }] } });
+      const c = await h({ m: 'POST', p: '/v1/checkouts/', b: { products: [id(prod)], customer_email: 's@example.test' } });
+      const conf = await h({ m: 'POST', p: `/v1/checkouts/${id(c)}/confirm`, b: { customer_email: 's@example.test' } });
+      const subId = field(conf, 'subscription_id') as string;
+      const g = await h({ m: 'GET', p: `/v1/subscriptions/${subId}` });
+      const miss = await h({ m: 'GET', p: '/v1/subscriptions/nope' });
+      return ok(g) && id(g) === subId && field(g, 'customer') != null && isNotFound(miss);
+    })),
+  done('polar.subscriptions.patch_cancel_at_period_end', 'subscriptions', 'PATCH cancel_at_period_end flips flag + records canceled_at', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const prod = await h({ m: 'POST', p: '/v1/products/', b: { name: 'P', recurring_interval: 'month', prices: [{ price_amount: 100 }] } });
+      const c = await h({ m: 'POST', p: '/v1/checkouts/', b: { products: [id(prod)], customer_email: 'p@example.test' } });
+      const conf = await h({ m: 'POST', p: `/v1/checkouts/${id(c)}/confirm`, b: { customer_email: 'p@example.test' } });
+      const subId = field(conf, 'subscription_id') as string;
+      const u = await h({ m: 'PATCH', p: `/v1/subscriptions/${subId}`, b: { cancel_at_period_end: true } });
+      return ok(u) && field(u, 'cancel_at_period_end') === true && field(u, 'canceled_at') != null && field(u, 'status') === 'active';
+    })),
+  done('polar.subscriptions.cancel', 'subscriptions', 'DELETE subscription → status canceled + ended_at', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const prod = await h({ m: 'POST', p: '/v1/products/', b: { name: 'C', recurring_interval: 'month', prices: [{ price_amount: 100 }] } });
+      const c = await h({ m: 'POST', p: '/v1/checkouts/', b: { products: [id(prod)], customer_email: 'c@example.test' } });
+      const conf = await h({ m: 'POST', p: `/v1/checkouts/${id(c)}/confirm`, b: { customer_email: 'c@example.test' } });
+      const subId = field(conf, 'subscription_id') as string;
+      const d = await h({ m: 'DELETE', p: `/v1/subscriptions/${subId}` });
+      return ok(d) && field(d, 'status') === 'canceled' && field(d, 'ended_at') != null;
+    })),
+
+  // ── Orders ──────────────────────────────────────────────────────────────────────────
+  done('polar.orders.list_filter', 'orders', 'List orders + filter by customer_id', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const prod = await h({ m: 'POST', p: '/v1/products/', b: { name: 'O', prices: [{ price_amount: 700 }] } });
+      const c = await h({ m: 'POST', p: '/v1/checkouts/', b: { products: [id(prod)], customer_email: 'o@example.test' } });
+      const conf = await h({ m: 'POST', p: `/v1/checkouts/${id(c)}/confirm`, b: { customer_email: 'o@example.test' } });
+      const custId = field(conf, 'customer_id') as string;
+      const l = await h({ m: 'GET', p: `/v1/orders/?customer_id=${custId}` });
+      return items(l).length === 1 && items(l)[0]!.customer_id === custId;
+    })),
+  done('polar.orders.refund', 'orders', 'Refund an order → status refunded + refunded_amount', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const prod = await h({ m: 'POST', p: '/v1/products/', b: { name: 'R', prices: [{ price_amount: 900 }] } });
+      const c = await h({ m: 'POST', p: '/v1/checkouts/', b: { products: [id(prod)], customer_email: 'r@example.test' } });
+      const conf = await h({ m: 'POST', p: `/v1/checkouts/${id(c)}/confirm`, b: { customer_email: 'r@example.test' } });
+      const ordList = await h({ m: 'GET', p: '/v1/orders/' });
+      const orderId = items(ordList)[0]!.id as string;
+      const ref = await h({ m: 'POST', p: `/v1/orders/${orderId}/refund`, b: { amount: 900 } });
+      const miss = await h({ m: 'POST', p: '/v1/orders/nope/refund', b: {} });
+      return ok(ref) && field(ref, 'status') === 'refunded' && field(ref, 'refunded_amount') === 900 && field(ref, 'paid') === false && isNotFound(miss) && Boolean(conf);
+    })),
+
+  // ── Benefits / Discounts / Meters ────────────────────────────────────────────────────
+  done('polar.benefits.crud', 'benefits', 'Create/list/delete a benefit', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const b = await h({ m: 'POST', p: '/v1/benefits/', b: { type: 'custom', description: 'VIP' } });
+      const g = await h({ m: 'GET', p: `/v1/benefits/${id(b)}` });
+      const d = await h({ m: 'DELETE', p: `/v1/benefits/${id(b)}` });
+      const after = await h({ m: 'GET', p: `/v1/benefits/${id(b)}` });
+      return b.status === 201 && field(g, 'description') === 'VIP' && d.status === 204 && isNotFound(after);
+    })),
+  done('polar.discounts.crud', 'discounts', 'Create/update/list discounts; requires name+type', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const bad = await h({ m: 'POST', p: '/v1/discounts/', b: { name: 'NoType' } });
+      const d = await h({ m: 'POST', p: '/v1/discounts/', b: { name: 'Launch', type: 'percentage', basis_points: 2000 } });
+      const u = await h({ m: 'PATCH', p: `/v1/discounts/${id(d)}`, b: { basis_points: 5000 } });
+      return isValidation(bad) && d.status === 201 && field(d, 'type') === 'percentage' && field(u, 'basis_points') === 5000;
+    })),
+  done('polar.meters.crud', 'meters', 'Create + retrieve a usage meter', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const m = await h({ m: 'POST', p: '/v1/meters/', b: { name: 'tokens', aggregation: { func: 'sum', property: 'amount' } } });
+      const g = await h({ m: 'GET', p: `/v1/meters/${id(m)}` });
+      return m.status === 201 && field(g, 'name') === 'tokens' && (field(g, 'aggregation') as Body).func === 'sum';
+    })),
+
+  // ── Events ────────────────────────────────────────────────────────────────────────
+  done('polar.events.ingest', 'events', 'Ingest usage events → inserted count', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/events/ingest', b: { events: [{ name: 'tokens', metadata: { cost_usd: 1 } }, { name: 'tokens' }] } });
+      return ok(r) && field(r, 'inserted') === 2 && field(r, 'duplicates') === 0;
+    })),
+  done('polar.events.ingest_validates_name', 'events', 'Ingest with a nameless event → 422', 'api', 'common', () =>
+    withRoot(async (h) => isValidation(await h({ m: 'POST', p: '/v1/events/ingest', b: { events: [{ metadata: {} }] } })))),
+  done('polar.events.list_filter', 'events', 'List events + filter by customer_id', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/customers/', b: { email: 'ev@example.test' } });
+      await h({ m: 'POST', p: '/v1/events/ingest', b: { events: [{ name: 'used', customer_id: id(c) }] } });
+      await h({ m: 'POST', p: '/v1/events/ingest', b: { events: [{ name: 'other' }] } });
+      const l = await h({ m: 'GET', p: `/v1/events/?customer_id=${id(c)}` });
+      return items(l).length === 1 && items(l)[0]!.name === 'used';
+    })),
+  done('polar.events.balance_reflects_usage', 'events', 'Customer state meter balance nets credits − consumption', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/customers/', b: { email: 'bal2@example.test' } });
+      await h({ m: 'POST', p: '/v1/events/ingest', b: { events: [{ name: 'credit', customer_id: id(c), metadata: { cost_usd: -5 } }, { name: 'use', customer_id: id(c), metadata: { cost_usd: 2 } }] } });
+      const s = await h({ m: 'GET', p: `/v1/customers/${id(c)}/state` });
+      return (field(s, 'active_meters') as Body[])[0]!.balance === 3;
+    })),
+
+  // ── Customer sessions ───────────────────────────────────────────────────────────────
+  done('polar.customer_sessions.create', 'customer-sessions', 'Create a customer portal session; unknown customer → 404', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/customers/', b: { email: 'cs@example.test' } });
+      const s = await h({ m: 'POST', p: '/v1/customer-sessions/', b: { customer_id: id(c) } });
+      const miss = await h({ m: 'POST', p: '/v1/customer-sessions/', b: { customer_id: 'nope' } });
+      return s.status === 201 && String(field(s, 'token')).startsWith('polar_cst_') && String(field(s, 'customer_portal_url')).includes('customer_session_token') && isNotFound(miss);
+    })),
+
+  // ── Webhook endpoints ───────────────────────────────────────────────────────────────
+  done('polar.webhooks.endpoints_crud', 'webhooks', 'Create/list/delete webhook endpoints; create requires url', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const bad = await h({ m: 'POST', p: '/v1/webhooks/endpoints/', b: {} });
+      const w = await h({ m: 'POST', p: '/v1/webhooks/endpoints/', b: { url: 'https://app.test/hook', events: ['order.created'] } });
+      const l = await h({ m: 'GET', p: '/v1/webhooks/endpoints/' });
+      const d = await h({ m: 'DELETE', p: `/v1/webhooks/endpoints/${id(w)}` });
+      return isValidation(bad) && w.status === 201 && items(l).length === 1 && d.status === 204;
+    })),
+
+  // ── Safety / honesty ────────────────────────────────────────────────────────────────
+  done('polar.read_only', 'safety', 'Read-only mode rejects writes with 405', 'api', 'core', () =>
+    withRoot(async () => {
+      const root = mkdtempSync(join(tmpdir(), 'polar-ro-'));
+      try {
+        const r = await handlePolarTwinRequest({ method: 'POST', path: '/v1/customers/', body: JSON.stringify({ email: 'ro@example.test' }), root, readOnly: true });
+        const g = await handlePolarTwinRequest({ method: 'GET', path: '/v1/customers/', root, readOnly: true });
+        return r.status === 405 && g.status === 200;
+      } finally {
+        rmSync(root, { recursive: true, force: true });
+      }
+    })),
+  done('polar.errors.unmodeled_route', 'errors', 'Unmodeled route → ResourceNotFound (never fabricated success)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/totally-made-up/', b: {} });
+      return isNotFound(r);
+    })),
+
+  // ── Connector (D6/D7) ────────────────────────────────────────────────────────────────
+  done('polar.connector.sync.entrypoint', 'connector', 'syncPolarFromReal folds pulled customers/products into the twin', 'connector', 'core', () =>
+    withRoot(async (h) => {
+      const root = mkdtempSync(join(tmpdir(), 'polar-sync-'));
+      try {
+        const client: PolarLikeClient = {
+          customers: { list: async () => ({ items: [{ id: 'cus_real_1', email: 'real@example.test', name: 'Real' }] }) },
+          products: { list: async () => ({ items: [{ id: 'prod_real_1', name: 'Real Plan', recurring_interval: 'month' }] }) },
+          subscriptions: { list: async () => ({ items: [] }) },
+          orders: { list: async () => ({ items: [] }) },
+        };
+        const first = await syncPolarFromReal(client, { root, occurredAt: '2026-01-01T00:00:00.000Z', budgetOptions: { root } });
+        const again = await syncPolarFromReal(client, { root, occurredAt: '2026-01-01T00:00:00.000Z', budgetOptions: { root } });
+        // pulled customer is now served by the twin's read path over the SAME root
+        const c = await handlePolarTwinRequest({ method: 'GET', path: '/v1/customers/cus_real_1', root });
+        return first.observed === 2 && first.deltasAppended === 2 && again.deltasAppended === 0 && c.status === 200 && field(c, 'email') === 'real@example.test' && Boolean(h);
+      } finally {
+        rmSync(root, { recursive: true, force: true });
+      }
+    })),
+  done('polar.connector.push.entrypoint', 'connector', 'pushPendingPolarActions pushes a local customer.create to the injected client', 'connector', 'core', () =>
+    withRoot(async () => {
+      const root = mkdtempSync(join(tmpdir(), 'polar-push-'));
+      try {
+        await handlePolarTwinRequest({ method: 'POST', path: '/v1/customers/', body: JSON.stringify({ email: 'push@example.test', name: 'P' }), root });
+        let pushedEmail: string | null = null;
+        const client: PolarLikeClient = {
+          customers: { list: async () => ({ items: [] }), create: async (params) => { pushedEmail = String((params as Body).email); return { id: 'cus_pushed' }; } },
+        };
+        const res = await pushPendingPolarActions(client, { root, occurredAt: '2026-01-01T00:00:00.000Z', budgetOptions: { root } });
+        const again = await pushPendingPolarActions(client, { root, occurredAt: '2026-01-01T00:00:00.000Z', budgetOptions: { root } });
+        return res.pushed === 1 && pushedEmail === 'push@example.test' && again.pushed === 0;
+      } finally {
+        rmSync(root, { recursive: true, force: true });
+      }
+    })),
+
+  done('polar.conformance.snapshot', 'conformance', 'Conformance snapshot covers implemented resource types and endpoints', 'api', 'common', () => {
+    const report = checkPolarConformance();
+    return report.ok && report.endpointsChecked >= 30 && report.resourceTypesChecked >= 10;
+  }),
+
+  // ── out of scope (a local twin cannot honestly do these) ──────────────────────────────
+  outOfScope('polar.payments.real_processing', 'payments', 'Real payment processor authorization, capture, disputes, and settlement', 'api', 'core', 'A local twin must not contact or emulate real card networks; it returns deterministic checkout/order shapes and "confirms" payment offline.'),
+  outOfScope('polar.tax.real_calculation', 'tax', 'Hosted tax/VAT calculation, nexus, remittance, and jurisdiction updates', 'api', 'common', 'Tax authority integrations and live jurisdiction rules are outside a deterministic local twin.'),
+
+  // ── the remaining real Polar surface (the honest TODO denominator) ─────────────────────
+  ...[
+    ['products.prices_full', 'products', 'Full price modeling (fixed/recurring/metered/custom/tiered)'],
+    ['products.benefits_attach', 'products', 'Attach/detach benefits to a product'],
+    ['products.medias', 'products', 'Product media uploads and ordering'],
+    ['products.custom_fields', 'products', 'Custom field attachment + validation'],
+    ['prices.archive', 'products', 'Archive/replace a price'],
+    ['benefits.grants', 'benefits', 'Grant/revoke customer benefits + benefit grants list'],
+    ['benefits.types', 'benefits', 'Built-in benefit types (downloadables, license keys, GitHub, Discord)'],
+    ['discounts.redemption', 'discounts', 'Discount redemption + max_redemptions enforcement'],
+    ['meters.quantities', 'meters', 'Meter quantities aggregation + time buckets'],
+    ['meters.update', 'meters', 'Update/archive a meter'],
+    ['events.dedupe', 'events', 'Event idempotency / external_id duplicate detection'],
+    ['events.external_customer', 'events', 'Ingest by external_customer_id resolution'],
+    ['customer_sessions.scopes', 'customer-sessions', 'Customer portal session scopes + expiry enforcement'],
+    ['customer_portal.api', 'customer-portal', 'Customer portal API (subscriptions/orders/benefit grants by session token)'],
+    ['checkouts.update', 'checkouts', 'Update an open checkout (customer fields, discount, amount)'],
+    ['checkouts.embed', 'checkouts', 'Embedded checkout embed_origin enforcement'],
+    ['checkouts.expiry', 'checkouts', 'Checkout expiry transitions'],
+    ['checkout_links.crud', 'checkouts', 'Reusable checkout links CRUD'],
+    ['subscriptions.proration', 'subscriptions', 'Plan changes with proration'],
+    ['subscriptions.trials', 'subscriptions', 'Trials and trial-end transitions'],
+    ['subscriptions.revoke', 'subscriptions', 'Revoke (cancel immediately) vs cancel-at-period-end'],
+    ['subscriptions.uncancel', 'subscriptions', 'Uncancel a subscription scheduled to cancel'],
+    ['subscriptions.seats', 'subscriptions', 'Seat-based subscription quantity'],
+    ['orders.invoice', 'orders', 'Generate/download an order invoice PDF'],
+    ['orders.list_filters', 'orders', 'Order filters (product/status/date) + sorting'],
+    ['refunds.crud', 'refunds', 'Refunds resource CRUD + partial refund accounting'],
+    ['webhooks.delivery', 'webhooks', 'Webhook delivery, signing (standard-webhooks), and retries'],
+    ['webhooks.deliveries_list', 'webhooks', 'Webhook delivery logs + redelivery'],
+    ['webhooks.endpoint_update', 'webhooks', 'Update a webhook endpoint (url/events/secret)'],
+    ['license_keys.crud', 'license-keys', 'License key create/activate/validate'],
+    ['license_keys.limits', 'license-keys', 'Activation limits and revocation'],
+    ['files.upload', 'files', 'File upload (S3 multipart) for downloadable benefits'],
+    ['organizations.crud', 'organizations', 'Organization settings, branding, and account'],
+    ['custom_fields.crud', 'custom-fields', 'Custom field definitions CRUD'],
+    ['oauth.apps', 'oauth', 'OAuth2 app + token flows'],
+    ['oauth.userinfo', 'oauth', 'OAuth userinfo + token introspection'],
+    ['pagination.cursors', 'pagination', 'Page/limit pagination + sorting across list endpoints'],
+    ['metadata.filter', 'metadata', 'Metadata filtering on list endpoints'],
+    ['auth.token', 'auth', 'Organization access token auth (401 on bad token)'],
+    ['rate_limits', 'limits', 'Rate-limit headers and retry semantics'],
+    ['idempotency', 'idempotency', 'Idempotency-Key dedupe on mutating requests'],
+    ['mirror.ui', 'ui', 'Operator mirror UI for customers/subscriptions/orders/events'],
+    ['connector.subscriptions_orders', 'connector', 'Pull subscriptions/orders incrementally with cursors'],
+    ['fixtures.seed', 'fixtures', 'Seed products, prices, and subscriptions from fixtures'],
+  ].map(([id, area, title]) => todo(`polar.${id}`, area, title, id.startsWith('connector') ? 'connector' : id === 'mirror.ui' ? 'ui' : 'api', id.includes('webhooks') || id.includes('connector') || id.includes('auth') ? 'core' : 'common')),
+  // ── Pull-surface coverage audit gaps (TWIN-46 / G2) — filed as manifest todos, which is
+  // what the demand-ordered build list is drawn from. See pull-audit.json (repo root) for the
+  // per-pack pull-vs-read-surface evidence.
+  todo('polar.connector.pull_webhook_endpoints', 'connector', 'Connector: pull registered webhook endpoints from the real account', 'connector', 'core'),
+  todo('polar.connector.pull_benefits', 'connector', 'Connector: pull benefits from the real account', 'connector', 'common'),
+  todo('polar.connector.pull_discounts', 'connector', 'Connector: pull discounts from the real account', 'connector', 'common'),
+
+  // ── Missing-area sweep (TWIN-87 / F1) ────────────────────────────────────────────────────
+  // /v1/metrics and /v1/customer-meters had NO manifest entry of any status, and the
+  // `payments` area held only the real-processing carve-out (list/read was unrepresented).
+  // Filed as honest todos (all genuinely buildable — reading back recorded payment metadata
+  // is not the same as real card processing, which stays out of scope above). See
+  // POLAR_AREAS below + polar-capabilities.test.ts's area-census meta-test, gate-wired so a
+  // future whole-area omission fails here instead of waiting for another review pass.
+  todo('polar.metrics.query', 'metrics', 'Metrics: aggregated revenue/orders/subscribers time-series (GET /v1/metrics/)', 'api', 'niche'),
+  todo('polar.metrics.limits', 'metrics', 'Metrics: query granularity/date-range validation limits', 'api', 'niche'),
+  todo('polar.customer_meters.list', 'customer-meters', 'Customer meters: list per-customer meter balances (GET /v1/customer-meters/)', 'api', 'niche'),
+  todo('polar.customer_meters.get', 'customer-meters', 'Customer meters: retrieve a single customer-meter by id', 'api', 'niche'),
+  todo('polar.payments.list', 'payments', 'Payments: list recorded payment metadata (GET /v1/payments/)', 'api', 'niche'),
+  todo('polar.payments.get', 'payments', 'Payments: retrieve a single recorded payment by id', 'api', 'niche'),
+
+];
+
+// TWIN-87 committed area census — the vendor's top-level API product areas (docs nav /
+// OpenAPI tags), authored top-down independent of what a manifest entry happens to already
+// exist for. polar-capabilities.test.ts's area-census meta-test (assertAreaCensus) fails the
+// gate if a declared area has zero manifest entries and no named exclusion, OR if a manifest
+// entry's `area` drifts outside this list — so a whole missing area (metrics, customer-
+// meters were the concrete F1 leak) can never again hide invisibly.
+export const POLAR_AREAS = [
+  'auth', 'benefits', 'checkouts', 'conformance', 'connector', 'custom-fields', 'customer-meters',
+  'customer-portal', 'customer-sessions', 'customers', 'discounts', 'errors', 'events', 'files',
+  'fixtures', 'idempotency', 'license-keys', 'limits', 'metadata', 'meters', 'metrics', 'oauth',
+  'orders', 'organizations', 'pagination', 'payments', 'products', 'refunds', 'safety',
+  'subscriptions', 'tax', 'ui', 'webhooks',
+] as const;
+
+export async function polarCapabilities(): Promise<CapabilityReport> {
+  return checkCapabilities('polar', POLAR_CAPABILITIES);
+}

package/src/polar-conformance.ts

@@ -0,0 +1,33 @@
+// Polar conformance (dev-only; lazy-imported by the CLI, NEVER from index.ts/runtime — E2).
+// Checks the twin's endpoint/resource inventory against the modeled Polar surface.
+import { polarTwinSnapshot, POLAR_RESOURCE_TYPES } from './polar-twin.ts';
+
+export type PolarConformanceReport = {
+  ok: boolean;
+  endpointsChecked: number;
+  resourceTypesChecked: number;
+  violations: string[];
+};
+
+export function checkPolarConformance(): PolarConformanceReport {
+  const snapshot = polarTwinSnapshot();
+  const violations: string[] = [];
+  // Every declared resource type must have at least one implemented endpoint touching it.
+  for (const type of POLAR_RESOURCE_TYPES) {
+    const stem = type === 'customer_session' ? 'customer-sessions'
+      : type === 'webhook_endpoint' ? 'webhooks/endpoints'
+      : `${type}s`;
+    if (!snapshot.implementedEndpoints.some((e) => e.includes(`/v1/${stem}`))) {
+      violations.push(`resource type '${type}' has no implemented endpoint`);
+    }
+  }
+  if (!snapshot.implementedEndpoints.some((e) => e.startsWith('POST /v1/customers/'))) {
+    violations.push('missing customer create endpoint');
+  }
+  return {
+    ok: violations.length === 0,
+    endpointsChecked: snapshot.implementedEndpoints.length,
+    resourceTypesChecked: snapshot.resourceTypes.length,
+    violations,
+  };
+}

package/src/polar-connector.ts

@@ -0,0 +1,155 @@
+// Polar CONNECTOR — the live-vendor pull/push path that gives the Polar twin the full
+// "git for SaaS" lifecycle over an INJECTED client (the auth boundary).
+//
+// PULL  (real → twin):  fetch real Polar objects via the injected client (customers, products,
+//                       subscriptions, orders), map them to SyncResource[], and fold them into
+//                       the event log via syncPull (shadow-diff dedup, so a re-pull of identical
+//                       state is a no-op). Kernel subject ids are TYPE-PREFIXED to stay
+//                       collision-safe (mirrors the twin handler).
+// PUSH  (twin → real):  for every PENDING local action, call the injected client and
+//                       confirmAction on success — recording the confirmed fields as observed
+//                       and suppressing the local projection.
+//
+// The vendor I/O is an INJECTED client interface (`PolarLikeClient`): a fake in tests, a real
+// `new Polar({ accessToken })` in prod. The pack imports NO SDK and holds NO key.
+import { confirmAction, pendingActions, syncPull } from '@volter/twin';
+import type { SyncResource, TwinAction } from '@volter/twin';
+//
+// ── The client-side RATE BUDGET is not optional here ────────────────────────────────────────
+// Polar publishes 500 requests/minute in production and 100/minute in sandbox per organization, and
+// is the one vendor in this batch that documents a Retry-After header — so the guard's cooldown is
+// armed by the vendor itself rather than inferred.
+// Every entrypoint below GUARDS the injected client before touching it (`guardPolarClient`, which is
+// idempotent — a caller who already wrapped is not double-charged, a caller who forgot is protected
+// anyway); there is deliberately no option that turns the budget off. See polar-budget.ts.
+import { polarBudgetOf, guardPolarClient, type PolarBudgetedOptions } from './polar-budget.ts';
+
+const SERVICE = 'polar';
+
+export type { PolarBudgetedOptions };
+
+export type PolarCustomer = { id: string; email?: string | null; name?: string | null; external_id?: string | null; created_at?: string; metadata?: Record<string, unknown> };
+export type PolarProduct = { id: string; name?: string | null; description?: string | null; recurring_interval?: string | null; is_archived?: boolean; created_at?: string };
+export type PolarSubscription = { id: string; status?: string; amount?: number; currency?: string; recurring_interval?: string; customer_id?: string | null; product_id?: string | null; created_at?: string; current_period_end?: string | null; cancel_at_period_end?: boolean };
+export type PolarOrder = { id: string; status?: string; amount?: number; total_amount?: number; currency?: string; customer_id?: string | null; product_id?: string | null; subscription_id?: string | null; created_at?: string };
+
+// Polar SDK list responses page through `{ result: { items, pagination } }`. The injected
+// client exposes the minimal subset the connector calls; a real `Polar` instance is structurally
+// assignable. Each `list` returns the items array directly (the caller paginates upstream).
+export interface PolarLikeClient {
+  customers?: { list: (params?: Record<string, unknown>) => Promise<{ items: PolarCustomer[] }>; create?: (params: Record<string, unknown>) => Promise<{ id: string }> };
+  products?: { list: (params?: Record<string, unknown>) => Promise<{ items: PolarProduct[] }>; create?: (params: Record<string, unknown>) => Promise<{ id: string }> };
+  subscriptions?: { list: (params?: Record<string, unknown>) => Promise<{ items: PolarSubscription[] }> };
+  orders?: { list: (params?: Record<string, unknown>) => Promise<{ items: PolarOrder[] }> };
+}
+
+// Kernel subject id (type-prefixed → collision-safe across types; mirrors polar-twin.ts).
+function kid(type: string, id: string): string {
+  return `${type}:${id}`;
+}
+
+// ── PULL mappers (real Polar object → SyncResource) ──────────────────────────────────
+export function mapCustomer(c: PolarCustomer): SyncResource {
+  return { type: 'customer', id: kid('customer', String(c.id)), fields: { created_at: c.created_at ?? null, modified_at: null, email: c.email ?? null, name: c.name ?? null, external_id: c.external_id ?? null, customer_type: 'individual', email_verified: false, locale: 'en', metadata: c.metadata ?? {} } };
+}
+export function mapProduct(p: PolarProduct): SyncResource {
+  return { type: 'product', id: kid('product', String(p.id)), fields: { created_at: p.created_at ?? null, modified_at: null, name: p.name ?? null, description: p.description ?? null, recurring_interval: p.recurring_interval ?? null, is_archived: p.is_archived ?? false, prices: [], benefits: [], metadata: {} } };
+}
+export function mapSubscription(s: PolarSubscription): SyncResource {
+  return { type: 'subscription', id: kid('subscription', String(s.id)), fields: { created_at: s.created_at ?? null, modified_at: null, status: s.status ?? 'active', amount: s.amount ?? 0, currency: s.currency ?? 'usd', recurring_interval: s.recurring_interval ?? 'month', customer_id: s.customer_id ?? null, product_id: s.product_id ?? null, current_period_end: s.current_period_end ?? null, cancel_at_period_end: s.cancel_at_period_end ?? false, metadata: {} } };
+}
+export function mapOrder(o: PolarOrder): SyncResource {
+  return { type: 'order', id: kid('order', String(o.id)), fields: { created_at: o.created_at ?? null, modified_at: null, status: o.status ?? 'paid', paid: o.status !== 'refunded', amount: o.amount ?? o.total_amount ?? 0, total_amount: o.total_amount ?? o.amount ?? 0, currency: o.currency ?? 'usd', customer_id: o.customer_id ?? null, product_id: o.product_id ?? null, subscription_id: o.subscription_id ?? null, metadata: {} } };
+}
+
+export async function pullPolarCustomers(rawClient: PolarLikeClient, opts: PolarBudgetedOptions = {}): Promise<SyncResource[]> {
+  const client = guardPolarClient(rawClient, opts);
+  if (!client.customers) return [];
+  return (await client.customers.list()).items.map(mapCustomer);
+}
+export async function pullPolarProducts(rawClient: PolarLikeClient, opts: PolarBudgetedOptions = {}): Promise<SyncResource[]> {
+  const client = guardPolarClient(rawClient, opts);
+  if (!client.products) return [];
+  return (await client.products.list()).items.map(mapProduct);
+}
+export async function pullPolarSubscriptions(rawClient: PolarLikeClient, opts: PolarBudgetedOptions = {}): Promise<SyncResource[]> {
+  const client = guardPolarClient(rawClient, opts);
+  if (!client.subscriptions) return [];
+  return (await client.subscriptions.list()).items.map(mapSubscription);
+}
+export async function pullPolarOrders(rawClient: PolarLikeClient, opts: PolarBudgetedOptions = {}): Promise<SyncResource[]> {
+  const client = guardPolarClient(rawClient, opts);
+  if (!client.orders) return [];
+  return (await client.orders.list()).items.map(mapOrder);
+}
+
+/**
+ * D7 entry point: pull from real Polar (customers + products + subscriptions + orders) and fold
+ * EVERY domain into the twin via ONE syncPull (shadow-diff dedup). Returns { observed,
+ * deltasAppended } — callers need not know vendor-specific pull mechanics.
+ */
+export async function syncPolarFromReal(
+  rawClient: PolarLikeClient,
+  opts: { root?: string; occurredAt?: string } & PolarBudgetedOptions = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  // Guard ONCE here and hand the guarded client down, so no domain pull can run unbudgeted.
+  const client = guardPolarClient(rawClient, polarBudgetOf(opts));
+  const occurredAt = opts.occurredAt ?? new Date().toISOString();
+  const resources: SyncResource[] = [
+    ...(await pullPolarCustomers(client)),
+    ...(await pullPolarProducts(client)),
+    ...(await pullPolarSubscriptions(client)),
+    ...(await pullPolarOrders(client)),
+  ];
+  const result = syncPull({ service: SERVICE, resources, occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+  return { observed: result.observed, deltasAppended: result.deltasAppended };
+}
+
+// ── PUSH ──────────────────────────────────────────────────────────────────────────
+// The twin operations this connector knows how to push to real Polar. Anything else FAILS
+// LOUDLY rather than being silently dropped.
+const PUSHABLE = new Set(['customer.create', 'product.create']);
+
+export async function pushPolarAction(
+  rawClient: PolarLikeClient,
+  action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>,
+  opts: PolarBudgetedOptions = {},
+): Promise<{ externalId: string }> {
+  // Writes count against the SAME per-minute budget reads do, so the push path is budgeted too.
+  const client = guardPolarClient(rawClient, opts);
+  const op = action.operation ?? `${action.subject.type}.update`;
+  if (!PUSHABLE.has(op)) throw new Error(`polar push: unsupported operation '${op}' — refusing to silently drop a local write`);
+  const fields = action.fields ?? {};
+  let externalId = action.subject.id;
+  if (op === 'customer.create' && client.customers?.create) {
+    externalId = (await client.customers.create({ email: fields.email, name: fields.name, external_id: fields.external_id })).id;
+  } else if (op === 'product.create' && client.products?.create) {
+    externalId = (await client.products.create({ name: fields.name, recurring_interval: fields.recurring_interval })).id;
+  }
+  return { externalId: externalId || action.subject.id };
+}
+
+/**
+ * Push the twin's PENDING local actions to real Polar and CONFIRM each. A confirmed action is
+ * no longer pending, so a re-push enacts NOTHING. Unpushable ops are skipped.
+ */
+export async function pushPendingPolarActions(
+  rawClient: PolarLikeClient,
+  opts: { root?: string; occurredAt?: string } & PolarBudgetedOptions = {},
+): Promise<{ pushed: number; confirmed: string[]; externalIds: Record<string, string> }> {
+  // Guard here as well as in pushPolarAction: guarding is idempotent, so the inner call is a no-op
+  // and the ledger/clock the caller chose is what the whole loop accounts against.
+  const client = guardPolarClient(rawClient, polarBudgetOf(opts));
+  const occurredAt = opts.occurredAt ?? new Date().toISOString();
+  const confirmed: string[] = [];
+  const externalIds: Record<string, string> = {};
+  for (const action of pendingActions(SERVICE, opts.root)) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    if (!PUSHABLE.has(op)) continue;
+    const { externalId } = await pushPolarAction(client, action, polarBudgetOf(opts));
+    confirmAction({ service: SERVICE, actionId: action.id, subject: action.subject, fields: action.fields ?? {}, occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+    confirmed.push(action.id);
+    externalIds[action.id] = externalId;
+  }
+  return { pushed: confirmed.length, confirmed, externalIds };
+}