@nimbus-sh/fabric 0.1.0 → 0.2.0

package/src/{fanout-pool.ts → fanout.ts}

@@ -4,7 +4,7 @@
  *
  * A single Durable Object method can drive at most four concurrent
  * Worker Loader fetches before extra dispatches serialize or fail. Small
- * batches therefore run in the coordinator DO through LoaderPool.
+ * batches therefore run in the coordinator DO through IsolatePool.
  * Wider batches are sharded across sibling NimbusSession DOs, each of
  * which owns its own four-loader budget.
  *
@@ -16,9 +16,9 @@
 
 import { serializeFunction } from './vendor/serialize.js';
 import { BindingError } from './vendor/errors.js';
-import { LoaderPool, type FacetTaskFn } from './loader-pool.js';
-import { disposeRpcResource } from '@nimbus-sh/core/_shared/rpc-dispose.js';
-import { describeError, isDoOverloaded, isTransientDoReset } from '@nimbus-sh/core/observability/oom-classify.js';
+import { IsolatePool, type FacetTaskFn } from './isolate-pool.js';
+import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
+import { describeError, isDoOverloaded, isTransientDoReset } from '@nimbus-sh/platform/oom-classify.js';
 import type { WorkerLoader } from './vendor/types.js';
 
 /**
@@ -31,7 +31,7 @@ interface PeerSessionNamespace {
 }
 
 /** The bindings a fan-out needs off the coordinator DO's env. */
-export interface FanoutPoolEnv {
+export interface FanoutEnv {
   LOADER?: WorkerLoader;
   NIMBUS_SESSION?: PeerSessionNamespace;
 }
@@ -104,45 +104,45 @@ export interface FanoutTask<A> {
   args: A;
 }
 
-/** Options handed to FanoutPool's constructor. */
-export interface FanoutPoolOptions {
+/** Options handed to Fanout's constructor. */
+export interface FanoutOptions {
   /**
    * Tag prepended to peer-DO ids and in-DO loader ids for debugging
    * (e.g. "npm-install-batch"). Affects neither isolate identity (in-DO
-   * path uses the existing LoaderPool's tag-fold) nor peer-DO
+   * path uses the existing IsolatePool's tag-fold) nor peer-DO
    * deterministic placement (peer ids fold tag + key).
    */
   tag: string;
   /**
    * Per-task timeout in ms. Default 60_000. Forwarded to the in-DO
-   * LoaderPool's submit calls and to the peer-DO RPC's own
-   * LoaderPool.
+   * IsolatePool's submit calls and to the peer-DO RPC's own
+   * IsolatePool.
    */
   timeoutMs?: number;
   /**
    * Preamble bundled into every facet (in-DO and inside each peer
-   * DO). Same semantics as LoaderPool's preamble option.
+   * DO). Same semantics as IsolatePool's preamble option.
    */
   preamble?: string;
   /**
    * Wasm modules forwarded to every facet. Same semantics as
-   * LoaderPool's wasmModules option.
+   * IsolatePool's wasmModules option.
    */
   wasmModules?: Record<string, ArrayBuffer>;
   /**
    * Extra bindings forwarded to every facet. Same semantics as
-   * LoaderPool's extraBindings option.
+   * IsolatePool's extraBindings option.
    */
   extraBindings?: Record<string, unknown>;
   /**
    * If set, skip the supervisor-RPC binding injection (mirrors
-   * LoaderPool's omitSupervisor flag).
+   * IsolatePool's omitSupervisor flag).
    */
   omitSupervisor?: boolean;
   /**
    * Invoking process pid, baked into each facet's SUPERVISOR binding so
    * filesystem RPCs (writeBatchStream) are authorized under the caller's
-   * credential (mirrors LoaderPool's supervisorPid). Threaded to both
+   * credential (mirrors IsolatePool's supervisorPid). Threaded to both
    * the in-DO loader pool and, via `_rpcFanoutExecute`, the peer-DO pools.
    * npm install passes the shell command's `ctx.pid`; resolve leaves it 0.
    */
@@ -186,10 +186,10 @@ function isFanoutPeerStub(value: unknown): value is FanoutPeerStub {
 
 function fanoutPeerStub(value: unknown): FanoutPeerStub {
   if ((typeof value !== 'object' && typeof value !== 'function') || value === null) {
-    throw new BindingError('FanoutPool: NIMBUS_SESSION.get() did not return a peer stub.');
+    throw new BindingError('Fanout: NIMBUS_SESSION.get() did not return a peer stub.');
   }
   if (!isFanoutPeerStub(value)) {
-    throw new BindingError('FanoutPool: peer stub does not expose _rpcFanoutExecute().');
+    throw new BindingError('Fanout: peer stub does not expose _rpcFanoutExecute().');
   }
   return value;
 }
@@ -203,23 +203,23 @@ function fanoutPeerStub(value: unknown): FanoutPeerStub {
  * exists primarily as a clean API surface; per-call dispatch state
  * lives only inside submitMany's promise.
  */
-export class FanoutPool {
-  private readonly env: FanoutPoolEnv;
+export class Fanout {
+  private readonly env: FanoutEnv;
   private readonly ctx: DurableObjectState;
-  private readonly opts: FanoutPoolOptions;
+  private readonly opts: FanoutOptions;
   private readonly coordDoId: string;
   private readonly coordDoIdShort: string;
 
-  constructor(rawEnv: unknown, ctx: DurableObjectState, opts: FanoutPoolOptions) {
+  constructor(rawEnv: unknown, ctx: DurableObjectState, opts: FanoutOptions) {
     // A host hands its whole env over; the bindings are claimed here and the
     // LOADER claim is checked immediately. Hard-fail on a missing LOADER —
-    // LoaderPool also enforces this, but checking up front points the
-    // diagnostic at the fanout-pool construction site rather than the
-    // deferred loader-pool one.
-    const env = (rawEnv as FanoutPoolEnv | null | undefined) ?? {};
+    // IsolatePool also enforces this, but checking up front points the
+    // diagnostic at the fanout construction site rather than the
+    // deferred isolate-pool one.
+    const env = (rawEnv as FanoutEnv | null | undefined) ?? {};
     if (!env.LOADER || typeof env.LOADER.get !== 'function') {
       throw new BindingError(
-        'FanoutPool: env.LOADER binding missing or invalid. ' +
+        'Fanout: env.LOADER binding missing or invalid. ' +
           'Add a [[worker_loaders]] entry to wrangler.jsonc.',
       );
     }
@@ -235,21 +235,21 @@ export class FanoutPool {
    * results in input order.
    *
    * Routing:
-   *   tasks.length < 5   -> coordinator-local LoaderPool
+   *   tasks.length < 5   -> coordinator-local IsolatePool
    *   tasks.length >= 5  -> sibling NimbusSession DOs
    *
    * Backpressure: if `tasks.length > MAX_PEER_FANOUT (32)`, tasks
    * are sharded modulo `MAX_PEER_FANOUT` and each shard's bucket
    * runs serially inside its assigned peer DO via the in-peer
-   * LoaderPool's concurrency (capped at 4 there too). A
+   * IsolatePool's concurrency (capped at 4 there too). A
    * single submitMany call returns when ALL tasks complete (or any
    * throws).
    *
    * `fn` is the user function executed per task. It runs INSIDE a
    * Worker Loader isolate (in the in-DO path) or inside a peer DO's
    * Worker Loader isolate (in the peer-DO path); same trust posture
-   * as LoaderPool.submit. The function is serialized via
-   * the vendored serializeFunction (same as LoaderPool#prepare).
+   * as IsolatePool.submit. The function is serialized via
+   * the vendored serializeFunction (same as IsolatePool#prepare).
    */
   async submitMany<A, R>(
     tasks: FanoutTask<A>[],
@@ -287,12 +287,12 @@ export class FanoutPool {
     tasks: FanoutTask<A>[],
     fn: FacetTaskFn<A, R>,
   ): Promise<R[]> {
-    // Use the existing LoaderPool. Concurrency = task count
+    // Use the existing IsolatePool. Concurrency = task count
     // (capped at 4 by constructor — tasks.length is already < 5
     // here, so the cap won't bite). Each task = one pool.submit;
     // pool.map runs them with stable-slot reuse.
     const concurrency = Math.min(tasks.length, IN_DO_THRESHOLD - 1);
-    const pool = new LoaderPool(this.env, this.ctx, {
+    const pool = new IsolatePool(this.env, this.ctx, {
       concurrency,
       timeoutMs: this.opts.timeoutMs,
       tag: this.opts.tag,
@@ -326,7 +326,7 @@ export class FanoutPool {
     const ns = this.env?.NIMBUS_SESSION;
     if (!ns || typeof ns.idFromName !== 'function' || typeof ns.get !== 'function') {
       throw new BindingError(
-        'FanoutPool: env.NIMBUS_SESSION binding missing or invalid. ' +
+        'Fanout: env.NIMBUS_SESSION binding missing or invalid. ' +
           'The peer-DO topology requires it. ' +
           'Add the binding via durable_objects.bindings in wrangler.jsonc.',
       );
@@ -340,7 +340,7 @@ export class FanoutPool {
 
     // Cap peer count at MAX_PEER_FANOUT. Tasks beyond N=32 are
     // bucketed into existing shards — each shard's peer DO then
-    // runs its bucket through its in-DO LoaderPool.map
+    // runs its bucket through its in-DO IsolatePool.map
     // (concurrency capped at 4 there).
     const peerCount = Math.min(tasks.length, this.opts.maxPeers ?? MAX_PEER_FANOUT);
     // Group tasks by deterministic shard. Same key → same shard, so
@@ -397,7 +397,7 @@ export class FanoutPool {
                 extraBindings: this.opts.extraBindings,
                 omitSupervisor: this.opts.omitSupervisor,
                 // INSTALL-HONESTY: forward the COORDINATOR's full doId so
-                // the peer's LoaderPool can mint a SUPERVISOR
+                // the peer's IsolatePool can mint a SUPERVISOR
                 // binding that routes back HERE (the user's session DO),
                 // not to the peer DO itself. Without this, peer DOs'
                 // env.SUPERVISOR.writeBatch / writeBatchStream / stdout /

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,7 +126,7 @@ 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
@@ -132,8 +137,8 @@ export class ResidentLaunchJournal<R extends ResidentLaunchRecord> {
   private recovered = false;
 
   constructor(
-    private readonly storage: LaunchJournalStorage,
-    private readonly host: LaunchJournalHost<R>,
+    private readonly storage: FencedWorkStorage,
+    private readonly host: FencedWorkHost<R>,
   ) {}
 
   /**
@@ -154,7 +159,7 @@ export class ResidentLaunchJournal<R extends ResidentLaunchRecord> {
   async journal(record: R): Promise<void> {
     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));
@@ -174,7 +179,7 @@ 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.delete(`${FENCED_WORK_KEY_PREFIX}${pid}`);
       await this.storage.sync();
     } catch (e: unknown) {
       console.warn('[nimbus] resident launch journal delete failed:', errorMessage(e));
@@ -196,19 +201,34 @@ export class ResidentLaunchJournal<R extends ResidentLaunchRecord> {
   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
@@ -218,10 +238,26 @@ export class ResidentLaunchJournal<R extends ResidentLaunchRecord> {
         this.host.redrive(record, record.attempt + 1)
           .catch((e: unknown) => {
             this.host.onRedriveFailed?.(record, e);
-          }),
+          })
+          .then(() => this.supersede(key)),
       );
     }
   }
+
+  /**
+   * 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> {
+    try {
+      await this.storage.delete(key);
+      await this.storage.sync();
+    } catch (e: unknown) {
+      console.warn('[nimbus] resident launch journal supersede failed:', errorMessage(e));
+    }
+  }
 }
 
 function errorMessage(error: unknown): string {

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';