@nimbus-sh/fabric 0.7.0 → 0.8.0

package/src/facet-pool.ts

@@ -42,6 +42,8 @@
  * and the facet-id ledger here counts only the names this pool minted.
  */
 
+import { forgetFacetStorage } from '@nimbus-sh/core/runtime/storage-ledger.js';
+import type { SqlDatabase } from '@nimbus-sh/core/runtime/os-contracts.js';
 import {
   FACET_ID_LIFETIME_BUDGET,
   facetNameCount,
@@ -63,6 +65,8 @@ export interface FacetPoolContext {
   storage: {
     get(key: string): Promise<unknown> | unknown;
     put(key: string, value: unknown): Promise<void>;
+    /** The session's SQL, where the storage ledger (N18) records facet databases. */
+    sql?: SqlDatabase;
   };
 }
 
@@ -134,6 +138,7 @@ export class FacetPool {
       if (keepStorage) return;
       try {
         facets.delete(name);
+        if (this.ctx.storage.sql) forgetFacetStorage(this.ctx.storage.sql, name);
       } catch (e) {
         throw new Error(
           `fabric: facet '${name}' was evicted but its storage was not reclaimed — `

package/src/fanout.ts

@@ -17,8 +17,9 @@
 import { serializeFunction } from './vendor/serialize.js';
 import { BindingError } from './vendor/errors.js';
 import { IsolatePool, type FacetTaskFn } from './isolate-pool.js';
+import { hostRoute } from './composition.js';
 import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
-import { describeError, isDoOverloaded, isTransientDoReset } from '@nimbus-sh/platform/oom-classify.js';
+import { classifyDoCall, describeError, isRetryableDoCall } from '@nimbus-sh/platform/oom-classify.js';
 import type { WorkerLoader } from './vendor/types.js';
 import {
   hostNamespaceBinding,
@@ -383,6 +384,7 @@ export class Fanout {
                   // ... write into the peer's own VFS — invisible to the
                   // user. See INSTALL-HONESTY-retro.md.
                   coordinatorDoId: this.coordDoId,
+                  coordinatorRoute: hostRoute() ?? undefined,
                   // Credential source for peer-side writeBatchStream — the
                   // invoking process pid, so package writes are authorized
                   // as the user (not rejected as pid:0).
@@ -412,8 +414,9 @@ export class Fanout {
             }
             return;
           } catch (err) {
-            const schedule = isTransientDoReset(err) ? PEER_RETRY_BACKOFF_MS
-              : isDoOverloaded(err) ? PEER_OVERLOAD_BACKOFF_MS
+            const cls = classifyDoCall(err);
+            const schedule = cls === 'overloaded' ? PEER_OVERLOAD_BACKOFF_MS
+              : isRetryableDoCall(cls) ? PEER_RETRY_BACKOFF_MS
               : null;
             if (schedule && attempt < PEER_TRANSIENT_RESET_RETRIES) {
               const backoff = schedule[Math.min(attempt, schedule.length - 1)];

package/src/fenced-work.ts

@@ -56,9 +56,9 @@ export const FENCED_WORK_MAX_ATTEMPT = 1;
  * (staging, 2026-08-13): every observed reset struck seconds AFTER the launch
  * settled — the platform kills the object while the resident runs, which is
  * when a launch-scoped row had already been deleted and recovery had nothing
- * to find. A resident's facet cannot outlive its session instance (the
- * process host's held-open leg dies with it), so a row from a previous
- * generation always names a process that is genuinely gone.
+ * to find. A resident's facet can outlive its session instance (a pending
+ * timer keeps it running), but nothing routes to it from the next one, and a
+ * spawn that takes its facet name ends it first.
  */
 export interface FencedWorkRecord {
   pid: number;

package/src/host-dispatch.ts

@@ -1,9 +1,9 @@
 import { BindingError } from './vendor/errors.js';
-import { hostDispatchMethod, hostNamespace } from './composition.js';
-import type { createSupervisorOpHandler } from '@nimbus-sh/core/workspace/supervisor-op.js';
+import { hostDispatchMethod, hostNamespace, type HostRoute } from './composition.js';
+import type { SupervisorOpDispatch } from '@nimbus-sh/core/workspace/supervisor-op.js';
 
 export type HostNamespaceBinding = Pick<DurableObjectNamespace, 'get' | 'idFromName' | 'idFromString'>;
-export type HostOpDispatch = ReturnType<typeof createSupervisorOpHandler>;
+export type HostOpDispatch = SupervisorOpDispatch;
 
 function isNamespace(value: object): value is HostNamespaceBinding {
   return typeof Reflect.get(value, 'idFromName') === 'function'
@@ -11,8 +11,19 @@ function isNamespace(value: object): value is HostNamespaceBinding {
     && typeof Reflect.get(value, 'get') === 'function';
 }
 
-export function hostNamespaceBinding(env: object | null | undefined, usage: string): HostNamespaceBinding {
-  const name = hostNamespace();
+/**
+ * The host's namespace binding. An entrypoint answering a facet passes the
+ * route the binding's props carry, minted in the host's isolate; the host
+ * itself, and a binding minted before routes travelled (a facet outlives
+ * the deploy that minted its binding), resolve from this isolate's
+ * composition.
+ */
+export function hostNamespaceBinding(
+  env: object | null | undefined,
+  usage: string,
+  route?: Pick<HostRoute, 'hostNamespace'>,
+): HostNamespaceBinding {
+  const name = route?.hostNamespace ?? 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`);
@@ -20,8 +31,12 @@ export function hostNamespaceBinding(env: object | null | undefined, usage: stri
   return binding;
 }
 
-export function hostOpDispatch(stub: object, usage: string): HostOpDispatch {
-  const name = hostDispatchMethod();
+export function hostOpDispatch(
+  stub: object,
+  usage: string,
+  route?: Pick<HostRoute, 'hostDispatchMethod'>,
+): HostOpDispatch {
+  const name = route?.hostDispatchMethod ?? hostDispatchMethod();
   if (stub === null || (typeof stub !== 'object' && typeof stub !== 'function')) {
     throw new BindingError(`${usage}: the workspace namespace returned no stub`);
   }

package/src/image-store.ts

@@ -138,12 +138,12 @@ export class ImageStore {
     fs.mkdirp(FACET_IMAGE_DIR);
     let count = 0;
     for await (const [moduleName, source] of images) {
-      const path = facetImagePath(await facetImageDigest(source));
+      const bytes = new TextEncoder().encode(source);
+      const path = facetImagePath(await facetImageDigest(bytes));
       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

package/src/inner-do-registry.ts

@@ -56,3 +56,34 @@ export function clearInnerDoClasses(supervisorDoId: string): void {
     if (k.startsWith(prefix)) _NIMBUS_INNER_DO_CLASSES.delete(k);
   }
 }
+
+/** Inner-DO facet names each incarnation has opened, by binding; keyed off ctx, so a new incarnation starts empty. */
+const openedInnerDoFacets = new WeakMap<DurableObjectState, Map<string, Set<string>>>();
+
+/**
+ * Record that this incarnation opens `facetName` for `bindingName`. True on the
+ * name's first open since the incarnation began or the binding's facets were
+ * last aborted: whatever still runs under it has a class this build no longer
+ * uses, and a get() with the new class on it resets the whole object.
+ */
+export function noteInnerDoFacetOpened(ctx: DurableObjectState, bindingName: string, facetName: string): boolean {
+  let byBinding = openedInnerDoFacets.get(ctx);
+  if (!byBinding) openedInnerDoFacets.set(ctx, byBinding = new Map());
+  let names = byBinding.get(bindingName);
+  if (!names) byBinding.set(bindingName, names = new Set());
+  if (names.has(facetName)) return false;
+  names.add(facetName);
+  return true;
+}
+
+/** Abort the facets this incarnation opened for `bindingNames`, keeping their storage, so each next request starts the class registered then. */
+export function abortInnerDoFacets(ctx: DurableObjectState, bindingNames: Iterable<string>, reason: Error): void {
+  const byBinding = openedInnerDoFacets.get(ctx);
+  if (!byBinding) return;
+  for (const bindingName of bindingNames) {
+    for (const facetName of byBinding.get(bindingName) ?? []) {
+      try { ctx.facets.abort(facetName, reason); } catch { /* already gone */ }
+    }
+    byBinding.delete(bindingName);
+  }
+}

package/src/isolate-pool.ts

@@ -15,7 +15,7 @@
  *   3. **Supervisor autoinjection**. The pool grabs the embedder's
  *      registered supervisor entrypoint stub (see `supervisorEntrypoint` in
  *      composition.ts) and forwards it as `env.SUPERVISOR` to every facet,
- *      same pattern as git-network-facet.ts. Callers can add more bindings
+ *      same pattern as git/network-facet.ts. Callers can add more bindings
  *      via `extraBindings`.
  *   4. **Fail-loud defaults**: timeout 60s, retries 0, onError 'throw'.
  *      Caller opts in to leniency.
@@ -25,7 +25,8 @@
  */
 
 import { CF_COMPAT_DATE } from '@nimbus-sh/core/constants.js';
-import { supervisorEntrypoint } from './composition.js';
+import { supervisorEntrypoint, type HostRoute } from './composition.js';
+import { supervisorBindingProps, supervisorLoaderKey } from './supervisor-props.js';
 import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
 import { serializeFunction, hashSource } from './vendor/serialize.js';
 import { beginLoaderFetch, recordLoaderId, withDynamicWorkerCapNamed } from './budgets.js';
@@ -120,6 +121,12 @@ export interface IsolatePoolOptions {
    * coordinator. Effective only when `omitSupervisor !== true`.
    */
   supervisorDoIdOverride?: string;
+  /**
+   * The coordinator's route, forwarded with `supervisorDoIdOverride`: the
+   * binding is the coordinator's, so its way back is the coordinator's
+   * too, whatever this peer's isolate composed.
+   */
+  supervisorRoute?: HostRoute;
   /**
    * Process pid baked into the auto-injected SUPERVISOR binding's props.
    * The supervisor derives the write credential from this pid
@@ -521,11 +528,11 @@ export class IsolatePool {
         // via supervisorDoIdOverride so SUPERVISOR.* RPCs route back
         // to the user's session DO, not the peer DO. Default to the
         // local ctx.id (single-DO callers and the in-DO in-DO fanout path).
-        const supDoId = opts?.supervisorDoIdOverride ?? ctx.id.toString();
-        const supPid = opts?.supervisorPid ?? 0;
-        bindings.SUPERVISOR = supervisorRpc({
-          props: { doId: supDoId, pid: supPid },
+        const supervisor = supervisorBindingProps(ctx, opts?.supervisorPid ?? 0, {
+          doId: opts?.supervisorDoIdOverride,
+          route: opts?.supervisorRoute,
         });
+        bindings.SUPERVISOR = supervisorRpc({ props: supervisor });
         // Whatever the minted worker's env carries must be in its loader
         // cache key — workerd's loader cache survives a DO hibernation
         // wake while generation-strided pids (1000001 → 2000001) do not:
@@ -533,8 +540,9 @@ export class IsolatePool {
         // the new generation still credentialed to the dead pid, and
         // every pid-authorized RPC from it fails "process pid … does
         // not exist". doIdShort alone cannot cover this — it changes
-        // across sessions, not across wakes of the same session.
-        this.supervisorKey = `s${supDoId.slice(0, 12)}-${supPid}`;
+        // across sessions, not across wakes of the same session. So does
+        // the instance a binding delivers mutations to, when it names one.
+        this.supervisorKey = supervisorLoaderKey(`s${supervisor.doId.slice(0, 12)}-${supervisor.pid}`, supervisor);
       } else {
         // Supervisor entrypoint unavailable — running without ctx.exports
         // (e.g. unit-test harness, or LOADER.load contexts where the

package/src/process-fabric.ts

@@ -74,6 +74,7 @@
  * `ResidentDiskReader` it was given.
  */
 
+import type { SupervisorBindingProps } from './supervisor-props.js';
 import { z } from 'zod/v4';
 import type { RouteableFacetTarget } from '@nimbus-sh/core/runtime/os-contracts.js';
 import type { ServiceStub } from './vendor/types.js';
@@ -209,8 +210,10 @@ export const FACET_IMAGE_DIR = 'var/lib/nimbus/facet-images';
  * generated text into `startArgs` would make every image per-PROGRAM and
  * shareable across spawns and sessions; the sweep bounds the store either way.
  */
-export async function facetImageDigest(source: string): Promise<string> {
-  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(source));
+export async function facetImageDigest(image: string | Uint8Array): Promise<string> {
+  // An image is its UTF-8 bytes; a caller holding them is not made to encode a second copy.
+  const bytes = typeof image === 'string' ? new TextEncoder().encode(image) : image;
+  const digest = await crypto.subtle.digest('SHA-256', bytes);
   return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
 }
 
@@ -265,8 +268,16 @@ export async function residentLoaderConfig(
   const resolved: Record<string, string | { wasm: ArrayBuffer }> = {};
   for (const [moduleName, path] of Object.entries(spec.vfsWasmModules ?? {})) {
     const bytes = await disk.readFile(path);
+    // The read's own buffer when it fits exactly, and only otherwise a copy.
+    // These are the largest members a spec carries — ruby's interpreter image
+    // is 34.3 MiB, esbuild's 13.3 — and an unconditional slice held both
+    // copies at once in the coordinator's 128 MiB isolate, at the one moment
+    // the module map is also resident.
+    const exact = bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength;
     resolved[moduleName] = {
-      wasm: bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer,
+      wasm: exact
+        ? bytes.buffer as ArrayBuffer
+        : bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer,
     };
   }
   for (const [moduleName, path] of Object.entries(spec.vfsTextModules ?? {})) {
@@ -294,15 +305,16 @@ async function readFacetImage(disk: ResidentDiskReader, path: string): Promise<s
   if (!expected) {
     throw new Error(`Nimbus: '${path}' is not a content-addressed facet image path`);
   }
-  const source = new TextDecoder().decode(await disk.readFile(path));
-  const actual = await facetImageDigest(source);
+  // Verified from the bytes read, and decoded only after: re-encoding the decoded string held a third copy of the largest member.
+  const bytes = await disk.readFile(path);
+  const actual = await facetImageDigest(bytes);
   if (actual !== expected) {
     throw new Error(
       `Nimbus: facet image '${path}' does not match its digest (read ${actual}); `
         + 'the image store is corrupt and the process cannot boot from it',
     );
   }
-  return source;
+  return new TextDecoder().decode(bytes);
 }
 
 // ── The hosting substrate ───────────────────────────────────────────────────
@@ -310,11 +322,12 @@ async function readFacetImage(disk: ResidentDiskReader, path: string): Promise<s
 /**
  * The identity a resident process's SUPERVISOR binding is minted for. Always
  * the COORDINATOR's — a process hosted somewhere else still reads and writes
- * the user's disk, and still reports to the user's process table.
+ * the user's disk, and still reports to the user's process table. Minted by
+ * `supervisorBindingProps` on the coordinator; `route` is absent only when
+ * the coordinator's isolate composed nothing, in which case no supervisor
+ * binding is minted either.
  */
-export interface ResidentSupervisorProps {
-  doId: string;
-  pid: number;
+export interface ResidentSupervisorProps extends SupervisorBindingProps {
   writerId: string;
 }
 
@@ -338,6 +351,13 @@ export interface ProcessHostParams {
    * the store on release.
    */
   facet?: { name: string; durable: boolean };
+  /**
+   * Bytes the process's store is filled with before it runs (its data plan).
+   * The hosting actor's storage ledger (N18) admits them under the facet's
+   * name before the facet starts: ENOSPC, and no facet, when they would cross
+   * the storage limit.
+   */
+  storageBytes?: number;
 }
 
 /**
@@ -650,6 +670,8 @@ export interface ResidentProcessSpawn {
    * ephemeral process, which takes a `proc-slot-<n>` name from the book.
    */
   facet?: { name: string; durable: boolean };
+  /** See {@link ProcessHostParams.storageBytes}. */
+  storageBytes?: number;
   /**
    * Called before any concrete host capability can expose this writer.
    * A spawn must not proceed unless the supervisor accepts the authority.
@@ -694,6 +716,7 @@ export class ProcessFabric {
         writerId,
         startArgs: spawn.startArgs,
         ...(spawn.facet !== undefined ? { facet: spawn.facet } : {}),
+        ...(spawn.storageBytes !== undefined ? { storageBytes: spawn.storageBytes } : {}),
       });
     } catch (error) {
       spawn.onWriterRetired(writerId);

package/src/process-host.ts

@@ -65,7 +65,7 @@
  */
 
 import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
-import { isTransientDoReset } from '@nimbus-sh/platform/oom-classify.js';
+import { classifyDoCall, isRetryableDoCall } from '@nimbus-sh/platform/oom-classify.js';
 import { PEER_RETRY_BACKOFF_MS, PEER_TRANSIENT_RESET_RETRIES } from './fanout.js';
 import { hostNamespaceBinding, hostOpDispatch, type HostNamespaceBinding } from './host-dispatch.js';
 import { z } from 'zod/v4';
@@ -85,6 +85,8 @@ import {
   processes,
   type ResidentFacetEnv,
 } from './workerd-facet-host.js';
+import type { HostRoute } from './composition.js';
+import { supervisorBindingProps } from './supervisor-props.js';
 
 /** The substrates this deployment can be configured for. */
 export type ProcessHostMode = 'facet' | 'peer';
@@ -137,18 +139,14 @@ class FacetProcessHost implements ProcessHost {
 
   runOnce<T>(params: OneShotParams, consume: (response: Response) => Promise<T>): Promise<T> {
     return processes(this.ctx, this.env).run(
-      { doId: this.coordDoId, pid: params.pid, writerId: params.writerId },
+      { ...supervisorBindingProps(this.ctx, params.pid), writerId: params.writerId },
       params,
       consume,
     );
   }
 
   async open(params: ProcessHostParams): Promise<HostedProcess> {
-    const supervisor: ResidentSupervisorProps = {
-      doId: this.coordDoId,
-      pid: params.pid,
-      writerId: params.writerId,
-    };
+    const supervisor: ResidentSupervisorProps = { ...supervisorBindingProps(this.ctx, params.pid), writerId: params.writerId };
     const { name, ...facet } = processes(this.ctx, this.env).spawn(this.disk, supervisor, params);
     return {
       ...facet,
@@ -192,8 +190,12 @@ export function isolateToken(): string {
 /** Options the coordinator hands a hosting peer. */
 export interface HostProcessOpts {
   coordinatorDoId: string;
+  /** The coordinator's route, minted into the process's SUPERVISOR binding. */
+  route?: HostRoute;
   pid: number;
   writerId: string;
+  /** The coordinator instance's delivery incarnation, minted into the SUPERVISOR binding (ResidentSupervisorProps). */
+  hostIncarnation?: string;
   workerKey: string;
   /** Unforgeable capability for the fetch-semantic WebSocket hop. */
   webSocketCapability: string;
@@ -354,7 +356,7 @@ class PeerProcessHost implements ProcessHost {
    */
   runOnce<T>(params: OneShotParams, consume: (response: Response) => Promise<T>): Promise<T> {
     return processes(this.ctx, this.env).run(
-      { doId: this.coordDoId, pid: params.pid, writerId: params.writerId },
+      { ...supervisorBindingProps(this.ctx, params.pid), writerId: params.writerId },
       params,
       consume,
     );
@@ -379,10 +381,15 @@ class PeerProcessHost implements ProcessHost {
     // also what keeps the hosting DO resident. It settles when a `lifetime`
     // runner exits or when a `boot` runner's host is cancelled, and rejects if
     // the peer dies under either.
+    // The peer mints the process's binding from these, for THIS object: the
+    // coordinator's doId, route and delivery instance.
+    const supervisor = supervisorBindingProps(this.ctx, params.pid);
     const hostLeg = placement.stub._rpcHostProcess(params.boot, {
-      coordinatorDoId: this.coordDoId,
-      pid: params.pid,
+      coordinatorDoId: supervisor.doId,
+      route: supervisor.route,
+      pid: supervisor.pid,
       writerId: params.writerId,
+      hostIncarnation: supervisor.hostIncarnation,
       workerKey: params.workerKey,
       webSocketCapability,
       startArgs: params.startArgs,
@@ -491,7 +498,7 @@ class PeerProcessHost implements ProcessHost {
         }
         return probe;
       } catch (err) {
-        if (attempt < PEER_TRANSIENT_RESET_RETRIES && isTransientDoReset(err)) {
+        if (attempt < PEER_TRANSIENT_RESET_RETRIES && isRetryableDoCall(classifyDoCall(err))) {
           await new Promise((r) => setTimeout(
             r, PEER_RETRY_BACKOFF_MS[Math.min(attempt, PEER_RETRY_BACKOFF_MS.length - 1)],
           ));

package/src/supervisor-props.ts

@@ -0,0 +1,56 @@
+/**
+ * supervisor-props.ts — what every SUPERVISOR binding a Durable Object mints
+ * for a process carries, and the one rule for naming the instance in it.
+ *
+ * A binding names its host INSTANCE (`hostIncarnation`) exactly when a
+ * mutation sent through it can be delivered once
+ * (@nimbus-sh/core/workspace/supervisor-delivery.js): the host opened a
+ * delivery store, the binding acts as a real process (SupervisorRPC refuses
+ * every filesystem mutation of pid 0), and it routes back to this very
+ * object rather than another (a fanout pool writes to its coordinator).
+ * Minting every binding here is what keeps a new mint site from forgetting
+ * that, which would fail silently: its mutations would simply never be
+ * re-sent.
+ */
+
+import { supervisorDeliveryProps } from '@nimbus-sh/core/workspace/supervisor-delivery.js';
+import { hostRoute, type HostRoute } from './composition.js';
+
+/** The props every SUPERVISOR binding for a process carries. */
+export interface SupervisorBindingProps {
+  /** The Durable Object the binding's calls reach. */
+  doId: string;
+  /** The process the calls act as; 0 is none, and can mutate nothing. */
+  pid: number;
+  /** The way back, minted with the binding in the host's isolate. */
+  route?: HostRoute;
+  /** The host instance that applies this binding's mutations once, when there is one. */
+  hostIncarnation?: string;
+}
+
+/**
+ * The props of a SUPERVISOR binding minted in the Durable Object whose state
+ * is `ctx`, for process `pid`, reaching `options.doId` (this object by
+ * default) by `options.route` (this isolate's composition by default).
+ */
+export function supervisorBindingProps(
+  ctx: { readonly id: { toString(): string } },
+  pid: number,
+  options: { doId?: string; route?: HostRoute } = {},
+): SupervisorBindingProps {
+  const own = ctx.id.toString();
+  const doId = options.doId ?? own;
+  const route = options.route ?? hostRoute() ?? undefined;
+  const delivery = pid > 0 && doId === own ? supervisorDeliveryProps(ctx) : {};
+  return { doId, pid, route, ...delivery };
+}
+
+/**
+ * `key`, for a loader cache entry whose worker holds a binding with `props`:
+ * made specific to the host instance the binding names, since the loader
+ * outlives that instance and the next one refuses every mutation the binding
+ * would deliver. A binding that names none keeps `key`, and its warm worker.
+ */
+export function supervisorLoaderKey(key: string, props: Pick<SupervisorBindingProps, 'hostIncarnation'>): string {
+  return props.hostIncarnation === undefined ? key : `${key}:${props.hostIncarnation}`;
+}