@nimbus-sh/fabric 0.1.0 → 0.3.0

package/src/{launch-journal.ts → fenced-work.ts}

@@ -1,5 +1,5 @@
 /**
- * launch-journal.ts — durable record of the resident launches a Durable Object
+ * fenced-work.ts — durable record of the resident launches a Durable Object
  * owes, and their recovery after an instance reset.
  *
  * The platform resets a session Durable Object over what one turn has
@@ -14,7 +14,7 @@
  *
  * What a launch IS stays the embedder's: the journal stores the record it is
  * given and hands it back on recovery. The mechanism reads only the fields in
- * {@link ResidentLaunchRecord}; everything else in the record rides through
+ * {@link FencedWorkRecord}; everything else in the record rides through
  * opaquely.
  */
 
@@ -37,10 +37,10 @@
  * storage key is a migration, and orphaned rows are the least of what it
  * breaks.
  */
-export const RESIDENT_LAUNCH_KEY_PREFIX = 'resident-launch:';
+export const FENCED_WORK_KEY_PREFIX = 'resident-launch:';
 
 /** A launch is re-driven once. A reset that recurs is not the transient one. */
-export const RESIDENT_LAUNCH_MAX_ATTEMPT = 1;
+export const FENCED_WORK_MAX_ATTEMPT = 1;
 
 /**
  * A resident process this session owes the user, as a later instance would
@@ -60,7 +60,7 @@ export const RESIDENT_LAUNCH_MAX_ATTEMPT = 1;
  * process host's held-open leg dies with it), so a row from a previous
  * generation always names a process that is genuinely gone.
  */
-export interface ResidentLaunchRecord {
+export interface FencedWorkRecord {
   pid: number;
   command: string;
   /** 0 for a launch the user asked for; 1 for the one re-drive it may get. */
@@ -74,9 +74,9 @@ export interface ResidentLaunchRecord {
 /**
  * The slice of Durable Object storage the journal writes through. Exactly a
  * `DurableObjectStorage`, narrowed to what the mechanism performs — `sync()`
- * is load-bearing, see {@link ResidentLaunchJournal.journal}.
+ * is load-bearing, see {@link FencedWork.journal}.
  */
-export interface LaunchJournalStorage {
+export interface FencedWorkStorage {
   put(key: string, value: unknown): Promise<void>;
   delete(key: string): Promise<boolean>;
   list<T = unknown>(options: { prefix: string }): Promise<Map<string, T>>;
@@ -84,7 +84,7 @@ export interface LaunchJournalStorage {
 }
 
 /** What the journal's recovery needs from its embedder. */
-export interface LaunchJournalHost<R extends ResidentLaunchRecord> {
+export interface FencedWorkHost<R extends FencedWorkRecord> {
   /**
    * The current instance generation's pid floor. A pid at or below it was
    * allocated by a PREVIOUS instance (core's process-table, PID_GEN_STRIDE),
@@ -94,8 +94,13 @@ export interface LaunchJournalHost<R extends ResidentLaunchRecord> {
    */
   generationBase(): number;
   /**
-   * Root a recovery re-drive on the instance (`ctx.waitUntil`) so it is not
-   * an abandoned promise between turns.
+   * Where an un-awaited re-drive goes so it is not a floating rejection —
+   * `ctx.waitUntil` in practice. Hygiene, not retention: a Durable Object
+   * cancels an in-flight promise on reset with no signal, and workerd's
+   * `waitUntil` is a no-op there (PLATFORM.md, probe 2026-08-17 — awaiting
+   * inside the invocation is the only retention an actor has). The recovery
+   * guarantee comes from the journal row and the platform's alarm
+   * re-delivery, never from this hook.
    */
   waitUntil(promise: Promise<unknown>): void;
   /**
@@ -121,25 +126,28 @@ export interface LaunchJournalHost<R extends ResidentLaunchRecord> {
  * read the journal a reset leaves behind. Rows from a previous instance are
  * recovery's to consume, never the release path's.
  */
-export class ResidentLaunchJournal<R extends ResidentLaunchRecord> {
+export class FencedWork<R extends FencedWorkRecord> {
   /**
    * Pids THIS instance holds journal rows for. What keeps the terminal hook —
    * which fires for every process, shells and one-shots included — from
    * 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;
 
   constructor(
-    private readonly storage: LaunchJournalStorage,
-    private readonly host: LaunchJournalHost<R>,
+    private readonly storage: FencedWorkStorage,
+    private readonly host: FencedWorkHost<R>,
   ) {}
 
   /**
    * 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
@@ -152,12 +160,12 @@ export class ResidentLaunchJournal<R extends ResidentLaunchRecord> {
    * 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(`${RESIDENT_LAUNCH_KEY_PREFIX}${record.pid}`, record);
+      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 });
     }
   }
 
@@ -173,12 +181,68 @@ export class ResidentLaunchJournal<R extends ResidentLaunchRecord> {
    */
   async release(pid: number): Promise<void> {
     if (!this.journalledPids.delete(pid)) return;
-    try {
-      await this.storage.delete(`${RESIDENT_LAUNCH_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;
   }
 
   /**
@@ -190,40 +254,63 @@ export class ResidentLaunchJournal<R extends ResidentLaunchRecord> {
    * 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;
     this.recovered = true;
-    const journal = await this.storage.list<R>({ prefix: RESIDENT_LAUNCH_KEY_PREFIX });
+    const journal = await this.storage.list<R>({ prefix: FENCED_WORK_KEY_PREFIX });
     const base = this.host.generationBase();
+    const abandoned: Array<[string, R]> = [];
+    const redriven: Array<[string, R]> = [];
     for (const [key, record] of journal) {
       // A pid at or below this instance's base was allocated by a PREVIOUS one
       // (process-table.ts, PID_GEN_STRIDE), so its launch never finished; above
       // the base is this instance's own, still running. Same predicate as
       // `session/rpc.ts` uses to attribute a prior generation's pid.
       if (!(record.pid > 0 && record.pid <= base)) continue;
-      await this.storage.delete(key);
-      if (record.attempt >= RESIDENT_LAUNCH_MAX_ATTEMPT) {
-        this.host.onAbandoned?.(record);
-        continue;
-      }
+      (record.attempt >= FENCED_WORK_MAX_ATTEMPT ? abandoned : redriven).push([key, record]);
+    }
+    // The attempt is SPENT in storage, synced, before any re-drive starts.
+    // Deleting the row here instead would open a loss window: writes flush in
+    // order, so a reset between the delete's flush and the re-driven launch's
+    // own journal write leaves a durable state with no row for an owed
+    // launch — and the un-awaited re-drive dies with the instance (waitUntil
+    // retains nothing). With the rewrite, every durable cut is either the
+    // untouched row (recovery re-runs) or a spent attempt (the recurrence
+    // abandons loudly). The superseded row is deleted only when its re-drive
+    // settles, after the launch's own row exists.
+    for (const [key] of abandoned) await this.storage.delete(key);
+    for (const [key, record] of redriven) {
+      await this.storage.put(key, { ...record, attempt: record.attempt + 1 });
+    }
+    if (abandoned.length > 0 || redriven.length > 0) await this.storage.sync();
+    for (const [, record] of abandoned) this.host.onAbandoned?.(record);
+    for (const [key, record] of redriven) {
       this.host.onRedrive?.(record);
       // 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);
-          }),
-      );
+      // 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));
     }
   }
-}
 
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+  /**
+   * Delete a row whose re-drive has settled — succeeded, failed and been
+   * reported, or handed off to its own journal row. Not `release()`: that
+   * path is for pids THIS instance journalled, and this row's pid belongs to
+   * a previous generation the terminal hook will never fire for.
+   */
+  private async supersede(key: string): Promise<void> {
+    await this.storage.delete(key);
+    await this.storage.sync();
+  }
 }

package/src/generation.ts

@@ -0,0 +1,144 @@
+/**
+ * generation.ts — the isolate-generation clock, and the deferred
+ * reconciliation that runs once per fresh incarnation.
+ *
+ * Workerd hibernates Durable Objects between requests to free memory. On
+ * wake, the new isolate must rebuild its in-memory state from SQL — but it
+ * also needs to know "is this the same lifecycle as before, or did workerd
+ * recycle me?" That distinction matters for recovery (warmJoin vs cold init)
+ * and is captured by the isolate generation, a counter persisted across
+ * hibernations.
+ *
+ * State is keyed weakly off the actor's `ctx`, which lives exactly as long as
+ * the incarnation: a fresh isolate gets a fresh `ctx`, adopts the persisted
+ * counter, and bumps it once. The embedder reads `generation(ctx)` wherever it
+ * needs the incarnation number — one source of truth instead of mirrored host
+ * fields.
+ */
+
+import { errorText } from '@nimbus-sh/core/_shared/error-text.js';
+
+/**
+ * Storage key for the isolate-generation counter (cold-start +
+ * post-hibernation wake; one increment per fresh isolate).
+ *
+ * The VALUE is live production DO storage ('w9_isolate_gen') and must never
+ * change — renaming a storage key is a migration, and orphaned rows are the
+ * least of what it breaks.
+ */
+export const GENERATION_KEY = 'w9_isolate_gen';
+
+/** The storage the generation counter persists through. */
+export interface GenerationStorage {
+  get(key: string): Promise<unknown>;
+  put(key: string, value: unknown): Promise<void>;
+}
+
+/** The hosting actor's context, as the generation clock reads it. */
+export interface GenerationContext {
+  storage: GenerationStorage;
+}
+
+interface GenerationState {
+  value: number;
+  adopted: boolean;
+  /** Deferred reconciliation tasks, drained by {@link runColdStart}. */
+  coldStart: Array<() => Promise<unknown>>;
+  /** Serializes drains so two callers never run one task twice. */
+  coldStartChain: Promise<void>;
+}
+
+const states = new WeakMap<object, GenerationState>();
+
+function stateOf(ctx: object): GenerationState {
+  let state = states.get(ctx);
+  if (!state) {
+    state = { value: 0, adopted: false, coldStart: [], coldStartChain: Promise.resolve() };
+    states.set(ctx, state);
+  }
+  return state;
+}
+
+/** This incarnation's generation. Zero until {@link adoptGeneration} ran. */
+export function generation(ctx: object): number {
+  return states.get(ctx)?.value ?? 0;
+}
+
+/** Increment + persist the generation counter once per fresh isolate. */
+export async function adoptGeneration(ctx: GenerationContext): Promise<void> {
+  const state = stateOf(ctx);
+  if (state.adopted) return;
+  state.adopted = true;
+  try {
+    const prev = (await ctx.storage.get(GENERATION_KEY)) as number | undefined;
+    // Adopt the persisted truth first, and adopt the bump only after the
+    // put resolves. An unpersisted `next` would be re-read as `prev` by the
+    // NEXT boot and re-issued — two instances sharing one generation is
+    // exactly the pid-aliasing this counter exists to prevent. Running on
+    // the previous persisted generation is the lesser lapse, and the
+    // put-failure case is replica-only in practice (replicas never spawn).
+    //
+    // What holds the guarantee is the output gate, not this await: measured,
+    // the block body resolves in 0 ms even with a confirmed put, because
+    // `await storage.put()` returns before durability. The gate is what
+    // keeps a pid from generation N from escaping before N is durable, which
+    // is why marking this put `allowUnconfirmed` is not a free speedup — see
+    // scratchpad/coldstart-s1.md.
+    state.value = typeof prev === 'number' ? prev : 0;
+    const next = state.value + 1;
+    await ctx.storage.put(GENERATION_KEY, next);
+    state.value = next;
+  } catch (e) {
+    console.warn('[nimbus/W9] generation bump failed:', errorText(e));
+  }
+}
+
+/**
+ * Take on a generation without persisting it, and clear the adopted guard so
+ * a later {@link adoptGeneration} re-derives from storage. The
+ * destroy-and-recreate path uses this: it wipes storage, re-persists the
+ * pre-destroy counter, and runs the rest of this incarnation on the successor
+ * generation the next boot will derive.
+ */
+export function assumeGeneration(ctx: object, value: number): void {
+  const state = stateOf(ctx);
+  state.value = value;
+  state.adopted = false;
+}
+
+/**
+ * Queue deferred async reconciliation for this incarnation.
+ *
+ * The task runs on the first {@link runColdStart} after registration — a turn
+ * the embedder already owns, NEVER the constructor's init gate. Awaiting
+ * recovery on the gate path is the trap this helper exists to avoid: the gate
+ * blocks every request to the object, and reconciliation wants a filesystem
+ * and a terminal that only a later turn has. The gate is also a wall, not
+ * just a stall: a `blockConcurrencyWhile` callback still pending at ~30 s
+ * (BLOCK_CONCURRENCY_CANCEL_MS, proven by probe) is cancelled and RESETS the
+ * object with every queued event — so never call {@link runColdStart} from
+ * inside one; the pump and the embedder's own turns are the places it runs.
+ */
+export function onColdStart(ctx: object, task: () => Promise<unknown>): void {
+  stateOf(ctx).coldStart.push(task);
+}
+
+/**
+ * Drain the queued cold-start tasks, serialized, each awaited so the turn
+ * that runs them pays for them. Idempotent between registrations: a drained
+ * queue is a cheap no-op, and a task registered after a drain runs on the
+ * next call.
+ */
+export function runColdStart(ctx: object): Promise<void> {
+  const state = stateOf(ctx);
+  if (state.coldStart.length === 0) return state.coldStartChain;
+  const tasks = state.coldStart;
+  state.coldStart = [];
+  const chained = state.coldStartChain.then(async () => {
+    for (const task of tasks) {
+      await task();
+    }
+  });
+  state.coldStartChain = chained.catch(() => {});
+  return chained;
+}

package/src/{facet-image-store.ts → image-store.ts}

@@ -1,5 +1,5 @@
 /**
- * facet-image-store.ts — materializing resident-process boot images into the
+ * image-store.ts — materializing resident-process boot images into the
  * content-addressed image store, and sweeping the ones nothing boots from.
  *
  * A resident process's module map is sized by the user's disk, so it does not
@@ -12,14 +12,14 @@
  * table.
  *
  * The filesystem itself stays the embedder's, reached through the
- * {@link FacetImageBlobStore} port — the store decides what is written where
+ * {@link ImageBlobStore} port — the store decides what is written where
  * and when; the port decides how bytes land on a disk and with what modes and
  * credentials.
  */
 
-import { MAX_TX_BLOB_BYTES, CHUNK_SIZE } from '@nimbus-sh/core/constants.js';
+import { MAX_TX_BLOB_BYTES, CHUNK_SIZE } from '@nimbus-sh/platform/limits.js';
 import { FACET_IMAGE_DIR, facetImageDigest, facetImagePath } from './process-fabric.js';
-import type { LaunchPacer } from './launch-pacer.js';
+import type { TurnBudget } from './turn-budget.js';
 
 /**
  * Bytes of an image written in one storage transaction.
@@ -39,7 +39,7 @@ export const FACET_IMAGE_WRITE_SLICE_BYTES = Math.floor(MAX_TX_BLOB_BYTES / CHUN
  * normalization are the implementation's: the store passes the same
  * store-relative paths it later roots and sweeps by.
  */
-export interface FacetImageBlobStore {
+export interface ImageBlobStore {
   /** Create a directory (and its parents) if it does not exist. */
   mkdirp(dir: string): void;
   /** The file's current size in bytes, or null when it does not exist. */
@@ -62,7 +62,7 @@ export interface FacetImageBlobStore {
  * hash's problem; everything else is idempotent — an image already present
  * at its own digest is already the bytes we were about to write.
  */
-export class FacetImageStore {
+export class ImageStore {
   /** pid → the boot images its facet loads from; the image sweep's root set. */
   private residentImages = new Map<number, string[]>();
   private dirReady = false;
@@ -75,7 +75,7 @@ export class FacetImageStore {
    *   is the process table, reached through this one predicate.
    */
   constructor(
-    private readonly blobs: () => FacetImageBlobStore,
+    private readonly blobs: () => ImageBlobStore,
     private readonly isLive: (pid: number) => boolean,
   ) {}
 
@@ -113,7 +113,7 @@ export class FacetImageStore {
   async materialize(
     pid: number,
     modules: Record<string, string>,
-    pacer: LaunchPacer,
+    pacer: TurnBudget,
   ): Promise<Record<string, string>> {
     const fs = this.blobs();
     const images: Record<string, string> = {};
@@ -177,7 +177,7 @@ export class FacetImageStore {
    * Nothing is left for a TTL or an eviction heuristic to guess at, and after
    * a DO reset the table is empty so every orphan goes.
    */
-  private sweep(fs: FacetImageBlobStore): void {
+  private sweep(fs: ImageBlobStore): void {
     const live = new Set<string>();
     for (const [pid, paths] of this.residentImages) {
       if (this.isLive(pid)) {

package/src/index.ts

@@ -7,16 +7,24 @@
  * modules they need instead.
  */
 
-export * from './alarms.js';
+export * from './generation.js';
+export * from './timers.js';
+export * from './outbox.js';
+export * from './journal.js';
+export * from './do-calls.js';
+export * from './facet-pool.js';
+export * from './derived.js';
+export * from './connections.js';
+export * from './sealed.js';
 export * from './bindings.js';
-export * from './ctx-exports.js';
-export * from './facet-image-store.js';
-export * from './fanout-pool.js';
+export * from './composition.js';
+export * from './image-store.js';
+export * from './fanout.js';
 export * from './inner-do-registry.js';
-export * from './launch-journal.js';
-export * from './launch-pacer.js';
-export * from './loader-ledger.js';
-export * from './loader-pool.js';
+export * from './fenced-work.js';
+export * from './turn-budget.js';
+export * from './budgets.js';
+export * from './isolate-pool.js';
 export * from './process-fabric.js';
 export * from './process-host.js';
 export * from './workerd-facet-host.js';