@nimbus-sh/fabric 0.2.0 → 0.3.0

package/dist/workerd-facet-host.d.ts

@@ -12,7 +12,7 @@
  * that is not a Durable Object implements `ProcessHost` against the same
  * `HostedProcess` and never imports this file.
  */
-import { type HostedProcess, type OneShotParams, type ProcessHostParams, type ResidentDiskReader, type ResidentSupervisorProps } from './process-fabric.js';
+import { type HostedProcess, type OneShotParams, type ProcessHostParams, type ResidentBootSpec, type ResidentDiskReader, type ResidentSupervisorProps } from './process-fabric.js';
 /** Structural surface of a NimbusLoadedEntrypoint RPC stub. */
 export interface LoadedWorkerEntrypointStub {
     handleHttpRequest?: (request: Request) => Promise<Response>;
@@ -57,9 +57,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>): {
+    get(id: string | null, code: () => unknown): {
         getDurableObjectClass(name: string): unknown;
     };
     load(code: unknown): LoadedWorkerStub;
@@ -106,7 +111,7 @@ export declare function cloneStorage(ctx: DurableObjectState, clone: {
     populated(name: string): boolean | Promise<boolean>;
 }): Promise<void>;
 /**
- * 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,
@@ -118,18 +123,36 @@ export declare function cloneStorage(ctx: DurableObjectState, 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 declare function residentFacetName(slot: number): string;
+/** The prefix every durable application's facet name carries. */
+export declare const DURABLE_FACET_NAME_PREFIX = "app-slot-";
+/**
+ * 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 declare function deleteFacetStorage(ctx: DurableObjectState, name: string): void;
 /**
  * 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;
+    name: string;
+    slot?: number;
 };
 /**
  * The process surface of one hosting actor: how a resident process comes
@@ -164,5 +187,18 @@ export declare class Processes {
      */
     run<T>(supervisor: ResidentSupervisorProps, params: OneShotParams, consume: (response: Response) => Promise<T>): Promise<T>;
 }
+/**
+ * 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 declare function residentWorkerConfig(env: ResidentFacetEnv, disk: () => ResidentDiskReader, supervisor: ResidentSupervisorProps, boot: ResidentBootSpec): Promise<Record<string, unknown>>;
 export {};
 //# sourceMappingURL=workerd-facet-host.d.ts.map

package/dist/workerd-facet-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workerd-facet-host.d.ts","sourceRoot":"","sources":["../src/workerd-facet-host.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workerd-facet-host.d.ts","sourceRoot":"","sources":["../src/workerd-facet-host.ts"],"names":[],"mappings":"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"}

package/dist/workerd-facet-host.js

@@ -98,7 +98,7 @@ export async function cloneStorage(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,
@@ -110,10 +110,18 @@ export async function cloneStorage(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}`;
 }
+/** 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.
@@ -128,6 +136,11 @@ export function residentFacetName(slot) {
  * 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) {
@@ -163,6 +176,16 @@ function releaseSlot(ctx, pid) {
     book.free.push(slot);
     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, 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.
@@ -207,8 +230,19 @@ export class Processes {
 }
 function spawnResident(ctx, env, disk, supervisor, params) {
     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 —
@@ -233,7 +267,8 @@ function spawnResident(ctx, env, disk, supervisor, params) {
         facet = facets.get(name, start);
     }
     catch (error) {
-        releaseSlot(ctx, params.pid);
+        if (slot !== undefined)
+            releaseSlot(ctx, params.pid);
         throw withFacetBudgetNamed(facetNameCount(ctx), error);
     }
     let disposed = false;
@@ -246,13 +281,21 @@ function spawnResident(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 {
@@ -280,6 +323,7 @@ function spawnResident(ctx, env, disk, supervisor, params) {
         handleHttpRequest: (request) => facet.handleHttpRequest(request),
         handleWebSocketRequest: (request) => facet.fetch(request),
         release,
+        name,
         slot,
     };
 }
@@ -373,14 +417,40 @@ async function runOneShot(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 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-sh/fabric",
-  "version": "0.2.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",
@@ -50,8 +50,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@nimbus-sh/core": "^0.6.0",
-    "@nimbus-sh/platform": "^0.1.0",
+    "@nimbus-sh/core": "^0.7.0",
+    "@nimbus-sh/platform": "^0.2.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/src/composition.ts

@@ -1,127 +1,16 @@
-/**
- * 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;
-}
+// Core and fabric share one holder without introducing a dependency cycle.
+export {
+  adoptCtxExports,
+  composeFabric,
+  getCtxExports,
+  stagedBootAssembler,
+  supervisorEntrypoint,
+  supervisorEntrypointName,
+} from '@nimbus-sh/platform/composition.js';
+
+export type {
+  CtxExports,
+  EntrypointLoopbackFactory,
+  FabricComposition,
+  StagedBootAssembler,
+} from '@nimbus-sh/platform/composition.js';

package/src/fenced-work.ts

@@ -133,6 +133,9 @@ export class FencedWork<R extends FencedWorkRecord> {
    * paying a storage delete for pids that never had a row.
    */
   private journalledPids = new Set<number>();
+  /** Re-drives in flight, by journal key — recovery's un-awaited ones and a
+   *  caller-driven one share the same drive for the same row. */
+  private drives = new Map<string, Promise<boolean>>();
   /** Whether this instance has already read the journal a reset leaves behind. */
   private recovered = false;
 
@@ -143,8 +146,8 @@ export class FencedWork<R extends FencedWorkRecord> {
 
   /**
    * Record a launch as in flight, so an instance that replaces this one knows
-   * it never finished. Best-effort: a launch that cannot be journalled still
-   * runs, and a reset then costs exactly what it cost before the journal.
+   * it never finished. A launch that cannot be journalled does not start: the
+   * rejection reaches the caller, which reports it like any launch failure.
    *
    * Synced, not merely put: `await put()` resolves before durability, and the
    * reset this journal exists for destroys every write its turn still had
@@ -157,12 +160,12 @@ export class FencedWork<R extends FencedWorkRecord> {
    * losing its row costs a retype, not a recovery.
    */
   async journal(record: R): Promise<void> {
+    this.journalledPids.add(record.pid);
     try {
-      this.journalledPids.add(record.pid);
       await this.storage.put(`${FENCED_WORK_KEY_PREFIX}${record.pid}`, record);
       await this.storage.sync();
-    } catch (e: unknown) {
-      console.warn('[nimbus] resident launch journal write failed:', errorMessage(e));
+    } catch (cause: unknown) {
+      throw new Error('resident launch journal write failed', { cause });
     }
   }
 
@@ -178,12 +181,68 @@ export class FencedWork<R extends FencedWorkRecord> {
    */
   async release(pid: number): Promise<void> {
     if (!this.journalledPids.delete(pid)) return;
-    try {
-      await this.storage.delete(`${FENCED_WORK_KEY_PREFIX}${pid}`);
-      await this.storage.sync();
-    } catch (e: unknown) {
-      console.warn('[nimbus] resident launch journal delete failed:', errorMessage(e));
+    await this.storage.delete(`${FENCED_WORK_KEY_PREFIX}${pid}`);
+    await this.storage.sync();
+  }
+
+  /**
+   * Drop every row `predicate` claims, live-pid bookkeeping included, synced
+   * like {@link release}. The one bulk delete the journal admits: an owner
+   * that removes its durable application is owed no recovery, however many
+   * generations back its rows were written.
+   */
+  async purgeWhere(predicate: (record: R) => boolean): Promise<number> {
+    const rows = await this.storage.list<R>({ prefix: FENCED_WORK_KEY_PREFIX });
+    let purged = 0;
+    for (const [key, record] of rows) {
+      if (!predicate(record)) continue;
+      this.journalledPids.delete(record.pid);
+      await this.storage.delete(key);
+      purged += 1;
+    }
+    if (purged > 0) await this.storage.sync();
+    return purged;
+  }
+
+  /**
+   * Every journal row, storage-true — the rows this instance wrote and the
+   * ones a previous instance left behind. The one read surface a request-
+   * driven recovery needs to find the durable launch a port belongs to.
+   */
+  async rows(): Promise<Map<string, R>> {
+    return this.storage.list<R>({ prefix: FENCED_WORK_KEY_PREFIX });
+  }
+
+  /**
+   * Re-drive one journal row — the awaited sibling of recovery's un-awaited
+   * re-drives, for a caller that must know whether the launch actually came
+   * back. Single-flight per row: a request-driven drive and recovery's own
+   * never boot the same launch twice. Resolves true only when the re-drive
+   * itself FAILED and the failure was reported; a settled drive supersedes
+   * the row the same way recovery's does.
+   */
+  drive(key: string, record: R): Promise<boolean> {
+    let inflight = this.drives.get(key);
+    if (inflight === undefined) {
+      inflight = (async (): Promise<boolean> => {
+        let failed = false;
+        try {
+          await this.host.redrive(record, record.attempt + 1);
+        } catch (e: unknown) {
+          this.host.onRedriveFailed?.(record, e);
+          failed = true;
+        }
+        // A reported failure is settled business — supersede either way, so
+        // the row never re-surfaces on the next recovery.
+        await this.supersede(key);
+        return failed;
+      })();
+      this.drives.set(key, inflight);
+      inflight.finally(() => {
+        if (this.drives.get(key) === inflight) this.drives.delete(key);
+      });
     }
+    return inflight;
   }
 
   /**
@@ -195,8 +254,12 @@ export class FencedWork<R extends FencedWorkRecord> {
    * that replaces this one. So the first turn after a reset is already this
    * one.
    *
-   * Runs once per instance: the journal only changes when a launch of THIS
-   * instance starts or settles, and those are rows this instance wrote.
+   * Runs once per instance — re-calls in the same instance are no-ops — and
+   * re-drives every row whose pid is `> 0` and at or below `generationBase()`
+   * with `attempt < FENCED_WORK_MAX_ATTEMPT`; the rest are abandoned. What the
+   * re-drive resolver receives is the journalled recipe and nothing else:
+   * env and credentials are never written to storage, so the resolver's
+   * embedder re-resolves them rather than reading them back.
    */
   async recoverInterrupted(): Promise<void> {
     if (this.recovered) return;
@@ -233,14 +296,10 @@ export class FencedWork<R extends FencedWorkRecord> {
       // Not awaited: this call is running inside the alarm that granted the
       // turn, and the launch it starts asks for turns of its own through that
       // same alarm — awaiting it here would be waiting on an alarm that cannot
-      // be scheduled until this one returns.
-      this.host.waitUntil(
-        this.host.redrive(record, record.attempt + 1)
-          .catch((e: unknown) => {
-            this.host.onRedriveFailed?.(record, e);
-          })
-          .then(() => this.supersede(key)),
-      );
+      // be scheduled until this one returns. `drive` single-flights it: a
+      // request that arrives mid-launch waits on this same drive rather than
+      // booting a second process.
+      this.host.waitUntil(this.drive(key, record));
     }
   }
 
@@ -251,15 +310,7 @@ export class FencedWork<R extends FencedWorkRecord> {
    * a previous generation the terminal hook will never fire for.
    */
   private async supersede(key: string): Promise<void> {
-    try {
-      await this.storage.delete(key);
-      await this.storage.sync();
-    } catch (e: unknown) {
-      console.warn('[nimbus] resident launch journal supersede failed:', errorMessage(e));
-    }
+    await this.storage.delete(key);
+    await this.storage.sync();
   }
 }
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}