@volter/twin-polar 0.1.2 → 2.0.1

package/dist/src/polar-capabilities.js

@@ -0,0 +1,389 @@
+// 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, verifyBoundary } from '@volter/world-tooling';
+import { checkPolarConformance } from "./polar-conformance.js";
+import { syncPolarFromReal, performPolarAction } from "./polar-connector.js";
+import { handlePolarTwinRequest } from "./polar-twin.js";
+const done = (id, area, title, dimension, tier, verify) => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id, area, title, dimension, tier) => ({ id, area, title, dimension, tier, expected: 'todo' });
+/** Run a sequence of real Polar requests against an isolated kernel root; return all responses. */
+async function withRoot(steps) {
+    const root = mkdtempSync(join(tmpdir(), 'polar-cap-'));
+    const h = (s) => 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) => r.status >= 200 && r.status < 300;
+const id = (r) => r.body?.id;
+const field = (r, k) => r.body?.[k];
+const items = (r) => r.body?.items;
+/** A Polar ResourceNotFound 404 (the real error envelope). */
+const isNotFound = (r) => r.status === 404 && r.body?.error === 'ResourceNotFound'; // Polar's envelope: { error, detail }
+/** A FastAPI/Polar 422 validation envelope. */
+const isValidation = (r) => r.status === 422 && Array.isArray(r.body?.detail);
+export const POLAR_CAPABILITIES = [
+    // ── 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').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').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');
+        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').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');
+        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');
+        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');
+        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');
+        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;
+        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').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')[0].balance === 3;
+    })),
+    // ── The customer by YOUR id, meters as Polar keeps them (2026-09-07, the platform's billing) ──
+    done('polar.customers.get_external_state', 'customers', 'GET /customers/external/{id} and its /state: the customer by external id; unknown → 404', 'api', 'core', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/customers/', b: { email: 'ext@example.test', external_id: 'org_1' } });
+        const g = await h({ m: 'GET', p: '/v1/customers/external/org_1' });
+        const s = await h({ m: 'GET', p: '/v1/customers/external/org_1/state' });
+        const miss = await h({ m: 'GET', p: '/v1/customers/external/nobody/state' });
+        return ok(g) && field(g, 'external_id') === 'org_1' && ok(s) && Array.isArray(field(s, 'active_subscriptions')) && isNotFound(miss);
+    })),
+    done('polar.checkouts.external_customer_id', 'checkouts', 'A checkout created with external_customer_id confirms onto the customer that id names (created if new)', 'api', 'core', () => withRoot(async (h) => {
+        const p = await h({ m: 'POST', p: '/v1/products/', b: { name: 'Team', recurring_interval: 'month', prices: [{ price_amount: 2000, price_currency: 'usd' }] } });
+        const c = await h({ m: 'POST', p: '/v1/checkouts/', b: { products: [id(p)], external_customer_id: 'org_42', customer_email: 'pay@example.test' } });
+        const done = await h({ m: 'POST', p: `/v1/checkouts/${id(c)}/confirm`, b: {} });
+        const s = await h({ m: 'GET', p: '/v1/customers/external/org_42/state' });
+        const subs = field(s, 'active_subscriptions');
+        return c.status === 201 && ok(done) && ok(s) && subs.length === 1 && subs[0].status === 'active';
+    })),
+    done('polar.events.ingest_dedupes_external_id', 'events', 'Ingest counts a repeated external_id as a duplicate and resolves external_customer_id to the customer', 'api', 'core', () => withRoot(async (h) => {
+        const first = await h({ m: 'POST', p: '/v1/events/ingest', b: { events: [{ name: 'world.hour', external_customer_id: 'org_7', external_id: 'org_7:h:1', metadata: { units: 1 } }] } });
+        const again = await h({ m: 'POST', p: '/v1/events/ingest', b: { events: [{ name: 'world.hour', external_customer_id: 'org_7', external_id: 'org_7:h:1', metadata: { units: 1 } }] } });
+        const list = await h({ m: 'GET', p: '/v1/events/?external_customer_id=org_7' });
+        const cust = await h({ m: 'GET', p: '/v1/customers/external/org_7' });
+        return field(first, 'inserted') === 1 && field(again, 'duplicates') === 1 && field(again, 'inserted') === 0 && field(list, 'items').length === 1 && ok(cust);
+    })),
+    done('polar.customers.state_per_meter_aggregation', 'customers', 'With meters defined, state carries one entry per meter aggregated by its filter and function', 'api', 'core', () => withRoot(async (h) => {
+        const m = await h({ m: 'POST', p: '/v1/meters/', b: { name: 'world_hours', filter: { conjunction: 'and', clauses: [{ property: 'name', operator: 'eq', value: 'world.hour' }] }, aggregation: { func: 'sum', property: 'units' } } });
+        await h({ m: 'POST', p: '/v1/meters/', b: { name: 'pushes', filter: { conjunction: 'and', clauses: [{ property: 'name', operator: 'eq', value: 'world.push' }] }, aggregation: { func: 'count' } } });
+        await h({ m: 'POST', p: '/v1/events/ingest', b: { events: [
+                    { name: 'world.hour', external_customer_id: 'org_9', external_id: 'a', metadata: { units: 2 } },
+                    { name: 'world.hour', external_customer_id: 'org_9', external_id: 'b', metadata: { units: 3 } },
+                    { name: 'world.push', external_customer_id: 'org_9', external_id: 'c' },
+                ] } });
+        const s = await h({ m: 'GET', p: '/v1/customers/external/org_9/state' });
+        const meters = field(s, 'active_meters');
+        const hours = meters.find((x) => x.meter_id === id(m));
+        const pushes = meters.find((x) => x.meter_id !== id(m));
+        return meters.length === 2 && hours?.consumed_units === 5 && pushes?.consumed_units === 1;
+    })),
+    // ── 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 = {
+                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', 'performPolarAction crosses a local customer.create to Polar through the executor (protocol 2)', 'connector', 'core', () => withRoot(async () => {
+        const root = mkdtempSync(join(tmpdir(), 'polar-push-'));
+        try {
+            const made = await handlePolarTwinRequest({ method: 'POST', path: '/v1/customers/', body: JSON.stringify({ email: 'push@example.test', name: 'P' }), root });
+            const wire = [];
+            const execute = async (r) => { wire.push(r); return { status: 201, headers: {}, body: JSON.stringify({ id: 'cus_pushed' }) }; };
+            const out = await performPolarAction(execute, { operation: 'customer.create', subject: { type: 'customer', id: `customer:${String(field(made, 'id'))}` }, fields: { email: 'push@example.test', name: 'P' } }, { resolve: (_t, l) => l, service: 'polar', root });
+            const sent = JSON.parse(typeof wire[0]?.body === 'string' ? wire[0].body : Buffer.from(wire[0]?.body ?? '{}').toString());
+            // one entry, one wire write, the vendor's id back; re-performing is the kernel's to refuse
+            return out.externalId === 'cus_pushed' && wire.length === 1 && wire[0].path === '/v1/customers' && sent.email === 'push@example.test';
+        }
+        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;
+    }),
+    // ── 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 a real-processing phantom (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 is what the real root does). 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',
+];
+export async function polarCapabilities() {
+    return checkCapabilities('polar', POLAR_CAPABILITIES);
+}

package/dist/src/polar-conformance.d.ts

@@ -0,0 +1,7 @@
+export type PolarConformanceReport = {
+    ok: boolean;
+    endpointsChecked: number;
+    resourceTypesChecked: number;
+    violations: string[];
+};
+export declare function checkPolarConformance(): PolarConformanceReport;

package/dist/src/polar-conformance.js

@@ -0,0 +1,25 @@
+// 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.js";
+export function checkPolarConformance() {
+    const snapshot = polarTwinSnapshot();
+    const violations = [];
+    // 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/dist/src/polar-connector.d.ts

@@ -0,0 +1,113 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { type PolarBudgetedOptions } from './polar-budget.js';
+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;
+    prices?: unknown[];
+    trial_interval?: string | null;
+    trial_interval_count?: number | null;
+};
+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;
+};
+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[];
+        }>;
+    };
+}
+export declare function mapCustomer(c: PolarCustomer): SyncResource;
+export declare function mapProduct(p: PolarProduct): SyncResource;
+export declare function mapSubscription(s: PolarSubscription): SyncResource;
+export declare function mapOrder(o: PolarOrder): SyncResource;
+export declare function pullPolarCustomers(rawClient: PolarLikeClient, opts?: PolarBudgetedOptions): Promise<SyncResource[]>;
+export declare function pullPolarProducts(rawClient: PolarLikeClient, opts?: PolarBudgetedOptions): Promise<SyncResource[]>;
+export declare function pullPolarSubscriptions(rawClient: PolarLikeClient, opts?: PolarBudgetedOptions): Promise<SyncResource[]>;
+export declare function pullPolarOrders(rawClient: PolarLikeClient, opts?: PolarBudgetedOptions): Promise<SyncResource[]>;
+/**
+ * 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 declare function syncPolarFromReal(rawClient: PolarLikeClient, opts?: {
+    root?: string;
+    occurredAt?: string;
+} & PolarBudgetedOptions): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/** A PolarLikeClient over a RemoteExecute: the calls the SDK makes, as wire requests the executor carries. */
+export declare function polarClientOver(execute: RemoteExecute): PolarLikeClient;
+/** The refresh adapter: pull Polar's customers, products, subscriptions and orders through the executor and fold them into the root. */
+export declare function syncPolarFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+} & PolarBudgetedOptions): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/** The perform adapter: one entry crosses to Polar through the executor; a customer or product it names by a local id resolves first. */
+export declare function performPolarAction(execute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome>;
+export declare function pushPolarAction(rawClient: PolarLikeClient, action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>, opts?: PolarBudgetedOptions): Promise<{
+    externalId: string;
+}>;
+/**
+ * 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.
+ */