@nimbus-sh/fabric 0.9.0 → 0.10.0

package/dist/budgets.js

@@ -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
@@ -31,23 +33,142 @@ import { hostWasmIdentity } from './host-wasm.js';
  * https://developers.cloudflare.com/changelog/post/2026-08-28-durable-objects-dynamic-workers-limit/
  */
 export const DO_DYNAMIC_WORKER_LIMIT = 10;
+/**
+ * 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();
+const claimEntries = new WeakMap();
 function ledger(ctx) {
     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) {
-    return entry.inFlight.size + entry.claimed;
+    let count = 0;
+    const covered = new Set();
+    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) {
+    return entry.pauseMs > 0 ? 0 : Math.max(0, DO_DYNAMIC_WORKER_LIMIT - inUse(entry));
+}
+function claimOf(ctx, claim) {
+    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, key, by) {
+    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, workerKey, claim) {
+    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, epoch) {
+    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, waiter) {
+    // 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) {
+    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
@@ -60,51 +181,96 @@ function inUse(entry) {
  * 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, workerKey) {
+export function beginLoaderFetch(ctx, workerKey, claim) {
     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)
+    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, workerKey, options = {}) {
+    const { signal } = options;
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
             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 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 = {
+            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) {
-    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, width) {
     const entry = ledger(ctx);
-    if (width < 1 || width > DO_DYNAMIC_WORKER_LIMIT - inUse(entry))
+    if (width < 1 || width > headroom(entry))
         return null;
-    entry.claimed += width;
+    const claim = { width, keys: new Map() };
+    entry.claims.add(claim);
     entry.peak = Math.max(entry.peak, inUse(entry));
-    let released = false;
-    return {
+    const handle = {
         release() {
-            if (released)
+            if (!entry.claims.delete(claim))
                 return;
-            released = true;
-            entry.claimed -= width;
+            admitWaiters(entry);
         },
     };
+    claimEntries.set(handle, { ledger: entry, entry: claim });
+    return handle;
 }
 /** Snapshot for the diag surface. Pure read; no I/O. */
 export function loaderLedgerStats(ctx) {
@@ -112,11 +278,19 @@ export function loaderLedgerStats(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) {
+    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
@@ -129,7 +303,7 @@ export function withDynamicWorkerCapNamed(ctx, error) {
     const entry = ledger(ctx);
     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 });
 }
 // ── Dynamic-worker module-map ceiling ───────────────────────────────────────

package/dist/fanout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fanout.d.ts","sourceRoot":"","sources":["../src/fanout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAKlE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAOtD;;+EAE+E;AAC/E,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,kCAAkC;AAClC,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,CAAC;AAEjD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,cAAc,CAAC;IACzB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAC9C,eAAO,MAAM,qBAAqB,UAAmB,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,UAAqB,CAAC;AAE3D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,uCAAuC;AACvC,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,IAAI,EAAE,CAAC,CAAC;CACT;AAED,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC1C;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D,mEAAmE;IACnE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACvC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAWD;;;;;;;;GAQG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,kBAAkB,EAAE,IAAI,EAAE,aAAa;IAoBzE;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,UAAU,CAAC,CAAC,EAAE,CAAC,EACnB,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,EACtB,EAAE,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,EAAE,CAAC;IAcf,2EAA2E;IAC3E,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,OAAO;IAKxD;;;;;;OAMG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;YAOvC,aAAa;YA8Bb,eAAe;CA2J9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAUrE"}
+{"version":3,"file":"fanout.d.ts","sourceRoot":"","sources":["../src/fanout.ts"],"names":[],"mappings":"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"}

package/dist/fanout.js

@@ -135,7 +135,7 @@ export class Fanout {
         if (!claim)
             return this._dispatchPeerDo(tasks, fn);
         try {
-            return await this._dispatchInDo(tasks, fn);
+            return await this._dispatchInDo(tasks, fn, claim);
         }
         finally {
             claim.release();
@@ -159,11 +159,12 @@ export class Fanout {
         return `nbf:${this.opts.tag}:${this.coordDoIdShort}:${shard}`;
     }
     // ── Private: in-DO dispatch (in-DO fanout) ──────────────────────────────
-    async _dispatchInDo(tasks, fn) {
+    async _dispatchInDo(tasks, fn, claim) {
         // 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/dist/fenced-work.d.ts

@@ -195,9 +195,9 @@ export declare 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.
      */
     recoverInterrupted(): Promise<void>;
     /**

package/dist/fenced-work.js

@@ -183,9 +183,9 @@ export class FencedWork {
      * 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() {
         if (this.recovered)

package/dist/inner-do-env.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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';
+/**
+ * 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 declare function innerDoIdFromName(name: string): string;
+/** 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 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 declare function innerDoAdapter(idFromName: (name: string) => string, names: readonly string[], main: object, runtime: InnerDoRuntime): {
+    NimbusDurableObjectClasses: unknown;
+};
+/**
+ * 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 declare function innerWorkerModules(bundle: string, names: readonly string[]): {
+    mainModule: string;
+    modules: Record<string, string>;
+    classesEntrypoint: string | null;
+};
+//# sourceMappingURL=inner-do-env.d.ts.map

package/dist/inner-do-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inner-do-env.d.ts","sourceRoot":"","sources":["../src/inner-do-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGpE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWtD;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,4FAA4F;IAC5F,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtE,iDAAiD;IACjD,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD;AAED,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,EAAE,OAAO,gBAAgB,CAAC;IAC1C,OAAO,EAAE,OAAO,OAAO,CAAC;CACzB;AAID;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EACpC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,GACtB;IAAE,0BAA0B,EAAE,OAAO,CAAA;CAAE,CAuFzC;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC,CAiBA"}

package/dist/inner-do-env.js

@@ -0,0 +1,181 @@
+/**
+ * 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 { 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) {
+    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');
+}
+/** 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, names, main, runtime) {
+    /** A Durable Object id: its string, and the name it was made from. */
+    class DurableObjectId {
+        name;
+        #id;
+        constructor(id, name) {
+            this.#id = id;
+            if (name !== undefined)
+                this.name = name;
+        }
+        toString() { return this.#id; }
+        equals(other) { 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) {
+        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, id, path) {
+        const next = (name) => member(remote, id, [...path, name]);
+        return new Proxy((..._args) => undefined, {
+            apply: (_target, _self, args) => remote.callOn(id, [...path], args),
+            get: (target, name) => {
+                if (name === 'then') {
+                    return (resolve, reject) => 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.create(Object.prototype, {
+        constructor: {
+            value: function DurableObject() { 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) {
+            return classNames.filter((name) => typeof Reflect.get(main, name) !== 'function');
+        }
+    }
+    /** env.MY_DO: the namespace, made locally; its stubs relay to `remote`. */
+    class DurableObjectNamespace {
+        #remote;
+        constructor(remote) { this.#remote = remote; }
+        idFromName(name) { return new DurableObjectId(idFromName(String(name)), String(name)); }
+        newUniqueId() { return new DurableObjectId('uniq:' + crypto.randomUUID().replaceAll('-', '')); }
+        idFromString(id) { return new DurableObjectId(String(id)); }
+        get(id) {
+            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) { return this.get(this.idFromName(name)); }
+        jurisdiction() { return this; }
+    }
+    for (const name of names) {
+        const remote = 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, names) {
+    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 };
+}