@nimbus-sh/fabric 0.4.0 → 0.6.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/generation.ts

@@ -14,6 +14,12 @@
  * counter, and bumps it once. The embedder reads `generation(ctx)` wherever it
  * needs the incarnation number — one source of truth instead of mirrored host
  * fields.
+ *
+ * This is also the allocator for a workspace's generation: an embedder
+ * composing NimbusWorkspace over its own Durable Object calls
+ * `adoptGeneration(ctx)` once per incarnation and passes `generation(ctx)`
+ * as the workspace's `generation` — the same persisted counter the session
+ * derives its pid generation from, so there is no second counter to keep.
  */
 
 import { errorText } from '@nimbus-sh/core/_shared/error-text.js';

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/image-store.ts

@@ -107,36 +107,48 @@ export class ImageStore {
    * Materialize generated module sources in the content-addressed image store
    * and return the module-name → path map naming them.
    *
+   * Takes the images as a SEQUENCE, produced on demand and released as each
+   * one's slices land, so exactly one image's text is resident here. The old
+   * record-shaped parameter held every source for the whole call, and the
+   * caller held its own copy beside it: measured on a real-vite launch, the
+   * second image reported not one slice — ~25 MB of module text as UTF-16 in
+   * two places, plus the first image's just-freed 10.36 MB encode buffer, on a
+   * 128 MiB isolate. Yielding and dropping is what makes the peak one image
+   * instead of all of them; it is not a pacing question, and a fresh turn does
+   * not shrink a live heap.
+   *
    * Writing the sources here, once, is what lets the session stop holding
    * them: after this returns, the only thing it keeps is a path.
    */
   async materialize(
     pid: number,
-    modules: Record<string, string>,
+    images: AsyncIterable<readonly [string, string]> | Iterable<readonly [string, string]>,
     pacer: TurnBudget,
   ): Promise<Record<string, string>> {
     const fs = this.blobs();
-    const images: Record<string, string> = {};
-    const sources = new Map<string, string>();
-    for (const [moduleName, source] of Object.entries(modules)) {
-      const path = facetImagePath(await facetImageDigest(source));
-      images[moduleName] = path;
-      sources.set(path, source);
-      await pacer.spend(source.length);
-    }
-    // Register the WHOLE root set here, in one synchronous step, before any
-    // byte of it exists on disk. That ordering is the entire protocol between
-    // a launch and the sweep: an image is rooted from before it is written, so
-    // a sweep can never observe a file this launch has written but not yet
-    // claimed. The old loop achieved it by not awaiting at all, which read as
-    // "the writes must not be interrupted" — they may be. What must not be
-    // interrupted is the gap between writing and rooting, and rooting first
-    // closes it for every write that follows, however many turns they span.
-    this.residentImages.set(pid, [...sources.keys()]);
+    const paths: Record<string, string> = {};
+    // The root set is this ARRAY, held by the sweep's map from before the
+    // first byte and appended to as each image is named. Rooting an image
+    // before its own first byte is the whole of the protocol: a sweep that
+    // runs while this launch is suspended sees every image already written as
+    // rooted, and an image not yet written is not yet a file. The array
+    // identity is what makes an append visible — do not replace it.
+    const rooted: string[] = [];
+    this.residentImages.set(pid, rooted);
     fs.mkdirp(FACET_IMAGE_DIR);
-    for (const [path, source] of sources) {
+    let count = 0;
+    for await (const [moduleName, source] of images) {
+      const path = facetImagePath(await facetImageDigest(source));
+      paths[moduleName] = path;
+      rooted.push(path);
+      count++;
       const stored = path.replace(/^\/+/, '');
       const bytes = new TextEncoder().encode(source);
+      console.log(
+        '[image-store] pid=' + pid + ' image ' + count + ' ' + moduleName + ' → '
+        + path.slice(-12) + ' ' + bytes.byteLength + ' bytes, slice=' + FACET_IMAGE_WRITE_SLICE_BYTES
+        + ' turns=' + pacer.chunks,
+      );
       // An image at its full size is a COMPLETE one: a write only ever grows
       // the file from offset zero, so a write cut short by a reset leaves a
       // strictly shorter file and fails this test. Size is enough of a check
@@ -163,7 +175,8 @@ export class ImageStore {
       } while (offset < bytes.byteLength);
     }
     this.sweep(fs);
-    return images;
+    console.log('[image-store] pid=' + pid + ' materialized ' + count + ' image(s) in ' + pacer.chunks + ' turn(s)');
+    return paths;
   }
 
   /**