@nimbus-sh/fabric 0.8.0 → 0.10.0

package/README.md

@@ -22,9 +22,19 @@ npm install @nimbus-sh/fabric
 
 ## Requirements
 
-Set `compatibility_flags: ["nodejs_compat"]` in your Worker. The timer
-dispatcher needs `AsyncLocalStorage`, which workerd ships only under that
-flag. Without it the module fails to load at deploy time.
+Use a compatibility date of 2026-08-04 or later, or list `nodejs_compat` in
+`compatibility_flags`. The timer dispatcher needs `AsyncLocalStorage`, which
+workerd ships only under `nodejs_compat`, on by date from 2026-08-04. Without
+it the module fails to load at deploy time.
+
+`composeFabric` also needs `enhanced_error_serialization`: a compatibility
+date of 2026-04-21 or later, or the flag in `compatibility_flags` on an older
+date. A program's filesystem errors reach it across workerd RPC, and only
+that flag carries their `code`. On workerd without it `composeFabric` throws,
+naming both fixes, rather than every program seeing `EIO`. It throws where
+it is called. At module scope the Worker fails at startup. A library host
+that composes through `NimbusWorkspace.create({ fabric })` deploys and
+starts, and its first create throws.
 
 Import the root inside a Worker. Outside workerd, import subpaths such as
 `@nimbus-sh/fabric/timers.js`, which are typed against plain objects and run
@@ -57,6 +67,15 @@ Worker that imports Nimbus's own entry (`@nimbus-sh/sdk/worker`) inherits
 that entry's composition, so a host that names its own namespace composes in
 a Worker that does not import it.
 
+A program's filesystem calls reach the supervisor entrypoint through its
+`answer(method, args)`, which resolves `{ value }`, or `{ refusal }` for an
+error with a `code` (ENOENT, ENOTDIR, EEXIST), and the program's client
+rethrows the refusal as the error a throw would have delivered. A refusal
+thrown from an entrypoint is recorded by the platform as an exception
+("canceled ... your Worker's code had hung") although its caller was
+answered. `SupervisorRPC` implements `answer`, so an entrypoint that extends
+it has it; one written from scratch must implement it too.
+
 The route back to the host (namespace, dispatch method, supervisor
 entrypoint) is minted into every binding the fabric hands a program, in the
 host's isolate, and the entrypoints that answer those bindings read it from
@@ -224,13 +243,55 @@ Warm isolates are scoped to one session. A pool may opt into
 `cacheScope: 'global'` only if it takes no supervisor binding and keeps no
 user state.
 
-`Fanout` handles wider batches. One DO method can drive at most 4 concurrent
-loader fetches, so batches under 5 run in the coordinator and larger ones
-shard across up to 32 sibling objects, 4 at a time.
+`Fanout` handles wider batches. A Durable Object may have 10 distinct Dynamic
+Workers with in-flight requests at once (`DO_DYNAMIC_WORKER_LIMIT`), shared
+across every concurrent request to it; repeated requests to one Dynamic
+Worker count once. A batch that fits the coordinator's remaining headroom
+runs there, one Dynamic Worker per task; a wider one shards across up to 32
+sibling objects, 4 at a time, each spending its own headroom.
+
+The loader ledger counts what is in flight per DO: pool and one-shot calls,
+esbuild facet calls, git network ops, and every resident process for as long
+as it lives. `dynamicWorkerHeadroom(ctx)` is what is left,
+`claimDynamicWorkers(ctx, n)` reserves a width, `loaderLedgerStats(ctx)`
+reports it all, and a limit refusal names the workers in flight.
+
+`beginLoaderFetch(ctx, key)` holds a worker and returns the function that
+ends the hold. To wait for room rather than be refused, take the hold with
+`beginLoaderFetchWhenFree` instead:
 
-Each keyed `loader.get(id)` permanently holds one of roughly 5–6
-dynamic-worker slots. `loaderLedgerStats(ctx)` reports what you have
-consumed, and a cap refusal names the IDs holding slots.
+```ts
+import { beginLoaderFetchWhenFree } from '@nimbus-sh/fabric';
+
+const end = await beginLoaderFetchWhenFree(ctx, key, { signal: AbortSignal.timeout(15_000) });
+try {
+  return await worker.getEntrypoint().run();
+} catch (error) {
+  end(error); // a limit refusal pauses the ledger; anything else just ends the hold
+  throw error;
+} finally {
+  end();
+}
+```
+
+It resolves, holding `key`, once `key` is already in flight (requests to
+one worker count once) or one more distinct worker fits. Waits are let in in
+the order they asked, one per freed slot, by whoever makes the room: any
+hold's end, a claim's release, or the end of a refusal's pause, so a wait
+sees Nimbus's own releases as well as the caller's. The hold is taken as the
+wait is let in, so no other caller can take the slot first, and it is the
+caller's to end. An aborted `signal` rejects the wait with its reason, and
+the wait holds nothing. A resident process holds its worker for as long as
+it runs, so bound a wait that room may never reach.
+
+The platform counts a worker for a moment after its call returns, which no
+release can show. So a call refused with "Dynamic worker concurrency limit
+exceeded" hands the refusal to its end function, and the ledger then admits
+no new worker for 50 ms, doubling to 2 s while refusals continue
+(`loaderLedgerStats(ctx).pauseMs`; the headroom reads 0 meanwhile).
+`IsolatePool` retries a refused call this way, for 15 s in all. Holds taken
+under a claim (`beginLoaderFetch(ctx, key, claim)`, or `IsolatePool`'s
+`claim` option, which `Fanout` passes) count inside its width.
 
 ## Process fabric
 
@@ -329,6 +390,32 @@ and never `method.call(ep, request)`, which workerd refuses.
 
 Nesting is capped at depth 4. Raise it with `NIMBUS_INNER_LOADER_DEPTH`.
 
+A classic Durable Object binding is a local namespace inside the inner
+Worker (`inner-do-env.ts`), because a namespace's API is synchronous and an
+RpcPromise cannot travel as an argument. `innerWorkerModules` makes an adapter
+the bundle's first import; it replaces `env.MY_DO` in the env every handler,
+entrypoint and object of the isolate sees, so
+`env.MY_DO.get(env.MY_DO.idFromName('x'))` needs no `await`. A stub is
+`new RpcStub(target)`, with a prototype shaped as a Durable Object stub's:
+an entrypoint of a dynamically-loaded Worker is not transferable, an RPC stub
+is. The target relays each member the caller reaches (a call, a read, or a
+path through both) to `NimbusDurableObjectNamespace.callOn` or `getOn`, and
+the session reaches it on the object's facet. The adapter also exports the
+build's class check, under a name the bundle never spells.
+tests/unit/wrangler-dev-do-rpc-workerd.mjs checks the whole stub surface
+against plain workerd.
+
+Limits, where a stub differs from Cloudflare's:
+
+- `typeof stub` is `'function'`, not `'object'`: the runtime makes every RPC
+  stub callable.
+- A Worker Loader env cannot carry a stub. `env.LOADER.load({ env: { S: stub } })`
+  throws "RpcStub cannot be serialized in this context because it is not a
+  persistent stub", where Cloudflare passes it. The loader shim 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; a namespace is refused there on
+  Cloudflare too.
+
 ## Measured platform limits
 
 Figures below come from production workerd, June to August 2026. The code
@@ -370,8 +457,8 @@ or left to you.
 | Request-time `WebAssembly.compile`/`instantiate` CSP-blocked; wasm rides the loader modules map as `{ wasm: ArrayBuffer }`, compiled at module load | RPC of a compiled `Module` refused by structured clone; inlined bytes OOMed the supervisor |
 | Module scope bans I/O; `new Function` succeeds at module scope and throws at request time | code reaches a facet through the module map or not at all |
 | The facet start callback fires at most once | re-running it would re-execute the user's program |
-| ~5–6 concurrent dynamic workers per DO; at most 4 concurrent Loader fetches per DO method; loader-cache entries are never released | `IN_DO_THRESHOLD` = 5 sits under the fetch cap; every `loader.get(id)` permanently consumes a slot — counted per DO by the loader ledger, and a cap refusal names the ids holding them |
-| `ctx.facets.clone` is same-object only, absent from `@cloudflare/workers-types` and the pinned workerd, present in production | 18–31 ms / 45.7 MB, 34–54 ms / 1 GB; an unresolvable `src` silently EMPTIES the destination and reports success — `cloneStorage` enforces the both-ends validation |
+| 10 distinct Dynamic Workers with in-flight requests per DO, shared across its concurrent requests; repeated requests to one Dynamic Worker count once ([changelog, 2026-08-28](https://developers.cloudflare.com/changelog/post/2026-08-28-durable-objects-dynamic-workers-limit/)) | `DO_DYNAMIC_WORKER_LIMIT`; `Fanout` sizes in-DO batches to the live headroom, and a refusal names the workers in flight |
+| `ctx.facets.clone` is same-object only; declared by `@cloudflare/workers-types` 5 and present in workerd ≥ 1.20260926.1 and in production | 18–31 ms / 45.7 MB, 34–54 ms / 1 GB; an unresolvable `src` silently EMPTIES the destination and reports success — `cloneStorage` enforces the both-ends validation |
 | A DO dies at ~200 MiB of live wasm linear memory; reserved and written pages die at the same ceiling | lazy growth buys nothing; bound guest memory by rewriting the memory section |
 | A wasm stack suspended (JSPI) in one request cannot resume in another | 3 in-context resumes took 6 ms; the first cross-context one hit a 30 s timeout |
 

package/dist/bindings.d.ts

@@ -226,30 +226,20 @@ interface NimbusDoNamespaceProps {
     route?: HostRoute;
 }
 /**
- * `env.MY_DO` shim — a DurableObjectNamespace-like WorkerEntrypoint.
+ * The binding the loader passes for `env.MY_DO` (a WorkerEntrypoint of the
+ * session's isolate). The inner Worker does not use it as its namespace: a
+ * DurableObjectNamespace's API is synchronous, and this one's answers are
+ * RpcPromises, which cannot travel as arguments. The inner Worker replaces it
+ * with a local namespace (inner-do-env.ts, innerWorkerModules) that makes ids
+ * and stubs itself, and relays each member a stub's caller reaches, its
+ * fetch included, to `callOn` or `getOn`.
  *
- * Usage from inner Worker:
- *   const id   = await env.MY_DO.idFromName('x');   // AWAIT required
- *   const stub = env.MY_DO.get(id);
- *   await stub.fetch(request);
- *
- * IMPORTANT: unlike the real DurableObjectNamespace, idFromName /
- * newUniqueId / idFromString here return **Promises**, because they're
- * RPC-backed WorkerEntrypoint methods. The inner caller MUST `await`
- * them before passing the result to `.get()`. Workers RPC pipelining
- * does not currently allow passing an RpcPromise as a method argument
- * — the no-await form fails with:
- *     "Could not serialize object of type \"RpcPromise\"."
- *
- * Typical real-Worker code written for Cloudflare's synchronous
- * DurableObjectNamespace needs a one-word change (add `await`).
- *
- * idFromName produces prefix `name:` (deterministic FNV-style hash);
- * newUniqueId uses `uniq:` (random). The prefixes keep the two id
- * spaces distinct so a name-derived id can't collide with a random
- * one.
+ * `idFromName`, `newUniqueId`, `idFromString` and `get` answer as before, for
+ * a caller that awaits them. idFromName produces prefix `name:` (a
+ * deterministic hash, innerDoIdFromName); newUniqueId uses `uniq:`; the
+ * prefixes keep the two id spaces distinct.
  */
-export declare class NimbusDurableObjectNamespace extends WorkerEntrypoint<unknown, NimbusDoNamespaceProps> {
+export declare class NimbusDurableObjectNamespace extends WorkerEntrypoint<object, NimbusDoNamespaceProps> {
     /** Stable string id derived from a name. Hash is deterministic. */
     idFromName(name: string): string;
     /** Fresh random id (matches DurableObjectNamespace.newUniqueId()). */
@@ -258,25 +248,33 @@ export declare class NimbusDurableObjectNamespace extends WorkerEntrypoint<unkno
     idFromString(s: string): string;
     /** Return a stub bound to the given id. */
     get(id: string): unknown;
+    /**
+     * The member of object `id` at `path` (names from the object down), called
+     * with `args`: its answer, or what it throws, as the object gave it.
+     */
+    callOn(id: string, path: string[], args: unknown[]): Promise<unknown>;
+    /** The member of object `id` at `path`, read. */
+    getOn(id: string, path: string[]): Promise<unknown>;
 }
 /** Props the DO stub carries: which binding, which supervisor, which id. */
 interface NimbusDoStubProps extends NimbusDoNamespaceProps {
     id?: string;
 }
+/** What the session's innerDoFetch answers: the object's response, as fields. */
+export interface InnerDoFetchAnswer {
+    status: number;
+    statusText: string;
+    headers: [string, string][];
+    body: ArrayBuffer | null;
+}
 /**
- * A Durable-Object-namespace-stub for a specific id. Exposes fetch()
- * and will, if we later need it, forward RPC method calls through a
- * dispatch helper. The important invariant: EVERY call resolves the
- * inner DO class via getInnerDoClass() (./inner-do-registry.js) and
- * spins up / attaches to a facet via the supervisor's ctx.facets in
- * the SAME outer request context — never reusing stubs across requests.
+ * A Durable-Object-namespace-stub for a specific id, for a caller of the
+ * binding's own `get`: its fetch. The important invariant: EVERY call
+ * resolves the inner DO class via getInnerDoClass() (./inner-do-registry.js)
+ * and spins up / attaches to a facet via the supervisor's ctx.facets in the
+ * SAME outer request context — never reusing stubs across requests.
  */
 export declare class NimbusDOStub extends WorkerEntrypoint<object, NimbusDoStubProps> {
-    /**
-     * Resolve the supervisor DO through the composed host namespace and
-     * dispatch the innerDoFetch op through its one supervisorOp entrypoint —
-     * a host forwards envelopes, not private _rpc* methods.
-     */
     fetch(request: Request): Promise<Response>;
 }
 export {};

package/dist/bindings.d.ts.map

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

package/dist/bindings.js

@@ -27,6 +27,7 @@ import { z } from 'zod/v4';
 import { disposeRpcResource, useRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
 import { supervisorEntrypoint, supervisorEntrypointName, stagedBootAssembler } from './composition.js';
 import { hostNamespaceBinding, hostOpDispatch } from './host-dispatch.js';
+import { innerDoIdFromName } from './inner-do-env.js';
 import { assertModuleMapWithinCodeLimit } from './budgets.js';
 /**
  * `ctx.exports` — workerd's loopback bag, which the installed
@@ -586,46 +587,23 @@ export class NimbusLoadedEntrypoint extends WorkerEntrypoint {
     }
 }
 /**
- * `env.MY_DO` shim — a DurableObjectNamespace-like WorkerEntrypoint.
+ * The binding the loader passes for `env.MY_DO` (a WorkerEntrypoint of the
+ * session's isolate). The inner Worker does not use it as its namespace: a
+ * DurableObjectNamespace's API is synchronous, and this one's answers are
+ * RpcPromises, which cannot travel as arguments. The inner Worker replaces it
+ * with a local namespace (inner-do-env.ts, innerWorkerModules) that makes ids
+ * and stubs itself, and relays each member a stub's caller reaches, its
+ * fetch included, to `callOn` or `getOn`.
  *
- * Usage from inner Worker:
- *   const id   = await env.MY_DO.idFromName('x');   // AWAIT required
- *   const stub = env.MY_DO.get(id);
- *   await stub.fetch(request);
- *
- * IMPORTANT: unlike the real DurableObjectNamespace, idFromName /
- * newUniqueId / idFromString here return **Promises**, because they're
- * RPC-backed WorkerEntrypoint methods. The inner caller MUST `await`
- * them before passing the result to `.get()`. Workers RPC pipelining
- * does not currently allow passing an RpcPromise as a method argument
- * — the no-await form fails with:
- *     "Could not serialize object of type \"RpcPromise\"."
- *
- * Typical real-Worker code written for Cloudflare's synchronous
- * DurableObjectNamespace needs a one-word change (add `await`).
- *
- * idFromName produces prefix `name:` (deterministic FNV-style hash);
- * newUniqueId uses `uniq:` (random). The prefixes keep the two id
- * spaces distinct so a name-derived id can't collide with a random
- * one.
+ * `idFromName`, `newUniqueId`, `idFromString` and `get` answer as before, for
+ * a caller that awaits them. idFromName produces prefix `name:` (a
+ * deterministic hash, innerDoIdFromName); newUniqueId uses `uniq:`; the
+ * prefixes keep the two id spaces distinct.
  */
 export class NimbusDurableObjectNamespace extends WorkerEntrypoint {
     /** Stable string id derived from a name. Hash is deterministic. */
     idFromName(name) {
-        // Simple 64-bit-ish FNV-style hash → hex. Stable across runs;
-        // distinct names → distinct strings; same name → same 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);
-        const high = (h1 >>> 0).toString(16).padStart(8, '0');
-        const low = (h2 >>> 0).toString(16).padStart(8, '0');
-        return 'name:' + high + low;
+        return innerDoIdFromName(name);
     }
     /** Fresh random id (matches DurableObjectNamespace.newUniqueId()). */
     newUniqueId() {
@@ -650,72 +628,105 @@ export class NimbusDurableObjectNamespace extends WorkerEntrypoint {
             },
         });
     }
+    /**
+     * The member of object `id` at `path` (names from the object down), called
+     * with `args`: its answer, or what it throws, as the object gave it.
+     */
+    callOn(id, path, args) {
+        return innerDoMember(this.env, { ...(this.ctx.props || {}), id: String(id) }, path, args);
+    }
+    /** The member of object `id` at `path`, read. */
+    getOn(id, path) {
+        return innerDoMember(this.env, { ...(this.ctx.props || {}), id: String(id) }, path, null);
+    }
 }
 /**
- * A Durable-Object-namespace-stub for a specific id. Exposes fetch()
- * and will, if we later need it, forward RPC method calls through a
- * dispatch helper. The important invariant: EVERY call resolves the
- * inner DO class via getInnerDoClass() (./inner-do-registry.js) and
- * spins up / attaches to a facet via the supervisor's ctx.facets in
- * the SAME outer request context — never reusing stubs across requests.
+ * The session Durable Object, through the composed host namespace, and its
+ * one supervisorOp entrypoint: a host forwards envelopes, not private _rpc*
+ * methods. Throws when the binding cannot reach it; `release` drops the stub.
  */
-export class NimbusDOStub extends WorkerEntrypoint {
-    /**
-     * Resolve the supervisor DO through the composed host namespace and
-     * dispatch the innerDoFetch op through its one supervisorOp entrypoint —
-     * a host forwards envelopes, not private _rpc* methods.
-     */
-    async fetch(request) {
-        const props = this.ctx.props || {};
-        const supervisorDoId = String(props.supervisorDoId || '');
-        if (!supervisorDoId)
-            return new Response('Nimbus: supervisorDoId missing', { status: 500 });
-        const bindingName = String(props.bindingName || '');
-        const id = String(props.id || '');
-        let stub = null;
-        let dispatch;
-        try {
-            const ns = hostNamespaceBinding(this.env ?? {}, 'NimbusDOStub', props.route);
-            stub = ns.get(ns.idFromString(supervisorDoId));
-            dispatch = hostOpDispatch(stub, 'NimbusDOStub', props.route);
-        }
-        catch (e) {
-            disposeRpcResource(stub);
-            return new Response(`Nimbus: ${e instanceof Error ? e.message : String(e)}`, { status: 500 });
-        }
-        // Forward the full request (method, body, headers preserved) by
-        // serializing what's needed and reconstructing on the other side.
-        // The supervisor reconstitutes the Request from these fields and
-        // invokes the facet.
-        const body = request.method !== 'GET' && request.method !== 'HEAD'
-            ? await request.arrayBuffer()
-            : null;
+function supervisorOf(env, props) {
+    const supervisorDoId = String(props.supervisorDoId || '');
+    if (!supervisorDoId)
+        throw new Error('supervisorDoId missing');
+    let stub = null;
+    try {
+        const ns = hostNamespaceBinding(env ?? {}, 'NimbusDOStub', props.route);
+        stub = ns.get(ns.idFromString(supervisorDoId));
+        const held = stub;
+        return { dispatch: hostOpDispatch(stub, 'NimbusDOStub', props.route), release: () => disposeRpcResource(held) };
+    }
+    catch (e) {
+        disposeRpcResource(stub);
+        throw e;
+    }
+}
+function isInnerDoFetchAnswer(value) {
+    return value !== null && typeof value === 'object'
+        && 'status' in value && typeof value.status === 'number'
+        && 'statusText' in value && typeof value.statusText === 'string'
+        && 'headers' in value && Array.isArray(value.headers)
+        && 'body' in value && (value.body === null || value.body instanceof ArrayBuffer);
+}
+/**
+ * The inner object's fetch: the request forwarded whole (method, body,
+ * headers) as fields the session reconstructs, and its response rebuilt here
+ * from the fields the session answers. A binding that cannot reach the
+ * session answers 500.
+ */
+async function innerDoFetch(env, props, request) {
+    let supervisor;
+    try {
+        supervisor = supervisorOf(env, props);
+    }
+    catch (e) {
+        return new Response(`Nimbus: ${e instanceof Error ? e.message : String(e)}`, { status: 500 });
+    }
+    try {
+        const body = request.method !== 'GET' && request.method !== 'HEAD' ? await request.arrayBuffer() : null;
         const headerList = [];
         request.headers.forEach((v, k) => { headerList.push([k, v]); });
-        try {
-            return await useRpcResource(dispatch({
-                op: 'innerDoFetch',
-                args: [{
-                        bindingName,
-                        id,
-                        method: request.method,
-                        url: request.url,
-                        headers: headerList,
-                        body,
-                    }],
-            }), (res) => {
-                if (!(res instanceof Response)) {
-                    return new Response('Nimbus: innerDoFetch returned an invalid result', { status: 502 });
-                }
-                return new Response(res.body, {
-                    status: res.status,
-                    statusText: res.statusText,
-                    headers: res.headers,
-                });
-            });
-        }
-        finally {
-            disposeRpcResource(stub);
-        }
+        return await useRpcResource(supervisor.dispatch({
+            op: 'innerDoFetch',
+            args: [{ bindingName: String(props.bindingName || ''), id: String(props.id || ''), method: request.method, url: request.url, headers: headerList, body }],
+        }), (res) => {
+            if (!isInnerDoFetchAnswer(res)) {
+                return new Response('Nimbus: innerDoFetch returned an invalid result', { status: 502 });
+            }
+            return new Response(res.body, { status: res.status, statusText: res.statusText, headers: res.headers });
+        });
+    }
+    finally {
+        supervisor.release();
+    }
+}
+/**
+ * A member of the inner object, called with `args` or read (`args` null): the
+ * session reaches it on the object's facet and answers what it answered (a
+ * stub, function or stream travels as one) or rejects with what it threw,
+ * type and message kept.
+ */
+async function innerDoMember(env, props, path, args) {
+    const supervisor = supervisorOf(env, props);
+    try {
+        return await supervisor.dispatch({
+            op: 'innerDoCall',
+            args: [{ bindingName: String(props.bindingName || ''), id: String(props.id || ''), path, args }],
+        });
+    }
+    finally {
+        supervisor.release();
+    }
+}
+/**
+ * A Durable-Object-namespace-stub for a specific id, for a caller of the
+ * binding's own `get`: its fetch. The important invariant: EVERY call
+ * resolves the inner DO class via getInnerDoClass() (./inner-do-registry.js)
+ * and spins up / attaches to a facet via the supervisor's ctx.facets in the
+ * SAME outer request context — never reusing stubs across requests.
+ */
+export class NimbusDOStub extends WorkerEntrypoint {
+    async fetch(request) {
+        return innerDoFetch(this.env, this.ctx.props || {}, request);
     }
 }