@volter/twin-polar 0.1.2 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-polar",
-  "version": "0.1.2",
+  "version": "2.0.1",
   "description": "Local Polar twin for customers, checkouts, subscriptions, meters, and usage events.",
   "author": "Volter (https://github.com/volter-ai)",
   "license": "Apache-2.0",
@@ -8,7 +8,8 @@
     "src",
     "README.md",
     "LICENSE",
-    "!**/*.test.ts"
+    "!**/*.test.ts",
+    "dist"
   ],
   "repository": {
     "type": "git",
@@ -18,26 +19,32 @@
   "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/polar#readme",
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
   },
   "bin": {
-    "world-polar": "src/cli.ts"
+    "world-polar": "dist/src/cli.js"
   },
   "scripts": {
     "test": "bun test src/*.test.ts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
   },
   "peerDependencies": {
-    "@volter/twin": "^0.1.2"
+    "@volter/world-core": "2.0.1"
   },
   "devDependencies": {
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",
-    "@volter/twin": "workspace:*",
-    "@volter/twin-tooling": "workspace:*",
+    "@volter/world-core": "2.0.1",
+    "@volter/world-tooling": "0.1.0",
     "typescript": "^5.9.0"
   },
   "engines": {
-    "bun": ">=1.2.0"
+    "node": ">=22.3"
   }
 }

package/src/cli.ts

@@ -1,9 +1,9 @@
-#!/usr/bin/env bun
-import { keepProcessAlive } from '@volter/twin/lifecycle';
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
 // world-polar CLI: serve the KERNEL-BACKED Polar API twin, or run conformance. State lives in
-// the @volter/twin action log (no in-memory side-store). Conformance is dev-only + lazy-imported
-// so the bin runs without @volter/twin-tooling (E2).
-import { hasFlag, optionValue } from '@volter/twin/args';
+// the @volter/world-core action log (no in-memory side-store). Conformance is dev-only + lazy-imported
+// so the bin runs without @volter/world-tooling (E2).
+import { hasFlag, optionValue } from '@volter/world-core/args';
 import { createPolarTwinServer } from './polar-server.ts';
 
 const [cmd, ...rest] = process.argv.slice(2);
@@ -12,7 +12,7 @@ const root = optionValue(rest, '--root') || undefined;
 const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
 
 if (cmd === 'serve' || cmd === undefined) {
-  const s = createPolarTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  const s = await createPolarTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
   process.stdout.write(`polar twin (merchant-of-record billing API)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
   await keepProcessAlive();
 } else if (cmd === 'conformance') {

package/src/index.ts

@@ -1,8 +1,8 @@
 // @volter/twin-polar — the Polar (polar.sh) merchant-of-record billing API twin, built on the
-// shared @volter/twin kernel. REST transport over api.polar.sh shapes; state lives entirely in
+// shared @volter/world-core kernel. REST transport over api.polar.sh shapes; state lives entirely in
 // the kernel action log (no side-store). Customers, products, subscriptions, orders, checkouts,
 // benefits, discounts, meters, usage events, customer sessions, and webhook endpoints.
-// (Conformance/capability tooling lives in @volter/twin-tooling, a dev dependency — NOT shipped.)
+// (Conformance/capability tooling lives in @volter/world-tooling, a dev dependency — NOT shipped.)
 export { handlePolarTwinRequest, polarTwinSnapshot, POLAR_RESOURCE_TYPES } from './polar-twin.ts';
 export type { PolarRequest, PolarResponse, PolarResourceType, PolarTwinSnapshot } from './polar-twin.ts';
 export { createPolarTwinFetch, createPolarTwinServer, type PolarTwinFetchOptions } from './polar-server.ts';
@@ -15,9 +15,11 @@ export {
   pullPolarOrders,
   pullPolarProducts,
   pullPolarSubscriptions,
-  pushPendingPolarActions,
   pushPolarAction,
   syncPolarFromReal,
+  polarClientOver,
+  syncPolarFromRemote,
+  performPolarAction,
 } from './polar-connector.ts';
 export type { PolarCustomer, PolarLikeClient, PolarOrder, PolarProduct, PolarSubscription, PolarBudgetedOptions } from './polar-connector.ts';
 // The client-side rate budget — the fail-closed backstop every live call goes through. The
@@ -43,9 +45,21 @@ export {
 export type { PolarBudgetErrorKind, PolarBudgetOptions, PolarBudgetReservation, PolarBudgetSnapshot } from './polar-budget.ts';
 
 // Registry descriptor: the pack self-describes so tooling can discover it.
-import type { TwinPack } from '@volter/twin';
+import { registerPack, type TwinPack } from '@volter/world-core';
 import { POLAR_RATE_BUDGET as RATE_BUDGET } from './polar-budget.ts';
+import { performPolarAction as perform, syncPolarFromRemote as refresh } from './polar-connector.ts';
 export const pack: TwinPack = {
+  // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of the real
+  // state system: perform one entry against Polar, refresh the root from it. Moved 2026-09-08.
+  protocol: '2',
+  refresh: { every: '5m', webhook: true, onDemand: { atMost: '30s' } },
+  stateSystem: { perform, refresh },
+  roundTrip: { method: 'POST', path: '/v1/products', body: { name: 'round trip', recurring_interval: 'month' }, headers: { authorization: 'Bearer polar_oat_round_trip' } },
+  // rule 5: a checkout names its product; when the head adopts Polar's id for the product, the kernel resolves it first
+  referenceTrip: { method: 'POST', path: '/v1/checkouts', body: { products: ['{{id}}'] }, headers: { authorization: 'Bearer polar_oat_round_trip' } },
+  references: [{ type: 'checkout', to: 'product', key: (f: Record<string, unknown>) => (typeof f.product_id === 'string' ? `product:${f.product_id}` : undefined), adopt: (_f: Record<string, unknown>, vendorId: string) => ({ product_id: vendorId.replace(/^product:/, '') }) }],
+  parityOrigin: 'http://twin',
+  shapeParity: 'held',
   // The SAME object polar-budget.ts declares at module load — one source of truth, so registering
   // the pack and importing the connector can never arm two different ceilings.
   rateBudget: RATE_BUDGET,
@@ -56,8 +70,8 @@ export const pack: TwinPack = {
   resources: ['customer', 'product', 'subscription', 'order', 'checkout', 'benefit', 'discount', 'meter', 'event', 'customer_session', 'webhook_endpoint'],
   specSource: 'polar-conformance.ts (endpoint/resource inventory from the Polar API docs at docs.polar.sh)',
   description: 'Polar merchant-of-record billing twin — customers, products, subscriptions, orders, checkouts (with confirm → subscription/order), benefits, discounts, meters, usage events, customer sessions, and webhook endpoints. Kernel-backed.',
-  // Adoption + interception, moved off the central maps unchanged (TWIN-PACK-CONTRACT
-  // back-migration 2026-08-31). Both the production API host and Polar's own sandbox host are
+  // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+  // 2026-08-31). Both the production API host and Polar's own sandbox host are
   // claimed — an integration picks one by configuration, and claiming only production would let
   // sandbox traffic escape the world.
   adoption: {
@@ -68,3 +82,5 @@ export const pack: TwinPack = {
   hosts: [{ host: 'api.polar.sh' }, { host: 'sandbox-api.polar.sh' }],
   browserRouting: { apiPathPrefix: '/v1', loaderHost: 'https://api.polar.sh' },
 };
+// registered at import: the kernel learns the pack's state system and its references (protocol 2)
+registerPack(pack);

package/src/polar-budget.ts

@@ -1,7 +1,7 @@
 // Polar's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus `guardPolarClient`,
 // the choke point every live Polar call goes through. The MECHANISM — the durable token-keyed
 // ledger, the rolling window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a
-// corrupt ledger — lives ONCE in the vendor-agnostic kernel (`@volter/twin` → `rateBudget.ts`).
+// corrupt ledger — lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`).
 // Read that module's header for the full rationale AND for the honest list of what the guard does
 // NOT guarantee (an injected clock or ledger path still defeats it — it guards carelessness, not
 // malice). This module is modeled on notion-budget.ts, the reference injected-client decorator.
@@ -47,11 +47,12 @@ import {
   rateBudgetPath,
   rateBudgetWeight,
   RateBudget,
+  RateBudgetError,
   type RateBudgetDeclaration,
   type RateBudgetOptions,
   type RateBudgetReservation,
   type RateBudgetSnapshot,
-} from '@volter/twin';
+} from '@volter/world-core';
 import type { PolarLikeClient } from './polar-connector.ts';
 
 const VENDOR = 'polar';
@@ -153,8 +154,8 @@ export class PolarBudget extends RateBudget {
   }
 }
 
-export type { RateBudgetErrorKind as PolarBudgetErrorKind } from '@volter/twin';
-export { RateBudgetError as PolarBudgetError } from '@volter/twin';
+export type { RateBudgetErrorKind as PolarBudgetErrorKind } from '@volter/world-core';
+export { RateBudgetError as PolarBudgetError } from '@volter/world-core';
 export type PolarBudgetReservation = RateBudgetReservation;
 export type PolarBudgetSnapshot = RateBudgetSnapshot;
 
@@ -253,6 +254,21 @@ export function guardPolarClient(client: PolarLikeClient, opts: PolarBudgetedOpt
     else budget.recordCall(weight, undefined, { reservation });
   };
 
+  /**
+   * Settle once the call RESOLVED: the vendor has answered. recordCall arms any cooldown before
+   * it throws (a back-off beyond the cap), so that refusal is swallowed and the answer kept — a
+   * write the vendor accepted is never reported failed and performed again on retry. A resolved
+   * answer that carries a non-2xx status still lets the louder refusal win.
+   */
+  const settleAnswered = (weight: number, reservation: RateBudgetReservation, v: unknown): void => {
+    try {
+      settle(weight, reservation, v);
+    } catch (e) {
+      const status = responseStatus(v);
+      if (!(e instanceof RateBudgetError) || (status !== undefined && (status < 200 || status >= 300))) throw e;
+    }
+  };
+
   /**
    * Charge, call, settle — for a MODELED method, whose interface declares it `async`. Refusing
    * REJECTS rather than throwing synchronously, so `client.x().catch(…)` behaves exactly as it does
@@ -265,7 +281,7 @@ export function guardPolarClient(client: PolarLikeClient, opts: PolarBudgetedOpt
       const reservation = budget.checkBudget(weight);
       try {
         const res = await invoke(...args);
-        settle(weight, reservation, res);
+        settleAnswered(weight, reservation, res);
         return res;
       } catch (e) {
         settle(weight, reservation, e); // may throw its own louder refusal, which wins
@@ -304,7 +320,7 @@ export function guardPolarClient(client: PolarLikeClient, opts: PolarBudgetedOpt
         : out;
     }
     return out.then(
-      (res) => { settle(weight, reservation, res); return res; },
+      (res) => { settleAnswered(weight, reservation, res); return res; },
       (e: unknown) => { settle(weight, reservation, e); throw e; },
     );
   };

package/src/polar-capabilities.ts

@@ -7,17 +7,15 @@
 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 { checkCapabilities, type CapabilityReport, type CapabilitySpec, verifyBoundary } from '@volter/world-tooling';
 import { checkPolarConformance } from './polar-conformance.ts';
-import { syncPolarFromReal, pushPendingPolarActions, type PolarLikeClient } from './polar-connector.ts';
+import { syncPolarFromReal, performPolarAction, 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 };
@@ -39,7 +37,7 @@ 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';
+const isNotFound = (r: PolarResponse) => r.status === 404 && (r.body as Body)?.error === 'ResourceNotFound'; // Polar's envelope: { error, detail }
 /** A FastAPI/Polar 422 validation envelope. */
 const isValidation = (r: PolarResponse) => r.status === 422 && Array.isArray((r.body as Body)?.detail);
 
@@ -241,6 +239,47 @@ export const POLAR_CAPABILITIES: CapabilitySpec[] = [
       return (field(s, 'active_meters') as Body[])[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') as Body[];
+      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') as unknown[]).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') as Body[];
+      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) => {
@@ -298,18 +337,17 @@ export const POLAR_CAPABILITIES: CapabilitySpec[] = [
         rmSync(root, { recursive: true, force: true });
       }
     })),
-  done('polar.connector.push.entrypoint', 'connector', 'pushPendingPolarActions pushes a local customer.create to the injected client', 'connector', 'core', () =>
+  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 {
-        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;
+        const made = await handlePolarTwinRequest({ method: 'POST', path: '/v1/customers/', body: JSON.stringify({ email: 'push@example.test', name: 'P' }), root });
+        const wire: Array<{ method: string; path: string; body?: string | Uint8Array }> = [];
+        const execute = async (r: { method: string; path: string; body?: string | Uint8Array }) => { 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' } } as never, { 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()) as Body;
+        // 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 });
       }
@@ -320,9 +358,6 @@ export const POLAR_CAPABILITIES: CapabilitySpec[] = [
     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) ─────────────────────
   ...[
@@ -380,9 +415,9 @@ export const POLAR_CAPABILITIES: CapabilitySpec[] = [
 
   // ── 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).
+  // `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 stays out of scope above). See
+  // 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'),

package/src/polar-connector.ts

@@ -12,8 +12,8 @@
 //
 // 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';
+import { observeResources } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
 //
 // ── The client-side RATE BUDGET is not optional here ────────────────────────────────────────
 // Polar publishes 500 requests/minute in production and 100/minute in sandbox per organization, and
@@ -29,7 +29,7 @@ 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 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 };
 
@@ -53,7 +53,7 @@ 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: {} } };
+  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, trial_interval: p.trial_interval ?? null, trial_interval_count: p.trial_interval_count ?? null, prices: p.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: {} } };
@@ -101,8 +101,43 @@ export async function syncPolarFromReal(
     ...(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 };
+  // protocol 2: an observation lands on the head through the kernel's fold — one batch, one instant
+  const report = observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), { ...(opts.root !== undefined ? { root: opts.root } : {}), at: occurredAt, batch: `obs:${SERVICE}:${occurredAt}` });
+  return { observed: report.observed, deltasAppended: report.appended };
+}
+
+// ── PROTOCOL 2: the state system's two adapters, over the kernel's executor ──────────
+/** A PolarLikeClient over a RemoteExecute: the calls the SDK makes, as wire requests the executor carries. */
+export function polarClientOver(execute: RemoteExecute): PolarLikeClient {
+  const call = async <T>(method: string, path: string, body?: Record<string, unknown>): Promise<T> => {
+    const res = await execute({ method, path, headers: { accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) });
+    if (res.status >= 300) throw new Error(`polar: ${method} ${path} answered ${res.status}: ${res.body.slice(0, 200)}`);
+    return (res.body === '' ? {} : JSON.parse(res.body)) as T;
+  };
+  const list = <T>(path: string) => async (): Promise<{ items: T[] }> => { const page = await call<{ items?: T[] }>('GET', `${path}?limit=100`); return { items: page.items ?? [] }; };
+  return {
+    customers: { list: list<PolarCustomer>('/v1/customers'), create: (params) => call<{ id: string }>('POST', '/v1/customers', params) },
+    products: { list: list<PolarProduct>('/v1/products'), create: (params) => call<{ id: string }>('POST', '/v1/products', params) },
+    subscriptions: { list: list<PolarSubscription>('/v1/subscriptions') },
+    orders: { list: list<PolarOrder>('/v1/orders') },
+  };
+}
+/** The refresh adapter: pull Polar's customers, products, subscriptions and orders through the executor and fold them into the root. */
+export async function syncPolarFromRemote(execute: RemoteExecute, opts: { root?: string; origin?: string; occurredAt?: string } & PolarBudgetedOptions = {}): Promise<{ observed: number; deltasAppended: number }> {
+  // guarded HERE too (idempotent), so the source tooth sees every entrypoint hold the budget
+  const budget = { ...(opts.budgetOptions ?? {}), ...(opts.root !== undefined && !opts.budgetOptions?.root ? { root: opts.root } : {}) };
+  const client = guardPolarClient(polarClientOver(execute), polarBudgetOf({ ...opts, budgetOptions: budget }));
+  return syncPolarFromReal(client, { ...opts, budgetOptions: budget });
+}
+/** The perform adapter: one entry crosses to Polar through the executor; a customer or product it names by a local id resolves first. */
+export async function performPolarAction(execute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome> {
+  const fields = { ...(action.fields ?? {}) };
+  for (const [field, type] of [['customer_id', 'customer'], ['product_id', 'product']] as const) {
+    if (typeof fields[field] === 'string') fields[field] = ctx.resolve(type, kid(type, String(fields[field]).replace(new RegExp(`^${type}:`), ''))).replace(new RegExp(`^${type}:`), '');
+  }
+  const budget = { budgetOptions: { ...(ctx.root !== undefined ? { root: ctx.root } : {}) } };
+  const { externalId } = await pushPolarAction(guardPolarClient(polarClientOver(execute), polarBudgetOf(budget)), { operation: action.operation, subject: action.subject, fields }, budget);
+  return { externalId };
 }
 
 // ── PUSH ──────────────────────────────────────────────────────────────────────────
@@ -133,23 +168,5 @@ export async function pushPolarAction(
  * 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 };
-}
+// protocol 2: the pending-actions loop is the kernel's (the head performs each entry through `performPolarAction`);
+// the v1 `pushPendingPolarActions` is gone with the log it read.

package/src/polar-server.ts

@@ -7,8 +7,9 @@
 // kernel's ONE adaptation (`createTwinFetchFromHandler`); this file contributes only VALUES. The
 // vendor's 204 deletes return `{ status: 204, body: null }`, which the adapter's null-body rule
 // serves as a genuinely empty response. The server is one line of Bun.serve around that closure.
+import { serveHttp } from '@volter/world-core';
 import { handlePolarTwinRequest } from './polar-twin.ts';
-import { createTwinFetchFromHandler, statefulTwinManifest } from '@volter/twin';
+import { createTwinFetchFromHandler, statefulTwinManifest, twinPublicBase } from '@volter/world-core';
 
 /** Options every Polar-twin HTTP surface needs, independent of who owns the socket. */
 export interface PolarTwinFetchOptions {
@@ -17,14 +18,37 @@ export interface PolarTwinFetchOptions {
 }
 
 export function createPolarTwinFetch(options: PolarTwinFetchOptions = {}): (request: Request) => Promise<Response> {
-  return createTwinFetchFromHandler(handlePolarTwinRequest, {
+  const api = createTwinFetchFromHandler(handlePolarTwinRequest, {
     ...options,
     manifest: statefulTwinManifest({ vendor: 'polar', twinOf: 'the Polar billing API', stores: 'customers, checkouts, subscriptions, meters and usage events' }),
+    // where this twin is reached (origin plus any served-World mount path): the checkout's hosted page is minted there
+    extras: (request) => ({ publicBase: twinPublicBase(request) }),
   });
+  // the hosted checkout page, at the twin's own address: what a person sees after "continue to checkout at
+  // Polar" in a walk — the product, the amount, a Pay button that confirms the checkout and returns to the
+  // app's success_url (in production this page is Polar's; the twin stands in for it, plainly labelled)
+  return async function polarFetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const page = /^\/twin\/checkout\/([a-zA-Z0-9-]+)(\/pay)?$/.exec(url.pathname);
+    if (!page) return api(request);
+    const id = page[1]!;
+    const read = await api(new Request(`${url.origin}/v1/checkouts/${id}`, { headers: { authorization: request.headers.get('authorization') ?? 'Bearer polar_oat_page' } }));
+    if (!read.ok) return new Response('no such checkout', { status: 404 });
+    const c = (await read.json()) as { status: string; amount: number; currency: string; success_url: string | null; product?: { name?: string } | null; customer_email?: string | null };
+    if (page[2] && request.method === 'POST') {
+      const done = await api(new Request(`${url.origin}/v1/checkouts/${id}/confirm`, { method: 'POST', headers: { 'content-type': 'application/json', authorization: 'Bearer polar_oat_page' }, body: '{}' }));
+      if (!done.ok) return new Response(`the checkout could not be confirmed (${done.status})`, { status: 502 });
+      return new Response(null, { status: 303, headers: { location: c.success_url ?? `${twinPublicBase(request)}/twin/checkout/${id}` } });
+    }
+    const money = `$${(Number(c.amount ?? 0) / 100).toFixed(2)} ${String(c.currency ?? 'usd').toUpperCase()}`;
+    const esc = (v: unknown): string => String(v ?? '').replace(/[&<>"]/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[ch]!);
+    const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Checkout — Polar (twin)</title><style>body{font:16px/1.5 -apple-system,system-ui,sans-serif;margin:0;background:#f6f6f7;color:#111}main{max-width:480px;margin:48px auto;background:#fff;border:1px solid #e3e3e6;border-radius:12px;padding:28px 32px}h1{font-size:20px;margin:0 0 4px}.mode{color:#666;font-size:13px}.price{font-size:32px;font-weight:650;margin:12px 0}button{font:inherit;padding:10px 18px;border-radius:8px;border:0;background:#111;color:#fff;cursor:pointer}label{display:block;margin:12px 0 4px;font-size:13px;color:#555}input{width:100%;padding:8px 10px;border:1px solid #ccc;border-radius:6px;font:inherit}</style></head><body><main><p class="mode">Polar checkout · this page is the polar twin's stand-in for Polar's hosted checkout</p><h1>${esc(c.product?.name ?? 'Subscription')}</h1><p class="price">${esc(money)} <span class="mode">/ month</span></p>${c.status !== 'open' ? `<p>This checkout is ${esc(c.status)}.</p>` : `<form method="post" action="${esc(twinPublicBase(request))}/twin/checkout/${esc(id)}/pay"><label>Email</label><input name="email" value="${esc(c.customer_email ?? '')}" readonly /><label>Card</label><input name="card" value="4242 4242 4242 4242 · any date · any code" readonly /><p class="mode">A test card: nothing is charged here.</p><button type="submit">Pay ${esc(money)}</button></form>`}</main></body></html>`;
+    return new Response(html, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+  };
 }
 
-export function createPolarTwinServer(options: { root?: string; port?: number; readOnly?: boolean } = {}): { port: number; stop: () => void } {
-  const server = Bun.serve({
+export async function createPolarTwinServer(options: { root?: string; port?: number; readOnly?: boolean } = {}): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
     port: options.port ?? 0,
     idleTimeout: 60,
     fetch: createPolarTwinFetch(options),