@nimbus-sh/fabric 0.1.0 → 0.3.0

package/dist/loader-ledger.d.ts

@@ -1,57 +0,0 @@
-/**
- * loader-ledger.ts — per-DO accounting for the Worker Loader's two caps.
- *
- * Measured on production workerd: a Durable Object admits ~5–6 concurrent
- * dynamic workers before the platform refuses with "Too many concurrent
- * dynamic workers", one DO method can drive at most 4 concurrent Loader
- * fetches, and loader-cache entries are never released — every DISTINCT
- * `loader.get(id)` permanently consumes one of the dynamic-worker slots for
- * the object's lifetime. Nimbus stays under the caps by construction
- * (`IN_DO_THRESHOLD` = 5 in the fanout pool), which until now meant the slots
- * were counted in prose. This ledger counts them at the fabric's loader call
- * sites instead — the loader pool's slots, a resident process's keyed worker,
- * a one-shot's load — so proximity is measurable and a cap failure can name
- * the ids actually holding slots.
- *
- * Measurement only: no admission control. The caps are the platform's, they
- * are approximate ("~5–6"), and a gate on an approximate number would refuse
- * work the platform would have run.
- *
- * Keyed weakly off the hosting actor's `ctx`, like the facet slot books: the
- * caps are per Durable Object, and dynamic workers die with the isolate that
- * loaded them, so a ledger that goes away with its host describes nothing
- * that still exists.
- */
-/** Record a keyed `loader.get(id)` — a permanent slot if the id is new. */
-export declare function recordLoaderId(ctx: object, id: string): void;
-/**
- * Count one call into a dynamic worker as a live Loader fetch; the returned
- * function ends it (idempotently), from the caller's own `finally`.
- *
- * A begin/end pair rather than a wrapper on purpose, and the shape is
- * load-bearing: wrapping the stub call in a ledger-owned async frame
- * (`trackLoaderFetch(ctx, () => entrypoint.execute(...))`) left the hosting
- * Durable Object poisoned after every pooled dispatch — the next fabric
- * activity hung the object or reset the instance outright (pid base jumped,
- * every attached WebSocket dropped with no close frame), measured 7/7 on
- * staging and gone 3/3 with the direct call restored. Same seam-quirk class
- * as pipelined `fetch.call`, which workerd refuses for dynamically-loaded
- * workers: an RPC stub call must stay a direct property call awaited by the
- * frame that made it, so the ledger only brackets it.
- */
-export declare function beginLoaderFetch(ctx: object): () => void;
-/** Snapshot for the diag surface. Pure read; no I/O. */
-export declare function loaderLedgerStats(ctx: object): {
-    idsEverGotten: string[];
-    liveFetches: number;
-    peakLiveFetches: number;
-};
-/**
- * Name the per-DO accounting on a "Too many concurrent dynamic workers"
- * failure; hand every other error back untouched. The platform's message
- * says only that the cap was hit — which ids hold the slots, and that a
- * keyed id can never give one back, is what the operator needs to know to
- * shrink anything.
- */
-export declare function withDynamicWorkerCapNamed<E>(ctx: object, error: E): E | Error;
-//# sourceMappingURL=loader-ledger.d.ts.map

package/dist/loader-ledger.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"loader-ledger.d.ts","sourceRoot":"","sources":["../src/loader-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAwBH,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,IAAI,CAUxD;AAED,wDAAwD;AACxD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG;IAC9C,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB,CAOA;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,CAW7E"}

package/dist/loader-ledger.js

@@ -1,91 +0,0 @@
-/**
- * loader-ledger.ts — per-DO accounting for the Worker Loader's two caps.
- *
- * Measured on production workerd: a Durable Object admits ~5–6 concurrent
- * dynamic workers before the platform refuses with "Too many concurrent
- * dynamic workers", one DO method can drive at most 4 concurrent Loader
- * fetches, and loader-cache entries are never released — every DISTINCT
- * `loader.get(id)` permanently consumes one of the dynamic-worker slots for
- * the object's lifetime. Nimbus stays under the caps by construction
- * (`IN_DO_THRESHOLD` = 5 in the fanout pool), which until now meant the slots
- * were counted in prose. This ledger counts them at the fabric's loader call
- * sites instead — the loader pool's slots, a resident process's keyed worker,
- * a one-shot's load — so proximity is measurable and a cap failure can name
- * the ids actually holding slots.
- *
- * Measurement only: no admission control. The caps are the platform's, they
- * are approximate ("~5–6"), and a gate on an approximate number would refuse
- * work the platform would have run.
- *
- * Keyed weakly off the hosting actor's `ctx`, like the facet slot books: the
- * caps are per Durable Object, and dynamic workers die with the isolate that
- * loaded them, so a ledger that goes away with its host describes nothing
- * that still exists.
- */
-import { classifyError } from '@nimbus-sh/core/observability/oom-classify.js';
-const ledgers = new WeakMap();
-function ledger(ctx) {
-    let entry = ledgers.get(ctx);
-    if (!entry) {
-        entry = { ids: new Set(), liveFetches: 0, peakLiveFetches: 0 };
-        ledgers.set(ctx, entry);
-    }
-    return entry;
-}
-/** Record a keyed `loader.get(id)` — a permanent slot if the id is new. */
-export function recordLoaderId(ctx, id) {
-    ledger(ctx).ids.add(id);
-}
-/**
- * Count one call into a dynamic worker as a live Loader fetch; the returned
- * function ends it (idempotently), from the caller's own `finally`.
- *
- * A begin/end pair rather than a wrapper on purpose, and the shape is
- * load-bearing: wrapping the stub call in a ledger-owned async frame
- * (`trackLoaderFetch(ctx, () => entrypoint.execute(...))`) left the hosting
- * Durable Object poisoned after every pooled dispatch — the next fabric
- * activity hung the object or reset the instance outright (pid base jumped,
- * every attached WebSocket dropped with no close frame), measured 7/7 on
- * staging and gone 3/3 with the direct call restored. Same seam-quirk class
- * as pipelined `fetch.call`, which workerd refuses for dynamically-loaded
- * workers: an RPC stub call must stay a direct property call awaited by the
- * frame that made it, so the ledger only brackets it.
- */
-export function beginLoaderFetch(ctx) {
-    const entry = ledger(ctx);
-    entry.liveFetches++;
-    entry.peakLiveFetches = Math.max(entry.peakLiveFetches, entry.liveFetches);
-    let ended = false;
-    return () => {
-        if (ended)
-            return;
-        ended = true;
-        entry.liveFetches--;
-    };
-}
-/** Snapshot for the diag surface. Pure read; no I/O. */
-export function loaderLedgerStats(ctx) {
-    const entry = ledger(ctx);
-    return {
-        idsEverGotten: [...entry.ids],
-        liveFetches: entry.liveFetches,
-        peakLiveFetches: entry.peakLiveFetches,
-    };
-}
-/**
- * Name the per-DO accounting on a "Too many concurrent dynamic workers"
- * failure; hand every other error back untouched. The platform's message
- * says only that the cap was hit — which ids hold the slots, and that a
- * keyed id can never give one back, is what the operator needs to know to
- * shrink anything.
- */
-export function withDynamicWorkerCapNamed(ctx, error) {
-    if (classifyError(error) !== 'dynamic_worker_cap')
-        return error;
-    const entry = ledger(ctx);
-    const platform = error instanceof Error ? error.message : String(error);
-    return new Error(`${platform} — this Durable Object has ${entry.ids.size} loader id(s) permanently `
-        + `holding dynamic-worker slots (a loader.get id is never released): `
-        + `${[...entry.ids].join(', ') || '(none recorded)'}; live Loader fetches ${entry.liveFetches}, `
-        + `peak ${entry.peakLiveFetches}`, { cause: error });
-}

package/dist/loader-pool.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"loader-pool.d.ts","sourceRoot":"","sources":["../src/loader-pool.ts"],"names":[],"mappings":"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"}

package/src/alarms.ts

@@ -1,275 +0,0 @@
-/**
- * alarms.ts — Durable Object alarm multiplexing + isolate-generation
- * machinery, persisted across hibernation.
- *
- * Workerd hibernates Durable Objects between requests to free memory. On
- * wake, the new isolate must rebuild its in-memory state from SQL — but it
- * also needs to know "is this the same lifecycle as before, or did workerd
- * recycle me?" That distinction matters for recovery (warmJoin vs cold init)
- * and is captured by the isolate generation, a counter persisted across
- * hibernations.
- *
- * A Durable Object has ONE alarm, and a second `setAlarm()` silently
- * overwrites the first — so every alarm-driven subsystem coordinates through
- * a single reason→deadline map and one dispatcher. Reasons are plain strings
- * registered by the embedder: `scheduleAlarm` arms one, and `dispatchAlarm`
- * runs the embedder-supplied handler for every reason whose deadline has
- * passed.
- */
-
-import { errorText } from '@nimbus-sh/core/_shared/error-text.js';
-
-/**
- * The storage the alarm map lives in. `setAlarm` is optional because
- * `wrangler dev` serves a storage without it, which is the whole reason
- * scheduling degrades to a no-op instead of throwing.
- */
-export interface AlarmStorage {
-  get(key: string): Promise<unknown>;
-  put(key: string, value: unknown): Promise<void>;
-  delete(key: string): Promise<boolean>;
-  setAlarm?(scheduledTime: number): Promise<void>;
-}
-
-/** The hosting actor's context, as the alarm coordination reads it. */
-export interface AlarmContext {
-  storage: AlarmStorage;
-}
-
-/**
- * Multi-reason alarm coordination map.
- *
- * JSON-serialised `Record<reason, deadlineMsEpoch>` where keys are the
- * embedder's canonical reason strings (e.g. 'w9-flush', 'log-janitor'). The
- * alarm() dispatcher reads this on fire, dispatches every reason whose
- * deadline has passed, and re-arms `ctx.storage.setAlarm` at the earliest
- * remaining deadline.
- *
- * Why a map (not a single nextAlarmAt + reason): two subsystems can have
- * distinct deadlines. Without the map, the later setAlarm() call would
- * overwrite the earlier reason silently, breaking whichever subsystem
- * expected its deadline.
- *
- * Forward-compat: the dispatcher silently drops unknown reasons so a
- * rollback from a future deploy that added new reasons doesn't leave the
- * alarm stuck.
- *
- * The VALUE is live production DO storage ('w1_next_alarm_reasons', from the
- * workstream that introduced it) and must never change — renaming a storage
- * key is a migration, and orphaned rows are the least of what it breaks.
- */
-export const ALARM_REASONS_KEY = 'w1_next_alarm_reasons';
-
-/**
- * Storage key for the isolate-generation counter (cold-start +
- * post-hibernation wake; one increment per fresh isolate).
- *
- * The VALUE is live production DO storage ('w9_isolate_gen') and must never
- * change, same contract as {@link ALARM_REASONS_KEY}.
- */
-export const ISOLATE_GEN_KEY = 'w9_isolate_gen';
-
-/**
- * The host instance carrying the per-instance alarm chain. The field lives on
- * the embedder's DO instance so one chain serializes every alarm-map
- * read-modify-write for that instance (see {@link scheduleAlarm}).
- */
-export interface AlarmHost {
-  _alarmChain?: Promise<unknown>;
-}
-
-/** The host instance carrying the isolate-generation state. */
-export interface IsolateGenHost {
-  _isolateGen: number;
-  _isolateGenPersisted: boolean;
-}
-
-/**
- * Schedule (or re-schedule) an alarm reason. Coordinated via a single map in
- * DO storage so multiple subsystems don't clobber each other's `setAlarm()`
- * calls.
- *
- * Semantics:
- *   - Reads the existing reasons map.
- *   - Sets `map[reason] = whenMs` IF `whenMs` is sooner than the
- *     currently-pending deadline for that reason (or no entry exists).
- *     Later-than-pending requests are silently ignored — the existing
- *     alarm will fire and re-arm anyway.
- *   - Writes the map back and calls `ctx.storage.setAlarm(min(deadlines))`.
- *
- * Cost: 1 storage read + 1 storage write + 1 setAlarm per call. setAlarm
- * itself is billed as 1 row written per DO pricing. At a 60s janitor
- * cadence, this is ~$0.05/mo/session at scale — dwarfed by the
- * hibernation duration savings.
- *
- * Fail-soft: any throw is swallowed with a warn. On older runtimes /
- * wrangler-dev where setAlarm is unavailable, this is a no-op (the
- * subsystem's in-isolate setTimeout fallback continues to work).
- */
-export function scheduleAlarm(
-  host: AlarmHost,
-  ctx: AlarmContext,
-  reason: string,
-  whenMs: number,
-): Promise<boolean> {
-  // Serialize every read-modify-write of the reasons map through one
-  // per-instance chain: two schedulers firing back-to-back from one activity
-  // hook would otherwise interleave their get→put cycles and silently drop
-  // whichever reason wrote first.
-  const run = async (): Promise<boolean> => {
-    try {
-      const setAlarmFn = ctx?.storage?.setAlarm;
-      if (typeof setAlarmFn !== 'function') return false;
-      const existing = (await ctx.storage.get(ALARM_REASONS_KEY)) as
-        | Record<string, number>
-        | undefined;
-      const map: Record<string, number> = { ...(existing || {}) };
-      // Earliest-deadline-first: only update if new request is sooner or
-      // this reason has no pending entry.
-      if (!(reason in map) || whenMs < map[reason]) {
-        map[reason] = whenMs;
-        await ctx.storage.put(ALARM_REASONS_KEY, map);
-      }
-      const earliest = Math.min(...Object.values(map));
-      setAlarmFn.call(ctx.storage, earliest);
-      return true;
-    } catch (e) {
-      console.warn('[nimbus/W1] scheduleAlarm threw:', errorText(e));
-      return false;
-    }
-  };
-  const chained = (host._alarmChain ?? Promise.resolve()).then(run, run);
-  host._alarmChain = chained;
-  return chained;
-}
-
-/**
- * What one alarm handler may return: nothing, or a deadline this reason
- * re-arms itself at. Re-arming through the return value keeps the map's
- * read-modify-write inside the dispatcher, where it is serialized.
- */
-export type AlarmHandlerResult = void | { rearmAt: number };
-
-/** The embedder's reasons, each with the handler that answers it. */
-export type AlarmHandlers = Record<
-  string,
-  (now: number) => AlarmHandlerResult | Promise<AlarmHandlerResult>
->;
-
-/**
- * Multi-reason alarm dispatcher. Called from the DO's `alarm()` handler with
- * the embedder's handler map.
- *
- * For each pending reason whose deadline has passed, run its handler.
- * Handlers are awaited in place: the alarm invocation is the fresh turn a
- * re-entering subsystem asked for, and it has to stay the one paying for the
- * work it just released.
- *
- * After running fireable reasons, re-arms `ctx.storage.setAlarm` at the
- * earliest remaining deadline. If no reasons remain, deletes the map key and
- * does NOT call setAlarm — the DO becomes hibernation-eligible after the 10s
- * idle window.
- *
- * Forward/back-compat: unknown reasons silently dropped. `onLegacyAlarm`
- * covers an alarm that fires with no map at all — a deploy from before the
- * map existed left a bare `setAlarm` behind, and the embedder decides what
- * that one-time fire means (one dispatch later the map is populated by the
- * next scheduleAlarm call).
- */
-export function dispatchAlarm(
-  host: AlarmHost,
-  ctx: AlarmContext,
-  handlers: AlarmHandlers,
-  onLegacyAlarm?: () => void,
-): Promise<void> {
-  // Same serialization as scheduleAlarm: the dispatcher's read→handlers→write
-  // cycle must not interleave with an activity-hook scheduleAlarm.
-  const chained = (host._alarmChain ?? Promise.resolve()).then(
-    () => dispatchAlarmBody(ctx, handlers, onLegacyAlarm),
-    () => dispatchAlarmBody(ctx, handlers, onLegacyAlarm),
-  );
-  host._alarmChain = chained;
-  return chained;
-}
-
-async function dispatchAlarmBody(
-  ctx: AlarmContext,
-  handlers: AlarmHandlers,
-  onLegacyAlarm?: () => void,
-): Promise<void> {
-  try {
-    const now = Date.now();
-    const existing = (await ctx?.storage?.get?.(ALARM_REASONS_KEY)) as
-      | Record<string, number>
-      | undefined;
-    if (!existing || Object.keys(existing).length === 0) {
-      onLegacyAlarm?.();
-      return;
-    }
-    const map: Record<string, number> = { ...existing };
-    // Snapshot fireable reasons BEFORE running any of them, so a
-    // handler that schedules itself for the next cycle doesn't get
-    // immediately re-fired in the same dispatch.
-    const fired: string[] = [];
-    for (const [reason, when] of Object.entries(map)) {
-      if (when <= now) fired.push(reason);
-    }
-    for (const reason of fired) {
-      delete map[reason];
-      const handler = handlers[reason];
-      // Unknown reasons silently dropped (forward-compat).
-      if (!handler) continue;
-      try {
-        const result = await handler(now);
-        if (result && typeof result.rearmAt === 'number') {
-          map[reason] = result.rearmAt;
-        }
-      } catch (e) {
-        console.warn(`[nimbus/W1] dispatch ${reason} threw:`, errorText(e));
-      }
-    }
-    // Re-arm or clear.
-    const setAlarmFn = ctx?.storage?.setAlarm;
-    if (Object.keys(map).length > 0) {
-      await ctx.storage.put(ALARM_REASONS_KEY, map);
-      const earliest = Math.min(...Object.values(map));
-      if (typeof setAlarmFn === 'function') {
-        setAlarmFn.call(ctx.storage, earliest);
-      }
-    } else {
-      try { await ctx.storage.delete(ALARM_REASONS_KEY); } catch {}
-      // No remaining reasons → no setAlarm call → DO becomes
-      // hibernation-eligible after the 10s idle window.
-    }
-  } catch (e) {
-    console.warn('[nimbus/W1] dispatchAlarm threw:', errorText(e));
-  }
-}
-
-/** Increment + persist the isolate-gen counter once per fresh isolate. */
-export async function maybeBumpIsolateGen(host: IsolateGenHost, ctx: AlarmContext): Promise<void> {
-  if (host._isolateGenPersisted) return;
-  host._isolateGenPersisted = true;
-  try {
-    const prev = (await ctx.storage.get(ISOLATE_GEN_KEY)) as number | undefined;
-    // Adopt the persisted truth first, and adopt the bump only after the
-    // put resolves. An unpersisted `next` would be re-read as `prev` by the
-    // NEXT boot and re-issued — two instances sharing one generation is
-    // exactly the pid-aliasing this counter exists to prevent. Running on
-    // the previous persisted generation is the lesser lapse, and the
-    // put-failure case is replica-only in practice (replicas never spawn).
-    //
-    // What holds the guarantee is the output gate, not this await: measured,
-    // the block body resolves in 0 ms even with a confirmed put, because
-    // `await storage.put()` returns before durability. The gate is what
-    // keeps a pid from generation N from escaping before N is durable, which
-    // is why marking this put `allowUnconfirmed` is not a free speedup — see
-    // scratchpad/coldstart-s1.md.
-    host._isolateGen = typeof prev === 'number' ? prev : 0;
-    const next = host._isolateGen + 1;
-    await ctx.storage.put(ISOLATE_GEN_KEY, next);
-    host._isolateGen = next;
-  } catch (e) {
-    console.warn('[nimbus/W9] isolate-gen bump failed:', errorText(e));
-  }
-}

package/src/ctx-exports.ts

@@ -1,77 +0,0 @@
-/**
- * ctx-exports.ts — leaf module holding the ctx.exports reference.
- *
- * Isolated from the embedder's entry module so helpers (notably
- * loader-pool.ts) can read `ctx.exports` without transitively importing the
- * Durable Object classes. Keeping this a leaf (no imports) lets the pool be
- * unit-tested in a plain Node/Bun process.
- *
- * The embedder's fetch handler calls `setCtxExports(ctx.exports)` on the
- * first request; callers like the loader pool read via `getCtxExports()`.
- * If the pool is constructed before the first fetch (unlikely) it just gets
- * null — the caller decides how to degrade.
- */
-
-/**
- * One entry of `ctx.exports`: a top-level entrypoint's loopback factory, which
- * mints a Service Binding stub for that entrypoint when called with props.
- *
- * The stub's RPC surface belongs to the entrypoint CLASS, which this leaf
- * cannot see — `Cloudflare.Exports` is derived from the embedder's own main
- * module, so for a library it evaluates to `{}`. A caller that knows the class
- * names the surface it expects (`factory<MySupervisorRpc>({ props })`); one
- * that does not gets `unknown` and has to narrow, same as
- * `DurableObjectNamespace<T>` and `RpcStub<T>` in @cloudflare/workers-types.
- */
-export type EntrypointLoopbackFactory = <Stub = unknown>(options: { props: object }) => Stub;
-
-/**
- * `ctx.exports` itself — one factory per top-level entrypoint export, keyed by
- * export name. Absent names read as undefined, which is how a caller finds out
- * the embedder's entry module does not re-export the class it needs.
- */
-export type CtxExports = Record<string, EntrypointLoopbackFactory | undefined>;
-
-let _ctxExports: CtxExports | null = null;
-
-export function setCtxExports(value: CtxExports): void {
-  if (_ctxExports) return; // first-write-wins, same as the prior inline impl
-  _ctxExports = value;
-}
-
-export function getCtxExports(): CtxExports | null {
-  return _ctxExports;
-}
-
-/**
- * The fabric mints supervisor bindings for the programs it hosts, but the
- * entrypoint class that answers them belongs to the embedder, so its
- * ctx.exports name is registered once at composition time rather than
- * hardcoded here. First-write-wins, same as the ctx.exports holder above.
- */
-let _supervisorEntrypointName: string | null = null;
-
-export function setSupervisorEntrypointName(name: string): void {
-  if (_supervisorEntrypointName) return;
-  _supervisorEntrypointName = name;
-}
-
-/**
- * Resolve the registered supervisor entrypoint on an exports object —
- * `exportsObj` when given (a WorkerEntrypoint reads its own ctx.exports),
- * the held ctx.exports otherwise. Calling the result with props mints one
- * supervisor binding (`env.SUPERVISOR`) for one hosted program. Null when
- * either half is missing; the caller decides whether that degrades or throws.
- */
-export function supervisorEntrypoint(exportsObj?: unknown): EntrypointLoopbackFactory | null {
-  const exports = exportsObj ?? _ctxExports;
-  if (!_supervisorEntrypointName) return null;
-  if ((typeof exports !== 'object' && typeof exports !== 'function') || exports === null) return null;
-  const factory = (exports as Record<string, unknown>)[_supervisorEntrypointName];
-  return typeof factory === 'function' ? (factory as EntrypointLoopbackFactory) : null;
-}
-
-/** The registered name, for error messages that point at the missing export. */
-export function supervisorEntrypointName(): string | null {
-  return _supervisorEntrypointName;
-}

package/src/loader-ledger.ts

@@ -1,112 +0,0 @@
-/**
- * loader-ledger.ts — per-DO accounting for the Worker Loader's two caps.
- *
- * Measured on production workerd: a Durable Object admits ~5–6 concurrent
- * dynamic workers before the platform refuses with "Too many concurrent
- * dynamic workers", one DO method can drive at most 4 concurrent Loader
- * fetches, and loader-cache entries are never released — every DISTINCT
- * `loader.get(id)` permanently consumes one of the dynamic-worker slots for
- * the object's lifetime. Nimbus stays under the caps by construction
- * (`IN_DO_THRESHOLD` = 5 in the fanout pool), which until now meant the slots
- * were counted in prose. This ledger counts them at the fabric's loader call
- * sites instead — the loader pool's slots, a resident process's keyed worker,
- * a one-shot's load — so proximity is measurable and a cap failure can name
- * the ids actually holding slots.
- *
- * Measurement only: no admission control. The caps are the platform's, they
- * are approximate ("~5–6"), and a gate on an approximate number would refuse
- * work the platform would have run.
- *
- * Keyed weakly off the hosting actor's `ctx`, like the facet slot books: the
- * caps are per Durable Object, and dynamic workers die with the isolate that
- * loaded them, so a ledger that goes away with its host describes nothing
- * that still exists.
- */
-
-import { classifyError } from '@nimbus-sh/core/observability/oom-classify.js';
-
-interface LoaderLedger {
-  /** Distinct loader ids ever gotten — each one a permanently consumed slot. */
-  ids: Set<string>;
-  /** In-flight calls into dynamic workers, right now. */
-  liveFetches: number;
-  /** The most that were ever in flight at once. */
-  peakLiveFetches: number;
-}
-
-const ledgers = new WeakMap<object, LoaderLedger>();
-
-function ledger(ctx: object): LoaderLedger {
-  let entry = ledgers.get(ctx);
-  if (!entry) {
-    entry = { ids: new Set(), liveFetches: 0, peakLiveFetches: 0 };
-    ledgers.set(ctx, entry);
-  }
-  return entry;
-}
-
-/** Record a keyed `loader.get(id)` — a permanent slot if the id is new. */
-export function recordLoaderId(ctx: object, id: string): void {
-  ledger(ctx).ids.add(id);
-}
-
-/**
- * Count one call into a dynamic worker as a live Loader fetch; the returned
- * function ends it (idempotently), from the caller's own `finally`.
- *
- * A begin/end pair rather than a wrapper on purpose, and the shape is
- * load-bearing: wrapping the stub call in a ledger-owned async frame
- * (`trackLoaderFetch(ctx, () => entrypoint.execute(...))`) left the hosting
- * Durable Object poisoned after every pooled dispatch — the next fabric
- * activity hung the object or reset the instance outright (pid base jumped,
- * every attached WebSocket dropped with no close frame), measured 7/7 on
- * staging and gone 3/3 with the direct call restored. Same seam-quirk class
- * as pipelined `fetch.call`, which workerd refuses for dynamically-loaded
- * workers: an RPC stub call must stay a direct property call awaited by the
- * frame that made it, so the ledger only brackets it.
- */
-export function beginLoaderFetch(ctx: object): () => void {
-  const entry = ledger(ctx);
-  entry.liveFetches++;
-  entry.peakLiveFetches = Math.max(entry.peakLiveFetches, entry.liveFetches);
-  let ended = false;
-  return () => {
-    if (ended) return;
-    ended = true;
-    entry.liveFetches--;
-  };
-}
-
-/** Snapshot for the diag surface. Pure read; no I/O. */
-export function loaderLedgerStats(ctx: object): {
-  idsEverGotten: string[];
-  liveFetches: number;
-  peakLiveFetches: number;
-} {
-  const entry = ledger(ctx);
-  return {
-    idsEverGotten: [...entry.ids],
-    liveFetches: entry.liveFetches,
-    peakLiveFetches: entry.peakLiveFetches,
-  };
-}
-
-/**
- * Name the per-DO accounting on a "Too many concurrent dynamic workers"
- * failure; hand every other error back untouched. The platform's message
- * says only that the cap was hit — which ids hold the slots, and that a
- * keyed id can never give one back, is what the operator needs to know to
- * shrink anything.
- */
-export function withDynamicWorkerCapNamed<E>(ctx: object, error: E): E | Error {
-  if (classifyError(error) !== 'dynamic_worker_cap') return error;
-  const entry = ledger(ctx);
-  const platform = error instanceof Error ? error.message : String(error);
-  return new Error(
-    `${platform} — this Durable Object has ${entry.ids.size} loader id(s) permanently `
-      + `holding dynamic-worker slots (a loader.get id is never released): `
-      + `${[...entry.ids].join(', ') || '(none recorded)'}; live Loader fetches ${entry.liveFetches}, `
-      + `peak ${entry.peakLiveFetches}`,
-    { cause: error },
-  );
-}