@nimbus-sh/fabric 0.7.1 → 0.8.0

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 { hostRoute, supervisorEntrypoint, type HostRoute } 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';
@@ -527,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, route: opts?.supervisorRoute ?? hostRoute() ?? undefined },
+        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:
@@ -539,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,7 +74,7 @@
  * `ResidentDiskReader` it was given.
  */
 
-import type { HostRoute } from './composition.js';
+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';
@@ -210,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('');
 }
 
@@ -266,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 ?? {})) {
@@ -295,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 ───────────────────────────────────────────────────
@@ -311,18 +322,13 @@ 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;
-  /**
-   * The way back to the coordinator, minted with the binding. Absent only
-   * when the coordinator's isolate composed nothing, in which case no
-   * supervisor binding is minted either.
-   */
-  route?: HostRoute;
 }
 
 /** Everything a host needs to run one process. Substrate-free by construction. */
@@ -345,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;
 }
 
 /**
@@ -657,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.
@@ -701,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,7 +85,8 @@ import {
   processes,
   type ResidentFacetEnv,
 } from './workerd-facet-host.js';
-import { hostRoute, type HostRoute } from './composition.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';
@@ -138,19 +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, route: hostRoute() ?? undefined },
+      { ...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,
-      route: hostRoute() ?? undefined,
-    };
+    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,
@@ -198,6 +194,8 @@ export interface HostProcessOpts {
   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;
@@ -358,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, route: hostRoute() ?? undefined },
+      { ...supervisorBindingProps(this.ctx, params.pid), writerId: params.writerId },
       params,
       consume,
     );
@@ -383,11 +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,
-      route: hostRoute() ?? undefined,
-      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,
@@ -496,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}`;
+}

package/src/workerd-facet-host.ts

@@ -14,6 +14,8 @@
  */
 
 import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
+import { StorageLedger, forgetFacetStorage } from '@nimbus-sh/core/runtime/storage-ledger.js';
+import type { SqlDatabase } from '@nimbus-sh/core/runtime/os-contracts.js';
 import {
   getCtxExports,
   stagedBootAssembler,
@@ -41,6 +43,7 @@ import {
   type ResidentDiskReader,
   type ResidentSupervisorProps,
 } from './process-fabric.js';
+import { supervisorLoaderKey } from './supervisor-props.js';
 
 // ── Loaded-worker entrypoint plumbing ───────────────────────────────────────
 
@@ -56,7 +59,7 @@ export interface NimbusCtxExports {
       key: string;
       name: string | null;
       depth: number;
-      supervisor: { doId: string; pid: number; writerId: string };
+      supervisor: ResidentSupervisorProps;
       stage?: unknown;
     };
   }) => LoadedWorkerEntrypointStub;
@@ -78,7 +81,7 @@ export function getNimbusCtxExports(): NimbusCtxExports {
  */
 export async function createLoadedWorkerEntrypoint(
   ctxExports: NimbusCtxExports,
-  supervisor: { doId: string; pid: number; writerId: string },
+  supervisor: ResidentSupervisorProps,
   stage: unknown,
   name: string | null = null,
 ): Promise<LoadedWorkerEntrypointStub> {
@@ -87,7 +90,9 @@ export async function createLoadedWorkerEntrypoint(
   }
   return await ctxExports.NimbusLoadedEntrypoint({
     props: {
-      key: `nimbus-process:${supervisor.doId}:${supervisor.pid}`,
+      // The entrypoint's loader outlives this instance, and a warm worker keeps
+      // the SUPERVISOR binding it was built with.
+      key: supervisorLoaderKey(`nimbus-process:${supervisor.doId}:${supervisor.pid}`, supervisor),
       name,
       depth: 0,
       supervisor,
@@ -262,26 +267,25 @@ interface SlotBook {
   next: number;
   /** Slot held by each live pid, so release can find it. */
   held: Map<number, number>;
+  /** Explicit (`app-slot-`) names this incarnation started a process under and has not released. */
+  live: Set<string>;
 }
 
 /**
  * Slot books, per hosting actor, because the facet index is per Durable
  * Object.
  *
- * Keyed weakly off `ctx`, and that is sound rather than lossy: a facet cannot
- * outlive the Durable Object hosting it, so a book that goes away with its
- * host describes nothing that still exists. A fresh incarnation restarts at
- * slot 0 and re-attaches to the SQLite a previous incarnation left there —
- * which is safe for the reason the store is sealed until it has reconciled.
- * Its persisted cursor is either datable against the current authority, in
- * which case the ACQUIRE delta brings it current, or it carries a different
- * 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.
+ * Keyed weakly off `ctx`, so a book describes one incarnation. A facet that
+ * is still running when that incarnation ends outlives it (measured: a timer
+ * or an outgoing call keeps it going), and a `get` of its name with a new
+ * class then resets the whole object. So a fresh incarnation's first get of
+ * each name ends whatever runs there first: a minted `proc-slot-` name is
+ * deleted, which also wipes the storage a previous incarnation left, and an
+ * explicit name is aborted, which keeps it.
  *
- * 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
+ * The book allocates 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>();
@@ -289,24 +293,28 @@ const slotBooks = new WeakMap<DurableObjectState, SlotBook>();
 function slotBook(ctx: DurableObjectState): SlotBook {
   let book = slotBooks.get(ctx);
   if (!book) {
-    book = { free: [], next: 0, held: new Map() };
+    book = { free: [], next: 0, held: new Map(), live: new Set() };
     slotBooks.set(ctx, book);
   }
   return book;
 }
 
-/** Take a slot for `pid`, reusing a returned one before minting a new name. */
-function acquireSlot(ctx: DurableObjectState, pid: number): number {
+/**
+ * Take a slot for `pid`, reusing a returned one before minting a new name.
+ * `minted` names may still hold storage a previous incarnation of this actor
+ * left there, so the caller deletes it before the first get.
+ */
+function acquireSlot(ctx: DurableObjectState, pid: number): { slot: number; minted: boolean } {
   const book = slotBook(ctx);
   const existing = book.held.get(pid);
-  if (existing !== undefined) return existing;
+  if (existing !== undefined) return { slot: existing, minted: false };
   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) recordFacetNameMinted(ctx, book.next);
-  return slot;
+  return { slot, minted: !reused };
 }
 
 /** Return `pid`'s slot to the free list. */
@@ -320,14 +328,36 @@ function releaseSlot(ctx: DurableObjectState, pid: number): void {
 }
 
 /**
- * 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.
+ * Drop one facet's SQLite by name, and its row in the session's storage
+ * ledger (N18) in the same step: the only way a facet database is deleted.
+ * `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.
  */
+/** The session's storage ledger (N18), over this actor's SQL; null where it has none. */
+function sessionLedger(ctx: DurableObjectState): StorageLedger | null {
+  const sql = (ctx as { storage?: { sql?: SqlDatabase } }).storage?.sql;
+  return sql ? new StorageLedger(sql) : null;
+}
+
+const facetNames = new WeakMap<object, Map<number, string>>();
+
+function facetOfPid(ctx: DurableObjectState): Map<number, string> {
+  let names = facetNames.get(ctx);
+  if (!names) facetNames.set(ctx, names = new Map());
+  return names;
+}
+
+/** The facet a running resident process `pid` lives in on this actor, for its storage ledger row. */
+export function residentFacetOf(ctx: DurableObjectState, pid: number): string | undefined {
+  return facetNames.get(ctx)?.get(pid);
+}
+
 export function deleteFacetStorage(ctx: DurableObjectState, name: string): void {
   facetContainer(ctx).delete(name);
+  const sql = (ctx as { storage?: { sql?: SqlDatabase } }).storage?.sql;
+  if (sql) forgetFacetStorage(sql, name);
 }
 
 
@@ -416,8 +446,12 @@ function spawnResident(
         + `prefix, got '${explicit.name}'`,
     );
   }
-  const slot = explicit ? undefined : acquireSlot(ctx, params.pid);
+  const grant = explicit ? undefined : acquireSlot(ctx, params.pid);
+  const slot = grant?.slot;
   const name = explicit ? explicit.name : residentFacetName(slot!);
+  if (grant?.minted) {
+    try { deleteFacetStorage(ctx, name); } catch { /* nothing stored under this name */ }
+  }
   // 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 —
@@ -439,27 +473,40 @@ function spawnResident(
     evaluated = true;
     return { class: residentProcessClass(ctx, env, disk, supervisor, params) };
   };
+  const book = slotBook(ctx);
+  const ledger = sessionLedger(ctx);
   let facet: ResidentFacetStub;
   try {
+    // N18: the fill is admitted, and recorded under the facet's name, before
+    // the facet exists; a refusal leaves no facet.
+    if (ledger !== null && params.storageBytes !== undefined) ledger.fill(name, params.storageBytes);
+    // get() with a new class on a facet an earlier incarnation left running resets this object.
+    if (explicit && !book.live.has(name)) {
+      facets.abort(name, new Error('Nimbus: a new incarnation takes this facet name'));
+    }
     facet = facets.get(name, start);
   } catch (error) {
     if (slot !== undefined) releaseSlot(ctx, params.pid);
     throw withFacetBudgetNamed(facetNameCount(ctx), error);
   }
+  if (explicit) book.live.add(name);
+  facetOfPid(ctx).set(params.pid, name);
 
   let disposed = false;
   const release = async () => {
     if (disposed) return;
     disposed = true;
     released = true;
+    facetOfPid(ctx).delete(params.pid);
     try { facets.abort(name, new Error('Nimbus: resident process released')); } catch { /* already gone */ }
+    if (explicit) book.live.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 */ }
+      try { deleteFacetStorage(ctx, 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.
@@ -468,7 +515,11 @@ function spawnResident(
 
   let started: Promise<unknown>;
   try {
-    started = facet.startProcess(params.startArgs);
+    // The allowance the ledger admitted, for the facet's store to keep under.
+    const startArgs = ledger !== null && params.storageBytes !== undefined && params.startArgs !== null && typeof params.startArgs === 'object'
+      ? { ...(params.startArgs as Record<string, unknown>), storage: { facet: name, grant: params.storageBytes } }
+      : params.startArgs;
+    started = facet.startProcess(startArgs);
   } catch (error) {
     void release();
     throw withFacetBudgetNamed(facetNameCount(ctx), error);
@@ -477,7 +528,17 @@ function spawnResident(
   // 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) => {
+  started = started.then((payload) => {
+    // Once the facet is up (N18) its row is the cap its store keeps under
+    // (what it measures plus what it may still grow into), or what it
+    // measures if that is more (overshoot).
+    const { databaseSize: size, storageCap: cap } = (payload ?? {}) as { databaseSize?: unknown; storageCap?: unknown };
+    const measured = typeof size === 'number' && Number.isFinite(size) ? size : null;
+    const capped = typeof cap === 'number' && Number.isFinite(cap) ? cap : null;
+    const row = capped !== null ? Math.max(capped, measured ?? 0) : measured;
+    if (ledger !== null && row !== null) ledger.reportSize(name, row);
+    return payload;
+  }, async (error) => {
     throw withFacetBudgetNamed(await facetNameCountDurable(ctx), error);
   });
   // A caller reads whichever of `started` and the lifecycle it needs, so keep
@@ -516,11 +577,14 @@ function residentProcessClass(
         + 'the Worker Loader binding; add it via worker_loaders in wrangler.jsonc.',
     );
   }
+  // A warm worker keeps the SUPERVISOR binding it was built with, and the
+  // loader outlives this instance.
+  const loaderKey = supervisorLoaderKey(params.workerKey, supervisor);
   try {
     const worker = loader
-      .get(params.workerKey, () => residentWorkerConfig(env, disk, supervisor, params.boot))
+      .get(loaderKey, () => residentWorkerConfig(env, disk, supervisor, params.boot))
       .getDurableObjectClass(RESIDENT_PROCESS_CLASS);
-    recordLoaderId(ctx, params.workerKey);
+    recordLoaderId(ctx, loaderKey);
     return worker;
   } catch (error) {
     throw withDynamicWorkerCapNamed(ctx, error);