@nimbus-sh/fabric 0.1.0 → 0.2.0

package/examples/agent-core-adapter.ts

@@ -0,0 +1,191 @@
+/**
+ * agent-core-adapter.ts — EXAMPLE: agent-core's process and environment
+ * seams, implemented over the fabric.
+ *
+ * agent-core defines two pure seams with no Cloudflare implementation:
+ * `ShellProcessBackend` (packages/agent-core/src/facets/shell/facet.ts:38-43
+ * — exactly `completion`, `forceTerminate`, `confirmTerminated`, `fence`)
+ * and `EnvironmentProvider` (src/environments/provider.ts:195-225 — every
+ * mutating verb paired with an inspect twin, requests generation-pinned,
+ * outcomes `ready | absent | failed | indeterminate`). This file shows the
+ * mapping onto fabric's `ResidentProcessHandle`, `cloneStorage`, and the
+ * hostname-per-port preview scheme. It is a worked example, not a shipped
+ * runtime: the seam types are mirrored here structurally (agent-core's repo
+ * is its own), and an embedder writes this file's equivalent against the
+ * real imports.
+ *
+ * The lifecycle facts the mapping rests on, from agent-core's own boundary
+ * (`ShellExecutionBoundary`, facet.ts:60-154):
+ *   - a rejected `completion` is treated as exit 1 by the boundary;
+ *   - `forceTerminate` may throw — the boundary then fences immediately;
+ *   - `confirmTerminated() === false` means "still deciding" and defers to
+ *     the boundary's timeout, never "failed";
+ *   - a throwing `fence` is swallowed: "The local fence still closes this
+ *     handle even if remote cleanup reports failure."
+ */
+
+import type { ResidentProcessHandle } from '../src/process-fabric.js';
+import { cloneStorage } from '../src/workerd-facet-host.js';
+
+// ── agent-core's seams, mirrored structurally (do not import their repo) ────
+
+/** facet.ts:38-43, verbatim shape. */
+export interface ShellProcessBackend {
+  readonly completion: Promise<number>;
+  forceTerminate(): void;
+  confirmTerminated(): boolean | Promise<boolean>;
+  fence(): void;
+}
+
+/** provider.ts:37-61 — the outcome unions the provider seam speaks. */
+export type ProviderActionOutcome = { readonly name: 'succeeded' | 'failed' | 'indeterminate' };
+export type ProviderResourceOutcome<Value> =
+  | { readonly name: 'ready'; readonly value: Value }
+  | { readonly name: 'absent' }
+  | { readonly name: 'failed' }
+  | { readonly name: 'indeterminate' };
+
+/** provider.ts:138-145 — the live-session handle openSession yields. */
+export interface LiveEnvironmentSession {
+  readonly children: ReadonlyArray<{ dispose(): void | Promise<void> }>;
+  release(): void | Promise<void>;
+}
+
+/** provider.ts:171-193 — every request pins environment identity and
+ *  generation, so a stale caller cannot act on a successor. */
+export interface OpenSessionRequest {
+  readonly environmentId: string;
+  readonly environmentRevision: number;
+  readonly generation: number;
+  readonly sessionId: string;
+}
+export interface SnapshotEnvironmentRequest extends OpenSessionRequest {
+  readonly sessionEpoch: number;
+  readonly snapshotId: string;
+}
+export interface ExposePortRequest extends OpenSessionRequest {
+  readonly sessionEpoch: number;
+  readonly exposureId: string;
+  readonly port: number;
+}
+
+// ── ShellProcessBackend over one resident process ───────────────────────────
+
+/**
+ * A shell command as a fabric resident. The exit code rides the `lifetime`
+ * runner's startProcess payload, whose shape is the embedder's — so the
+ * embedder names how to read it.
+ */
+export function shellBackendFor(
+  handle: ResidentProcessHandle,
+  exitCodeOf: (startPayload: unknown) => number,
+): ShellProcessBackend {
+  return {
+    // A lifetime runner settles booted() at exit; a host that dies under the
+    // process rejects it, and the boundary maps that rejection to exit 1.
+    completion: handle.booted().then(exitCodeOf),
+    // Synchronous and idempotent, matching ResidentProcessHandle.kill.
+    forceTerminate(): void {
+      handle.kill();
+    },
+    // False before a kill was asked for — "still deciding", the boundary
+    // waits on its own timeout. After a kill, settle with the teardown: done
+    // resolves only once the process is actually gone.
+    confirmTerminated(): boolean | Promise<boolean> {
+      if (!handle.killed) return false;
+      return handle.done.then(() => true, () => true);
+    },
+    // The local fence: close this handle's side whatever the remote did.
+    // kill() is idempotent and swallows teardown throws, which is exactly
+    // the "local fence still closes this handle" contract.
+    fence(): void {
+      handle.kill();
+    },
+  };
+}
+
+// ── The four EnvironmentProvider verbs over the fabric ──────────────────────
+
+/** What the example provider needs from its embedder: how to spawn one
+ *  session process, and where port previews are served. */
+export interface FabricEnvironmentHost {
+  /** Spawn the resident process backing one session (the embedder owns the
+   *  boot spec; `ProcessFabric.startResidentProcess` is the fabric half). */
+  spawnSession(request: OpenSessionRequest): Promise<ResidentProcessHandle>;
+  /** The hosting Durable Object's ctx — snapshots clone same-object only. */
+  ctx: Parameters<typeof cloneStorage>[0];
+  /** Positive populated-ness probe for a facet name (the caller's schema —
+   *  see cloneStorage: a clone of an unresolvable source silently EMPTIES
+   *  the destination, so both ends are verified). */
+  facetPopulated(name: string): boolean | Promise<boolean>;
+  /** The facet name holding a session's storage. */
+  sessionFacetName(sessionId: string): string;
+  /** Preview apex, e.g. 'nimbus-os.dev' — ports serve as `<port>--<id>.<apex>`. */
+  previewApex: string;
+}
+
+export class FabricEnvironmentProvider {
+  /** exposureId → preview URL. Inbound requests for these hosts route into
+   *  the session's `ResidentProcessHandle.routeTarget.handleHttpRequest`. */
+  private readonly exposures = new Map<string, string>();
+
+  constructor(private readonly host: FabricEnvironmentHost) {}
+
+  async openSession(request: OpenSessionRequest): Promise<ProviderResourceOutcome<LiveEnvironmentSession>> {
+    try {
+      const handle = await this.host.spawnSession(request);
+      return {
+        name: 'ready',
+        value: { children: [], release: () => handle.kill() },
+      };
+    } catch {
+      // The spawn either failed before any facet existed (failed) or the
+      // host died mid-boot (indeterminate); the fabric rejects both loudly.
+      return { name: 'failed' };
+    }
+  }
+
+  /**
+   * Snapshot = same-object copy-on-write of the session facet's SQLite
+   * (measured 18-31 ms for a 45.73 MB corpus, flat in size). The ContentRef
+   * is the snapshot facet's name; `cloneStorage` verifies BOTH ends are
+   * populated, because an unresolvable source silently empties the
+   * destination while reporting success.
+   */
+  async createSnapshot(request: SnapshotEnvironmentRequest): Promise<ProviderResourceOutcome<string>> {
+    const src = this.host.sessionFacetName(request.sessionId);
+    const dst = `snapshot-${request.snapshotId}`;
+    try {
+      await cloneStorage(this.host.ctx, {
+        src,
+        dst,
+        populated: (name) => this.host.facetPopulated(name),
+      });
+      return { name: 'ready', value: dst };
+    } catch {
+      // A refused clone left nothing to trust in dst — never 'ready'.
+      return { name: 'failed' };
+    }
+  }
+
+  /**
+   * Hostname-per-port: `<port>--<sessionId>.<apex>`, no path rewriting. The
+   * URL is derivable, so re-exposing is idempotent and inspection is a map
+   * read.
+   */
+  async exposePort(request: ExposePortRequest): Promise<ProviderResourceOutcome<string>> {
+    const url = `https://${request.port}--${request.sessionId}.${this.host.previewApex}/`;
+    this.exposures.set(request.exposureId, url);
+    return { name: 'ready', value: url };
+  }
+
+  async inspectExposure(request: ExposePortRequest): Promise<ProviderResourceOutcome<string>> {
+    const url = this.exposures.get(request.exposureId);
+    return url === undefined ? { name: 'absent' } : { name: 'ready', value: url };
+  }
+
+  async revokeExposure(request: ExposePortRequest): Promise<ProviderActionOutcome> {
+    this.exposures.delete(request.exposureId);
+    return { name: 'succeeded' };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-sh/fabric",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The Cloudflare half of Nimbus — Durable Object facet hosting, dynamic-worker loader pools, the resident-process fabric, and DO alarm/hibernation machinery.",
   "keywords": [
     "cloudflare",
@@ -40,6 +40,7 @@
   "files": [
     "dist",
     "src",
+    "examples",
     "README.md",
     "LICENSE"
   ],
@@ -49,7 +50,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@nimbus-sh/core": "^0.5.0",
+    "@nimbus-sh/core": "^0.6.0",
+    "@nimbus-sh/platform": "^0.1.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/src/bindings.ts

@@ -25,11 +25,11 @@
 
 import { WorkerEntrypoint } from 'cloudflare:workers';
 import { z } from 'zod/v4';
-import { disposeRpcResource, useRpcResource } from '@nimbus-sh/core/_shared/rpc-dispose.js';
-import { supervisorEntrypoint, supervisorEntrypointName } from './ctx-exports.js';
-import { requireStagedBootAssembler } from './process-fabric.js';
-import { assertModuleMapWithinCodeLimit } from './workerd-facet-host.js';
-import type { EntrypointLoopbackFactory } from './ctx-exports.js';
+import { disposeRpcResource, useRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
+import { supervisorEntrypoint, supervisorEntrypointName } from './composition.js';
+import { stagedBootAssembler } from './composition.js';
+import { assertModuleMapWithinCodeLimit } from './budgets.js';
+import type { EntrypointLoopbackFactory } from './composition.js';
 import type { WorkerCode } from './vendor/types.js';
 
 /**
@@ -578,7 +578,7 @@ export class NimbusLoadedEntrypoint extends WorkerEntrypoint<NimbusLoaderShimEnv
       // alive.
       const stage = props.stage;
       outerStub = outerLoader.get(props.key, async () => {
-        const assembled = await requireStagedBootAssembler()(this.env, stage);
+        const assembled = await stagedBootAssembler()(this.env, stage);
         assertModuleMapWithinCodeLimit(
           (assembled as { modules?: Record<string, unknown> }).modules ?? {},
         );

package/src/budgets.ts

@@ -0,0 +1,308 @@
+/**
+ * budgets.ts — per-DO accounting for the platform budgets the fabric spends:
+ * the Worker Loader's two caps, the facet-ID lifetime budget, and the
+ * dynamic-worker module-map ceiling.
+ *
+ * Measured on production workerd: a Durable Object admits ~5–6 concurrent
+ * dynamic workers before the platform refuses with "Too many concurrent
+ * dynamic workers", one DO method can drive at most 4 concurrent Loader
+ * fetches, and loader-cache entries are never released — every DISTINCT
+ * `loader.get(id)` permanently consumes one of the dynamic-worker slots for
+ * the object's lifetime. Nimbus stays under the caps by construction
+ * (`IN_DO_THRESHOLD` = 5 in the fanout pool), which until now meant the slots
+ * were counted in prose. This ledger counts them at the fabric's loader call
+ * sites instead — the loader pool's slots, a resident process's keyed worker,
+ * a one-shot's load — so proximity is measurable and a cap failure can name
+ * the ids actually holding slots.
+ *
+ * Measurement only: no admission control. The caps are the platform's, they
+ * are approximate ("~5–6"), and a gate on an approximate number would refuse
+ * work the platform would have run.
+ *
+ * Keyed weakly off the hosting actor's `ctx`, like the facet slot books: the
+ * caps are per Durable Object, and dynamic workers die with the isolate that
+ * loaded them, so a ledger that goes away with its host describes nothing
+ * that still exists.
+ */
+
+import { classifyError } from '@nimbus-sh/platform/oom-classify.js';
+
+interface LoaderLedger {
+  /** Distinct loader ids ever gotten — each one a permanently consumed slot. */
+  ids: Set<string>;
+  /** In-flight calls into dynamic workers, right now. */
+  liveFetches: number;
+  /** The most that were ever in flight at once. */
+  peakLiveFetches: number;
+}
+
+const ledgers = new WeakMap<object, LoaderLedger>();
+
+function ledger(ctx: object): LoaderLedger {
+  let entry = ledgers.get(ctx);
+  if (!entry) {
+    entry = { ids: new Set(), liveFetches: 0, peakLiveFetches: 0 };
+    ledgers.set(ctx, entry);
+  }
+  return entry;
+}
+
+/** Record a keyed `loader.get(id)` — a permanent slot if the id is new. */
+export function recordLoaderId(ctx: object, id: string): void {
+  ledger(ctx).ids.add(id);
+}
+
+/**
+ * Count one call into a dynamic worker as a live Loader fetch; the returned
+ * function ends it (idempotently), from the caller's own `finally`.
+ *
+ * A begin/end pair rather than a wrapper on purpose, and the shape is
+ * load-bearing: wrapping the stub call in a ledger-owned async frame
+ * (`trackLoaderFetch(ctx, () => entrypoint.execute(...))`) left the hosting
+ * Durable Object poisoned after every pooled dispatch — the next fabric
+ * activity hung the object or reset the instance outright (pid base jumped,
+ * every attached WebSocket dropped with no close frame), measured 7/7 on
+ * staging and gone 3/3 with the direct call restored. Same seam-quirk class
+ * as pipelined `fetch.call`, which workerd refuses for dynamically-loaded
+ * workers: an RPC stub call must stay a direct property call awaited by the
+ * frame that made it, so the ledger only brackets it.
+ */
+export function beginLoaderFetch(ctx: object): () => void {
+  const entry = ledger(ctx);
+  entry.liveFetches++;
+  entry.peakLiveFetches = Math.max(entry.peakLiveFetches, entry.liveFetches);
+  let ended = false;
+  return () => {
+    if (ended) return;
+    ended = true;
+    entry.liveFetches--;
+  };
+}
+
+/** Snapshot for the diag surface. Pure read; no I/O. */
+export function loaderLedgerStats(ctx: object): {
+  idsEverGotten: string[];
+  liveFetches: number;
+  peakLiveFetches: number;
+} {
+  const entry = ledger(ctx);
+  return {
+    idsEverGotten: [...entry.ids],
+    liveFetches: entry.liveFetches,
+    peakLiveFetches: entry.peakLiveFetches,
+  };
+}
+
+/**
+ * Name the per-DO accounting on a "Too many concurrent dynamic workers"
+ * failure; hand every other error back untouched. The platform's message
+ * says only that the cap was hit — which ids hold the slots, and that a
+ * keyed id can never give one back, is what the operator needs to know to
+ * shrink anything.
+ */
+export function withDynamicWorkerCapNamed<E>(ctx: object, error: E): E | Error {
+  if (classifyError(error) !== 'dynamic_worker_cap') return error;
+  const entry = ledger(ctx);
+  const platform = error instanceof Error ? error.message : String(error);
+  return new Error(
+    `${platform} — this Durable Object has ${entry.ids.size} loader id(s) permanently `
+      + `holding dynamic-worker slots (a loader.get id is never released): `
+      + `${[...entry.ids].join(', ') || '(none recorded)'}; live Loader fetches ${entry.liveFetches}, `
+      + `peak ${entry.peakLiveFetches}`,
+    { cause: error },
+  );
+}
+
+// ── Dynamic-worker module-map ceiling ───────────────────────────────────────
+
+/**
+ * Total bytes a dynamic Worker's module map may carry, across every member of
+ * it. A hard platform limit, not a policy knob: 62 MiB lands and 64 MiB is
+ * refused with "Dynamic Worker code size (N bytes) exceeds the maximum allowed
+ * size of 67108864 bytes", confirmed at five sizes with two trials each. The
+ * budget is shared, so a ruby process is already 34.3 MiB down before its disk
+ * is counted.
+ */
+export const DYNAMIC_WORKER_CODE_LIMIT_BYTES = 67_108_864;
+
+/**
+ * Refuse a module map over {@link DYNAMIC_WORKER_CODE_LIMIT_BYTES}, naming
+ * the largest members. The platform's own refusal reports one number for a
+ * budget shared across every member of the map, which tells the operator
+ * nothing about WHAT to shrink — so every fabric seam that assembles a map
+ * runs this before the loader sees it.
+ *
+ * Costed to its two paths. Under the ceiling: one length read per member —
+ * UTF-16 code units for text, which equal UTF-8 bytes for the ASCII module
+ * text the generators emit and undercount otherwise; the platform's own
+ * refusal still backstops the exotic case, because this check exists to name
+ * members, not to be the ceiling. Over it: exact UTF-8 sizes, computed only
+ * then, sorted so the biggest lever is first.
+ */
+export function assertModuleMapWithinCodeLimit(modules: Record<string, unknown>): void {
+  let estimate = 0;
+  for (const content of Object.values(modules)) {
+    estimate += memberBytes(content, null);
+  }
+  if (estimate <= DYNAMIC_WORKER_CODE_LIMIT_BYTES) return;
+
+  const encoder = new TextEncoder();
+  const sized = Object.entries(modules)
+    .map(([name, content]) => ({ name, bytes: memberBytes(content, encoder) }))
+    .sort((a, b) => b.bytes - a.bytes);
+  const total = sized.reduce((sum, member) => sum + member.bytes, 0);
+  const top = sized.slice(0, 5)
+    .map(({ name, bytes }) => `'${name}' (${bytes.toLocaleString('en-US')} bytes)`)
+    .join(', ');
+  throw new Error(
+    `Nimbus: dynamic-worker module map is ${total.toLocaleString('en-US')} bytes, over the `
+      + `${DYNAMIC_WORKER_CODE_LIMIT_BYTES.toLocaleString('en-US')}-byte platform ceiling shared by `
+      + `every member. Largest members: ${top}`,
+  );
+}
+
+/**
+ * Bytes one module-map member carries, across the loader's content kinds
+ * (plain string, `{ js | cjs | py | text }`, `{ wasm | data }`). With an
+ * encoder, text is measured exactly; without one, by code-unit length.
+ */
+function memberBytes(content: unknown, encoder: TextEncoder | null): number {
+  const textBytes = (text: string): number =>
+    encoder ? encoder.encode(text).byteLength : text.length;
+  if (typeof content === 'string') return textBytes(content);
+  if (content !== null && typeof content === 'object') {
+    for (const value of Object.values(content)) {
+      if (typeof value === 'string') return textBytes(value);
+      if (value instanceof ArrayBuffer) return value.byteLength;
+      if (ArrayBuffer.isView(value)) return value.byteLength;
+    }
+  }
+  return 0;
+}
+
+// ── Facet-ID lifetime budget ────────────────────────────────────────────────
+
+/**
+ * Facet IDs a Durable Object is granted over its LIFETIME. Append-only and
+ * never reclaimed, so crossing it is unrecoverable for the object — which is
+ * why the ledger below counts consumption durably instead of leaving the
+ * bound as prose the slot book merely respects.
+ */
+export const FACET_ID_LIFETIME_BUDGET = 65_536;
+
+/** Where the ledger persists the count of facet names ever minted. */
+export const FACET_NAME_HIGH_WATER_KEY = 'fabric_facet_name_high_water';
+
+/** The slice of storage the facet-name ledger persists through. */
+interface FacetNameLedgerStorage {
+  storage: {
+    get(key: string): Promise<unknown> | unknown;
+    put(key: string, value: unknown): Promise<void>;
+  };
+}
+
+/**
+ * One hosting actor's durable facet-name count, as an adopt-then-advance
+ * chain. It starts as the read of {@link FACET_NAME_HIGH_WATER_KEY} and
+ * every later link writes only a LARGER count — a fresh incarnation restarts
+ * its slot cursor at zero, and a write that had not adopted first would
+ * clobber the lifetime count down to this incarnation's. The chain never
+ * rejects.
+ */
+interface FacetNameLedger {
+  chain: Promise<number>;
+  /** The largest count the chain has adopted or durably written. */
+  known: number;
+  /** The largest count ever recorded this incarnation, durable or not. */
+  minted: number;
+}
+
+const facetNameLedgers = new WeakMap<object, FacetNameLedger>();
+
+function facetNameLedger(ctx: FacetNameLedgerStorage): FacetNameLedger {
+  let ledger = facetNameLedgers.get(ctx);
+  if (!ledger) {
+    const created: FacetNameLedger = { chain: Promise.resolve(0), known: 0, minted: 0 };
+    created.chain = Promise.resolve(ctx.storage.get(FACET_NAME_HIGH_WATER_KEY))
+      .then((value) => (typeof value === 'number' ? value : 0))
+      .catch(() => 0)
+      .then((adopted) => {
+        created.known = Math.max(created.known, adopted);
+        return adopted;
+      });
+    ledger = created;
+    facetNameLedgers.set(ctx, ledger);
+  }
+  return ledger;
+}
+
+/**
+ * Advance the durable ledger to this incarnation's name count, if it is a new
+ * lifetime high. Chained behind adoption so the comparison is always against
+ * the real persisted value; a failed write leaves the old link's count and the
+ * next mint tries again — the ledger may transiently undercount, never over.
+ */
+export function recordFacetNameMinted(ctx: FacetNameLedgerStorage, count: number): void {
+  const ledger = facetNameLedger(ctx);
+  ledger.minted = Math.max(ledger.minted, count);
+  ledger.chain = ledger.chain.then(async (durable) => {
+    if (count <= durable) return durable;
+    try {
+      await ctx.storage.put(FACET_NAME_HIGH_WATER_KEY, count);
+    } catch {
+      return durable;
+    }
+    ledger.known = Math.max(ledger.known, count);
+    return count;
+  });
+}
+
+/** The best count available without awaiting storage: minted or adopted. */
+export function facetNameCount(ctx: FacetNameLedgerStorage): number {
+  const ledger = facetNameLedger(ctx);
+  return Math.max(ledger.known, ledger.minted);
+}
+
+/** The count with adoption awaited, for a first failure on a fresh boot. */
+export async function facetNameCountDurable(ctx: FacetNameLedgerStorage): Promise<number> {
+  const ledger = facetNameLedger(ctx);
+  const durable = await ledger.chain;
+  return Math.max(durable, ledger.minted);
+}
+
+/**
+ * The lifetime facet-ID ledger: how many facet names this fabric has ever
+ * minted on the Durable Object, against the 65,536 the platform will ever
+ * grant it. `consumed` only ever counts FIRST uses — a reused name, in this
+ * incarnation or any earlier one, cost no new ID, which is the slot book's
+ * whole reason to exist. Surfaced so an operator can see proximity to a wall
+ * whose crossing is unrecoverable, instead of discovering it from the
+ * platform's opaque failure.
+ */
+export async function facetIdBudget(
+  ctx: FacetNameLedgerStorage,
+): Promise<{ consumed: number; budget: number }> {
+  return {
+    consumed: await facetNameCountDurable(ctx),
+    budget: FACET_ID_LIFETIME_BUDGET,
+  };
+}
+
+/**
+ * Name the facet-ID budget on a creation failure at the wall; below it, hand
+ * the error back untouched. Exhaustion is the one failure here the platform
+ * reports opaquely AND that no teardown, retry or reset can undo, so the
+ * ledger — the only witness to the real cause — does the naming. Not a
+ * threshold: the comparison is against the budget itself.
+ */
+export function withFacetBudgetNamed(consumed: number, error: unknown): unknown {
+  if (consumed < FACET_ID_LIFETIME_BUDGET) return error;
+  const platform = error instanceof Error ? error.message : String(error);
+  return new Error(
+    `Nimbus: facet creation failed with this Durable Object's `
+      + `${FACET_ID_LIFETIME_BUDGET.toLocaleString('en-US')} facet-ID lifetime budget consumed `
+      + `(${consumed} facet names ever created). Facet IDs are append-only and never reclaimed, `
+      + `so this failure is permanent for the object: ${platform}`,
+    { cause: error },
+  );
+}

package/src/composition.ts

@@ -0,0 +1,127 @@
+/**
+ * composition.ts — the ONE seam an embedder wires the fabric through.
+ *
+ * The fabric mints supervisor bindings and assembles staged boots for the
+ * programs it hosts, but the entrypoint class that answers those bindings and
+ * the artifact sources a stage names both belong to the embedder. The
+ * embedder states them once, in its composition root, with one call:
+ *
+ *   composeFabric({
+ *     supervisorEntrypoint: 'SupervisorRPC',
+ *     stagedBootAssembler: (env, stage) => assembleConfig(env, stage),
+ *   });
+ *
+ * First-write-wins, like every holder in this module: the composition root's
+ * module scope runs once per isolate, before any request.
+ *
+ * `ctx.exports` is runtime state, not composition: workerd mints it per
+ * instance, so the embedder captures it where the platform hands it over —
+ * the first fetch, or the DO constructor — with {@link adoptCtxExports}.
+ *
+ * This module stays a leaf (no fabric imports) so helpers (notably
+ * isolate-pool.ts) can read `ctx.exports` without transitively importing the
+ * Durable Object classes, which is what lets the pool be unit-tested in a
+ * plain Node/Bun process.
+ */
+
+/**
+ * One entry of `ctx.exports`: a top-level entrypoint's loopback factory, which
+ * mints a Service Binding stub for that entrypoint when called with props.
+ *
+ * The stub's RPC surface belongs to the entrypoint CLASS, which this leaf
+ * cannot see — `Cloudflare.Exports` is derived from the embedder's own main
+ * module, so for a library it evaluates to `{}`. A caller that knows the class
+ * names the surface it expects (`factory<MySupervisorRpc>({ props })`); one
+ * that does not gets `unknown` and has to narrow, same as
+ * `DurableObjectNamespace<T>` and `RpcStub<T>` in @cloudflare/workers-types.
+ */
+export type EntrypointLoopbackFactory = <Stub = unknown>(options: { props: object }) => Stub;
+
+/**
+ * `ctx.exports` itself — one factory per top-level entrypoint export, keyed by
+ * export name. Absent names read as undefined, which is how a caller finds out
+ * the embedder's entry module does not re-export the class it needs.
+ */
+export type CtxExports = Record<string, EntrypointLoopbackFactory | undefined>;
+
+/**
+ * Assemble a complete Worker Loader config from a staged-artifact spec. The
+ * embedder supplies this: a stage names artifact sources only the embedder
+ * knows how to fetch (Nimbus's largest staged artifact is a ~23 MB module map
+ * from ASSETS), and the assembler runs inside the loader's cache-miss callback
+ * so those sources are materialized only while the facet actually loads.
+ * `env` is whichever hosting actor's env the facet is opened with.
+ */
+export type StagedBootAssembler = (
+  env: unknown,
+  stage: unknown,
+) => Promise<object>;
+
+/** What an embedder states about itself, once, in its composition root. */
+export interface FabricComposition {
+  /**
+   * The ctx.exports name of the embedder's supervisor WorkerEntrypoint. The
+   * fabric mints one supervisor binding per hosted program from it
+   * (`env.SUPERVISOR` inside the facet).
+   */
+  supervisorEntrypoint: string;
+  /** Only embedders that use 'staged' boot specs supply one. */
+  stagedBootAssembler?: StagedBootAssembler;
+}
+
+let _composition: FabricComposition | null = null;
+
+/** Register the embedder's composition. First-write-wins. */
+export function composeFabric(composition: FabricComposition): void {
+  if (_composition) return;
+  _composition = composition;
+}
+
+let _ctxExports: CtxExports | null = null;
+
+/**
+ * Capture `ctx.exports` for the helpers that mint loopback bindings. The
+ * embedder calls this where the platform hands the bag over — the first
+ * fetch, or the DO constructor. First-write-wins.
+ */
+export function adoptCtxExports(value: CtxExports): void {
+  if (_ctxExports) return;
+  _ctxExports = value;
+}
+
+export function getCtxExports(): CtxExports | null {
+  return _ctxExports;
+}
+
+/**
+ * Resolve the composed supervisor entrypoint on an exports object —
+ * `exportsObj` when given (a WorkerEntrypoint reads its own ctx.exports),
+ * the adopted ctx.exports otherwise. Calling the result with props mints one
+ * supervisor binding (`env.SUPERVISOR`) for one hosted program. Null when
+ * either half is missing; the caller decides whether that degrades or throws.
+ */
+export function supervisorEntrypoint(exportsObj?: unknown): EntrypointLoopbackFactory | null {
+  const exports = exportsObj ?? _ctxExports;
+  const name = _composition?.supervisorEntrypoint;
+  if (!name) return null;
+  if ((typeof exports !== 'object' && typeof exports !== 'function') || exports === null) return null;
+  const factory = (exports as Record<string, unknown>)[name];
+  return typeof factory === 'function' ? (factory as EntrypointLoopbackFactory) : null;
+}
+
+/** The composed name, for error messages that point at the missing export. */
+export function supervisorEntrypointName(): string | null {
+  return _composition?.supervisorEntrypoint ?? null;
+}
+
+/** The composed assembler; a 'staged' boot spec cannot assemble without one. */
+export function stagedBootAssembler(): StagedBootAssembler {
+  const assembler = _composition?.stagedBootAssembler;
+  if (!assembler) {
+    throw new Error(
+      'fabric: no staged-boot assembler composed; a \'staged\' boot spec '
+        + 'cannot be assembled without one (composeFabric)',
+    );
+  }
+  return assembler;
+}