@nimbus-sh/fabric 0.1.0 → 0.2.0

package/dist/{fanout-pool.d.ts → fanout.d.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.
  *
@@ -13,7 +13,7 @@
  * missing LOADER or NIMBUS_SESSION bindings fail loudly so install and
  * runtime operations do not appear successful after partial dispatch.
  */
-import { type FacetTaskFn } from './loader-pool.js';
+import { type FacetTaskFn } from './isolate-pool.js';
 import type { WorkerLoader } from './vendor/types.js';
 /**
  * The sibling-session namespace the peer-DO topology routes through. Ids are
@@ -24,7 +24,7 @@ interface PeerSessionNamespace {
     get(id: DurableObjectId): unknown;
 }
 /** The bindings a fan-out needs off the coordinator DO's env. */
-export interface FanoutPoolEnv {
+export interface FanoutEnv {
     LOADER?: WorkerLoader;
     NIMBUS_SESSION?: PeerSessionNamespace;
 }
@@ -90,45 +90,45 @@ export interface FanoutTask<A> {
     /** Argument passed to the user fn. */
     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.
      */
@@ -162,33 +162,33 @@ export interface FanoutPoolOptions {
  * exists primarily as a clean API surface; per-call dispatch state
  * lives only inside submitMany's promise.
  */
-export declare class FanoutPool {
+export declare class Fanout {
     private readonly env;
     private readonly ctx;
     private readonly opts;
     private readonly coordDoId;
     private readonly coordDoIdShort;
-    constructor(rawEnv: unknown, ctx: DurableObjectState, opts: FanoutPoolOptions);
+    constructor(rawEnv: unknown, ctx: DurableObjectState, opts: FanoutOptions);
     /**
      * Dispatch `tasks` across the appropriate topology and return
      * 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).
      */
     submitMany<A, R>(tasks: FanoutTask<A>[], fn: FacetTaskFn<A, R>): Promise<R[]>;
     /** Report which topology a task count uses without dispatching. */
@@ -220,4 +220,4 @@ export declare class FanoutPool {
  */
 export declare function hashKeyToShard(key: string, peerCount: number): number;
 export {};
-//# sourceMappingURL=fanout-pool.d.ts.map
+//# sourceMappingURL=fanout.d.ts.map

package/dist/fanout.d.ts.map

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

package/dist/{fanout-pool.js → fanout.js}

@@ -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.
  *
@@ -15,9 +15,9 @@
  */
 import { serializeFunction } from './vendor/serialize.js';
 import { BindingError } from './vendor/errors.js';
-import { LoaderPool } 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 } from './isolate-pool.js';
+import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
+import { describeError, isDoOverloaded, isTransientDoReset } from '@nimbus-sh/platform/oom-classify.js';
 /**
  * Threshold at which routing switches from coordinator-local loaders to
  * sibling Durable Objects.
@@ -79,10 +79,10 @@ function isFanoutPeerStub(value) {
 }
 function fanoutPeerStub(value) {
     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;
 }
@@ -95,7 +95,7 @@ function fanoutPeerStub(value) {
  * exists primarily as a clean API surface; per-call dispatch state
  * lives only inside submitMany's promise.
  */
-export class FanoutPool {
+export class Fanout {
     env;
     ctx;
     opts;
@@ -104,12 +104,12 @@ export class FanoutPool {
     constructor(rawEnv, ctx, opts) {
         // 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.
+        // 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 ?? {};
         if (!env.LOADER || typeof env.LOADER.get !== 'function') {
-            throw new BindingError('FanoutPool: env.LOADER binding missing or invalid. ' +
+            throw new BindingError('Fanout: env.LOADER binding missing or invalid. ' +
                 'Add a [[worker_loaders]] entry to wrangler.jsonc.');
         }
         this.env = env;
@@ -123,21 +123,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(tasks, fn) {
         if (tasks.length === 0)
@@ -166,12 +166,12 @@ export class FanoutPool {
     }
     // ── Private: in-DO dispatch (in-DO fanout) ──────────────────────────────
     async _dispatchInDo(tasks, fn) {
-        // 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,
@@ -203,7 +203,7 @@ export class FanoutPool {
     async _dispatchPeerDo(tasks, fn) {
         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. ' +
+            throw new BindingError('Fanout: env.NIMBUS_SESSION binding missing or invalid. ' +
                 'The peer-DO topology requires it. ' +
                 'Add the binding via durable_objects.bindings in wrangler.jsonc.');
         }
@@ -214,7 +214,7 @@ export class FanoutPool {
         const fnSource = serializeFunction(fn);
         // 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
@@ -266,7 +266,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/dist/{launch-journal.d.ts → fenced-work.d.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.
  */
 /**
@@ -36,9 +36,9 @@
  * storage key is a migration, and orphaned rows are the least of what it
  * breaks.
  */
-export declare const RESIDENT_LAUNCH_KEY_PREFIX = "resident-launch:";
+export declare const FENCED_WORK_KEY_PREFIX = "resident-launch:";
 /** A launch is re-driven once. A reset that recurs is not the transient one. */
-export declare const RESIDENT_LAUNCH_MAX_ATTEMPT = 1;
+export declare const FENCED_WORK_MAX_ATTEMPT = 1;
 /**
  * A resident process this session owes the user, as a later instance would
  * have to re-drive it.
@@ -57,7 +57,7 @@ export declare 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. */
@@ -70,9 +70,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: {
@@ -81,7 +81,7 @@ export interface LaunchJournalStorage {
     sync(): Promise<void>;
 }
 /** 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),
@@ -91,8 +91,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;
     /**
@@ -117,7 +122,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 declare class ResidentLaunchJournal<R extends ResidentLaunchRecord> {
+export declare class FencedWork<R extends FencedWorkRecord> {
     private readonly storage;
     private readonly host;
     /**
@@ -128,7 +133,7 @@ export declare class ResidentLaunchJournal<R extends ResidentLaunchRecord> {
     private journalledPids;
     /** Whether this instance has already read the journal a reset leaves behind. */
     private recovered;
-    constructor(storage: LaunchJournalStorage, host: LaunchJournalHost<R>);
+    constructor(storage: FencedWorkStorage, 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
@@ -166,5 +171,12 @@ export declare class ResidentLaunchJournal<R extends ResidentLaunchRecord> {
      * instance starts or settles, and those are rows this instance wrote.
      */
     recoverInterrupted(): Promise<void>;
+    /**
+     * 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 supersede;
 }
-//# sourceMappingURL=launch-journal.d.ts.map
+//# sourceMappingURL=fenced-work.d.ts.map

package/dist/fenced-work.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fenced-work.d.ts","sourceRoot":"","sources":["../src/fenced-work.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAEzD,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB;;4DAEwD;IACxD,KAAK,EAAE,UAAU,GAAG,SAAS,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IACxE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,2DAA2D;AAC3D,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,gBAAgB;IACxD;;;;;;OAMG;IACH,cAAc,IAAI,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3C;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtD,mDAAmD;IACnD,SAAS,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IAC5B,yEAAyE;IACzE,WAAW,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IAC9B,kCAAkC;IAClC,eAAe,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACnD;AAED;;;;;;;GAOG;AACH,qBAAa,UAAU,CAAC,CAAC,SAAS,gBAAgB;IAW9C,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAXvB;;;;OAIG;IACH,OAAO,CAAC,cAAc,CAAqB;IAC3C,gFAAgF;IAChF,OAAO,CAAC,SAAS,CAAS;gBAGP,OAAO,EAAE,iBAAiB,EAC1B,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;IAG1C;;;;;;;;;;;;;;OAcG;IACG,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAUvC,8DAA8D;IAC9D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB;;;;OAIG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUzC;;;;;;;;;;;OAWG;IACG,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IA8CzC;;;;;OAKG;YACW,SAAS;CAQxB"}

package/dist/{launch-journal.js → fenced-work.js}

@@ -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.
  */
 /**
@@ -36,9 +36,9 @@
  * 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;
 /**
  * The resident-launch journal of one Durable Object instance.
  *
@@ -47,7 +47,7 @@ export const RESIDENT_LAUNCH_MAX_ATTEMPT = 1;
  * 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 {
+export class FencedWork {
     storage;
     host;
     /**
@@ -80,7 +80,7 @@ export class ResidentLaunchJournal {
     async journal(record) {
         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) {
@@ -100,7 +100,7 @@ export class ResidentLaunchJournal {
         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) {
@@ -123,8 +123,10 @@ export class ResidentLaunchJournal {
         if (this.recovered)
             return;
         this.recovered = true;
-        const journal = await this.storage.list({ prefix: RESIDENT_LAUNCH_KEY_PREFIX });
+        const journal = await this.storage.list({ prefix: FENCED_WORK_KEY_PREFIX });
         const base = this.host.generationBase();
+        const abandoned = [];
+        const redriven = [];
         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
@@ -132,11 +134,27 @@ export class ResidentLaunchJournal {
             // `session/rpc.ts` uses to attribute a prior generation's pid.
             if (!(record.pid > 0 && record.pid <= base))
                 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);
-            if (record.attempt >= RESIDENT_LAUNCH_MAX_ATTEMPT) {
-                this.host.onAbandoned?.(record);
-                continue;
-            }
+        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
@@ -145,7 +163,23 @@ export class ResidentLaunchJournal {
             this.host.waitUntil(this.host.redrive(record, record.attempt + 1)
                 .catch((e) => {
                 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.
+     */
+    async supersede(key) {
+        try {
+            await this.storage.delete(key);
+            await this.storage.sync();
+        }
+        catch (e) {
+            console.warn('[nimbus] resident launch journal supersede failed:', errorMessage(e));
         }
     }
 }

package/dist/generation.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare 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;
+}
+/** This incarnation's generation. Zero until {@link adoptGeneration} ran. */
+export declare function generation(ctx: object): number;
+/** Increment + persist the generation counter once per fresh isolate. */
+export declare function adoptGeneration(ctx: GenerationContext): Promise<void>;
+/**
+ * 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 declare function assumeGeneration(ctx: object, value: number): void;
+/**
+ * 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 declare function onColdStart(ctx: object, task: () => Promise<unknown>): void;
+/**
+ * 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 declare function runColdStart(ctx: object): Promise<void>;
+//# sourceMappingURL=generation.d.ts.map

package/dist/generation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generation.d.ts","sourceRoot":"","sources":["../src/generation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAE/C,2DAA2D;AAC3D,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAED,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAsBD,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,yEAAyE;AACzE,wBAAsB,eAAe,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0B3E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAE3E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYvD"}