@volter/twin-polar 0.1.1 → 2.0.0

package/README.md

@@ -24,12 +24,12 @@ capability):
 - `polar.tax.real_calculation` — tax-authority integrations and live jurisdiction rules are
   outside a deterministic local twin.
 
-### UI mirror — a tracked gap, not a carve-out
+### UI mirror — a tracked gap
 
 This pack ships **no mirror UI, and that is an unfinished gap rather than a decision.** Polar is a
 merchant-of-record billing product with a real operator dashboard — the same shape as `stripe`,
 which does mirror — so under the rule in
-[docs/ADDING_A_TWIN.md](../../../docs/ADDING_A_TWIN.md) ("Does this vendor get a mirror?") it
+[../../../docs/contributing/adding-a-twin.md](../../../docs/contributing/adding-a-twin.md) ("Does this vendor get a mirror?") it
 should have one. The work is tracked in the manifest as `polar.mirror.ui`
 (operator mirror for customers/subscriptions/orders/events).
 

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,26 @@
+#!/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/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.js";
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', String(process.env.PORT ?? '0'))) || undefined;
+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 = 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') {
+    const { checkPolarConformance } = await import("./polar-conformance.js");
+    const report = checkPolarConformance();
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.ok)
+        process.exitCode = 1;
+}
+else {
+    process.stdout.write('Usage: world-polar serve|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/dist/src/index.d.ts

@@ -0,0 +1,9 @@
+export { handlePolarTwinRequest, polarTwinSnapshot, POLAR_RESOURCE_TYPES } from './polar-twin.js';
+export type { PolarRequest, PolarResponse, PolarResourceType, PolarTwinSnapshot } from './polar-twin.js';
+export { createPolarTwinFetch, createPolarTwinServer, type PolarTwinFetchOptions } from './polar-server.js';
+export { mapCustomer, mapOrder, mapProduct, mapSubscription, pullPolarCustomers, pullPolarOrders, pullPolarProducts, pullPolarSubscriptions, pushPolarAction, syncPolarFromReal, polarClientOver, syncPolarFromRemote, performPolarAction, } from './polar-connector.js';
+export type { PolarCustomer, PolarLikeClient, PolarOrder, PolarProduct, PolarSubscription, PolarBudgetedOptions } from './polar-connector.js';
+export { POLAR_BUDGETED_METHODS, POLAR_BUDGET_CEILING, POLAR_BUDGET_MAX_RETRY_AFTER_S, POLAR_BUDGET_WINDOW_MS, POLAR_CALL_WEIGHTS, POLAR_RATE_BUDGET, PolarBudget, PolarBudgetError, polarBudgetPath, polarCallWeight, polarClientBudget, guardPolarClient, } from './polar-budget.js';
+export type { PolarBudgetErrorKind, PolarBudgetOptions, PolarBudgetReservation, PolarBudgetSnapshot } from './polar-budget.js';
+import { type TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,55 @@
+// @volter/twin-polar — the Polar (polar.sh) merchant-of-record billing API twin, built on the
+// 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/world-tooling, a dev dependency — NOT shipped.)
+export { handlePolarTwinRequest, polarTwinSnapshot, POLAR_RESOURCE_TYPES } from "./polar-twin.js";
+export { createPolarTwinFetch, createPolarTwinServer } from "./polar-server.js";
+export { mapCustomer, mapOrder, mapProduct, mapSubscription, pullPolarCustomers, pullPolarOrders, pullPolarProducts, pullPolarSubscriptions, pushPolarAction, syncPolarFromReal, polarClientOver, syncPolarFromRemote, performPolarAction, } from "./polar-connector.js";
+// The client-side rate budget — the fail-closed backstop every live call goes through. The
+// MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives here is this vendor's
+// DECLARATION (window/ceiling/per-method weights) plus `guardPolarClient`, the choke point the
+// connector entrypoints apply unconditionally. Exported so an operator can inspect spend
+// (`snapshot`) and a caller can catch `PolarBudgetError` by type; there is deliberately no export
+// that disables the guard.
+export { POLAR_BUDGETED_METHODS, POLAR_BUDGET_CEILING, POLAR_BUDGET_MAX_RETRY_AFTER_S, POLAR_BUDGET_WINDOW_MS, POLAR_CALL_WEIGHTS, POLAR_RATE_BUDGET, PolarBudget, PolarBudgetError, polarBudgetPath, polarCallWeight, polarClientBudget, guardPolarClient, } from "./polar-budget.js";
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack } from '@volter/world-core';
+import { POLAR_RATE_BUDGET as RATE_BUDGET } from "./polar-budget.js";
+import { performPolarAction as perform, syncPolarFromRemote as refresh } from "./polar-connector.js";
+export const pack = {
+    // 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) => (typeof f.product_id === 'string' ? `product:${f.product_id}` : undefined), adopt: (_f, vendorId) => ({ 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,
+    vendor: 'polar',
+    transport: 'rest',
+    archetype: 'crud',
+    bin: 'world-polar',
+    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 (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: {
+        // Polar's official Python SDK (polarsource/polar-python).
+        pypi: ['polar-sdk'],
+        sdks: ['@polar-sh/sdk'], scopes: ['@polar-sh/'], envStems: ['POLAR'],
+    },
+    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/dist/src/polar-budget.d.ts

@@ -0,0 +1,83 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+import type { PolarLikeClient } from './polar-connector.js';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export declare const POLAR_BUDGET_WINDOW_MS = 60000;
+/** Weighted units allowed inside one window. See the header for where this number comes from. */
+export declare const POLAR_BUDGET_CEILING = 60;
+/** Seconds. A `Retry-After` above this means the credential is throttled hard — fail loudly. */
+export declare const POLAR_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** Per-call cost, keyed by the client method the guard is about to invoke. See the header. */
+export declare const POLAR_CALL_WEIGHTS: {
+    /** Every modeled call. Polar meters one per-minute budget across the API. */
+    readonly other: 1;
+};
+/**
+ * The client methods this pack PRICES BY NAME, as dotted paths into the injected client.
+ *
+ * Two kinds of entry: (a) every method this connector actually calls, and (b) an endpoint the
+ * VENDOR documents in a distinct tier which a consumer can reach through the guarded client even
+ * though this connector never calls it (see the weights section of the header). Used to build the
+ * guarded surface — and, in the pack's own suite, the counting fake.
+ *
+ * NOT a closed list, and not a claim about the injected client's shape. A path the real client does
+ * not have is SKIPPED (this connector's members are optional; inventing one would turn "observe
+ * nothing" into "call something that isn't there"), and a method absent from this list is still
+ * PRICED at `defaultWeight` when a caller reaches for it — an unmodeled endpoint must never be
+ * free, and dropping one would be worse than free because it would be invisible.
+ */
+export declare const POLAR_BUDGETED_METHODS: readonly ["customers.list", "customers.create", "products.list", "products.create", "subscriptions.list", "orders.list"];
+/** THE PACK'S DECLARATION — pure data, the only Polar-specific thing in the whole budget. */
+export declare const POLAR_RATE_BUDGET: RateBudgetDeclaration;
+/** Price one Polar call by its client method key (a dotted path, e.g. `customers.list`). */
+export declare function polarCallWeight(method: string): number;
+/** Where Polar's ledger lives. Token-keyed and cwd-independent by default (the vendor limits per
+ *  credential, so a cwd-scoped ledger would hand the same credential a fresh allowance in every
+ *  checkout, worktree and CI matrix leg); pass `root` to opt into world-scoped accounting. */
+export declare function polarBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+/** Construction options for Polar's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type PolarBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+/**
+ * Polar's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof PolarBudget` means "a budget that accounts against this
+ * vendor's ledger under this vendor's ceiling": another vendor's `RateBudget` (with its own,
+ * possibly larger, ceiling) is NOT assignable where one of these is required.
+ */
+export declare class PolarBudget extends RateBudget {
+    constructor(opts?: PolarBudgetOptions);
+}
+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;
+/** What every budgeted connector entrypoint accepts. There is deliberately no option that turns the
+ *  guard OFF — only ones that say WHICH ledger and clock to account against. */
+export type PolarBudgetedOptions = {
+    /** An existing budget to share across calls. Omit and one is constructed. Cannot be null. */
+    budget?: PolarBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: PolarBudgetOptions;
+};
+/** Pull the budget wiring out of a caller's opts bag, so an entrypoint can forward it verbatim. */
+export declare function polarBudgetOf(opts: PolarBudgetedOptions): PolarBudgetedOptions;
+/** Is this client already behind a budget? Returns the budget it is behind, if so. */
+export declare function polarClientBudget(client: unknown): RateBudget | undefined;
+/**
+ * Wrap an INJECTED Polar client so EVERY call it makes is charged against the shared budget
+ * BEFORE the request goes out. This pack's connector never constructs the transport itself (the
+ * consumer injects a client that satisfies `PolarLikeClient` structurally), so the guard is a
+ * DECORATOR rather than a factory — which is exactly why every connector entrypoint applies it
+ * UNCONDITIONALLY instead of trusting the caller to have done it.
+ *
+ * IDEMPOTENT: wrapping an already-guarded client returns it unchanged, so a caller who forgot is
+ * protected and a caller who wrapped deliberately is not double-charged.
+ *
+ * A method that THROWS is still inspected: an SDK typically RAISES on a 429 rather than returning
+ * it, and that error's back-off is exactly the signal that must become a persisted cooldown. Losing
+ * it would leave the ledger cheerfully spending into a throttled credential. The original error is
+ * always re-raised afterwards — the budget never swallows a vendor failure — EXCEPT when the
+ * back-off is beyond the cap, where the budget's own louder "stop calling" error takes precedence.
+ */
+export declare function guardPolarClient(client: PolarLikeClient, opts?: PolarBudgetedOptions): PolarLikeClient;

package/dist/src/polar-budget.js

@@ -0,0 +1,413 @@
+// 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/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.
+//
+// ── WHY POLAR NEEDS ONE ─────────────────────────────────────────────────────────────
+// Polar publishes its limits cleanly and is the only vendor in this batch that documents a
+// `Retry-After` header (polar.sh/docs/api-reference/introduction): "500 requests per minute" in
+// production and "100 requests per minute" in sandbox, in both cases per organization/customer or
+// OAuth2 client, plus a separate "3 requests per second" budget for the unauthenticated license-key
+// validation/activation/deactivation endpoints. Its 429 "includes a Retry-After header indicating how
+// long you should wait" — which is exactly the signal the kernel's cooldown is built to consume, so
+// on this vendor the guard's second line of defence is genuinely armed rather than inferred.
+//
+// ── HOW THE CEILING WAS CHOSEN ──────────────────────────────────────────────────────────────
+// THIS PACK IS DELIBERATELY MORE PERMISSIVE THAN THE KERNEL FALLBACK, and the documented limits are
+// why. The ceiling is derived from the SANDBOX figure, not production: 100 requests/minute is the
+// tighter of the two published numbers, and a twin consumer is at least as likely to be pointed at
+// sandbox as at production, so budgeting against 500/min would be the wrong default. 60 weighted
+// units / 60s at weight 1 admits 60 calls/minute — 60% of the documented sandbox limit and 12% of
+// production, against the fallback's 30/min. A pull of all four domains is 4 calls, so this leaves a
+// pull-heavy caller real headroom while still stopping a loop well inside the vendor's own limit.
+//
+// ── WHAT THIS DOES NOT DO: PACE ─────────────────────────────────────────────────────────────
+// It bounds the 60s AVERAGE; it does NOT bound the instantaneous rate. The window has no
+// spacing, so a tight `await` loop can legitimately fire the whole allowance in a fraction of a
+// second. In that shape the vendor's own 429 can arrive BEFORE this ceiling does, and the backstop
+// is then the COOLDOWN: the guard reads the back-off off the thrown error (or the response's
+// exhaustion headers) and refuses every later call without touching the vendor. So the honest claim
+// is "bounds the 60s average, and converts the vendor's first 429 into a hard stop" — never
+// "refuses before the vendor ever 429s". Pacing is the CALLER's job; this module REFUSES, it never
+// sleeps (see the kernel header: it is deliberately not a scheduler). A tighter window would not
+// close the gap, it would only turn every legitimate multi-page pull into a cascade of refusals.
+//
+// ── HOW THE WEIGHTS WERE CHOSEN (and what is a judgement call) ──────────────────────────────
+// FLAT: every call costs 1. Polar meters ONE per-minute budget across the authenticated API — its
+// docs give a single figure per environment rather than a per-endpoint table — so pricing one list
+// above another would be invention. The one genuinely separate budget Polar publishes (3 requests/
+// second for the unauthenticated license-key endpoints) is not part of this connector's surface and
+// is per-second rather than per-minute, so it is recorded here rather than modeled as a rule. An
+// unmodeled method reached through the guarded client is charged the same 1, never free.
+import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, RateBudgetError, } from '@volter/world-core';
+const VENDOR = 'polar';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const POLAR_BUDGET_WINDOW_MS = 60_000;
+/** Weighted units allowed inside one window. See the header for where this number comes from. */
+export const POLAR_BUDGET_CEILING = 60;
+/** Seconds. A `Retry-After` above this means the credential is throttled hard — fail loudly. */
+export const POLAR_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** Per-call cost, keyed by the client method the guard is about to invoke. See the header. */
+export const POLAR_CALL_WEIGHTS = {
+    /** Every modeled call. Polar meters one per-minute budget across the API. */
+    other: 1,
+};
+/**
+ * The client methods this pack PRICES BY NAME, as dotted paths into the injected client.
+ *
+ * Two kinds of entry: (a) every method this connector actually calls, and (b) an endpoint the
+ * VENDOR documents in a distinct tier which a consumer can reach through the guarded client even
+ * though this connector never calls it (see the weights section of the header). Used to build the
+ * guarded surface — and, in the pack's own suite, the counting fake.
+ *
+ * NOT a closed list, and not a claim about the injected client's shape. A path the real client does
+ * not have is SKIPPED (this connector's members are optional; inventing one would turn "observe
+ * nothing" into "call something that isn't there"), and a method absent from this list is still
+ * PRICED at `defaultWeight` when a caller reaches for it — an unmodeled endpoint must never be
+ * free, and dropping one would be worse than free because it would be invisible.
+ */
+export const POLAR_BUDGETED_METHODS = [
+    'customers.list',
+    'customers.create',
+    'products.list',
+    'products.create',
+    'subscriptions.list',
+    'orders.list',
+];
+/** THE PACK'S DECLARATION — pure data, the only Polar-specific thing in the whole budget. */
+export const POLAR_RATE_BUDGET = {
+    windowMs: POLAR_BUDGET_WINDOW_MS,
+    ceiling: POLAR_BUDGET_CEILING,
+    defaultWeight: POLAR_CALL_WEIGHTS.other,
+    maxRetryAfterSeconds: POLAR_BUDGET_MAX_RETRY_AFTER_S,
+    // Ordered: the kernel prices FIRST-MATCH-WINS, so the tightest tier is listed first.
+    rules: [],
+    reason: "Polar publishes \"500 requests per minute\" in production and \"100 requests per minute\" in sandbox, per " +
+        "organization/customer or OAuth2 client, plus a separate 3 requests/second budget for the unauthenticated " +
+        "license-key endpoints; its 429 explicitly \"includes a Retry-After header\". THIS DECLARATION IS MORE " +
+        "PERMISSIVE THAN the kernel's DEFAULT_RATE_BUDGET (30 calls/min) and the documented limits are why: 60 " +
+        "units / 60s at weight 1 admits 60 calls/min, derived from the tighter SANDBOX figure (60% of 100/min, 12% " +
+        "of production's 500/min) because a twin consumer is at least as likely to be pointed at sandbox. Weights " +
+        "are flat because Polar meters one per-minute budget across the authenticated API rather than publishing a " +
+        "per-endpoint table; the separate 3/s license-key budget is not in this connector's surface. Polar is the " +
+        "one vendor in this batch that documents Retry-After, so the cooldown path is armed by the vendor itself.",
+};
+// Declared at module load, so merely importing this module (which `polar-connector.ts` does) is
+// enough to arm the real ceiling. A budget constructed BEFORE this runs falls back to the kernel's
+// DEFAULT_RATE_BUDGET — which is tighter in call COUNT but prices every call at 2, so for a vendor
+// with an expensive endpoint the fallback is CHEAPER there, not safer. `RateBudget` reads its policy
+// LIVE precisely so this declaration takes effect the moment it lands, and constructing through the
+// subclass below (whose module IS this one) makes the ordering a non-issue in practice.
+declareRateBudget(VENDOR, POLAR_RATE_BUDGET);
+/** Price one Polar call by its client method key (a dotted path, e.g. `customers.list`). */
+export function polarCallWeight(method) {
+    return rateBudgetWeight(VENDOR, method);
+}
+/** Where Polar's ledger lives. Token-keyed and cwd-independent by default (the vendor limits per
+ *  credential, so a cwd-scoped ledger would hand the same credential a fresh allowance in every
+ *  checkout, worktree and CI matrix leg); pass `root` to opt into world-scoped accounting. */
+export function polarBudgetPath(opts = {}) {
+    const o = typeof opts === 'string' ? { root: opts } : opts;
+    // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+    // excess-property check only catches object literals) must not redirect this pack's ledger to
+    // another vendor's file.
+    return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+/**
+ * Polar's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof PolarBudget` means "a budget that accounts against this
+ * vendor's ledger under this vendor's ceiling": another vendor's `RateBudget` (with its own,
+ * possibly larger, ceiling) is NOT assignable where one of these is required.
+ */
+export class PolarBudget extends RateBudget {
+    constructor(opts = {}) {
+        super({ ...opts, vendor: VENDOR });
+    }
+}
+export { RateBudgetError as PolarBudgetError } from '@volter/world-core';
+/** Pull the budget wiring out of a caller's opts bag, so an entrypoint can forward it verbatim. */
+export function polarBudgetOf(opts) {
+    return {
+        ...(opts.budget !== undefined ? { budget: opts.budget } : {}),
+        ...(opts.budgetOptions !== undefined ? { budgetOptions: opts.budgetOptions } : {}),
+    };
+}
+// ── the choke point ─────────────────────────────────────────────────────────────────────────
+/**
+ * Marks a client this module has already wrapped, so guarding twice cannot charge twice.
+ *
+ * A MODULE-PRIVATE `Symbol()`, deliberately not `Symbol.for()`: a global-registry symbol is
+ * reachable BY NAME, so any caller could stamp `client[Symbol.for(…)] = anything` on a RAW client and
+ * the guard would hand it straight back UNGUARDED — a one-line bypass of the whole budget. With a
+ * private symbol the only way to be branded is to have been wrapped by this function. The cost is
+ * that two copies of this module in one dependency tree would each wrap (double-charging a call);
+ * that is the SAFE direction, and over-charging is the tradeoff this module takes everywhere else.
+ */
+const GUARDED = Symbol('@volter/twin-polar.budget.guarded');
+/** Is this client already behind a budget? Returns the budget it is behind, if so. */
+export function polarClientBudget(client) {
+    const mark = client?.[GUARDED];
+    // Belt and braces: only a REAL budget counts as "already guarded". A non-RateBudget value here
+    // could only come from a forged brand, and the answer to a forgery is to wrap anyway.
+    return mark instanceof RateBudget ? mark : undefined;
+}
+/**
+ * Wrap an INJECTED Polar client so EVERY call it makes is charged against the shared budget
+ * BEFORE the request goes out. This pack's connector never constructs the transport itself (the
+ * consumer injects a client that satisfies `PolarLikeClient` structurally), so the guard is a
+ * DECORATOR rather than a factory — which is exactly why every connector entrypoint applies it
+ * UNCONDITIONALLY instead of trusting the caller to have done it.
+ *
+ * IDEMPOTENT: wrapping an already-guarded client returns it unchanged, so a caller who forgot is
+ * protected and a caller who wrapped deliberately is not double-charged.
+ *
+ * A method that THROWS is still inspected: an SDK typically RAISES on a 429 rather than returning
+ * it, and that error's back-off is exactly the signal that must become a persisted cooldown. Losing
+ * it would leave the ledger cheerfully spending into a throttled credential. The original error is
+ * always re-raised afterwards — the budget never swallows a vendor failure — EXCEPT when the
+ * back-off is beyond the cap, where the budget's own louder "stop calling" error takes precedence.
+ */
+export function guardPolarClient(client, opts = {}) {
+    // There is no value a caller can pass to end up with an UNGUARDED client. `null`/`undefined` (or
+    // omitting it) build the default budget; anything that is not a REAL `PolarBudget` is refused
+    // loudly rather than trusted — a duck-typed stand-in with a no-op `checkBudget` would otherwise be
+    // the one clean way around the guard. Validated BEFORE the already-guarded early return, so
+    // `guardPolarClient(alreadyGuarded, { budget: impostor })` is refused too rather than silently
+    // ignoring the impostor.
+    if (opts.budget !== undefined && opts.budget !== null && !(opts.budget instanceof PolarBudget)) {
+        throw new Error('guardPolarClient: `budget` must be a PolarBudget — refusing to guard a Polar client with an unverified rate guard');
+    }
+    if (polarClientBudget(client))
+        return client;
+    const budget = opts.budget instanceof PolarBudget
+        ? opts.budget
+        : new PolarBudget({
+            // The default ledger is keyed by a hash of the credential — the vendor limits per credential,
+            // so a cwd-scoped ledger would hand it a fresh allowance per worktree/CI leg.
+            //
+            // HONESTLY: this pack does NOT hold the credential — the consumer's injected client does — so
+            // `POLAR_ACCESS_TOKEN` is a BEST-EFFORT stand-in for it, not the real thing. If that env var names a
+            // different account than the injected client, spend is booked against the wrong ledger; if it
+            // is unset, every unattributed Polar credential on the machine shares one (over-tight,
+            // which is the safe direction). A caller who knows the credential should say so:
+            // `budgetOptions: { token }` overrides this, and does so deliberately last in the spread.
+            ...(process.env.POLAR_ACCESS_TOKEN !== undefined ? { token: process.env.POLAR_ACCESS_TOKEN } : {}),
+            ...(opts.budgetOptions ?? {}),
+        });
+    /** Settle a reservation from whatever the call produced. May THROW (a back-off past the cap). */
+    const settle = (weight, reservation, v) => {
+        const status = responseStatus(v);
+        const headers = responseHeaders(v);
+        if (status !== undefined || headers !== undefined)
+            budget.recordCall(weight, headers, { status, reservation });
+        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, reservation, v) => {
+        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
+     * on an unguarded client. `checkBudget` RESERVES under lock, so nothing after its line runs when
+     * the budget refuses: the request is never made.
+     */
+    const chargeAsync = (method, invoke) => async (...args) => {
+        const weight = budget.weightFor(method);
+        const reservation = budget.checkBudget(weight);
+        try {
+            const res = await invoke(...args);
+            settleAnswered(weight, reservation, res);
+            return res;
+        }
+        catch (e) {
+            settle(weight, reservation, e); // may throw its own louder refusal, which wins
+            throw e;
+        }
+    };
+    /**
+     * Charge, call, settle — for an UNMODELED member reached through the passthrough Proxy, where the
+     * shape is unknown.
+     *
+     * Deliberately NOT `async`. Some vendor SDKs (twilio-shaped ones) build requests through
+     * SYNCHRONOUS chained accessors — `client.a.b('sid').c.create()` — where the intermediate calls
+     * return a resource context, not a promise. An `async` wrapper would turn every one of those into
+     * a `Promise` and `.c` would come back `undefined`: the guard would BREAK the client instead of
+     * guarding it. So a non-thenable return is treated as an accessor — still charged (we cannot know
+     * before calling, and over-charging is the safe direction) and wrapped, so the eventual async leaf
+     * is charged too rather than escaping the budget. The cost of the sync shape is that a REFUSAL on
+     * this path throws synchronously instead of rejecting; that is the honest signal for an accessor,
+     * and the modeled surface above (every method this connector actually calls) does not have it.
+     */
+    const charge = (method, invoke) => (...args) => {
+        const weight = budget.weightFor(method);
+        const reservation = budget.checkBudget(weight);
+        let out;
+        try {
+            out = invoke(...args);
+        }
+        catch (e) {
+            settle(weight, reservation, e); // may throw its own louder refusal, which wins
+            throw e;
+        }
+        if (!isThenable(out)) {
+            settle(weight, reservation, undefined);
+            return out !== null && (typeof out === 'object' || typeof out === 'function')
+                ? proxyThrough({}, out, method, charge)
+                : out;
+        }
+        return out.then((res) => { settleAnswered(weight, reservation, res); return res; }, (e) => { settle(weight, reservation, e); throw e; });
+    };
+    // Build the charged surface from POLAR_BUDGETED_METHODS (see its docstring for why an absent path is
+    // SKIPPED rather than stubbed).
+    const guarded = {};
+    for (const path of POLAR_BUDGETED_METHODS) {
+        const segs = path.split('.');
+        const leaf = segs[segs.length - 1];
+        let owner = client;
+        for (const seg of segs.slice(0, -1))
+            owner = owner?.[seg];
+        if (typeof owner?.[leaf] !== 'function')
+            continue;
+        const realOwner = owner;
+        let node = guarded;
+        for (const seg of segs.slice(0, -1))
+            node = (node[seg] ??= {});
+        // The method is resolved at CALL time, not here, so a client whose method is swapped later is
+        // still charged for whatever it actually runs.
+        node[leaf] = chargeAsync(path, (...args) => realOwner[leaf].apply(realOwner, args));
+    }
+    Object.defineProperty(guarded, GUARDED, { value: budget, enumerable: false });
+    // The surface above is what this connector calls. A real client has MORE — and a consumer who
+    // needs any of it must not be forced to keep the RAW client alongside, because every call through
+    // that would be unbudgeted. So the guarded object is a Proxy: known members come from the map
+    // above, anything else is taken from the real client and PRICED at `defaultWeight`.
+    return proxyThrough(guarded, client, '', charge);
+}
+/**
+ * Members JavaScript itself asks for. Wrapping any of these turns the object into something that
+ * looks thenable / mis-reports its own identity, which breaks `await`, `instanceof` and logging —
+ * so they always come from the target untouched, never priced.
+ */
+const NEVER_WRAP = new Set(['then', 'catch', 'finally', 'constructor', 'prototype', 'toJSON', 'toString', 'valueOf', 'inspect']);
+/** Does this look like a promise? (Only a thenable gets the settle-on-resolution treatment.) */
+function isThenable(v) {
+    return v !== null && (typeof v === 'object' || typeof v === 'function') && typeof v.then === 'function';
+}
+/**
+ * Symbols that name an ITERATION PROTOCOL. Reaching for one of these on a vendor object is how a
+ * paginator is driven (`for await (const page of client.things.list())`), i.e. it is the doorway to
+ * an unbounded sequence of REQUESTS — exactly what this budget exists to bound — so they are charged
+ * and their result is kept behind the proxy. Every other symbol (`Symbol.toStringTag`,
+ * `nodejs.util.inspect.custom`, …) is metadata rather than a request and passes through untouched.
+ */
+const ITERATOR_SYMBOLS = new Set([Symbol.asyncIterator, Symbol.iterator]);
+/**
+ * Serve `known` where it has the member; otherwise price a passthrough to `real`. Applied
+ * recursively, so a namespace member this pack never modeled is charged at `defaultWeight` rather
+ * than coming back `undefined`.
+ *
+ * CALLABLE NAMESPACES (§9 finding): a member can be BOTH a function and a namespace — twilio's
+ * `client.messages` is called as `client.messages(sid)` to get one message's context AND read as
+ * `client.messages.list()`. An earlier version returned the modeled node as a plain object whenever
+ * this pack modeled any child of it, which silently DROPPED the call signature and every unmodeled
+ * sibling — the module's own docstring calls a dropped member "worse than free, because it is
+ * invisible", and that is what it was doing. So when `real` is callable the proxy target is a
+ * function and an `apply` trap charges the call, while `known` stays the source of modeled members.
+ */
+function proxyThrough(known, real, prefix, charge, owner) {
+    const callable = typeof real === 'function';
+    // The target must itself be callable for the `apply` trap to exist at all. `known` stays the
+    // source of modeled members, read explicitly below rather than through the target.
+    const target = callable ? function proxied() { } : known;
+    return new Proxy(target, {
+        apply(_t, _thisArg, args) {
+            // Calling the namespace is itself a request-builder hop: charge it, and keep the result
+            // behind the proxy (charge() re-proxies a non-thenable) so the eventual leaf is charged too.
+            // `owner` is the object the function was read from — dropping it would silently break every
+            // method that relies on `this`.
+            return charge(prefix || 'call', (...a) => real.apply(owner, a))(...args);
+        },
+        get(_t, prop, receiver) {
+            if (typeof prop === 'symbol') {
+                const ownSym = Reflect.get(known, prop, receiver);
+                if (ownSym !== undefined)
+                    return ownSym; // the GUARDED brand, and anything we model
+                const fromSym = real?.[prop];
+                if (ITERATOR_SYMBOLS.has(prop) && typeof fromSym === 'function') {
+                    return charge(`${prefix}[${prop.description ?? 'iterator'}]`, (...args) => fromSym.apply(real, args));
+                }
+                return fromSym;
+            }
+            const name = String(prop);
+            if (NEVER_WRAP.has(name))
+                return Reflect.get(known, prop, receiver);
+            const key = prefix ? `${prefix}.${name}` : name;
+            const own = Reflect.get(known, prop, receiver);
+            const from = real?.[name];
+            // A member we model: the charged wrapper (a function) or a namespace we must keep descending
+            // into, so an unmodeled sibling is still priced rather than dropped.
+            if (typeof own === 'function')
+                return own;
+            if (own && typeof own === 'object') {
+                // `from` may be an object OR a CALLABLE namespace — both keep descending, which is what
+                // preserves `client.messages(sid)` alongside the modeled `client.messages.list()`.
+                return from && (typeof from === 'object' || typeof from === 'function')
+                    ? proxyThrough(own, from, key, charge, real)
+                    : own;
+            }
+            if (own !== undefined)
+                return own;
+            // A member only the real client has. Functions go through proxyThrough too, so one that also
+            // carries members (a callable namespace) keeps both its call signature and its siblings.
+            if (typeof from === 'function')
+                return proxyThrough({}, from, key, charge, real);
+            if (from && typeof from === 'object')
+                return proxyThrough({}, from, key, charge, real);
+            return from;
+        },
+        has(_t, prop) {
+            return Reflect.has(known, prop) || (real !== null && Reflect.has(real, prop));
+        },
+    });
+}
+/** The HTTP status a value carries, if it looks like one (an SDK error, or a raw response). */
+function responseStatus(v) {
+    const s = v?.status;
+    return typeof s === 'number' && Number.isFinite(s) ? s : undefined;
+}
+/**
+ * Response/error headers as a plain lower-cased record, or `undefined` when there are none. Accepts
+ * a `Headers` instance, a `Map`, or a plain object — an SDK's error type changes shape across
+ * versions and none of the three is worth depending on.
+ */
+function responseHeaders(v) {
+    const h = v?.headers;
+    if (!h || typeof h !== 'object')
+        return undefined;
+    const out = {};
+    if (typeof h.forEach === 'function') {
+        h.forEach((value, key) => { out[String(key).toLowerCase()] = String(value); });
+    }
+    else {
+        for (const [k, value] of Object.entries(h))
+            out[k.toLowerCase()] = String(value);
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}

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

@@ -0,0 +1,4 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const POLAR_CAPABILITIES: CapabilitySpec[];
+export declare const POLAR_AREAS: readonly ["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 declare function polarCapabilities(): Promise<CapabilityReport>;