@nimbus-sh/fabric 0.2.0 → 0.3.0

package/src/process-fabric.ts

@@ -76,6 +76,7 @@
 
 import { z } from 'zod/v4';
 import type { RouteableFacetTarget } from '@nimbus-sh/core/runtime/os-contracts.js';
+import type { ServiceStub } from './vendor/types.js';
 
 /**
  * The class every generated resident runner exports. One name for every
@@ -131,6 +132,19 @@ export const ResidentCodeSpecSchema = z.object({
    * image store below and the spec names it.
    */
   vfsTextModules: z.record(z.string(), z.string()).optional(),
+  /**
+   * The isolate's exact `env`: one entry per binding the embedder minted,
+   * carried by reference so loopback stubs survive untouched. Defined —
+   * even as `{}` — means the embedder takes the whole env and no
+   * SUPERVISOR binding is injected; absent keeps the default (a SUPERVISOR
+   * minted from the composed supervisor entrypoint).
+   */
+  env: z.record(z.string(), z.unknown()).optional(),
+  /** Absent inherits outbound, null denies it, a binding mediates it by reference. */
+  globalOutbound: z.custom<ServiceStub>((value) =>
+    value !== null && (typeof value === 'object' || typeof value === 'function')
+    && 'fetch' in value && typeof value.fetch === 'function',
+  ).nullable().optional(),
 });
 
 export type ResidentCodeSpec = z.infer<typeof ResidentCodeSpecSchema>;
@@ -238,6 +252,11 @@ export interface ResidentDiskReader {
  * path, verifying each generated image against the digest its own path claims.
  * Runs inside the loader's cache-miss callback, so the bytes exist only for
  * the duration of the load.
+ *
+ * The spec's isolation posture rides along verbatim: an explicit `env` is
+ * the isolate's whole env (loopback stubs by reference, never cloned or
+ * re-minted). An absent env stays absent
+ * so the worker config can tell "embedder takes the env" from the default.
  */
 export async function residentLoaderConfig(
   spec: ResidentCodeSpec,
@@ -258,6 +277,8 @@ export async function residentLoaderConfig(
     compatibilityFlags: spec.compatibilityFlags,
     mainModule: spec.mainModule,
     modules: { ...spec.modules, ...resolved },
+    ...(spec.env !== undefined ? { env: spec.env } : {}),
+    ...(spec.globalOutbound !== undefined ? { globalOutbound: spec.globalOutbound } : {}),
   };
 }
 
@@ -309,6 +330,14 @@ export interface ProcessHostParams {
   writerId: string;
   /** Forwarded verbatim to the runner's startProcess. */
   startArgs: unknown;
+  /**
+   * Set only by the coordinator's durable-application path: an explicit facet
+   * name (`app-slot-<n>`) allocated from DO storage, plus the release split
+   * that keeps its SQLite across aborts. Absent, the host allocates an
+   * ephemeral `proc-slot-<n>` name from its in-memory free list and deletes
+   * the store on release.
+   */
+  facet?: { name: string; durable: boolean };
 }
 
 /**
@@ -611,10 +640,16 @@ export interface ResidentProcessSpawn {
   pid: number;
   /** Keyed dynamic-worker identity (`nimbus-process:${doId}:${pid}`). */
   workerKey: string;
-  /** What the facet boots from. */
+  /** What the process boots from. */
   boot: ResidentBootSpec;
   /** Forwarded verbatim to the runner's startProcess. */
   startArgs?: unknown;
+  /**
+   * A durable application's explicit facet name (`app-slot-<n>`) and the
+   * release split that keeps its SQLite. Coordinator-allocated; absent for an
+   * ephemeral process, which takes a `proc-slot-<n>` name from the book.
+   */
+  facet?: { name: string; durable: boolean };
   /**
    * Called before any concrete host capability can expose this writer.
    * A spawn must not proceed unless the supervisor accepts the authority.
@@ -658,6 +693,7 @@ export class ProcessFabric {
         boot: spawn.boot,
         writerId,
         startArgs: spawn.startArgs,
+        ...(spawn.facet !== undefined ? { facet: spawn.facet } : {}),
       });
     } catch (error) {
       spawn.onWriterRetired(writerId);

package/src/process-host.ts

@@ -78,12 +78,11 @@ import {
   type ResidentSupervisorProps,
 } from './process-fabric.js';
 import { DYNAMIC_WORKER_CODE_LIMIT_BYTES } from './budgets.js';
+import { BindingError } from './vendor/errors.js';
 import {
   processes,
-  residentFacetName,
   type ResidentFacetEnv,
 } from './workerd-facet-host.js';
-import { BindingError } from './vendor/errors.js';
 
 /** The substrates this deployment can be configured for. */
 export type ProcessHostMode = 'facet' | 'peer';
@@ -148,11 +147,11 @@ class FacetProcessHost implements ProcessHost {
       pid: params.pid,
       writerId: params.writerId,
     };
-    const { slot, ...facet } = processes(this.ctx, this.env).spawn(this.disk, supervisor, params);
+    const { name, ...facet } = processes(this.ctx, this.env).spawn(this.disk, supervisor, params);
     return {
       ...facet,
       describe: () =>
-        `facet '${residentFacetName(slot)}' (pid ${params.pid})`
+        `facet '${name}' (pid ${params.pid})`
         + ` of session ${this.coordDoId.slice(-12)}`
         + `; ${describeImageDelivery(this.imageDelivery)}`,
     };
@@ -340,10 +339,18 @@ class PeerProcessHost implements ProcessHost {
       consume,
     );
   }
-
   async open(params: ProcessHostParams): Promise<HostedProcess> {
+    if (params.facet) {
+      // A durable application's facet must be a child of the COORDINATOR's
+      // Durable Object — its `app-slot-<n>` row and retained SQLite live in
+      // that DO's storage. A sibling host would own storage the coordinator's
+      // durable-slot book and removeDurableApp cannot reach.
+      throw new Error(
+        'Nimbus: a durable spawn must be facet-hosted on its own coordinator; '
+          + 'the peer substrate cannot serve one',
+      );
+    }
     const placement = await this._place(params.pid);
-    this.tokensInUse.set(params.pid, placement.isolateToken);
     // Minted per open, held only by this coordinator and the peer that hosts
     // the process. The workerKey is derivable from a pid; this is not.
     const webSocketCapability = crypto.randomUUID();

package/src/turn-budget.ts

@@ -123,9 +123,10 @@ export class TurnBudget {
   }
 }
 
-function withResolvers(): { promise: Promise<void>; resolve: () => void } {
-  let resolve!: () => void;
-  const promise = new Promise<void>((r) => { resolve = r; });
+/** `Promise.withResolvers` for the runtime the project targets. */
+export function withResolvers<T = void>(): { promise: Promise<T>; resolve: (value: T | PromiseLike<T>) => void } {
+  let resolve!: (value: T | PromiseLike<T>) => void;
+  const promise = new Promise<T>((r) => { resolve = r; });
   return { promise, resolve };
 }
 

package/src/workerd-facet-host.ts

@@ -136,9 +136,14 @@ interface LoadedWorkerStub {
  * Durable Object class, so a resident process can be re-entered; `load` is
  * unkeyed and yields a stateless entrypoint, which is all a program that ends
  * with its call can ever need.
+ *
+ * `get` stays wide on purpose: the platform passes a null id for the unkeyed
+ * call and answers the callback with the code object or a promise of it, so a
+ * narrower declaration would refuse the real binding. The fabric itself always
+ * passes a string id and a promise callback.
  */
 interface WorkerLoaderBinding {
-  get(id: string, code: () => Promise<unknown>): { getDurableObjectClass(name: string): unknown };
+  get(id: string | null, code: () => unknown): { getDurableObjectClass(name: string): unknown };
   load(code: unknown): LoadedWorkerStub;
 }
 
@@ -223,7 +228,7 @@ export async function cloneStorage(
 }
 
 /**
- * The facet name for a slot. Reused, and that is the entire point.
+ * The facet name for an ephemeral slot. Reused, and that is the entire point.
  *
  * A Durable Object admits 65,536 facets over its LIFETIME: the IDs are
  * append-only and are never reclaimed, so the bound is on facets ever CREATED,
@@ -235,11 +240,20 @@ export async function cloneStorage(
  * Reusing a NAME costs no new ID. So the name comes from a free list and the
  * pid stays what it always was: the process identity in the ProcessTable. The
  * two were only ever conflated because one of them happened to be handy.
+ *
+ * The book shares the facet-ID space with one other namespace: durable
+ * applications, which mint `app-slot-<n>` names of their own (one ID per app,
+ * ever). The prefixes are disjoint BY CONSTRUCTION, and that disjointness is
+ * load-bearing — a proc-slot name reissued onto a durable app's retained
+ * storage would boot the wrong process into someone else's disk.
  */
 export function residentFacetName(slot: number): string {
   return `proc-slot-${slot}`;
 }
 
+/** The prefix every durable application's facet name carries. */
+export const DURABLE_FACET_NAME_PREFIX = 'app-slot-';
+
 /** One hosting actor's slot book. */
 interface SlotBook {
   /** Returned slots, lowest reused first so the high-water mark stays low. */
@@ -264,6 +278,11 @@ interface SlotBook {
  * VFS epoch, in which case `invalidatedSince` can only answer poison and the
  * whole store is dropped. A process therefore cannot boot onto a previous
  * tenant's filesystem even when release never ran.
+ *
+ * The book names only the `proc-slot-` space. Durable `app-slot-` names are
+ * allocated against DO storage instead (their owner survives a reset), so a
+ * fresh incarnation's `next` starting at 0 can never collide with them even
+ * before the durable ledger is adopted.
  */
 const slotBooks = new WeakMap<DurableObjectState, SlotBook>();
 
@@ -300,16 +319,29 @@ function releaseSlot(ctx: DurableObjectState, pid: number): void {
   book.free.sort((a, b) => a - b);
 }
 
+/**
+ * Drop one facet's SQLite by name — the ONLY call site that may delete facet
+ * storage. `spawnResident` releases ephemeral processes with abort+delete
+ * (storage is slot-reuse hygiene) and durable ones with abort alone (the
+ * storage IS the durable application's state); explicit removal arrives here
+ * through the coordinator's durable-slot book, owner-checked.
+ */
+export function deleteFacetStorage(ctx: DurableObjectState, name: string): void {
+  facetContainer(ctx).delete(name);
+}
+
+
 
 /**
  * What `processes(ctx, env).spawn` hands back: a running process, minus its placement.
  *
- * `slot` rides along because the caller's `describe` needs the facet's real
- * name and the slot is not derivable from the pid — that indirection is the
- * whole point of the free list. Reading it back out of the book later would
- * also race the release that empties it.
+ * `name` is the facet's real name and `slot` its ephemeral book entry (absent
+ * for a durable spawn, whose name its coordinator allocated out of storage).
+ * Both ride along because the caller's `describe` needs them and neither is
+ * derivable from the pid — reading a slot back out of the book would race the
+ * release that empties it.
  */
-export type ResidentFacet = Omit<HostedProcess, 'describe'> & { slot: number };
+export type ResidentFacet = Omit<HostedProcess, 'describe'> & { name: string; slot?: number };
 
 /**
  * The process surface of one hosting actor: how a resident process comes
@@ -371,8 +403,21 @@ function spawnResident(
   params: ProcessHostParams,
 ): ResidentFacet {
   const facets = facetContainer(ctx);
-  const slot = acquireSlot(ctx, params.pid);
-  const name = residentFacetName(slot);
+  // An explicit name is the durable path: the caller allocated an
+  // `app-slot-<n>` identity out of DO storage and this facet keeps its SQLite
+  // across aborts. Anything else takes the in-memory book — and that book's
+  // `proc-slot-` names must never be minted for it, or an ephemeral release's
+  // delete would wipe the app's storage and a reused slot would land a new
+  // process on someone else's disk.
+  const explicit = params.facet;
+  if (explicit && !explicit.name.startsWith(DURABLE_FACET_NAME_PREFIX)) {
+    throw new Error(
+      `Nimbus: an explicit facet name must carry the '${DURABLE_FACET_NAME_PREFIX}' `
+        + `prefix, got '${explicit.name}'`,
+    );
+  }
+  const slot = explicit ? undefined : acquireSlot(ctx, params.pid);
+  const name = explicit ? explicit.name : residentFacetName(slot!);
   // The start callback is the ONLY way this facet is ever created, and it
   // fires AT MOST ONCE. Every later use goes through the stub below, so the
   // callback running a second time means the facet was released or died —
@@ -398,7 +443,7 @@ function spawnResident(
   try {
     facet = facets.get(name, start);
   } catch (error) {
-    releaseSlot(ctx, params.pid);
+    if (slot !== undefined) releaseSlot(ctx, params.pid);
     throw withFacetBudgetNamed(facetNameCount(ctx), error);
   }
 
@@ -408,10 +453,17 @@ function spawnResident(
     disposed = true;
     released = true;
     try { facets.abort(name, new Error('Nimbus: resident process released')); } catch { /* already gone */ }
-    try { facets.delete(name); } catch { /* already gone */ }
+    // The two release classes: an ephemeral facet's SQLite is slot-reuse
+    // hygiene — the name is handed out again, so the store must not be — and
+    // a durable one's is the application itself: abort ends the process, the
+    // data stays for the next boot, and only removeDurableApp's explicit
+    // deleteFacetStorage call ever drops it.
+    if (!explicit?.durable) {
+      try { facets.delete(name); } catch { /* already gone */ }
+    }
     // Only after the facet is gone. A slot handed out while its previous
     // tenant were still being torn down would have two processes on one name.
-    releaseSlot(ctx, params.pid);
+    if (slot !== undefined) releaseSlot(ctx, params.pid);
   };
 
   let started: Promise<unknown>;
@@ -439,6 +491,7 @@ function spawnResident(
     handleHttpRequest: (request: Request) => facet.handleHttpRequest(request),
     handleWebSocketRequest: (request: Request) => facet.fetch(request),
     release,
+    name,
     slot,
   };
 }
@@ -546,18 +599,33 @@ async function runOneShot<T>(
   }
 }
 
-async function residentWorkerConfig(
+/**
+ * The WorkerCode the loader callback returns for one resident boot: the
+ * module map from {@link residentLoaderConfig} (or the staged assembler),
+ * plus the isolate's env and network posture.
+ *
+ * A `code` boot with an explicit `env` — defined, even as `{}` — is the
+ * embedder's whole statement about the isolate: the env rides through
+ * exactly as minted (loopback stubs by reference), and the composed supervisor
+ * entrypoint is not consulted at all, so no SUPERVISOR binding appears.
+ * Without one, the default holds: inherited network plus a SUPERVISOR
+ * minted from the composed entrypoint for the coordinator's identity.
+ */
+export async function residentWorkerConfig(
   env: ResidentFacetEnv,
   disk: () => ResidentDiskReader,
   supervisor: ResidentSupervisorProps,
   boot: ResidentBootSpec,
 ): Promise<Record<string, unknown>> {
+  if (boot.kind === 'code' && boot.code.env !== undefined) {
+    const isolated = await residentLoaderConfig(boot.code, disk());
+    assertModuleMapWithinCodeLimit(configModules(isolated));
+    return isolated;
+  }
   const config = boot.kind === 'staged'
     ? await stagedBootAssembler()(env, boot.stage)
     : await residentLoaderConfig(boot.code, disk());
-  assertModuleMapWithinCodeLimit(
-    (config as { modules?: Record<string, unknown> }).modules ?? {},
-  );
+  assertModuleMapWithinCodeLimit(configModules(config));
   const supervisorRpc = supervisorEntrypoint();
   if (!supervisorRpc) {
     throw new Error(
@@ -566,3 +634,12 @@ async function residentWorkerConfig(
   }
   return { ...config, env: { SUPERVISOR: supervisorRpc({ props: supervisor }) } };
 }
+
+/** The module map a loader config assembled, or empty when it named none. */
+function configModules(config: object): Record<string, unknown> {
+  const modules: unknown = 'modules' in config ? config.modules : undefined;
+  if (typeof modules !== 'object' || modules === null) return {};
+  // Loader configs only ever carry a module map under this key.
+  const map: Record<string, unknown> = modules as Record<string, unknown>;
+  return map;
+}