@nimbus-sh/fabric 0.5.0 → 0.6.0

package/dist/isolate-pool.js

@@ -85,7 +85,10 @@ export function assembleLoaderWorkerModuleSource(options) {
     const callExpr = options.hasBindings
         ? '__fn__(...args, this.env)'
         : '__fn__(...args)';
-    lines.push('export default class extends WorkerEntrypoint {', '  execute(...args) {', `    const result = ${callExpr};`, '    if (result instanceof Promise) return result;', '    return result;', '  }', '}');
+    const requestCallExpr = options.hasBindings
+        ? '__fn__(request, this.env)'
+        : '__fn__(request)';
+    lines.push('export default class extends WorkerEntrypoint {', '  execute(...args) {', `    const result = ${callExpr};`, '    if (result instanceof Promise) return result;', '    return result;', '  }', '', '  // Request/Response transport: the ONE dispatch path whose abort is', '  // real. workerd cancels the inner execution context when the request', '  // signal aborts while the fn is suspended on I/O; RPC execute() above', '  // has no equivalent (measured: Symbol.dispose on a pending RPC does', '  // not cancel). The fn is request-shaped — it encodes and decodes its', '  // own payload; nothing generic is serialized here.', '  async fetch(request) {', '    try {', `      const result = await ${requestCallExpr};`, '      if (result instanceof Response) return result;', '      return Response.json(result ?? null);', '    } catch (err) {', '      // Fail loud inside the response so an abort of the transport is', '      // not conflated with a guest exception: the caller sees 500 only', '      // for a real fn failure, and aborts arrive as fetch rejections.', '      const message = err instanceof Error && err.message ? err.message : String(err);', '      return Response.json({ __nimbusFacetError: message }, { status: 500 });', '    }', '  }', '}');
     return lines.join('\n');
 }
 /**
@@ -159,6 +162,8 @@ export class IsolatePool {
      * the old key shape and its warm slots stay shared.
      */
     supervisorKey;
+    /** Extra loader-id segment from options.scope — see IsolatePoolOptions. */
+    scope;
     constructor(env, ctx, opts) {
         // A host hands its whole env over; the binding is claimed here and the
         // claim is checked on the next line.
@@ -180,6 +185,7 @@ export class IsolatePool {
         this.doIdShort = opts?.cacheScope === 'global'
             ? 'global'
             : ctx.id.toString().slice(0, 12);
+        this.scope = opts?.scope ?? '';
         // Materialise the wasm-modules table. Sanitise each name into a
         // valid JS identifier for the static import binding; key collisions
         // (e.g. 'esbuild.wasm' and 'esbuild_wasm' both sanitise to
@@ -430,8 +436,14 @@ export class IsolatePool {
      * warm isolate services the call; callers round-robin slots themselves.
      * Serialized per slot: this call waits for the slot's previous
      * execution to settle before touching the warm isolate.
+     *
+     * `invoke` is the single-attempt call against the slot's entrypoint
+     * stub. `execute` dispatches call `entrypoint.execute(...args)`;
+     * `fetch` dispatches call `entrypoint.fetch(<per-attempt Request>)` —
+     * the attempt index lets a fetch invoke mint a fresh clone for retries,
+     * since a Request's body is consumed once.
      */
-    async #dispatchSlot(fnSource, fnHash, slotIndex, args, resilience, perCallWasm) {
+    async #dispatchSlot(fnSource, fnHash, slotIndex, invoke, resilience, perCallWasm, wasAborted) {
         // A warm slot executes one dispatch at a time: queue behind the
         // previous owner, then record this dispatch as the new tail. The
         // tail outlives the caller's outcome: a timeout rejects the
@@ -448,7 +460,7 @@ export class IsolatePool {
         }
         const inFlight = [];
         try {
-            return await this.#dispatchSlotOwned(fnSource, fnHash, slotIndex, args, resilience, perCallWasm, inFlight);
+            return await this.#dispatchSlotOwned(fnSource, fnHash, slotIndex, invoke, resilience, perCallWasm, inFlight, wasAborted);
         }
         finally {
             // Do not delay the caller's own outcome — the tail releases when
@@ -456,7 +468,7 @@ export class IsolatePool {
             void Promise.allSettled(inFlight).then(() => release());
         }
     }
-    async #dispatchSlotOwned(fnSource, fnHash, slotIndex, args, resilience, perCallWasm, inFlight) {
+    async #dispatchSlotOwned(fnSource, fnHash, slotIndex, invoke, resilience, perCallWasm, inFlight, wasAborted) {
         // Per-call wasm fingerprint. Mixed into the cache key so two calls
         // with different bytes hit different slots (no cache poisoning).
         // For the common case (no per-call wasm) the fingerprint is '0',
@@ -468,7 +480,7 @@ export class IsolatePool {
         // identity so a wake of that same session can never reuse a warm
         // worker whose SUPERVISOR binding still names the dead generation's
         // pid. See the supervisorKey field comment for the failure mode.
-        const buildId = (generation) => `nfp:${this.tag}:${this.doIdShort}:${fnHash}:${this.preambleHash}:${this.wasmHash}:${perCallWasmHash}:${this.supervisorKey}:slot-${slotIndex}:g${generation}`;
+        const buildId = (generation) => `nfp:${this.tag}:${this.doIdShort}:${fnHash}:${this.preambleHash}:${this.wasmHash}:${perCallWasmHash}:${this.supervisorKey}:slot-${slotIndex}:g${generation}${this.scope ? `:${this.scope}` : ''}`;
         let id = buildId(this.slotGenerations.get(slotIndex) ?? 0);
         const code = this.#buildCode(fnSource, perCallWasmEntries);
         // W5 Lever 5: record the dispatch so /api/_diag/memory shows the
@@ -510,8 +522,7 @@ export class IsolatePool {
             // wrapped. See beginLoaderFetch for the measured DO-poisoning hazard.
             const endFetch = beginLoaderFetch(this.ctx);
             try {
-                const out = await entrypoint.execute(...args);
-                return out;
+                return await invoke(entrypoint, attempt);
             }
             catch (err) {
                 if (err instanceof Error) {
@@ -585,6 +596,18 @@ export class IsolatePool {
                     });
                 }
                 catch { /* fail-soft */ }
+                if (wasAborted?.()) {
+                    // The caller aborted this dispatch's Request. workerd cancelled
+                    // the isolate's execution context wherever it was suspended —
+                    // mid-syscall, mid-stream — so the interpreter's heap may hold
+                    // half-applied state. Bump the slot generation: the next
+                    // dispatch lands on a FRESH worker under a new id rather than
+                    // reusing the abandoned one. Retrying is wrong — the user
+                    // interrupted; surface the abort.
+                    const generation = (this.slotGenerations.get(slotIndex) ?? 0) + 1;
+                    this.slotGenerations.set(slotIndex, generation);
+                    throw lastError;
+                }
                 if (cause === 'clone_refused' && !retriedCloneRefusal) {
                     retriedCloneRefusal = true;
                     const generation = (this.slotGenerations.get(slotIndex) ?? 0) + 1;
@@ -628,7 +651,28 @@ export class IsolatePool {
     async submit(fn, arg, opts) {
         const { fnSource, fnHash } = this.#prepare(fn);
         const resilience = this.#resolve(opts);
-        return (await this.#dispatchSlot(fnSource, fnHash, 0, [arg], resilience, opts?.wasmModules));
+        return (await this.#dispatchSlot(fnSource, fnHash, 0, (entrypoint) => entrypoint.execute(arg), resilience, opts?.wasmModules));
+    }
+    /**
+     * Dispatch `fn` through the fetch transport — the pool's only
+     * cancellable path: aborting `request.signal` cancels the inner
+     * execution context at its next I/O suspension (a synchronous CPU
+     * section cannot be preempted — the platform's honest limit), the
+     * call rejects, and the slot generation bumps so the next dispatch
+     * gets a fresh interpreter. `fn` is request-shaped: it encodes and
+     * decodes its own payload.
+     */
+    async submitRequest(fn, request, opts) {
+        if (request.bodyUsed) {
+            throw new BindingError('IsolatePool.submitRequest: request body is already consumed — ' +
+                'pass an unconsumed Request so retries can re-issue it.');
+        }
+        const { fnSource, fnHash } = this.#prepare(fn);
+        const resilience = this.#resolve(opts);
+        // Every attempt fetches a clone: a Request's body is consumed once,
+        // so the caller's original stays unspent and retries get a fresh
+        // body that follows the same signal.
+        return this.#dispatchSlot(fnSource, fnHash, 0, (entrypoint) => entrypoint.fetch(request.clone()), resilience, opts?.wasmModules, () => request.signal.aborted);
     }
     /**
      * Run `fn` on every item in `items`, at most `concurrency` at a time,
@@ -677,7 +721,7 @@ export class IsolatePool {
                 if (idx >= items.length)
                     return;
                 try {
-                    const value = (await this.#dispatchSlot(fnSource, fnHash, slotIndex, [items[idx]], resilience, opts?.wasmModules));
+                    const value = (await this.#dispatchSlot(fnSource, fnHash, slotIndex, (entrypoint) => entrypoint.execute(items[idx]), resilience, opts?.wasmModules));
                     settled[idx] = { ok: true, value };
                 }
                 catch (err) {

package/dist/process-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-host.d.ts","sourceRoot":"","sources":["../src/process-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAKH,OAAO,EAGL,KAAK,WAAW,EAIhB,KAAK,kBAAkB,EAExB,MAAM,qBAAqB,CAAC;AAQ7B,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,CAAC;AAE/C;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,eAAe,EACrB,GAAG,EAAE,kBAAkB,EACvB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,kBAAkB,GAC7B,WAAW,CAIb;AA8ED,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC5B,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC5B,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;CAC7B;AA2BD;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,8BAA8B,CAAC;AACvE,eAAO,MAAM,kCAAkC,yCAAyC,CAAC;AAgSzF;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAWhE"}
+{"version":3,"file":"process-host.d.ts","sourceRoot":"","sources":["../src/process-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAOH,OAAO,EAGL,KAAK,WAAW,EAIhB,KAAK,kBAAkB,EAExB,MAAM,qBAAqB,CAAC;AAQ7B,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,CAAC;AAE/C;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,eAAe,EACrB,GAAG,EAAE,kBAAkB,EACvB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,kBAAkB,GAC7B,WAAW,CAIb;AA8ED,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC5B,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC5B,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;CAC7B;AAaD;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,8BAA8B,CAAC;AACvE,eAAO,MAAM,kCAAkC,yCAAyC,CAAC;AAgUzF;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAWhE"}

package/dist/process-host.js

@@ -66,6 +66,8 @@
 import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
 import { isTransientDoReset } from '@nimbus-sh/platform/oom-classify.js';
 import { PEER_RETRY_BACKOFF_MS, PEER_TRANSIENT_RESET_RETRIES } from './fanout.js';
+import { hostNamespaceBinding, hostOpDispatch } from './host-dispatch.js';
+import { z } from 'zod/v4';
 import { DYNAMIC_WORKER_CODE_LIMIT_BYTES } from './budgets.js';
 import { BindingError } from './vendor/errors.js';
 import { processes, } from './workerd-facet-host.js';
@@ -149,19 +151,6 @@ export function isolateToken() {
         _isolateToken = crypto.randomUUID();
     return _isolateToken;
 }
-/**
- * Every method a hosting sibling must answer. Checked as a set at first
- * contact: a stub that has the probe but not the router is a deployment skew,
- * and finding that out mid-process is finding it out too late.
- */
-const PROCESS_PEER_METHODS = [
-    '_rpcProcessHostProbe',
-    '_rpcHostProcess',
-    '_rpcAwaitHostedOpen',
-    '_rpcAwaitHostedBoot',
-    '_rpcRouteHostedHttp',
-    '_rpcCancelHostProcess',
-];
 /**
  * Which hosted process a fetched upgrade is for. An upgrade cannot travel as
  * RPC arguments, so the two values `_rpcRouteHostedHttp` would have taken ride
@@ -174,31 +163,66 @@ const PROCESS_PEER_METHODS = [
  */
 export const HOSTED_WEBSOCKET_KEY_HEADER = 'x-nimbus-hosted-websocket';
 export const HOSTED_WEBSOCKET_CAPABILITY_HEADER = 'x-nimbus-hosted-websocket-capability';
+/**
+ * Peer stubs forward one supervisorOp entrypoint: every method the host-
+ * process surface needs is an envelope op, not a private _rpc* method.
+ */
 function peerNamespace(env) {
-    const ns = (typeof env === 'object' || typeof env === 'function') && env !== null
-        ? Reflect.get(env, 'NIMBUS_SESSION')
-        : undefined;
-    if ((typeof ns !== 'object' && typeof ns !== 'function') || ns === null
-        || typeof Reflect.get(ns, 'idFromName') !== 'function'
-        || typeof Reflect.get(ns, 'get') !== 'function') {
-        throw new BindingError('ProcessFabric: env.NIMBUS_SESSION binding missing or invalid. '
-            + "NIMBUS_PROCESS_HOST='peer' hosts every resident process on a sibling "
-            + 'Durable Object; add the binding via durable_objects.bindings in wrangler.jsonc.');
+    try {
+        return hostNamespaceBinding(env, 'ProcessFabric');
+    }
+    catch (e) {
+        if (e instanceof BindingError) {
+            throw new BindingError(e.message
+                + " NIMBUS_PROCESS_HOST='peer' hosts every resident process on a sibling "
+                + "Durable Object; name the host's own binding with composeFabric({ hostNamespace }).");
+        }
+        throw e;
     }
-    return ns;
 }
+const PeerProbeResult = z.object({ isolateToken: z.string() });
+const PeerOpenResult = z.object({ ok: z.boolean() });
+const PeerBootResult = z.object({ payload: z.unknown() });
+const PeerCancelResult = z.object({ cancelled: z.boolean() });
+const PeerHttpResult = z.object({
+    status: z.number().int(),
+    statusText: z.string(),
+    headers: z.array(z.tuple([z.string(), z.string()])),
+    body: z.instanceof(ReadableStream).nullable(),
+});
 function processPeerStub(value, peerName) {
-    if ((typeof value !== 'object' && typeof value !== 'function') || value === null) {
-        throw new BindingError(`ProcessFabric: NIMBUS_SESSION.get() returned no stub for peer '${peerName}'.`);
+    const dispatch = hostOpDispatch(value, `ProcessFabric peer '${peerName}'`);
+    const fetchFn = (typeof value === 'object' || typeof value === 'function') && value !== null
+        ? Reflect.get(value, 'fetch')
+        : undefined;
+    if (typeof fetchFn !== 'function') {
+        throw new BindingError(`ProcessFabric: peer '${peerName}' exposes no fetch() — the hosted-websocket `
+            + 'upgrade leg still travels as a service-binding fetch.');
     }
-    for (const method of PROCESS_PEER_METHODS) {
-        if (typeof Reflect.get(value, method) !== 'function') {
-            throw new BindingError(`ProcessFabric: peer '${peerName}' does not expose ${method}(). `
-                + 'A sibling that answers some of the host-process surface and not the rest '
-                + 'would fail somewhere inside a running process instead of here.');
-        }
+    const adapter = {
+        _rpcProcessHostProbe: async () => PeerProbeResult.parse(await dispatch({ op: 'processHostProbe', args: [] })),
+        _rpcHostProcess: async (boot, opts) => PeerOpenResult.parse(await dispatch({ op: 'hostProcess', args: [boot, opts] })),
+        _rpcAwaitHostedOpen: async (key) => PeerOpenResult.parse(await dispatch({ op: 'awaitHostedOpen', args: [key] })),
+        _rpcAwaitHostedBoot: async (key) => {
+            const result = PeerBootResult.parse(await dispatch({ op: 'awaitHostedBoot', args: [key] }));
+            return { payload: result.payload };
+        },
+        _rpcRouteHostedHttp: async (key, request) => PeerHttpResult.parse(await dispatch({ op: 'routeHostedHttp', args: [key, request] })),
+        _rpcCancelHostProcess: async (key) => PeerCancelResult.parse(await dispatch({ op: 'cancelHostProcess', args: [key] })),
+        fetch: async (request) => {
+            const response = await Reflect.apply(fetchFn, value, [request]);
+            if (!(response instanceof Response))
+                throw new BindingError(`ProcessFabric: peer '${peerName}' returned no Response`);
+            return response;
+        },
+    };
+    // The adapter wraps the raw stub; releasing the adapter must release it —
+    // a held RPC stub pins the peer DO for the session's life.
+    const disposerKey = Reflect.get(Symbol, 'dispose');
+    if (typeof disposerKey === 'symbol') {
+        Object.defineProperty(adapter, disposerKey, { value: () => disposeRpcResource(value) });
     }
-    return value;
+    return adapter;
 }
 class PeerProcessHost {
     ctx;
@@ -219,6 +243,9 @@ class PeerProcessHost {
     tokensInUse = new Map();
     constructor(ctx, env) {
         this.ctx = ctx;
+        if (env === null || (typeof env !== 'object' && typeof env !== 'function')) {
+            throw new BindingError('ProcessFabric: a peer host requires environment bindings');
+        }
         this.ns = peerNamespace(env);
         this.env = (env ?? {});
         this.coordDoId = ctx.id.toString();
@@ -339,7 +366,7 @@ class PeerProcessHost {
     /** One sibling name, resolved and probed. Leaks nothing on failure. */
     async _probePlacement(pid, attempt) {
         const peerName = `${this.coordDoId}:proc:${pid}:${attempt}`;
-        let resource;
+        let resource = null;
         try {
             resource = this.ns.get(this.ns.idFromName(peerName));
             const stub = processPeerStub(resource, peerName);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-sh/fabric",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The Cloudflare half of Nimbus — Durable Object facet hosting, dynamic-worker loader pools, the resident-process fabric, and DO alarm/hibernation machinery.",
   "keywords": [
     "cloudflare",
@@ -46,11 +46,11 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json --noCheck --noEmit false --declaration true --declarationMap true --outDir dist --rootDir src",
-    "prepack": "npm run build",
+    "prepack": "bun run build",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@nimbus-sh/core": "^0.9.0",
+    "@nimbus-sh/core": "^0.10.0",
     "@nimbus-sh/platform": "^0.4.0",
     "zod": "^4.4.3"
   },

package/src/bindings.ts

@@ -26,8 +26,9 @@
 import { WorkerEntrypoint } from 'cloudflare:workers';
 import { z } from 'zod/v4';
 import { disposeRpcResource, useRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
-import { supervisorEntrypoint, supervisorEntrypointName } from './composition.js';
+import { hostNamespace, supervisorEntrypoint, supervisorEntrypointName } from './composition.js';
 import { stagedBootAssembler } from './composition.js';
+import { hostNamespaceBinding, hostOpDispatch, type HostOpDispatch } from './host-dispatch.js';
 import { assertModuleMapWithinCodeLimit } from './budgets.js';
 import type { EntrypointLoopbackFactory } from './composition.js';
 import type { WorkerCode } from './vendor/types.js';
@@ -44,17 +45,6 @@ interface ShimCtxExports {
   NimbusDOStub?: EntrypointLoopbackFactory;
 }
 
-/**
- * The supervisor DO namespace a shim resolves ONE stub from, by the id its
- * props carry. `Stub` is that DO's RPC surface as the calling shim uses it —
- * the supervisor class belongs to the embedder, so each shim names the methods
- * it calls rather than the class.
- */
-interface SupervisorNamespace<Stub> {
-  idFromString(id: string): DurableObjectId;
-  get(id: DurableObjectId): Stub;
-}
-
 /**
  * A dynamic worker's entrypoint, as hop 3 relays to it. `fetch` is the
  * entrypoint contract every loaded worker answers; `handleHttpRequest` is the
@@ -116,34 +106,6 @@ function shimCtxExports(ctx: unknown): ShimCtxExports {
   return exports as ShimCtxExports;
 }
 
-// ── Inner-Worker loopback bindings ────────────────────────────────────
-//
-// These WorkerEntrypoint classes are top-level exports so that ctx.exports
-// auto-populates Service Bindings for them (enable_ctx_exports compat
-// flag is already enabled via default compatibility_date 2026-04-01).
-//
-// They are re-exported from src/index.ts so wrangler detects them as
-// reachable from the entry file and bundles their classes.
-//
-// Usage pattern (in nimbus-wrangler.ts):
-//   ctx.exports.NimbusAssetsRPC({ props: { vfsRoot, assetsDir } })
-// produces a Service Binding stub that can be placed in the inner
-// Worker's `env` under whatever binding name the user declared in
-// wrangler.jsonc's `assets.binding` (typically "ASSETS").
-
-/**
- * What the assets shim reads off the supervisor DO: the VFS bytes of one path,
- * or null when it holds no such file.
- */
-interface AssetsSupervisorStub {
-  _rpcReadFileBytes(path: string): Promise<ArrayBuffer | Uint8Array | null>;
-}
-
-/** `env` for the assets shim: the supervisor its VFS reads round-trip through. */
-interface NimbusAssetsEnv {
-  NIMBUS_SESSION?: SupervisorNamespace<AssetsSupervisorStub>;
-}
-
 /** Props the assets shim is minted with. */
 interface NimbusAssetsProps {
   /** Project root in VFS (e.g. "home/user/myapp"). */
@@ -175,7 +137,7 @@ interface NimbusAssetsProps {
  * For Phase 1, we use a simpler approach: the props carry a supervisor
  * DO id so we can round-trip through an RPC method that reads the file.
  */
-export class NimbusAssetsRPC extends WorkerEntrypoint<NimbusAssetsEnv, NimbusAssetsProps> {
+export class NimbusAssetsRPC extends WorkerEntrypoint<object, NimbusAssetsProps> {
   /**
    * Fetch a static asset. Called by the inner Worker as
    * `env.ASSETS.fetch(request)`. The request URL's pathname is used to
@@ -193,12 +155,22 @@ export class NimbusAssetsRPC extends WorkerEntrypoint<NimbusAssetsEnv, NimbusAss
     const parts = clean.split('/').filter((p) => p && p !== '..' && p !== '.');
     clean = parts.join('/');
 
-    // Resolve the supervisor DO stub so we can call its VFS read RPC.
-    const ns = this.env.NIMBUS_SESSION;
-    if (!ns || !doId) {
-      return new Response('ASSETS binding not wired: missing NIMBUS_SESSION or doId', { status: 500 });
+    // Resolve the supervisor DO through the composed host namespace and
+    // dispatch readFileBytes through its supervisorOp entrypoint — a host
+    // forwards envelopes, not private _rpc* methods.
+    if (!doId) {
+      return new Response('ASSETS binding not wired: missing doId', { status: 500 });
+    }
+    let stub: DurableObjectStub | null = null;
+    let dispatch: HostOpDispatch;
+    try {
+      const ns = hostNamespaceBinding(this.env, 'NimbusAssetsRPC');
+      stub = ns.get(ns.idFromString(doId));
+      dispatch = hostOpDispatch(stub, 'NimbusAssetsRPC');
+    } catch (e) {
+      disposeRpcResource(stub);
+      return new Response(`ASSETS binding not wired: ${e instanceof Error ? e.message : String(e)}`, { status: 500 });
     }
-    const stub = ns.get(ns.idFromString(doId));
 
     // Candidate VFS paths, tried in order. The assetsDir is relative to
     // the project root in VFS. Trailing-slash and bare dir → index.html.
@@ -219,10 +191,14 @@ export class NimbusAssetsRPC extends WorkerEntrypoint<NimbusAssetsEnv, NimbusAss
       for (const candidate of candidates) {
         try {
           const response = await useRpcResource(
-            stub._rpcReadFileBytes(candidate),
-            (bytes: ArrayBuffer | Uint8Array | null) => {
-              if (!bytes || bytes.byteLength === undefined) return null;
-              return new Response(bytes, {
+            dispatch({ op: 'readFileBytes', args: [candidate] }),
+            (bytes) => {
+              if (bytes === null) return null;
+              const body = bytes instanceof ArrayBuffer ? bytes
+                : bytes instanceof Uint8Array && bytes.buffer instanceof ArrayBuffer
+                  ? new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength) : null;
+              if (!body) return new Response('Nimbus: readFileBytes returned invalid bytes', { status: 502 });
+              return new Response(body, {
                 status: 200,
                 headers: {
                   'Content-Type': mimeTypeForPath(candidate),
@@ -785,31 +761,6 @@ export class NimbusDurableObjectNamespace extends WorkerEntrypoint<unknown, Nimb
   }
 }
 
-/**
- * What the DO shim reads off the supervisor: one inner-DO request, answered
- * from the facet the supervisor resolves in its own request context.
- */
-interface InnerDoSupervisorStub {
-  _rpcInnerDoFetch(request: {
-    bindingName: string;
-    id: string;
-    method: string;
-    url: string;
-    headers: [string, string][];
-    body: ArrayBuffer | null;
-  }): Promise<{
-    body: ArrayBuffer;
-    status: number;
-    statusText: string;
-    headers: [string, string][];
-  }>;
-}
-
-/** `env` for the DO shim: the supervisor that owns the facet. */
-interface NimbusInnerDoEnv {
-  NIMBUS_SESSION?: SupervisorNamespace<InnerDoSupervisorStub>;
-}
-
 /** Props the DO stub carries: which binding, which supervisor, which id. */
 interface NimbusDoStubProps extends NimbusDoNamespaceProps {
   id?: string;
@@ -823,21 +774,28 @@ interface NimbusDoStubProps extends NimbusDoNamespaceProps {
  * 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<NimbusInnerDoEnv, NimbusDoStubProps> {
+export class NimbusDOStub extends WorkerEntrypoint<object, NimbusDoStubProps> {
   /**
-   * Resolve the supervisor DO from env.NIMBUS_SESSION and route through
-   * its _rpcInnerDoFetch RPC method, which runs ctx.facets.get(...) in
-   * its own context and forwards the request.
+   * 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: Request): Promise<Response> {
     const props: NimbusDoStubProps = this.ctx.props || {};
-    const ns = this.env?.NIMBUS_SESSION;
-    if (!ns) return new Response('Nimbus: env.NIMBUS_SESSION unavailable', { status: 500 });
     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 || '');
-    const stub = ns.get(ns.idFromString(supervisorDoId));
+    let stub: DurableObjectStub | null = null;
+    let dispatch: HostOpDispatch;
+    try {
+      const ns = hostNamespaceBinding(this.env ?? {}, 'NimbusDOStub');
+      stub = ns.get(ns.idFromString(supervisorDoId));
+      dispatch = hostOpDispatch(stub, 'NimbusDOStub');
+    } 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
@@ -849,20 +807,27 @@ export class NimbusDOStub extends WorkerEntrypoint<NimbusInnerDoEnv, NimbusDoStu
     request.headers.forEach((v, k) => { headerList.push([k, v]); });
     try {
       return await useRpcResource(
-        stub._rpcInnerDoFetch({
-          bindingName,
-          id,
-          method: request.method,
-          url: request.url,
-          headers: headerList,
-          body,
+        dispatch({
+          op: 'innerDoFetch',
+          args: [{
+            bindingName,
+            id,
+            method: request.method,
+            url: request.url,
+            headers: headerList,
+            body,
+          }],
         }),
-        (res) =>
-          new Response(res.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);