@volter/twin-inngest 0.1.0

package/src/index.ts

@@ -0,0 +1,107 @@
+// @volter/twin-inngest — the Inngest durable-execution / event-driven workflow-orchestration
+// twin, built on the shared @volter/world-core kernel. REST transport over three surfaces: the Event
+// API (POST /e/{eventKey}), the SDK execution protocol (/api/inngest, /fn/register), and the
+// dev-server/cloud v2 REST management API (/api/v2/*, GROUNDED at that exact path from a
+// live-fetched first-party OpenAPI document — see inngest-twin.ts header). State lives entirely
+// in the kernel action log (no side-store).
+//
+// THE DECLARED STEP PLAN: this twin does not run user code — a function's steps
+// are DECLARED (at register time, or by a test) as an ordered `step_plan`, and the twin advances
+// that plan deterministically with REAL kernel-persisted memoization/replay (step outputs are
+// read back from the kernel on every re-invocation, never recomputed), instant sleep/sleepUntil
+// advance (no wall clock), waitForEvent gating (holds a run at a step until a matching event
+// arrives, or a deterministic poll-count timeout), and an exact retry-attempt counter. This is
+// the manifest files calling into a real running app as `exec.sdk_executor_roundtrip`.
+export {
+  handleInngestTwinRequest,
+  routeInngestSurface,
+  inngestTwinSnapshot,
+  INNGEST_RESOURCE_TYPES,
+} from './inngest-twin.ts';
+export type {
+  InngestRequest,
+  InngestResponse,
+  InngestResourceType,
+  InngestSurface,
+  InngestTwinSnapshot,
+} from './inngest-twin.ts';
+export { createInngestTwinFetch, createInngestTwinServer, type InngestTwinFetchOptions } from './inngest-server.ts';
+export {
+  mapEvent,
+  mapRun,
+  pullInngestEvents,
+  pullInngestRuns,
+  syncInngestFromReal,
+} from './inngest-connector.ts';
+export type { InngestLikeClient, InngestEventHandle, InngestRunHandle, InngestRealEvent, InngestRealRun, InngestBudgetedOptions } from './inngest-connector.ts';
+// 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 `guardInngestClient`, the choke point the
+// connector entrypoints apply unconditionally. Exported so an operator can inspect spend
+// (`snapshot`) and a caller can catch `InngestBudgetError` by type; there is deliberately no export
+// that disables the guard.
+export {
+  INNGEST_BUDGETED_METHODS,
+  INNGEST_BUDGET_CEILING,
+  INNGEST_BUDGET_MAX_RETRY_AFTER_S,
+  INNGEST_BUDGET_WINDOW_MS,
+  INNGEST_CALL_WEIGHTS,
+  INNGEST_RATE_BUDGET,
+  InngestBudget,
+  InngestBudgetError,
+  inngestBudgetPath,
+  inngestCallWeight,
+  inngestClientBudget,
+  guardInngestClient,
+} from './inngest-budget.ts';
+export type { InngestBudgetErrorKind, InngestBudgetOptions, InngestBudgetReservation, InngestBudgetSnapshot } from './inngest-budget.ts';
+export {
+  INNGEST_SIGNING_KEY_TYPE,
+  inngestSigningKey,
+  mintInngestSigningKey,
+  storedInngestSigningKey,
+  signInngestRequest,
+  buildInngestSignatureHeader,
+  verifyInngestSignature,
+  InngestSignatureError,
+} from './inngest-signing.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import type { TwinPack } from '@volter/world-core';
+import { INNGEST_RATE_BUDGET as RATE_BUDGET } from './inngest-budget.ts';
+export const pack: TwinPack = {
+  // The SAME object inngest-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: 'inngest',
+  transport: 'rest',
+  archetype: 'crud',
+  bin: 'world-inngest',
+  // The subject types the twin SERVES over its own API — the R2 resource-level claim, held in
+  // lockstep with inngest-twin.ts's INNGEST_RESOURCE_TYPES. `signing_key` IS here: the world's
+  // executor<->SDK signing key is minted once from real entropy and persisted
+  // (inngest-signing.ts), and `GET /api/v2/keys/signing` establishes it on first touch — a real
+  // held subject, not a name with nothing behind it. What that route serves stays masked.
+  resources: ['event', 'function', 'run', 'step', 'signing_key'],
+  // World wiring — declared HERE, not in init.ts's central table (descriptor-first exemplar (adding-a-twin.md §3)).
+  endpointEnv: {
+    name: 'INNGEST_BASE_URL',
+    templates: { INNGEST_EVENT_API_BASE_URL: '${url}' },
+    note: 'no injector entry: the inngest SDK is base-URL-configured through INNGEST_BASE_URL / INNGEST_EVENT_API_BASE_URL.',
+  },
+  specSource: 'inngest-conformance.ts (self-referential endpoint/resource inventory) — grounded read-only against inngest.com/docs, the installed inngest@4.12.0 npm package source (npm pack), and the live-fetched v2 REST OpenAPI document (api-docs.inngest.com/api-specs/v2.json); see spec-sources.json.',
+  description: 'Inngest durable-execution workflow-orchestration twin — event send (Event API), function register/introspect (SDK exec protocol), and a kernel-persisted step machine (step.run memoize/replay, sleep/sleepUntil instant-advance, waitForEvent gating, exact retry-attempt counters), run status/get/list, event-based cancellation, HMAC-SHA256 executor<->SDK request signing. Twin does not execute real user code — steps are declared, not run. Kernel-backed.',
+  browserRouting: { apiPathPrefix: '/', loaderHost: 'http://localhost:8288' },
+  // INTERCEPTION RULING — hostsNone, the pack's own home for it: SDK is base-URL-configured by
+  // design (options.baseUrl / INNGEST_BASE_URL / INNGEST_EVENT_API_BASE_URL, verified in the
+  // pack README) — worlds wire the twin through those vars.
+  hostsNone:
+    "SDK is base-URL-configured by design (options.baseUrl / INNGEST_BASE_URL / INNGEST_EVENT_API_BASE_URL, verified in the pack README) — worlds wire the twin through those vars",
+  // Adoption, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+  // 2026-08-31).
+  adoption: {
+    // Inngest's official Python SDK - same distribution name as the npm one.
+    pypi: ['inngest'],
+    sdks: ['inngest'], envStems: ['INNGEST'],
+  },
+};

package/src/inngest-budget.ts

@@ -0,0 +1,450 @@
+// Inngest's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus `guardInngestClient`,
+// the choke point every live Inngest 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 INNGEST NEEDS ONE ───────────────────────────────────────────────────────────
+// Inngest's REST reference (inngest.com/docs/reference/rest-api, api-docs.inngest.com) documents NO
+// rate limit, no 429, and no Retry-After for /v1/events or /v1/runs. The single rate-limit statement
+// in the whole API reference is an annotation on a DIFFERENT endpoint — "Fetch function run jobs …
+// This endpoint is rate limited and cached for 5 seconds" — with no number, and that endpoint is not
+// part of this connector's surface. The documented usage limits are payload-shape limits (5000 events
+// per request, 10 MiB batches, per-plan event payload sizes), not rates. So the vendor's rate
+// behaviour here is entirely undocumented, which is the case a client-side ceiling exists for.
+//
+// ── HOW THE CEILING WAS CHOSEN ──────────────────────────────────────────────────────────────
+// NO DOCUMENTED SCALAR LIMIT exists for the endpoints this connector calls, so this budget does NOT
+// claim one. It is pinned to the kernel's conservative fallback (DEFAULT_RATE_BUDGET: 60 weighted
+// units / 60s at weight 2 = 30 calls/minute) — no more permissive than an undeclared vendor already
+// gets.
+//
+// ── 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 2. Both modeled endpoints are single fetch-by-id reads
+// (`GET /runs/{runId}`, the event lookup), neither fans out, and Inngest publishes no per-endpoint
+// rate. The one endpoint Inngest DOES annotate as rate limited ("fetch function run jobs", cached for
+// 5 seconds, no number given) is not in this connector's surface — so there is nothing honest to
+// price up. An unmodeled method reached through the guarded client is charged the same 2, never free.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  RateBudgetError,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+import type { InngestLikeClient } from './inngest-connector.ts';
+
+const VENDOR = 'inngest';
+
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const INNGEST_BUDGET_WINDOW_MS = 60_000;
+
+/** Weighted units allowed inside one window. See the header for where this number comes from. */
+export const INNGEST_BUDGET_CEILING = 60;
+
+/** Seconds. A `Retry-After` above this means the credential is throttled hard — fail loudly. */
+export const INNGEST_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 INNGEST_CALL_WEIGHTS = {
+  /** Every modeled call. Inngest publishes no per-endpoint rate to differentiate. */
+  other: 2,
+} as const;
+
+/**
+ * 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 INNGEST_BUDGETED_METHODS = [
+  'events.get',
+  'runs.get',
+] as const;
+
+/** THE PACK'S DECLARATION — pure data, the only Inngest-specific thing in the whole budget. */
+export const INNGEST_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: INNGEST_BUDGET_WINDOW_MS,
+  ceiling: INNGEST_BUDGET_CEILING,
+  defaultWeight: INNGEST_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: INNGEST_BUDGET_MAX_RETRY_AFTER_S,
+  // Ordered: the kernel prices FIRST-MATCH-WINS, so the tightest tier is listed first.
+  rules: [],
+  reason:
+    "Inngest documents NO rate limit, no 429 and no Retry-After for the REST endpoints this connector calls " +
+    "(/v1/events, /v1/runs); its published usage limits are payload-shape limits (5000 events/request, 10 MiB " +
+    "batches) rather than rates. The only rate-limit statement in its whole API reference annotates a different " +
+    "endpoint (\"fetch function run jobs … rate limited and cached for 5 seconds\") and gives no number. With no " +
+    "documented figure to aim at, this ceiling is pinned to the kernel's conservative fallback (60 units / 60s " +
+    "at weight 2 = 30 calls/min) rather than invented — no more permissive than an undeclared vendor already " +
+    "gets. Weights are flat because both modeled endpoints are single fetch-by-id reads and no per-endpoint " +
+    "rate is published.",
+};
+
+// Declared at module load, so merely importing this module (which `inngest-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, INNGEST_RATE_BUDGET);
+
+/** Price one Inngest call by its client method key (a dotted path, e.g. `events.get`). */
+export function inngestCallWeight(method: string): number {
+  return rateBudgetWeight(VENDOR, method);
+}
+
+/** Where Inngest'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 inngestBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  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 });
+}
+
+/** Construction options for Inngest's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type InngestBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * Inngest's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof InngestBudget` 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 InngestBudget extends RateBudget {
+  constructor(opts: InngestBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+export type { RateBudgetErrorKind as InngestBudgetErrorKind } from '@volter/world-core';
+export { RateBudgetError as InngestBudgetError } from '@volter/world-core';
+export type InngestBudgetReservation = RateBudgetReservation;
+export type InngestBudgetSnapshot = 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 InngestBudgetedOptions = {
+  /** An existing budget to share across calls. Omit and one is constructed. Cannot be null. */
+  budget?: InngestBudget;
+  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+  budgetOptions?: InngestBudgetOptions;
+};
+
+/** Pull the budget wiring out of a caller's opts bag, so an entrypoint can forward it verbatim. */
+export function inngestBudgetOf(opts: InngestBudgetedOptions): InngestBudgetedOptions {
+  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: unique symbol = Symbol('@volter/twin-inngest.budget.guarded');
+
+type Guarded = { [GUARDED]?: unknown };
+
+/** Is this client already behind a budget? Returns the budget it is behind, if so. */
+export function inngestClientBudget(client: unknown): RateBudget | undefined {
+  const mark = (client as Guarded | null)?.[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;
+}
+
+/** Charge a call keyed by `method`, invoke it, settle. Returns whatever the call returned. */
+type Charge = (method: string, invoke: (...args: unknown[]) => unknown) => (...args: unknown[]) => unknown;
+
+/**
+ * Wrap an INJECTED Inngest 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 `InngestLikeClient` 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 guardInngestClient(client: InngestLikeClient, opts: InngestBudgetedOptions = {}): InngestLikeClient {
+  // 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 `InngestBudget` 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
+  // `guardInngestClient(alreadyGuarded, { budget: impostor })` is refused too rather than silently
+  // ignoring the impostor.
+  if (opts.budget !== undefined && opts.budget !== null && !(opts.budget instanceof InngestBudget)) {
+    throw new Error('guardInngestClient: `budget` must be a InngestBudget — refusing to guard a Inngest client with an unverified rate guard');
+  }
+  if (inngestClientBudget(client)) return client;
+  const budget = opts.budget instanceof InngestBudget
+    ? opts.budget
+    : new InngestBudget({
+      // 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
+      // `INNGEST_SIGNING_KEY` 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 Inngest 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.INNGEST_SIGNING_KEY !== undefined ? { token: process.env.INNGEST_SIGNING_KEY } : {}),
+      ...(opts.budgetOptions ?? {}),
+    });
+
+  /** Settle a reservation from whatever the call produced. May THROW (a back-off past the cap). */
+  const settle = (weight: number, reservation: RateBudgetReservation, v: unknown): void => {
+    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: 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
+   * 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: string, invoke: (...args: unknown[]) => unknown) =>
+    async (...args: unknown[]): Promise<unknown> => {
+      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: Charge = (method, invoke) => (...args) => {
+    const weight = budget.weightFor(method);
+    const reservation = budget.checkBudget(weight);
+    let out: unknown;
+    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 as object, method, charge)
+        : out;
+    }
+    return out.then(
+      (res) => { settleAnswered(weight, reservation, res); return res; },
+      (e: unknown) => { settle(weight, reservation, e); throw e; },
+    );
+  };
+
+  // Build the charged surface from INNGEST_BUDGETED_METHODS (see its docstring for why an absent path is
+  // SKIPPED rather than stubbed).
+  const guarded: Record<string, unknown> & Guarded = {};
+  for (const path of INNGEST_BUDGETED_METHODS) {
+    const segs = path.split('.');
+    const leaf = segs[segs.length - 1]!;
+    let owner: Record<string, unknown> | undefined = client as unknown as Record<string, unknown>;
+    for (const seg of segs.slice(0, -1)) owner = owner?.[seg] as Record<string, unknown> | undefined;
+    if (typeof owner?.[leaf] !== 'function') continue;
+    const realOwner = owner;
+    let node: Record<string, unknown> = guarded;
+    for (const seg of segs.slice(0, -1)) node = (node[seg] ??= {}) as Record<string, unknown>;
+    // 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] as (...a: unknown[]) => unknown).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 as object, '', charge) as InngestLikeClient;
+}
+
+/**
+ * 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: unknown): v is Promise<unknown> {
+  return v !== null && (typeof v === 'object' || typeof v === 'function') && typeof (v as { then?: unknown }).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>([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: object, real: object, prefix: string, charge: Charge, owner?: object): object {
+  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: object = callable ? function proxied() { /* every call goes through the trap */ } : known;
+  return new Proxy(target, {
+    apply(_t, _thisArg, args: unknown[]) {
+      // 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 as (...x: unknown[]) => unknown).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 as Record<symbol, unknown> | null)?.[prop];
+        if (ITERATOR_SYMBOLS.has(prop) && typeof fromSym === 'function') {
+          return charge(`${prefix}[${prop.description ?? 'iterator'}]`, (...args) => (fromSym as (...a: unknown[]) => unknown).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 as Record<string, unknown> | null)?.[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: unknown): number | undefined {
+  const s = (v as { status?: unknown } | null)?.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: unknown): Record<string, string> | undefined {
+  const h = (v as { headers?: unknown } | null)?.headers;
+  if (!h || typeof h !== 'object') return undefined;
+  const out: Record<string, string> = {};
+  if (typeof (h as Headers).forEach === 'function') {
+    (h as Headers).forEach((value: string, key: string) => { out[String(key).toLowerCase()] = String(value); });
+  } else {
+    for (const [k, value] of Object.entries(h as Record<string, unknown>)) out[k.toLowerCase()] = String(value);
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}