@nimbus-sh/fabric 0.9.0 → 0.10.0

package/src/budgets.ts

@@ -15,7 +15,9 @@
  * the width fan-outs have claimed and not yet released. A fan-out spends only
  * the {@link dynamicWorkerHeadroom} that leaves, so work a Durable Object
  * already has in flight — a resident process, the esbuild facet, a git
- * network op, another fan-out — keeps its slots.
+ * network op, another fan-out — keeps its slots. Work that would rather wait
+ * than be refused waits on the ledger ({@link beginLoaderFetchWhenFree}) and
+ * is let in, in the order it asked, by whichever release makes room.
  *
  * Keyed weakly off the hosting actor's `ctx`, like the facet slot books: the
  * limit is per Durable Object, and dynamic workers die with the isolate that
@@ -34,35 +36,180 @@ import { hostWasmIdentity } from './host-wasm.js';
  */
 export const DO_DYNAMIC_WORKER_LIMIT = 10;
 
+/**
+ * Ends one hold, idempotently. Pass the error the call failed with, if it
+ * did: a "Dynamic worker concurrency limit exceeded" refusal pauses the
+ * ledger's admissions (see {@link beginLoaderFetchWhenFree}); anything else,
+ * or nothing, just ends the hold.
+ */
+export type EndLoaderFetch = (failure?: unknown) => void;
+
+/**
+ * A width one fan-out reserved with {@link claimDynamicWorkers}. Holds taken
+ * under it (`beginLoaderFetch(ctx, key, claim)`) count inside that width, not
+ * on top of it, until `release` (idempotent).
+ */
+export interface DynamicWorkerClaim {
+  release(): void;
+}
+
+interface ClaimEntry {
+  width: number;
+  /** Loader id → open holds taken under this claim. */
+  keys: Map<string, number>;
+}
+
+interface Waiter {
+  key: string;
+  claim: ClaimEntry | undefined;
+  admit(end: EndLoaderFetch): void;
+}
+
 interface LoaderLedger {
-  /** Loader id → open holds on it. A key is present only while held. */
+  /** Loader id → open holds on it, under a claim or not. A key is present only while held. */
   inFlight: Map<string, number>;
-  /** Width claimed by fan-outs that have not released it. */
-  claimed: number;
+  /** Claims not yet released. */
+  claims: Set<ClaimEntry>;
   /** The most distinct workers (holds plus claims) ever counted at once. */
   peak: number;
+  /** Waits not yet admitted, in the order they asked. */
+  waiters: Waiter[];
+  /** Length of the pause a refusal started, while it lasts; 0 when admitting. */
+  pauseMs: number;
+  pauseTimer: ReturnType<typeof setTimeout> | undefined;
+  /** Advanced when a pause starts and when it ends; a hold keeps the one it began in. */
+  epoch: number;
+  /** Pauses in a row with no worker admitted between them. */
+  refusals: number;
 }
 
+/**
+ * The first pause after a limit refusal, doubling while refusals continue,
+ * up to {@link REFUSAL_PAUSE_MAX_MS}. A deployed Durable Object admitted a
+ * batch it had refused after a 6 s pause.
+ */
+const REFUSAL_PAUSE_MS = 50;
+const REFUSAL_PAUSE_MAX_MS = 2_000;
+
 const ledgers = new WeakMap<object, LoaderLedger>();
+const claimEntries = new WeakMap<DynamicWorkerClaim, { ledger: LoaderLedger; entry: ClaimEntry }>();
 
 function ledger(ctx: object): LoaderLedger {
   let entry = ledgers.get(ctx);
   if (!entry) {
-    entry = { inFlight: new Map(), claimed: 0, peak: 0 };
+    entry = {
+      inFlight: new Map(), claims: new Set(), peak: 0,
+      waiters: [], pauseMs: 0, pauseTimer: undefined, epoch: 0, refusals: 0,
+    };
     ledgers.set(ctx, entry);
   }
   return entry;
 }
 
+/** Distinct workers counted: each claim's width (or more, if its holds exceed it), plus held keys no claim covers. */
 function inUse(entry: LoaderLedger): number {
-  return entry.inFlight.size + entry.claimed;
+  let count = 0;
+  const covered = new Set<string>();
+  for (const claim of entry.claims) {
+    count += Math.max(claim.width, claim.keys.size);
+    for (const key of claim.keys.keys()) covered.add(key);
+  }
+  for (const key of entry.inFlight.keys()) if (!covered.has(key)) count++;
+  return count;
+}
+
+function headroom(entry: LoaderLedger): number {
+  return entry.pauseMs > 0 ? 0 : Math.max(0, DO_DYNAMIC_WORKER_LIMIT - inUse(entry));
+}
+
+function claimOf(ctx: object, claim: DynamicWorkerClaim | undefined): ClaimEntry | undefined {
+  if (claim === undefined) return undefined;
+  const owned = claimEntries.get(claim);
+  if (owned === undefined || owned.ledger !== ledger(ctx)) {
+    throw new Error('Nimbus: a Dynamic Worker claim is used only on the ledger of the actor that claimed it');
+  }
+  return owned.ledger.claims.has(owned.entry) ? owned.entry : undefined;
+}
+
+function count(map: Map<string, number>, key: string, by: 1 | -1): void {
+  const open = (map.get(key) ?? 0) + by;
+  if (open > 0) map.set(key, open);
+  else map.delete(key);
+}
+
+/** Take one hold; the caller admits waiters after. */
+function hold(entry: LoaderLedger, workerKey: string, claim: ClaimEntry | undefined): EndLoaderFetch {
+  count(entry.inFlight, workerKey, 1);
+  if (claim) count(claim.keys, workerKey, 1);
+  entry.peak = Math.max(entry.peak, inUse(entry));
+  const epoch = entry.epoch;
+  let ended = false;
+  return (failure) => {
+    if (ended) return;
+    ended = true;
+    count(entry.inFlight, workerKey, -1);
+    if (claim) count(claim.keys, workerKey, -1);
+    if (classifyError(failure) === 'dynamic_worker_cap') refused(entry, epoch);
+    else if (epoch === entry.epoch && entry.pauseMs === 0) entry.refusals = 0;
+    admitWaiters(entry);
+  };
+}
+
+/**
+ * The platform refused a worker this ledger counted room for: it still
+ * counts workers the ledger has released, which no release here can show.
+ * So nothing new is admitted until a pause has passed. A refusal of a call
+ * that began before the latest pause started or ended is the same lag and
+ * changes nothing; one of a call let in after it doubles the next pause.
+ */
+function refused(entry: LoaderLedger, epoch: number): void {
+  if (epoch !== entry.epoch) return;
+  if (entry.pauseTimer !== undefined) clearTimeout(entry.pauseTimer);
+  entry.pauseMs = Math.min(REFUSAL_PAUSE_MAX_MS, REFUSAL_PAUSE_MS * 2 ** entry.refusals);
+  entry.refusals++;
+  entry.epoch++;
+  entry.pauseTimer = setTimeout(() => {
+    entry.pauseMs = 0;
+    entry.pauseTimer = undefined;
+    entry.epoch++;
+    admitWaiters(entry);
+  }, entry.pauseMs);
+}
+
+function admissible(entry: LoaderLedger, waiter: Waiter): boolean {
+  // Requests to a worker already in flight count once, even while paused.
+  if (entry.inFlight.has(waiter.key)) return true;
+  if (entry.pauseMs > 0) return false;
+  if (waiter.claim && entry.claims.has(waiter.claim) && waiter.claim.keys.size < waiter.claim.width) return true;
+  return inUse(entry) < DO_DYNAMIC_WORKER_LIMIT;
+}
+
+/**
+ * Let in every waiter that fits, in the order they asked: each takes its
+ * hold here, so a freed slot goes to exactly one waiter and is never left
+ * between a wake and a begin. Run after every change that can make room.
+ * A waiter let in on a new key lets in the later ones on that key, and the
+ * earlier ones too: the scan starts over.
+ */
+function admitWaiters(entry: LoaderLedger): void {
+  for (let i = 0; i < entry.waiters.length;) {
+    const waiter = entry.waiters[i];
+    if (!admissible(entry, waiter)) { i++; continue; }
+    const joins = entry.inFlight.has(waiter.key);
+    entry.waiters.splice(i, 1);
+    waiter.admit(hold(entry, waiter.key, waiter.claim));
+    if (!joins) i = 0;
+  }
 }
 
 /**
  * Hold the Dynamic Worker `workerKey` in flight on this actor's ledger; the
  * returned function ends the hold (idempotently), from the caller's own
  * `finally`. Holds on one key nest: the worker counts once until the last
- * one ends, as the platform counts it.
+ * one ends, as the platform counts it. Under a `claim`, the hold counts
+ * inside the claim's width. This never waits: it is for work the actor
+ * starts regardless (a resident process); {@link beginLoaderFetchWhenFree}
+ * waits for room.
  *
  * 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
@@ -75,48 +222,100 @@ function inUse(entry: LoaderLedger): number {
  * 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, workerKey: string): () => void {
+export function beginLoaderFetch(ctx: object, workerKey: string, claim?: DynamicWorkerClaim): EndLoaderFetch {
   const entry = ledger(ctx);
-  entry.inFlight.set(workerKey, (entry.inFlight.get(workerKey) ?? 0) + 1);
-  entry.peak = Math.max(entry.peak, inUse(entry));
-  let ended = false;
-  return () => {
-    if (ended) return;
-    ended = true;
-    const open = (entry.inFlight.get(workerKey) ?? 1) - 1;
-    if (open > 0) entry.inFlight.set(workerKey, open);
-    else entry.inFlight.delete(workerKey);
-  };
+  const end = hold(entry, workerKey, claimOf(ctx, claim));
+  admitWaiters(entry);
+  return end;
+}
+
+/**
+ * {@link beginLoaderFetch} once the ledger has room: resolves, holding
+ * `workerKey`, as soon as that worker is already in flight (holds on it
+ * count once) or a distinct worker more fits — within the `claim`'s width,
+ * or the actor's headroom. Waits are let in in the order they asked, by
+ * whoever's release makes the room: a hold's end, a claim's release, a
+ * pause's end. The hold is taken as the wait is let in, so a freed slot
+ * wakes one waiter and no other caller can take it first; once resolved, it
+ * is the caller's to end.
+ *
+ * A call refused with "Dynamic worker concurrency limit exceeded" ends its
+ * hold with the refusal (`end(error)`) and waits again: the refusal pauses
+ * admission (50 ms, doubling to 2 s while refusals continue), because the
+ * platform counts a worker for a moment after its call returns and no
+ * release can show that.
+ *
+ * `signal` abandons the wait: it rejects with the signal's reason and holds
+ * nothing. A wait outlives nothing on its own: bound it with a signal when
+ * room may never come (a resident process holds its worker for as long as
+ * it runs).
+ *
+ *   const end = await beginLoaderFetchWhenFree(ctx, key, { signal });
+ *   try { return await worker.getEntrypoint().run(); }
+ *   catch (error) { end(error); throw error; }
+ *   finally { end(); }
+ */
+export function beginLoaderFetchWhenFree(
+  ctx: object,
+  workerKey: string,
+  options: { signal?: AbortSignal; claim?: DynamicWorkerClaim } = {},
+): Promise<EndLoaderFetch> {
+  const { signal } = options;
+  return new Promise<EndLoaderFetch>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const entry = ledger(ctx);
+    const abandon = () => {
+      const at = entry.waiters.indexOf(waiter);
+      if (at < 0) return;
+      entry.waiters.splice(at, 1);
+      reject(signal?.reason);
+    };
+    const waiter: Waiter = {
+      key: workerKey,
+      claim: claimOf(ctx, options.claim),
+      admit(end) {
+        signal?.removeEventListener('abort', abandon);
+        resolve(end);
+      },
+    };
+    entry.waiters.push(waiter);
+    signal?.addEventListener('abort', abandon, { once: true });
+    admitWaiters(entry);
+  });
 }
 
 /**
  * Distinct Dynamic Workers this actor may still put in flight: the limit
- * less what is held and claimed right now. Never negative.
+ * less what is held and claimed right now, and none while a limit refusal's
+ * pause lasts. Never negative.
  */
 export function dynamicWorkerHeadroom(ctx: object): number {
-  return Math.max(0, DO_DYNAMIC_WORKER_LIMIT - inUse(ledger(ctx)));
+  return headroom(ledger(ctx));
 }
 
 /**
  * Claim `width` distinct Dynamic Workers for one fan-out, or null when the
  * headroom cannot hold it. The claim counts until `release` (idempotent), so
  * a second fan-out sizing itself meanwhile sees it; the claimant's own
- * dispatches are held as well while they run, which only ever over-counts
- * toward sending that second fan-out elsewhere.
+ * dispatches, held under the claim, count inside it.
  */
-export function claimDynamicWorkers(ctx: object, width: number): { release(): void } | null {
+export function claimDynamicWorkers(ctx: object, width: number): DynamicWorkerClaim | null {
   const entry = ledger(ctx);
-  if (width < 1 || width > DO_DYNAMIC_WORKER_LIMIT - inUse(entry)) return null;
-  entry.claimed += width;
+  if (width < 1 || width > headroom(entry)) return null;
+  const claim: ClaimEntry = { width, keys: new Map() };
+  entry.claims.add(claim);
   entry.peak = Math.max(entry.peak, inUse(entry));
-  let released = false;
-  return {
+  const handle: DynamicWorkerClaim = {
     release() {
-      if (released) return;
-      released = true;
-      entry.claimed -= width;
+      if (!entry.claims.delete(claim)) return;
+      admitWaiters(entry);
     },
   };
+  claimEntries.set(handle, { ledger: entry, entry: claim });
+  return handle;
 }
 
 /** Snapshot for the diag surface. Pure read; no I/O. */
@@ -126,17 +325,29 @@ export function loaderLedgerStats(ctx: object): {
   claimed: number;
   headroom: number;
   peak: number;
+  /** Waits not yet admitted. */
+  waiting: number;
+  /** Length of the pause a limit refusal started, while it lasts; 0 when admitting. */
+  pauseMs: number;
 } {
   const entry = ledger(ctx);
   return {
     limit: DO_DYNAMIC_WORKER_LIMIT,
     inFlightWorkers: [...entry.inFlight.keys()],
-    claimed: entry.claimed,
-    headroom: dynamicWorkerHeadroom(ctx),
+    claimed: claimedWidth(entry),
+    headroom: headroom(entry),
     peak: entry.peak,
+    waiting: entry.waiters.length,
+    pauseMs: entry.pauseMs,
   };
 }
 
+function claimedWidth(entry: LoaderLedger): number {
+  let width = 0;
+  for (const claim of entry.claims) width += claim.width;
+  return width;
+}
+
 /**
  * Name the per-DO accounting on a "Dynamic worker concurrency limit exceeded"
  * failure; hand every other error back untouched. The platform's message
@@ -149,7 +360,7 @@ export function withDynamicWorkerCapNamed<E>(ctx: object, error: E): E | Error {
   const platform = error instanceof Error ? error.message : String(error);
   return new Error(
     `${platform} — this Durable Object had ${entry.inFlight.size} distinct dynamic worker(s) in flight `
-      + `(${[...entry.inFlight.keys()].join(', ') || 'none recorded'}) and ${entry.claimed} claimed by fan-outs, `
+      + `(${[...entry.inFlight.keys()].join(', ') || 'none recorded'}) and ${claimedWidth(entry)} claimed by fan-outs, `
       + `against a limit of ${DO_DYNAMIC_WORKER_LIMIT}; peak ${entry.peak}`,
     { cause: error },
   );

package/src/fanout.ts

@@ -21,7 +21,7 @@
 import { serializeFunction } from './vendor/serialize.js';
 import { BindingError } from './vendor/errors.js';
 import { IsolatePool, type FacetTaskFn } from './isolate-pool.js';
-import { claimDynamicWorkers, dynamicWorkerHeadroom } from './budgets.js';
+import { claimDynamicWorkers, dynamicWorkerHeadroom, type DynamicWorkerClaim } from './budgets.js';
 import { hostRoute } from './composition.js';
 import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
 import { classifyDoCall, describeError, isRetryableDoCall } from '@nimbus-sh/platform/oom-classify.js';
@@ -254,7 +254,7 @@ export class Fanout {
     this.opts.onRoute?.({ topology: claim ? 'in-do' : 'peer-do', tasks: tasks.length, headroom });
     if (!claim) return this._dispatchPeerDo<A, R>(tasks, fn);
     try {
-      return await this._dispatchInDo<A, R>(tasks, fn);
+      return await this._dispatchInDo<A, R>(tasks, fn, claim);
     } finally {
       claim.release();
     }
@@ -283,11 +283,13 @@ export class Fanout {
   private async _dispatchInDo<A, R>(
     tasks: FanoutTask<A>[],
     fn: FacetTaskFn<A, R>,
+    claim: DynamicWorkerClaim,
   ): Promise<R[]> {
     // One slot — one Dynamic Worker — per task; submitMany has claimed
-    // that width on the ledger.
+    // that width on the ledger, and the pool's dispatches are held inside it.
     const pool = new IsolatePool(this.env, this.ctx, {
       concurrency: tasks.length,
+      claim,
       timeoutMs: this.opts.timeoutMs,
       tag: this.opts.tag,
       preamble: this.opts.preamble,

package/src/fenced-work.ts

@@ -262,9 +262,9 @@ export class FencedWork<R extends FencedWorkRecord> {
    * Runs once per instance — re-calls in the same instance are no-ops — and
    * re-drives every row whose pid is `> 0` and at or below `generationBase()`
    * with `attempt < FENCED_WORK_MAX_ATTEMPT`; the rest are abandoned. What the
-   * re-drive resolver receives is the journalled recipe and nothing else:
-   * env and credentials are never written to storage, so the resolver's
-   * embedder re-resolves them rather than reading them back.
+   * re-drive resolver receives is the journalled record and nothing else: a
+   * host keeps env and secrets out of it, so the resolver's embedder
+   * re-resolves them rather than reading them back.
    */
   async recoverInterrupted(): Promise<void> {
     if (this.recovered) return;

package/src/inner-do-env.ts

@@ -0,0 +1,213 @@
+/**
+ * inner-do-env.ts — a classic Durable Object binding inside an inner Worker.
+ *
+ * `nimbus wrangler dev` loads the user's Worker as a dynamic worker, and its
+ * Durable Object bindings run as facets of the session Durable Object. The
+ * binding the loader passes (`NimbusDurableObjectNamespace`, an entrypoint of
+ * the session's isolate) answers RPC, so it cannot be the inner Worker's
+ * namespace: a DurableObjectNamespace's API is synchronous (`env.P.get(
+ * env.P.idFromName('x'))` takes no await), and an RpcPromise cannot travel as
+ * an argument ("Could not serialize object of type RpcPromise").
+ *
+ * So a module the inner Worker runs before any of its own code (its main
+ * module's first import, `innerWorkerModules`) replaces each such binding in
+ * the isolate's env, which every handler, entrypoint and Durable Object of the
+ * isolate sees, with a local namespace. Ids are made locally, and `get`
+ * answers at once an RPC stub (`new RpcStub(target)`) of a local target that
+ * relays each member the stub's caller reaches (a call, a read, or a path
+ * through members, fetch included) to the binding's `callOn` or `getOn`,
+ * which the session runs on the object's facet. An RPC stub is what a
+ * Durable Object stub is to the runtime: callable by any method name, read by
+ * any property name, pipelined, bound to its request, and transferable, as an
+ * argument or an answer, where an entrypoint of a dynamically-loaded Worker
+ * is not. Arguments and answers cross natively, stubs, functions and streams
+ * included.
+ *
+ * Its prototype is not RpcStub's but one shaped as a Durable Object stub's:
+ * its constructor is a class `DurableObject` that cannot be constructed, its
+ * tag is 'DurableObject', and it has no `dup` or Symbol.dispose of its own,
+ * so `dup` is a member, which the runtime refuses as on Cloudflare. It
+ * differs from a Durable Object stub in two ways the runtime fixes. `typeof`
+ * is 'function'. And it is not persistent, so a Worker Loader env cannot carry
+ * it ("RpcStub cannot be serialized in this context because it is not a
+ * persistent stub"): the loader shim (NimbusLoaderRPC) keeps a child's code
+ * and loads it again in each later request, so the child's env can carry
+ * nothing made in one request, the session's own stubs included.
+ */
+
+import type { RpcStub, WorkerEntrypoint } from 'cloudflare:workers';
+import { ESBUILD_NAME_MODULE_SHIM } from '@nimbus-sh/core/_shared/esbuild-facet-shim.js';
+
+/**
+ * The id string a name gives: deterministic (FNV-style, 64-bit hex), with the
+ * prefix `name:` so it never collides with a `uniq:` id. Self-contained: its
+ * source also runs in the inner isolate (innerDoAdapter).
+ */
+export function innerDoIdFromName(name: string): string {
+  let h1 = 0xdeadbeef ^ name.length;
+  let h2 = 0x41c6ce57 ^ name.length;
+  for (let i = 0; i < name.length; i++) {
+    const ch = name.charCodeAt(i);
+    h1 = Math.imul(h1 ^ ch, 2654435761);
+    h2 = Math.imul(h2 ^ ch, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+  return 'name:' + (h1 >>> 0).toString(16).padStart(8, '0') + (h2 >>> 0).toString(16).padStart(8, '0');
+}
+
+/** What the binding the loader passes answers: one access to one object. */
+export interface InnerDoRemote {
+  /** The member of object `id` at `path` (names from the object down), called with `args`. */
+  callOn(id: string, path: string[], args: unknown[]): Promise<unknown>;
+  /** The member of object `id` at `path`, read. */
+  getOn(id: string, path: string[]): Promise<unknown>;
+}
+
+/** What the adapter runs over: the inner isolate's `cloudflare:workers`. */
+export interface InnerDoRuntime {
+  env: object;
+  WorkerEntrypoint: typeof WorkerEntrypoint;
+  RpcStub: typeof RpcStub;
+}
+
+/** The entrypoint a build asks which Durable Object classes are missing, unless the bundle spells it. */
+const CLASSES_ENTRYPOINT = 'NimbusDurableObjectClasses';
+/**
+ * The adapter, as it runs in the inner isolate: it replaces each of `names`
+ * in `runtime.env` that holds the binding with a local DurableObjectNamespace,
+ * and answers the class check the main module exports. `main` is the main
+ * module's namespace. Self-contained (serialized with toString): it reaches
+ * nothing outside itself but its arguments.
+ */
+export function innerDoAdapter(
+  idFromName: (name: string) => string,
+  names: readonly string[],
+  main: object,
+  runtime: InnerDoRuntime,
+): { NimbusDurableObjectClasses: unknown } {
+  /** A Durable Object id: its string, and the name it was made from. */
+  class DurableObjectId {
+    readonly name?: string;
+    readonly #id: string;
+    constructor(id: string, name?: string) {
+      this.#id = id;
+      if (name !== undefined) this.name = name;
+    }
+    toString(): string { return this.#id; }
+    equals(other: unknown): boolean { return other instanceof DurableObjectId && String(other) === this.#id; }
+  }
+
+  /** Whether `value` is the binding the loader passes (an RPC stub's methods are its properties). */
+  function isRemote(value: unknown): value is InnerDoRemote {
+    return value !== null && (typeof value === 'object' || typeof value === 'function')
+      && typeof Reflect.get(value, 'callOn') === 'function' && typeof Reflect.get(value, 'getOn') === 'function';
+  }
+
+  /**
+   * The member of object `id` at `path`, as the runtime reaches it in an RPC
+   * to the stub: called, read (it is thenable, and the runtime awaits what a
+   * read answers), or walked through to one of its own members (the runtime
+   * walks a path through own properties only, so every name is reported as
+   * one). At the empty path it is the stub's target.
+   */
+  function member(remote: InnerDoRemote, id: string, path: readonly string[]): (...args: unknown[]) => unknown {
+    const next = (name: string) => member(remote, id, [...path, name]);
+    return new Proxy((..._args: unknown[]): unknown => undefined, {
+      apply: (_target, _self, args: unknown[]) => remote.callOn(id, [...path], args),
+      get: (target, name) => {
+        if (name === 'then') {
+          return (resolve: (value: unknown) => unknown, reject: (reason: unknown) => unknown) => remote.getOn(id, [...path]).then(resolve, reject);
+        }
+        return typeof name === 'string' ? next(name) : Reflect.get(target, name);
+      },
+      getOwnPropertyDescriptor: (target, name) => (typeof name === 'string' && name !== 'then'
+        ? { value: next(name), writable: true, enumerable: true, configurable: true }
+        : Reflect.getOwnPropertyDescriptor(target, name)),
+    });
+  }
+
+  /**
+   * A stub's prototype, as a Durable Object stub's shows: its constructor
+   * cannot be called or constructed, and it is tagged 'DurableObject'.
+   */
+  const stubPrototype: object = Object.create(Object.prototype, {
+    constructor: {
+      value: function DurableObject(): never { throw new TypeError('Illegal constructor'); },
+      writable: true,
+      configurable: true,
+    },
+    [Symbol.toStringTag]: { value: 'DurableObject', configurable: true },
+  });
+
+  /** Asked once by a build: which classes the main module does not export. */
+  class NimbusDurableObjectClasses extends runtime.WorkerEntrypoint {
+    missing(classNames: string[]): string[] {
+      return classNames.filter((name) => typeof Reflect.get(main, name) !== 'function');
+    }
+  }
+
+  /** env.MY_DO: the namespace, made locally; its stubs relay to `remote`. */
+  class DurableObjectNamespace {
+    readonly #remote: InnerDoRemote;
+    constructor(remote: InnerDoRemote) { this.#remote = remote; }
+    idFromName(name: string): DurableObjectId { return new DurableObjectId(idFromName(String(name)), String(name)); }
+    newUniqueId(): DurableObjectId { return new DurableObjectId('uniq:' + crypto.randomUUID().replaceAll('-', '')); }
+    idFromString(id: string): DurableObjectId { return new DurableObjectId(String(id)); }
+    get(id: DurableObjectId | string): object {
+      const at = id instanceof DurableObjectId ? id : new DurableObjectId(String(id));
+      const stub = Object.setPrototypeOf(new runtime.RpcStub(member(this.#remote, String(at), [])), stubPrototype);
+      // As a Durable Object stub has them: its own, enumerable, in this order.
+      return Object.defineProperties(stub, {
+        name: { value: at.name, enumerable: true },
+        id: { value: at, enumerable: true },
+      });
+    }
+    getByName(name: string): object { return this.get(this.idFromName(name)); }
+    jurisdiction(): DurableObjectNamespace { return this; }
+  }
+
+  for (const name of names) {
+    const remote: unknown = Reflect.get(runtime.env, name);
+    if (isRemote(remote)) Reflect.set(runtime.env, name, new DurableObjectNamespace(remote));
+  }
+  return { NimbusDurableObjectClasses };
+}
+
+/** The inner Worker's own module, as bundled, and the adapter's. */
+const MAIN_MODULE = 'worker.js';
+const ADAPTER_MODULE = 'nimbus-do-env.js';
+
+/**
+ * The modules an inner Worker runs with Durable Object bindings `names`: its
+ * bundle as the main module, whose first import is the adapter (so the
+ * adapter has run before any of the Worker's code) and which exports the
+ * class check as `classesEntrypoint`, and the adapter. The import shares the
+ * bundle's first line, so line numbers stay the bundle's. A Worker with no
+ * such binding runs its bundle as it is, and has no class check (null).
+ *
+ * `classesEntrypoint` is a name the bundle never spells, so it exports no
+ * such name itself (a bundler prints an ASCII name as it is).
+ */
+export function innerWorkerModules(bundle: string, names: readonly string[]): {
+  mainModule: string;
+  modules: Record<string, string>;
+  classesEntrypoint: string | null;
+} {
+  if (names.length === 0) return { mainModule: MAIN_MODULE, modules: { [MAIN_MODULE]: bundle }, classesEntrypoint: null };
+  let classesEntrypoint = CLASSES_ENTRYPOINT;
+  for (let n = 2; bundle.includes(classesEntrypoint); n++) classesEntrypoint = `${CLASSES_ENTRYPOINT}_${n}`;
+  const head = `export { ${CLASSES_ENTRYPOINT} as ${classesEntrypoint} } from './${ADAPTER_MODULE}';`;
+  // A hashbang must stay first.
+  const at = bundle.startsWith('#!') ? bundle.indexOf('\n') + 1 : 0;
+  const main = bundle.slice(0, at) + head + bundle.slice(at);
+  const adapter = [
+    "import { env, RpcStub, WorkerEntrypoint } from 'cloudflare:workers';",
+    `import * as main from './${MAIN_MODULE}';`,
+    // The functions below are serialized from the bundled worker, which wraps them in __name.
+    ESBUILD_NAME_MODULE_SHIM,
+    `const { ${CLASSES_ENTRYPOINT} } = (${innerDoAdapter.toString()})(${innerDoIdFromName.toString()}, ${JSON.stringify(names)}, main, { env, RpcStub, WorkerEntrypoint });`,
+    `export { ${CLASSES_ENTRYPOINT} };`,
+  ].join('\n');
+  return { mainModule: MAIN_MODULE, modules: { [MAIN_MODULE]: main, [ADAPTER_MODULE]: adapter }, classesEntrypoint };
+}