@nimbus-sh/fabric 0.1.0 → 0.3.0

package/dist/workerd-facet-host.js

@@ -12,10 +12,10 @@
  * that is not a Durable Object implements `ProcessHost` against the same
  * `HostedProcess` and never imports this file.
  */
-import { disposeRpcResource } from '@nimbus-sh/core/_shared/rpc-dispose.js';
-import { getCtxExports, supervisorEntrypoint, supervisorEntrypointName, } from './ctx-exports.js';
-import { beginLoaderFetch, recordLoaderId, withDynamicWorkerCapNamed, } from './loader-ledger.js';
-import { RESIDENT_PROCESS_CLASS, requireStagedBootAssembler, residentLoaderConfig, } from './process-fabric.js';
+import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
+import { getCtxExports, stagedBootAssembler, supervisorEntrypoint, supervisorEntrypointName, } from './composition.js';
+import { assertModuleMapWithinCodeLimit, beginLoaderFetch, facetNameCount, facetNameCountDurable, recordFacetNameMinted, recordLoaderId, withDynamicWorkerCapNamed, withFacetBudgetNamed, } from './budgets.js';
+import { RESIDENT_PROCESS_CLASS, residentLoaderConfig, } from './process-fabric.js';
 export function getNimbusCtxExports() {
     const ctxExports = getCtxExports();
     if (!ctxExports || typeof ctxExports !== 'object') {
@@ -43,69 +43,6 @@ export async function createLoadedWorkerEntrypoint(ctxExports, supervisor, stage
         },
     });
 }
-/**
- * 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) {
-    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, encoder) {
-    const textBytes = (text) => 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;
-}
 function facetContainer(ctx) {
     const facets = ctx.facets;
     if (!facets || typeof facets.get !== 'function') {
@@ -142,7 +79,7 @@ function facetContainer(ctx) {
  * storage budget grants no copy-on-write credit — crossing it resets the
  * object rather than raising an error.
  */
-export async function cloneFacetStorage(ctx, clone) {
+export async function cloneStorage(ctx, clone) {
     const facets = facetContainer(ctx);
     if (typeof facets.clone !== 'function') {
         throw new Error('Nimbus: ctx.facets.clone is unavailable in this runtime; the reflink image '
@@ -161,7 +98,7 @@ export async function cloneFacetStorage(ctx, clone) {
     }
 }
 /**
- * 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,
@@ -173,19 +110,18 @@ export async function cloneFacetStorage(ctx, clone) {
  * 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) {
     return `proc-slot-${slot}`;
 }
-/**
- * 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 prefix every durable application's facet name carries. */
+export const DURABLE_FACET_NAME_PREFIX = 'app-slot-';
 /**
  * Slot books, per hosting actor, because the facet index is per Durable
  * Object.
@@ -200,47 +136,21 @@ export const FACET_NAME_HIGH_WATER_KEY = 'fabric_facet_name_high_water';
  * 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();
 function slotBook(ctx) {
     let book = slotBooks.get(ctx);
     if (!book) {
-        const created = {
-            free: [],
-            next: 0,
-            held: new Map(),
-            ledger: Promise.resolve(0),
-            ledgerKnown: 0,
-        };
-        created.ledger = Promise.resolve(ctx.storage.get(FACET_NAME_HIGH_WATER_KEY))
-            .then((value) => (typeof value === 'number' ? value : 0))
-            .catch(() => 0)
-            .then((adopted) => {
-            created.ledgerKnown = Math.max(created.ledgerKnown, adopted);
-            return adopted;
-        });
-        book = created;
+        book = { free: [], next: 0, held: new Map() };
         slotBooks.set(ctx, book);
     }
     return book;
 }
-/**
- * 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) {
-    const book = slotBook(ctx);
-    const durable = await book.ledger;
-    return {
-        consumed: Math.max(durable, book.next),
-        budget: FACET_ID_LIFETIME_BUDGET,
-    };
-}
 /** Take a slot for `pid`, reusing a returned one before minting a new name. */
 function acquireSlot(ctx, pid) {
     const book = slotBook(ctx);
@@ -250,47 +160,12 @@ function acquireSlot(ctx, pid) {
     const reused = book.free.length > 0;
     const slot = reused ? book.free.shift() : book.next++;
     book.held.set(pid, slot);
+    // A fresh name is a permanently consumed facet ID; the durable count lives
+    // in the budgets ledger (see budgets.ts).
     if (!reused)
-        recordNameMinted(ctx, book);
+        recordFacetNameMinted(ctx, book.next);
     return slot;
 }
-/**
- * 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.
- */
-function recordNameMinted(ctx, book) {
-    const count = book.next;
-    book.ledger = book.ledger.then(async (durable) => {
-        if (count <= durable)
-            return durable;
-        try {
-            await ctx.storage.put(FACET_NAME_HIGH_WATER_KEY, count);
-        }
-        catch {
-            return durable;
-        }
-        book.ledgerKnown = Math.max(book.ledgerKnown, count);
-        return count;
-    });
-}
-/**
- * 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.
- */
-function withFacetBudgetNamed(consumed, error) {
-    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 });
-}
 /** Return `pid`'s slot to the free list. */
 function releaseSlot(ctx, pid) {
     const book = slotBook(ctx);
@@ -302,21 +177,72 @@ function releaseSlot(ctx, pid) {
     book.free.sort((a, b) => a - b);
 }
 /**
- * Open a resident process as a facet of the actor whose `ctx` and `env` are
- * given, and start its runner.
+ * 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, name) {
+    facetContainer(ctx).delete(name);
+}
+/**
+ * The process surface of one hosting actor: how a resident process comes
+ * into existence on workerd, and how a one-shot program runs to completion.
  *
- * This is the ONE way a resident process comes into existence, and every
+ * `spawn` is the ONE way a resident process comes into existence, and every
  * substrate goes through it: the facet host calls it with the coordinator's
  * own `ctx`, the peer host calls it — over one RPC — with a sibling session
  * DO's. Everything a substrate could plausibly want to special-case is a
  * PARAMETER here rather than a branch: which actor hosts the child, and how
  * the boot spec's by-path members are read.
  */
-export function openResidentFacet(ctx, env, disk, supervisor, params) {
+export function processes(ctx, env) {
+    return new Processes(ctx, env);
+}
+export class Processes {
+    ctx;
+    env;
+    constructor(ctx, env) {
+        this.ctx = ctx;
+        this.env = env;
+    }
+    /** Open a resident process as a facet of this actor, and start its runner. */
+    spawn(disk, supervisor, params) {
+        return spawnResident(this.ctx, this.env, disk, supervisor, params);
+    }
+    /**
+     * Run one program to completion as an UNKEYED dynamic worker.
+     *
+     * Unkeyed is the whole difference from `spawn`: nothing can re-resolve this
+     * worker into a later request's context, so it can never be a routeable
+     * target and never has to be released by name. It exists for the duration
+     * of one call and its stubs are dropped as that call unwinds.
+     *
+     * Shared by both substrates on purpose. `peer` places processes that have a
+     * residency to place; a one-shot has none, and shipping its fully-inline
+     * map across a sibling hop would meet the 32 MiB RPC ceiling that by-path
+     * boot specs exist to avoid — for a run that gains nothing by moving.
+     */
+    run(supervisor, params, consume) {
+        return runOneShot(this.ctx, this.env, supervisor, params, consume);
+    }
+}
+function spawnResident(ctx, env, disk, supervisor, params) {
     const facets = facetContainer(ctx);
-    const book = slotBook(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 —
@@ -341,8 +267,9 @@ export function openResidentFacet(ctx, env, disk, supervisor, params) {
         facet = facets.get(name, start);
     }
     catch (error) {
-        releaseSlot(ctx, params.pid);
-        throw withFacetBudgetNamed(Math.max(book.ledgerKnown, book.next), error);
+        if (slot !== undefined)
+            releaseSlot(ctx, params.pid);
+        throw withFacetBudgetNamed(facetNameCount(ctx), error);
     }
     let disposed = false;
     const release = async () => {
@@ -354,13 +281,21 @@ export function openResidentFacet(ctx, env, disk, supervisor, params) {
             facets.abort(name, new Error('Nimbus: resident process released'));
         }
         catch { /* already gone */ }
-        try {
-            facets.delete(name);
+        // 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 */ }
         }
-        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;
     try {
@@ -368,15 +303,14 @@ export function openResidentFacet(ctx, env, disk, supervisor, params) {
     }
     catch (error) {
         void release();
-        throw withFacetBudgetNamed(Math.max(book.ledgerKnown, book.next), error);
+        throw withFacetBudgetNamed(facetNameCount(ctx), error);
     }
     // The rejection that carries the platform's failure at ID exhaustion is
     // this one, and it is annotated AFTER awaiting the ledger — the first
     // failure of a fresh incarnation must compare against the persisted count,
     // not the zero its adoption read has not yet replaced.
     started = started.catch(async (error) => {
-        const durable = await book.ledger;
-        throw withFacetBudgetNamed(Math.max(durable, book.next), error);
+        throw withFacetBudgetNamed(await facetNameCountDurable(ctx), error);
     });
     // A caller reads whichever of `started` and the lifecycle it needs, so keep
     // the runtime from reporting the other as an unhandled rejection.
@@ -389,6 +323,7 @@ export function openResidentFacet(ctx, env, disk, supervisor, params) {
         handleHttpRequest: (request) => facet.handleHttpRequest(request),
         handleWebSocketRequest: (request) => facet.fetch(request),
         release,
+        name,
         slot,
     };
 }
@@ -415,20 +350,7 @@ function residentProcessClass(ctx, env, disk, supervisor, params) {
         throw withDynamicWorkerCapNamed(ctx, error);
     }
 }
-/**
- * Run one program to completion as an UNKEYED dynamic worker.
- *
- * Unkeyed is the whole difference from `openResidentFacet`: nothing can
- * re-resolve this worker into a later request's context, so it can never be a
- * routeable target and never has to be released by name. It exists for the
- * duration of one call and its stubs are dropped as that call unwinds.
- *
- * Shared by both substrates on purpose. `peer` places processes that have a
- * residency to place; a one-shot has none, and shipping its fully-inline map
- * across a sibling hop would meet the 32 MiB RPC ceiling that by-path boot
- * specs exist to avoid — for a run that gains nothing by moving.
- */
-export async function runOneShotWorker(ctx, env, supervisor, params, consume) {
+async function runOneShot(ctx, env, supervisor, params, consume) {
     const loader = env.LOADER;
     if (!loader || typeof loader.load !== 'function') {
         throw new Error('Nimbus: env.LOADER binding missing or invalid. Running a program requires '
@@ -495,14 +417,40 @@ export async function runOneShotWorker(ctx, env, supervisor, params, consume) {
         disposeRpcResource(supervisorBinding);
     }
 }
-async function residentWorkerConfig(env, disk, supervisor, boot) {
+/**
+ * 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, disk, supervisor, boot) {
+    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 requireStagedBootAssembler()(env, boot.stage)
+        ? await stagedBootAssembler()(env, boot.stage)
         : await residentLoaderConfig(boot.code, disk());
-    assertModuleMapWithinCodeLimit(config.modules ?? {});
+    assertModuleMapWithinCodeLimit(configModules(config));
     const supervisorRpc = supervisorEntrypoint();
     if (!supervisorRpc) {
         throw new Error(`Nimbus: ctx.exports.${supervisorEntrypointName() ?? '<supervisor entrypoint>'} unavailable`);
     }
     return { ...config, env: { SUPERVISOR: supervisorRpc({ props: supervisor }) } };
 }
+/** The module map a loader config assembled, or empty when it named none. */
+function configModules(config) {
+    const modules = '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 = modules;
+    return map;
+}

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.3.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.7.0",
+    "@nimbus-sh/platform": "^0.2.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {