@nimbus-sh/fabric 0.1.0 → 0.3.0

package/src/process-host.ts

@@ -9,7 +9,7 @@
  *   peer  — the process is a named child actor of a SIBLING session DO, and
  *           the coordinator reaches it over one held-open RPC.
  *
- * Both call the same `openResidentFacet`. The peer leg is not a second process
+ * Both call the same `processes(ctx, env).spawn`. The peer leg is not a second process
  * implementation; it is the same call made on a different actor, which is why
  * the runner, the boot spec, the class name, the writer handshake, the start
  * contract and the lifecycle are shared code rather than parallel paths.
@@ -64,9 +64,9 @@
  * that pair unforgeable by anything that did not open the process.
  */
 
-import { disposeRpcResource } from '@nimbus-sh/core/_shared/rpc-dispose.js';
-import { isTransientDoReset } from '@nimbus-sh/core/observability/oom-classify.js';
-import { PEER_RETRY_BACKOFF_MS, PEER_TRANSIENT_RESET_RETRIES } from './fanout-pool.js';
+import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
+import { isTransientDoReset } from '@nimbus-sh/platform/oom-classify.js';
+import { PEER_RETRY_BACKOFF_MS, PEER_TRANSIENT_RESET_RETRIES } from './fanout.js';
 import {
   type HostedProcess,
   type OneShotParams,
@@ -77,14 +77,12 @@ import {
   type ResidentDiskReader,
   type ResidentSupervisorProps,
 } from './process-fabric.js';
+import { DYNAMIC_WORKER_CODE_LIMIT_BYTES } from './budgets.js';
+import { BindingError } from './vendor/errors.js';
 import {
-  DYNAMIC_WORKER_CODE_LIMIT_BYTES,
-  openResidentFacet,
-  residentFacetName,
-  runOneShotWorker,
+  processes,
   type ResidentFacetEnv,
 } from './workerd-facet-host.js';
-import { BindingError } from './vendor/errors.js';
 
 /** The substrates this deployment can be configured for. */
 export type ProcessHostMode = 'facet' | 'peer';
@@ -136,9 +134,7 @@ class FacetProcessHost implements ProcessHost {
   }
 
   runOnce<T>(params: OneShotParams, consume: (response: Response) => Promise<T>): Promise<T> {
-    return runOneShotWorker(
-      this.ctx,
-      this.env,
+    return processes(this.ctx, this.env).run(
       { doId: this.coordDoId, pid: params.pid, writerId: params.writerId },
       params,
       consume,
@@ -151,11 +147,11 @@ class FacetProcessHost implements ProcessHost {
       pid: params.pid,
       writerId: params.writerId,
     };
-    const { slot, ...facet } = openResidentFacet(this.ctx, this.env, this.disk, supervisor, params);
+    const { name, ...facet } = processes(this.ctx, this.env).spawn(this.disk, supervisor, params);
     return {
       ...facet,
       describe: () =>
-        `facet '${residentFacetName(slot)}' (pid ${params.pid})`
+        `facet '${name}' (pid ${params.pid})`
         + ` of session ${this.coordDoId.slice(-12)}`
         + `; ${describeImageDelivery(this.imageDelivery)}`,
     };
@@ -337,18 +333,24 @@ class PeerProcessHost implements ProcessHost {
    * worker of the coordinator here exactly as it does on `facet`.
    */
   runOnce<T>(params: OneShotParams, consume: (response: Response) => Promise<T>): Promise<T> {
-    return runOneShotWorker(
-      this.ctx,
-      this.env,
+    return processes(this.ctx, this.env).run(
       { doId: this.coordDoId, pid: params.pid, writerId: params.writerId },
       params,
       consume,
     );
   }
-
   async open(params: ProcessHostParams): Promise<HostedProcess> {
+    if (params.facet) {
+      // A durable application's facet must be a child of the COORDINATOR's
+      // Durable Object — its `app-slot-<n>` row and retained SQLite live in
+      // that DO's storage. A sibling host would own storage the coordinator's
+      // durable-slot book and removeDurableApp cannot reach.
+      throw new Error(
+        'Nimbus: a durable spawn must be facet-hosted on its own coordinator; '
+          + 'the peer substrate cannot serve one',
+      );
+    }
     const placement = await this._place(params.pid);
-    this.tokensInUse.set(params.pid, placement.isolateToken);
     // Minted per open, held only by this coordinator and the peer that hosts
     // the process. The workerKey is derivable from a pid; this is not.
     const webSocketCapability = crypto.randomUUID();
@@ -386,7 +388,7 @@ class PeerProcessHost implements ProcessHost {
     } catch (error) {
       this.tokensInUse.delete(params.pid);
       // Awaited, not fired off: a spawn that rejects must mean nothing was
-      // left running, which is what a throw from `openResidentFacet` means on
+      // left running, which is what a throw from `processes().spawn` means on
       // the other substrate.
       try { await this._cancel(params.workerKey, placement.peerName); }
       finally { disposeRpcResource(placement.stub); }

package/src/sealed.ts

@@ -0,0 +1,150 @@
+/**
+ * sealed.ts — prototype-chain RPC sealing, and the versioned surface
+ * constants that make it safe to run over the Agents SDK.
+ *
+ * Cloudflare resolves `stub.foo(...)` on the receiver's PROTOTYPE CHAIN.
+ * Proteus verified the three consequences against real workerd
+ * (`cf-backend/src/rpc-surface.ts:4-22`, catalog `rpc.prototype_chain`,
+ * proven-by-probe): TypeScript `private` is erased, so private methods ARE
+ * callable over RPC; superclass methods are reachable too — inherited
+ * `Agent.sql` hands any stub-holder arbitrary SQL against the receiver's
+ * storage, and `Agent` + `Server` alone contribute hundreds of reachable
+ * names; and OWN instance properties are NOT reachable — workerd rejects
+ * them exactly as it rejects a missing name, including when the own
+ * property shadows a prototype method.
+ *
+ * That third consequence is the primitive: {@link sealRpcSurface} copies
+ * every reachable member that is NOT on the declared surface down onto the
+ * instance as a non-enumerable own property. In-process behaviour is
+ * unchanged — `this.x(...)` finds the same function object, `super.x()`
+ * still reaches the prototype, accessors stay accessors. From outside, the
+ * name has ceased to exist. Call it as the LAST statement of the
+ * constructor, after every base class installed its wrappers.
+ *
+ * The surface constants are the part that breaks whenever the SDK moves,
+ * which is why fabric owns them: Proteus reverse-engineered its facet
+ * surface from `agents/dist` by hand, and a fabric test diffs these
+ * constants against the INSTALLED packages so drift is caught by CI, not by
+ * a leak. Verified against agents@0.20.1 and partyserver@0.5.10
+ * (2026-08-19); an SDK upgrade that changes the cross-stub set fails that
+ * test and demands re-derivation, which is the intended failure.
+ */
+
+/**
+ * Every name RPC can resolve on `target`: own property names of every
+ * prototype up to (and excluding) Object.prototype, minus `constructor` and
+ * minus anything `target` already carries as an own property — own
+ * properties are not RPC-reachable, so they need no seal. The single
+ * definition {@link sealRpcSurface} and its tests both work from.
+ */
+export function rpcReachableNames(target: object): string[] {
+  const names = new Set<string>();
+  const own = new Set(Object.getOwnPropertyNames(target));
+  let proto = Object.getPrototypeOf(target) as object | null;
+  while (proto !== null && proto !== Object.prototype) {
+    for (const name of Object.getOwnPropertyNames(proto)) {
+      if (name === 'constructor' || own.has(name)) continue;
+      names.add(name);
+    }
+    proto = Object.getPrototypeOf(proto) as object | null;
+  }
+  return [...names].sort();
+}
+
+function inheritedDescriptor(target: object, name: string): PropertyDescriptor | undefined {
+  let proto = Object.getPrototypeOf(target) as object | null;
+  while (proto !== null && proto !== Object.prototype) {
+    const descriptor = Object.getOwnPropertyDescriptor(proto, name);
+    if (descriptor) return descriptor;
+    proto = Object.getPrototypeOf(proto) as object | null;
+  }
+  return undefined;
+}
+
+/**
+ * Shadow every RPC-reachable member not on `surface` with a non-enumerable
+ * own property carrying the SAME descriptor — the same function object, the
+ * same accessor pair — so in-process behaviour cannot change while the name
+ * stops resolving over RPC. Surface names the class lacks are ignored: a
+ * surface is a ceiling, and the runtime already denies what does not exist.
+ */
+export function sealRpcSurface<Instance extends object>(
+  instance: Instance,
+  surface: readonly string[],
+): void {
+  const allowed = new Set(surface);
+  for (const name of rpcReachableNames(instance)) {
+    if (allowed.has(name)) continue;
+    const descriptor = inheritedDescriptor(instance, name);
+    if (descriptor) Object.defineProperty(instance, name, { ...descriptor, enumerable: false });
+  }
+}
+
+/**
+ * The platform half of any surface built on partyserver's `Server` (and
+ * therefore the Agents SDK's `Agent`): what the RUNTIME and the SDK's own
+ * routing must still reach after sealing. From the consumer's verified list
+ * (`rpc-surface.ts:63-86`): `setName` is called by `getServerByName` before
+ * the stub is returned; `_initAndFetch` is `setName` plus `fetch`, so it
+ * exposes nothing new; the WebSocket handlers' arguments cannot cross an
+ * RPC boundary anyway.
+ */
+export const PLATFORM_RPC_SURFACE = [
+  'fetch',
+  'setName',
+  '_initAndFetch',
+  'alarm',
+  'webSocketMessage',
+  'webSocketClose',
+  'webSocketError',
+] as const;
+
+/**
+ * The Agents SDK's own cross-stub facet protocol at agents@0.20.1: every
+ * `_cf_` method the SDK calls on a receiver that is not `this`, derived
+ * from `agents/dist` (the SDK's ACTUAL cross-stub surface, not a prefix
+ * rule — Agent's prototype defines 58 `_cf_` methods and only these are
+ * cross-called). An Agent that hosts SDK facets must keep these; one that
+ * does not (Proteus's UserDO) should not carry them at all.
+ */
+export const AGENTS_FACET_RPC_SURFACE = [
+  '_cf_acquireFacetKeepAlive',
+  '_cf_broadcastToSubAgent',
+  '_cf_cancelScheduleForFacet',
+  '_cf_checkRunFibersForFacet',
+  '_cf_cleanupFacetPrefix',
+  '_cf_closeSubAgentConnection',
+  '_cf_destroyDescendantFacet',
+  '_cf_dispatchScheduledCallback',
+  '_cf_getScheduleForFacet',
+  '_cf_handleSubAgentWebSocketClose',
+  '_cf_handleSubAgentWebSocketConnect',
+  '_cf_handleSubAgentWebSocketMessage',
+  '_cf_initAsFacet',
+  '_cf_listSchedulesForFacet',
+  '_cf_registerFacetRun',
+  '_cf_releaseFacetKeepAlive',
+  '_cf_scheduleEveryForFacet',
+  '_cf_scheduleForFacet',
+  '_cf_sendToSubAgentConnection',
+  '_cf_setSubAgentConnectionState',
+  '_cf_subAgentConnectionMetas',
+  '_cf_unregisterFacetRun',
+] as const;
+
+/**
+ * Cross-stub `_cf_` members deliberately absent from EVERY surface: each
+ * takes a method NAME and calls it on the receiver, which would re-open
+ * everything sealing closes. Sealing them fail-closes the SDK features
+ * built on them (`parentAgent()` proxies, workflow-to-agent bridges) — the
+ * consumer accepts exactly that cost, and fail-closed is the right default
+ * for a bridge that dispatches arbitrary names. (`_cf_invokeStubMethod` is
+ * only ever self-called in the pinned dist, but it is prototype-defined, so
+ * it is named here and sealed.)
+ */
+export const AGENTS_INVOKE_BRIDGES = [
+  '_cf_invokeAgentPath',
+  '_cf_invokeStubMethod',
+  '_cf_invokeSubAgent',
+  '_cf_invokeSubAgentPath',
+] as const;

package/src/timers.ts

@@ -0,0 +1,294 @@
+/**
+ * timers.ts — Durable Object alarm multiplexing, persisted across
+ * hibernation.
+ *
+ * A Durable Object has ONE alarm, and a second `setAlarm()` silently
+ * overwrites the first — so every alarm-driven subsystem coordinates through
+ * a single reason→deadline map and one dispatcher. Reasons are plain strings
+ * registered by the embedder: `timers(host, ctx).schedule` arms one, and
+ * `timers(host, ctx).dispatch` runs the embedder-supplied handler for every
+ * reason whose deadline has passed.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { errorText } from '@nimbus-sh/core/_shared/error-text.js';
+
+/**
+ * The storage the timer map lives in. `setAlarm` is optional because
+ * `wrangler dev` serves a storage without it, which is the whole reason
+ * scheduling degrades to a no-op instead of throwing.
+ */
+export interface TimerStorage {
+  get(key: string): Promise<unknown>;
+  put(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  setAlarm?(scheduledTime: number): Promise<void>;
+}
+
+/** The hosting actor's context, as the timer coordination reads it. */
+export interface TimerContext {
+  storage: TimerStorage;
+}
+
+/**
+ * Multi-reason timer coordination map.
+ *
+ * JSON-serialised `Record<reason, deadlineMsEpoch>` where keys are the
+ * embedder's canonical reason strings (e.g. 'w9-flush', 'log-janitor'). The
+ * alarm() dispatcher reads this on fire, dispatches every reason whose
+ * deadline has passed, and re-arms `ctx.storage.setAlarm` at the earliest
+ * remaining deadline.
+ *
+ * Why a map (not a single nextAlarmAt + reason): two subsystems can have
+ * distinct deadlines. Without the map, the later setAlarm() call would
+ * overwrite the earlier reason silently, breaking whichever subsystem
+ * expected its deadline.
+ *
+ * Forward-compat: the dispatcher silently drops unknown reasons so a
+ * rollback from a future deploy that added new reasons doesn't leave the
+ * alarm stuck.
+ *
+ * The VALUE is live production DO storage ('w1_next_alarm_reasons', from the
+ * workstream that introduced it) and must never change — renaming a storage
+ * key is a migration, and orphaned rows are the least of what it breaks.
+ */
+export const TIMER_REASONS_KEY = 'w1_next_alarm_reasons';
+
+/**
+ * The host instance carrying the per-instance timer chain. The field lives on
+ * the embedder's DO instance so one chain serializes every timer-map
+ * read-modify-write for that instance (see {@link Timers.schedule}).
+ */
+export interface TimerHost {
+  _timerChain?: Promise<unknown>;
+}
+
+/**
+ * The async context of a running dispatch's handlers. A schedule request
+ * made inside it lands in the dispatch's arm collection instead of the
+ * chain — a handler that AWAITED a chained schedule would be waiting on an
+ * entry queued behind the dispatch it is running inside, which is a
+ * deadlock. `Outbox.queue` awaits `timers.schedule`, so any handler that
+ * queues into an outbox reaches this. The dispatcher folds the collected
+ * arms into the reason map before its own re-arm.
+ *
+ * AsyncLocalStorage, not a host field, so the redirect is scoped to the
+ * dispatch's OWN async context: a concurrent turn that schedules while a
+ * handler awaits external IO takes the normal chain path and keeps its own
+ * turn-gated persistence. Requires the `nodejs_compat` (or `nodejs_als`)
+ * compatibility flag on workerd.
+ */
+const dispatchArms = new AsyncLocalStorage<Array<{ reason: string; whenMs: number }>>();
+
+/**
+ * What one timer handler may return: nothing, or a deadline this reason
+ * re-arms itself at. Re-arming through the return value keeps the map's
+ * read-modify-write inside the dispatcher, where it is serialized.
+ */
+export type TimerHandlerResult = void | { rearmAt: number };
+
+/**
+ * The platform's alarm-invocation report, forwarded to every handler: the
+ * platform retries a failed alarm() with backoff and abandons it after its
+ * retry budget, and `isRetry`/`retryCount` are the only way a handler can
+ * tell how close it is to that abandonment. Structurally identical to
+ * workers-types' AlarmInvocationInfo; declared here so the module stays
+ * usable without the ambient types.
+ */
+export interface TimerAlarmInfo {
+  readonly isRetry: boolean;
+  readonly retryCount: number;
+  readonly scheduledTime: number;
+}
+
+/** The embedder's reasons, each with the handler that answers it. */
+export type TimerHandlers = Record<
+  string,
+  (now: number, info?: TimerAlarmInfo) => TimerHandlerResult | Promise<TimerHandlerResult>
+>;
+
+/**
+ * One actor's timers: the reason map over its ONE platform alarm.
+ *
+ * A cheap accessor over `(host, ctx)` — the chain that serializes the map's
+ * read-modify-write lives on the host instance, so every `timers()` call for
+ * one instance coordinates through the same chain.
+ */
+export function timers(host: TimerHost, ctx: TimerContext): Timers {
+  return new Timers(host, ctx);
+}
+
+export class Timers {
+  constructor(
+    private readonly host: TimerHost,
+    private readonly ctx: TimerContext,
+  ) {}
+
+  /**
+   * Schedule (or re-schedule) a timer reason. Coordinated via a single map in
+   * DO storage so multiple subsystems don't clobber each other's `setAlarm()`
+   * calls.
+   *
+   * Semantics:
+   *   - Reads the existing reasons map.
+   *   - Sets `map[reason] = whenMs` IF `whenMs` is sooner than the
+   *     currently-pending deadline for that reason (or no entry exists).
+   *     Later-than-pending requests are silently ignored — the existing
+   *     alarm will fire and re-arm anyway.
+   *   - Writes the map back and calls `ctx.storage.setAlarm(min(deadlines))`.
+   *
+   * Cost: 1 storage read + 1 storage write + 1 setAlarm per call. setAlarm
+   * itself is billed as 1 row written per DO pricing. At a 60s janitor
+   * cadence, this is ~$0.05/mo/session at scale — dwarfed by the
+   * hibernation duration savings.
+   *
+   * Fail-soft: any throw is swallowed with a warn. On older runtimes /
+   * wrangler-dev where setAlarm is unavailable, this is a no-op (the
+   * subsystem's in-isolate setTimeout fallback continues to work).
+   */
+  schedule(reason: string, whenMs: number): Promise<boolean> {
+    const { host, ctx } = this;
+    // From inside a dispatch handler, hand the arm to the dispatcher
+    // instead of the chain (see dispatchArms): the fold keeps EDF
+    // semantics, and the dispatch's own write and re-arm carry it. The
+    // setAlarm gate matches the chain path's, so both paths refuse alike
+    // on a runtime without alarms.
+    const arms = dispatchArms.getStore();
+    if (arms) {
+      if (typeof ctx?.storage?.setAlarm !== 'function') return Promise.resolve(false);
+      arms.push({ reason, whenMs });
+      return Promise.resolve(true);
+    }
+    // Serialize every read-modify-write of the reasons map through one
+    // per-instance chain: two schedulers firing back-to-back from one activity
+    // hook would otherwise interleave their get→put cycles and silently drop
+    // whichever reason wrote first.
+    const run = async (): Promise<boolean> => {
+      try {
+        const setAlarmFn = ctx?.storage?.setAlarm;
+        if (typeof setAlarmFn !== 'function') return false;
+        const existing = (await ctx.storage.get(TIMER_REASONS_KEY)) as
+          | Record<string, number>
+          | undefined;
+        const map: Record<string, number> = { ...(existing || {}) };
+        // Earliest-deadline-first: only update if new request is sooner or
+        // this reason has no pending entry.
+        if (!(reason in map) || whenMs < map[reason]) {
+          map[reason] = whenMs;
+          await ctx.storage.put(TIMER_REASONS_KEY, map);
+        }
+        const earliest = Math.min(...Object.values(map));
+        setAlarmFn.call(ctx.storage, earliest);
+        return true;
+      } catch (e) {
+        console.warn('[nimbus/W1] timers.schedule threw:', errorText(e));
+        return false;
+      }
+    };
+    const chained = (host._timerChain ?? Promise.resolve()).then(run, run);
+    host._timerChain = chained;
+    return chained;
+  }
+
+  /**
+   * Multi-reason timer dispatcher. Called from the DO's `alarm()` handler
+   * with the embedder's handler map.
+   *
+   * For each pending reason whose deadline has passed, run its handler.
+   * Handlers are awaited in place: the alarm invocation is the fresh turn a
+   * re-entering subsystem asked for, and it has to stay the one paying for the
+   * work it just released.
+   *
+   * After running fireable reasons, re-arms `ctx.storage.setAlarm` at the
+   * earliest remaining deadline. If no reasons remain, deletes the map key and
+   * does NOT call setAlarm — the DO becomes hibernation-eligible after the 10s
+   * idle window.
+   *
+   * Forward/back-compat: unknown reasons silently dropped. `onLegacyAlarm`
+   * covers an alarm that fires with no map at all — a deploy from before the
+   * map existed left a bare `setAlarm` behind, and the embedder decides what
+   * that one-time fire means (one dispatch later the map is populated by the
+   * next schedule call).
+   */
+  dispatch(
+    handlers: TimerHandlers,
+    onLegacyAlarm?: () => void,
+    alarmInfo?: TimerAlarmInfo,
+  ): Promise<void> {
+    const { host, ctx } = this;
+    // Same serialization as schedule: the dispatcher's read→handlers→write
+    // cycle must not interleave with an activity-hook schedule.
+    const chained = (host._timerChain ?? Promise.resolve()).then(
+      () => dispatchBody(ctx, handlers, onLegacyAlarm, alarmInfo),
+      () => dispatchBody(ctx, handlers, onLegacyAlarm, alarmInfo),
+    );
+    host._timerChain = chained;
+    return chained;
+  }
+}
+
+async function dispatchBody(
+  ctx: TimerContext,
+  handlers: TimerHandlers,
+  onLegacyAlarm?: () => void,
+  alarmInfo?: TimerAlarmInfo,
+): Promise<void> {
+  // Collect schedule requests made inside handler context (see
+  // dispatchArms) and fold them into the map below, so an in-dispatch arm
+  // neither deadlocks on the chain nor races the write.
+  const arms: Array<{ reason: string; whenMs: number }> = [];
+  try {
+    const now = Date.now();
+    const existing = (await ctx?.storage?.get?.(TIMER_REASONS_KEY)) as
+      | Record<string, number>
+      | undefined;
+    const map: Record<string, number> = { ...(existing || {}) };
+    const hadMap = Object.keys(map).length > 0;
+    if (!hadMap) {
+      dispatchArms.run(arms, () => onLegacyAlarm?.());
+    } else {
+      // Snapshot fireable reasons BEFORE running any of them, so a
+      // handler that schedules itself for the next cycle doesn't get
+      // immediately re-fired in the same dispatch.
+      const fired: string[] = [];
+      for (const [reason, when] of Object.entries(map)) {
+        if (when <= now) fired.push(reason);
+      }
+      for (const reason of fired) {
+        delete map[reason];
+        const handler = handlers[reason];
+        // Unknown reasons silently dropped (forward-compat).
+        if (!handler) continue;
+        try {
+          const result = await dispatchArms.run(arms, () => handler(now, alarmInfo));
+          if (result && typeof result.rearmAt === 'number') {
+            map[reason] = result.rearmAt;
+          }
+        } catch (e) {
+          console.warn(`[nimbus/W1] dispatch ${reason} threw:`, errorText(e));
+        }
+      }
+    }
+    // Fold the in-dispatch arms, earliest-deadline-first per reason.
+    for (const arm of arms) {
+      if (!(arm.reason in map) || arm.whenMs < map[arm.reason]) {
+        map[arm.reason] = arm.whenMs;
+      }
+    }
+    // Re-arm or clear.
+    const setAlarmFn = ctx?.storage?.setAlarm;
+    if (Object.keys(map).length > 0) {
+      await ctx.storage.put(TIMER_REASONS_KEY, map);
+      const earliest = Math.min(...Object.values(map));
+      if (typeof setAlarmFn === 'function') {
+        setAlarmFn.call(ctx.storage, earliest);
+      }
+    } else if (hadMap) {
+      try { await ctx.storage.delete(TIMER_REASONS_KEY); } catch {}
+      // No remaining reasons → no setAlarm call → DO becomes
+      // hibernation-eligible after the 10s idle window.
+    }
+  } catch (e) {
+    console.warn('[nimbus/W1] timers.dispatch threw:', errorText(e));
+  }
+}

package/src/{launch-pacer.ts → turn-budget.ts}

@@ -1,5 +1,5 @@
 /**
- * launch-pacer.ts — spreading a resident launch across Durable Object turns.
+ * turn-budget.ts — spreading a resident launch across Durable Object turns.
  *
  * Building a resident process is the largest single span of computation this
  * session performs: for pi it walks a 17 MB source tree through eight
@@ -33,8 +33,10 @@
  * bytes and treats its wall guard as coarse.
  */
 
+import { runColdStart } from './generation.js';
+
 /** How a paced launch gets back onto a fresh Durable Object turn. */
-export interface LaunchTurnScheduler {
+export interface TurnScheduler {
   /**
    * Suspend until a fresh turn is running this launch again.
    *
@@ -54,7 +56,7 @@ export interface LaunchTurnScheduler {
  * each an alarm round trip — small enough not to dominate a launch. pi's
  * 22.9 MB map crosses this about a dozen times per phase that handles it.
  */
-export const LAUNCH_CHUNK_MAX_BYTES = 2_000_000;
+export const TURN_CHUNK_MAX_BYTES = 2_000_000;
 
 /**
  * Accounts launch progress and ends the turn when a chunk's worth has been
@@ -66,7 +68,7 @@ export const LAUNCH_CHUNK_MAX_BYTES = 2_000_000;
  * behaviour and cost. Nothing here decides WHAT the launch does, only where it
  * is allowed to stop.
  */
-export class LaunchPacer {
+export class TurnBudget {
   /** Turn handoffs this launch has taken. Reported with the launch. */
   chunks = 0;
   /** Total work accounted, for the same report. */
@@ -84,8 +86,8 @@ export class LaunchPacer {
    *   remembered to ask.
    */
   constructor(
-    private readonly scheduler: LaunchTurnScheduler,
-    private readonly maxChunkBytes: number = LAUNCH_CHUNK_MAX_BYTES,
+    private readonly scheduler: TurnScheduler,
+    private readonly maxChunkBytes: number = TURN_CHUNK_MAX_BYTES,
     private readonly stillWanted?: () => void,
   ) {}
 
@@ -121,39 +123,33 @@ export class LaunchPacer {
   }
 }
 
-function withResolvers(): { promise: Promise<void>; resolve: () => void } {
-  let resolve!: () => void;
-  const promise = new Promise<void>((r) => { resolve = r; });
+/** `Promise.withResolvers` for the runtime the project targets. */
+export function withResolvers<T = void>(): { promise: Promise<T>; resolve: (value: T | PromiseLike<T>) => void } {
+  let resolve!: (value: T | PromiseLike<T>) => void;
+  const promise = new Promise<T>((r) => { resolve = r; });
   return { promise, resolve };
 }
 
-/** What {@link LaunchTurnPump} needs from the Durable Object hosting it. */
-export interface LaunchTurnPumpHost {
+/** What {@link PacedWork} needs from the Durable Object hosting it. */
+export interface PacedWorkHost {
   /**
-   * Arrange for {@link LaunchTurnPump.pump} to run on a fresh Durable Object
+   * Arrange for {@link PacedWork.pump} to run on a fresh Durable Object
    * turn.
    *
    * The embedder satisfies this with an alarm, which is the only primitive
    * that genuinely re-enters the object: a fresh turn is both a released
    * thread and a fresh CPU budget, and a launch needs each for a different
    * reason. Without it the pump degrades to a same-context timer — see
-   * {@link LaunchTurnPump.nextTurn}.
+   * {@link PacedWork.nextTurn}.
    */
   requestTurn?: () => void;
-  /**
-   * Awaited first on every pump, before any waiter resumes. Where the
-   * resident-launch journal's recovery sits: the pump is what an alarm calls,
-   * and the first turn after a reset is the re-delivered alarm of a launch
-   * the reset interrupted.
-   */
-  recover?: () => Promise<void>;
 }
 
 /**
- * The granting side of {@link LaunchTurnScheduler}: parks suspended launches
+ * The granting side of {@link TurnScheduler}: parks suspended launches
  * and resumes every one of them when the host grants a fresh turn.
  */
-export class LaunchTurnPump implements LaunchTurnScheduler {
+export class PacedWork implements TurnScheduler {
   /**
    * Launches suspended between chunks, waiting for a turn of their own.
    *
@@ -166,7 +162,14 @@ export class LaunchTurnPump implements LaunchTurnScheduler {
    */
   private waiters: Array<{ resume: () => void; chunkEnded: Promise<void> }> = [];
 
-  constructor(private readonly host: LaunchTurnPumpHost) {}
+  /**
+   * `ctx` keys the cold-start queue the pump drains first on every turn it
+   * grants — see {@link pump}.
+   */
+  constructor(
+    private readonly ctx: object,
+    private readonly host: PacedWorkHost,
+  ) {}
 
   /**
    * How a paced launch asks for a fresh turn.
@@ -198,7 +201,11 @@ export class LaunchTurnPump implements LaunchTurnScheduler {
    * the runtime may tear the context down mid-chunk.
    */
   async pump(): Promise<void> {
-    await this.host.recover?.();
+    // Deferred reconciliation runs first, before any waiter resumes. Where
+    // the resident-launch journal's recovery sits (`onColdStart`): the pump
+    // is what an alarm calls, and the first turn after a reset is the
+    // re-delivered alarm of a launch the reset interrupted.
+    await runColdStart(this.ctx);
     const waiting = this.waiters;
     if (waiting.length === 0) return;
     this.waiters = [];
@@ -222,10 +229,10 @@ export class LaunchTurnPump implements LaunchTurnScheduler {
  * `git/commands.ts` carries `NIMBUS_GIT_CHECKOUT_CHUNK_ENTRIES`. Unset in
  * production, where the default applies.
  */
-export function launchChunkMaxBytes(env: unknown): number {
+export function turnChunkMaxBytes(env: unknown): number {
   const raw = (env as { NIMBUS_LAUNCH_CHUNK_BYTES?: string } | null | undefined)
     ?.NIMBUS_LAUNCH_CHUNK_BYTES;
-  if (!raw) return LAUNCH_CHUNK_MAX_BYTES;
+  if (!raw) return TURN_CHUNK_MAX_BYTES;
   const parsed = Number(raw);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : LAUNCH_CHUNK_MAX_BYTES;
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : TURN_CHUNK_MAX_BYTES;
 }