@nimbus-sh/fabric 0.5.0 → 0.7.0

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);

package/src/fanout.ts

@@ -20,20 +20,18 @@ import { IsolatePool, type FacetTaskFn } from './isolate-pool.js';
 import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
 import { describeError, isDoOverloaded, isTransientDoReset } from '@nimbus-sh/platform/oom-classify.js';
 import type { WorkerLoader } from './vendor/types.js';
+import {
+  hostNamespaceBinding,
+  hostOpDispatch,
+  type HostOpDispatch,
+} from './host-dispatch.js';
 
-/**
- * The sibling-session namespace the peer-DO topology routes through. Ids are
- * derived from a name so a task key always lands on the same peer.
- */
-interface PeerSessionNamespace {
-  idFromName(name: string): DurableObjectId;
-  get(id: DurableObjectId): unknown;
-}
-
-/** The bindings a fan-out needs off the coordinator DO's env. */
+/** The bindings a fan-out needs off the coordinator DO's env. The host
+ *  namespace key is the composed one — whatever this host named its own
+ *  binding (default NIMBUS_SESSION); peers dispatch supervisorOp envelopes. */
 export interface FanoutEnv {
   LOADER?: WorkerLoader;
-  NIMBUS_SESSION?: PeerSessionNamespace;
+  NIMBUS_SESSION?: unknown;
 }
 
 /**
@@ -168,30 +166,13 @@ export interface FanoutOptions {
   maxPeers?: number;
 }
 
-interface FanoutPeerStub {
-  _rpcFanoutExecute<R>(
-    fnSource: string,
-    args: unknown[],
-    poolOpts?: Record<string, unknown>,
-  ): Promise<{ results?: R[] }>;
+interface FanoutPeerResult<R> {
+  results: R[];
 }
 
-function isFanoutPeerStub(value: unknown): value is FanoutPeerStub {
-  if ((typeof value !== 'object' && typeof value !== 'function') || value === null) {
-    return false;
-  }
-  const execute = Reflect.get(value, '_rpcFanoutExecute');
-  return typeof execute === 'function';
-}
-
-function fanoutPeerStub(value: unknown): FanoutPeerStub {
-  if ((typeof value !== 'object' && typeof value !== 'function') || value === null) {
-    throw new BindingError('Fanout: NIMBUS_SESSION.get() did not return a peer stub.');
-  }
-  if (!isFanoutPeerStub(value)) {
-    throw new BindingError('Fanout: peer stub does not expose _rpcFanoutExecute().');
-  }
-  return value;
+// Task values retain the submitted function's type; validate the wire envelope.
+function isPeerResult<R>(value: Awaited<ReturnType<HostOpDispatch>>): value is FanoutPeerResult<R> {
+  return value !== null && typeof value === 'object' && 'results' in value && Array.isArray(value.results);
 }
 
 /**
@@ -323,14 +304,10 @@ export class Fanout {
     tasks: FanoutTask<A>[],
     fn: FacetTaskFn<A, R>,
   ): Promise<R[]> {
-    const ns = this.env?.NIMBUS_SESSION;
-    if (!ns || typeof ns.idFromName !== 'function' || typeof ns.get !== 'function') {
-      throw new BindingError(
-        'Fanout: env.NIMBUS_SESSION binding missing or invalid. ' +
-          'The peer-DO topology requires it. ' +
-          'Add the binding via durable_objects.bindings in wrangler.jsonc.',
-      );
-    }
+    // The peer-DO topology routes through the composed host namespace —
+    // a workspace host names its own binding, and its stub forwards one
+    // supervisorOp entrypoint, not private _rpc* methods.
+    const ns = hostNamespaceBinding(this.env ?? {}, 'Fanout');
 
     // Serialize the user function ONCE here on the supervisor side.
     // Each peer DO receives the same fnSource string; warm peer
@@ -380,38 +357,42 @@ export class Fanout {
           // stub points at a torn-down object, so a retry re-resolves the
           // sibling by its stable id.
           const peerStub = ns.get(id);
-          const stub = fanoutPeerStub(peerStub);
           try {
+            const dispatch = hostOpDispatch(peerStub, `Fanout peer ${siblingName}`);
             // Each peer DO RPC call uses ONE LOADER worker on its side.
             // Supervisor → peer DO is a stub.fetch / RPC method call,
             // NOT an env.LOADER.get(); that's the cap-sidestep that
             // makes peer-DO fanout work.
-            const rpcResp = await stub._rpcFanoutExecute<R>(
-              fnSource,
-              peerArgs,
-              {
-                tag: this.opts.tag,
-                timeoutMs: this.opts.timeoutMs,
-                preamble: this.opts.preamble,
-                wasmModules: this.opts.wasmModules,
-                extraBindings: this.opts.extraBindings,
-                omitSupervisor: this.opts.omitSupervisor,
-                // INSTALL-HONESTY: forward the COORDINATOR's full doId so
-                // the peer's IsolatePool can mint a SUPERVISOR
-                // binding that routes back HERE (the user's session DO),
-                // not to the peer DO itself. Without this, peer DOs'
-                // env.SUPERVISOR.writeBatch / writeBatchStream / stdout /
-                // ... write into the peer's own VFS — invisible to the
-                // user. See INSTALL-HONESTY-retro.md.
-                coordinatorDoId: this.coordDoId,
-                // Credential source for peer-side writeBatchStream — the
-                // invoking process pid, so package writes are authorized
-                // as the user (not rejected as pid:0).
-                supervisorPid: this.opts.supervisorPid,
-              },
-            );
+            const rpcResp = await dispatch({
+              op: 'fanoutExecute',
+              args: [
+                fnSource,
+                peerArgs,
+                {
+                  tag: this.opts.tag,
+                  timeoutMs: this.opts.timeoutMs,
+                  preamble: this.opts.preamble,
+                  wasmModules: this.opts.wasmModules,
+                  extraBindings: this.opts.extraBindings,
+                  omitSupervisor: this.opts.omitSupervisor,
+                  // INSTALL-HONESTY: forward the COORDINATOR's full doId so
+                  // the peer's IsolatePool can mint a SUPERVISOR
+                  // binding that routes back HERE (the user's session DO),
+                  // not to the peer DO itself. Without this, peer DOs'
+                  // env.SUPERVISOR.writeBatch / writeBatchStream / stdout /
+                  // ... write into the peer's own VFS — invisible to the
+                  // user. See INSTALL-HONESTY-retro.md.
+                  coordinatorDoId: this.coordDoId,
+                  // Credential source for peer-side writeBatchStream — the
+                  // invoking process pid, so package writes are authorized
+                  // as the user (not rejected as pid:0).
+                  supervisorPid: this.opts.supervisorPid,
+                },
+              ],
+            });
             try {
-              const peerResults = rpcResp.results ?? [];
+              if (!isPeerResult<R>(rpcResp)) throw new BindingError(`Fanout peer '${siblingName}' returned no result array`);
+              const peerResults = rpcResp.results;
               if (peerResults.length !== bucket.length) {
                 throw new Error(
                   `peer DO returned ${peerResults.length} results for ${bucket.length} tasks ` +

package/src/host-dispatch.ts

@@ -0,0 +1,34 @@
+import { BindingError } from './vendor/errors.js';
+import { hostDispatchMethod, hostNamespace } from './composition.js';
+import type { createSupervisorOpHandler } from '@nimbus-sh/core/workspace/supervisor-op.js';
+
+export type HostNamespaceBinding = Pick<DurableObjectNamespace, 'get' | 'idFromName' | 'idFromString'>;
+export type HostOpDispatch = ReturnType<typeof createSupervisorOpHandler>;
+
+function isNamespace(value: object): value is HostNamespaceBinding {
+  return typeof Reflect.get(value, 'idFromName') === 'function'
+    && typeof Reflect.get(value, 'idFromString') === 'function'
+    && typeof Reflect.get(value, 'get') === 'function';
+}
+
+export function hostNamespaceBinding(env: object | null | undefined, usage: string): HostNamespaceBinding {
+  const name = hostNamespace();
+  const binding = env ? Reflect.get(env, name) : undefined;
+  if (binding === null || (typeof binding !== 'object' && typeof binding !== 'function') || !isNamespace(binding)) {
+    throw new BindingError(`${usage}: env.${name} must be the Durable Object namespace configured by composeFabric`);
+  }
+  return binding;
+}
+
+export function hostOpDispatch(stub: object, usage: string): HostOpDispatch {
+  const name = hostDispatchMethod();
+  if (stub === null || (typeof stub !== 'object' && typeof stub !== 'function')) {
+    throw new BindingError(`${usage}: the workspace namespace returned no stub`);
+  }
+  const dispatch = Reflect.get(stub, name);
+  if (typeof dispatch !== 'function') {
+    throw new BindingError(`${usage}: the workspace host must forward ${name}(envelope) to the runtime`);
+  }
+  // RpcStub.call would invoke a remote method named "call".
+  return (envelope) => Promise.resolve(Reflect.apply(dispatch, stub, [envelope]));
+}

package/src/isolate-pool.ts

@@ -93,6 +93,15 @@ export interface IsolatePoolOptions {
    * not receive a Supervisor binding and do not retain user state.
    */
   cacheScope?: 'session' | 'global';
+  /**
+   * Baked into the loader id. Two pools sharing tag, preamble, wasm and
+   * supervisor but differing in `scope` never reuse each other's warm
+   * workers: an interpreter scope that ENDS (REPL close, Ctrl-C reset)
+   * must not resurrect the loader-cached heap for the next owner.
+   * Default '' preserves the existing id bytes — only scoped pools get
+   * the extra segment.
+   */
+  scope?: string;
   /**
    * Override the `doId` baked into the auto-injected SUPERVISOR binding.
    * Default: `ctx.id.toString()` (the DO that constructs the pool).
@@ -308,6 +317,9 @@ export function assembleLoaderWorkerModuleSource(
   const callExpr = options.hasBindings
     ? '__fn__(...args, this.env)'
     : '__fn__(...args)';
+  const requestCallExpr = options.hasBindings
+    ? '__fn__(request, this.env)'
+    : '__fn__(request)';
   lines.push(
     'export default class extends WorkerEntrypoint {',
     '  execute(...args) {',
@@ -315,6 +327,26 @@ export function assembleLoaderWorkerModuleSource(
     '    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');
@@ -400,6 +432,8 @@ export class IsolatePool {
    */
   private readonly supervisorKey: string;
 
+  /** Extra loader-id segment from options.scope — see IsolatePoolOptions. */
+  private readonly scope: string;
   constructor(
     env: unknown,
     ctx: DurableObjectState,
@@ -427,6 +461,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
@@ -701,15 +736,22 @@ 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(
+  async #dispatchSlot<T>(
     fnSource: string,
     fnHash: string,
     slotIndex: number,
-    args: unknown[],
+    invoke: (entrypoint: { execute(...args: unknown[]): Promise<unknown>; fetch(input: RequestInfo, init?: RequestInit): Promise<Response> }, attempt: number) => Promise<T>,
     resilience: ResolvedResilience,
     perCallWasm?: Record<string, ArrayBuffer>,
-  ): Promise<unknown> {
+    wasAborted?: () => boolean,
+  ): Promise<T> {
     // 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
@@ -726,7 +768,7 @@ export class IsolatePool {
     }
     const inFlight: Promise<unknown>[] = [];
     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
       // the RPCs the body launched have actually settled.
@@ -734,15 +776,17 @@ export class IsolatePool {
     }
   }
 
-  async #dispatchSlotOwned(
+
+  async #dispatchSlotOwned<T>(
     fnSource: string,
     fnHash: string,
     slotIndex: number,
-    args: unknown[],
+    invoke: (entrypoint: { execute(...args: unknown[]): Promise<unknown>; fetch(input: RequestInfo, init?: RequestInit): Promise<Response> }, attempt: number) => Promise<T>,
     resilience: ResolvedResilience,
     perCallWasm: Record<string, ArrayBuffer> | undefined,
     inFlight: Promise<unknown>[],
-  ): Promise<unknown> {
+    wasAborted?: () => boolean,
+  ): Promise<T> {
     // 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',
@@ -756,7 +800,7 @@ export class IsolatePool {
     // worker whose SUPERVISOR binding still names the dead generation's
     // pid. See the supervisorKey field comment for the failure mode.
     const buildId = (generation: number): string =>
-      `nfp:${this.tag}:${this.doIdShort}:${fnHash}:${this.preambleHash}:${this.wasmHash}:${perCallWasmHash}:${this.supervisorKey}:slot-${slotIndex}:g${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);
 
@@ -765,7 +809,7 @@ export class IsolatePool {
     // slot updated on every dispatch.
     try { setLastFacetId(id, slotIndex); } catch { /* best-effort */ }
 
-    const runOnce = async (): Promise<unknown> => {
+    const runOnce = async (): Promise<T> => {
       // loader.get() is synchronous from the caller's POV; the callback
       // is only invoked on cache miss. We wrap the callback tightly so a
       // retry doesn't rebuild workerCode — that's already stable here.
@@ -797,8 +841,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) {
           throw new ExecutionError(err.message, err.stack);
@@ -870,6 +913,18 @@ export class IsolatePool {
             message: lastError.message,
           });
         } 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;
@@ -920,12 +975,49 @@ export class IsolatePool {
       fnSource,
       fnHash,
       0,
-      [arg],
+      (entrypoint) => entrypoint.execute(arg) as Promise<Awaited<R>>,
+      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: Request, env: FacetBindings) => Response | Promise<Response>,
+    request: Request,
+    opts?: IsolateCallOptions,
+  ): Promise<Response> {
+    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,
-    )) as Awaited<R>;
+      () => request.signal.aborted,
+    );
   }
 
+
   /**
    * Run `fn` on every item in `items`, at most `concurrency` at a time,
    * pinned to stable slots so warm isolates are reused.
@@ -998,7 +1090,7 @@ export class IsolatePool {
             fnSource,
             fnHash,
             slotIndex,
-            [items[idx]],
+            (entrypoint) => entrypoint.execute(items[idx]),
             resilience,
             opts?.wasmModules,
           )) as Awaited<R>;