@nimbus-sh/fabric 0.1.0 → 0.3.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;
     /**
@@ -126,13 +131,16 @@ export declare class ResidentLaunchJournal<R extends ResidentLaunchRecord> {
      * paying a storage delete for pids that never had a row.
      */
     private journalledPids;
+    /** 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;
     /** 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
-     * 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
@@ -153,6 +161,28 @@ export declare class ResidentLaunchJournal<R extends ResidentLaunchRecord> {
      * resurrect a process the user watched end.
      */
     release(pid: number): Promise<void>;
+    /**
+     * 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.
+     */
+    purgeWhere(predicate: (record: R) => boolean): Promise<number>;
+    /**
+     * 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.
+     */
+    rows(): Promise<Map<string, R>>;
+    /**
+     * 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>;
     /**
      * Re-drive the launches a previous instance was building when it was reset.
      *
@@ -162,9 +192,20 @@ export declare 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.
      */
     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":"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"}

package/dist/fenced-work.js

@@ -0,0 +1,241 @@
+/**
+ * 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
+ * outstanding in storage ("Internal error in Durable Object storage caused
+ * object to be reset"), and a resident launch is the largest writer a session
+ * has. Everything a launch holds is in memory, so the process it is building
+ * and the terminal watching it both go with the instance — the journal is what
+ * a LATER instance reads to know that happened, and this module is the whole
+ * of that mechanism: the put→sync durability barrier on the way in, the
+ * delete→sync release on the way out, and the once-per-instance recovery pump
+ * that re-drives what a previous generation left behind.
+ *
+ * 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 FencedWorkRecord}; everything else in the record rides through
+ * opaquely.
+ */
+/**
+ * Prefix for the resident-process journal: one row per resident this session
+ * owes the user, keyed by the pid it was built for.
+ *
+ * A resident holds its state in memory — the process table entry, the facet
+ * handle, the terminal — so an instance reset destroys it silently. The row
+ * is what a LATER instance reads to know a resident ended that way rather
+ * than on purpose: a pid at or below the reader's own pid base was allocated
+ * by a previous generation (PID_GEN_STRIDE, core's process-table). Written
+ * (and synced) before the launch's first byte of work, rewritten as `running`
+ * when the launch settles, and released only when the PROCESS ends — because
+ * the resets this row survives strike after the launch as often as during it
+ * (measured live, staging 2026-08-13: every observed reset landed seconds
+ * AFTER settle).
+ *
+ * The VALUE is live production DO storage and must never change — renaming a
+ * storage key is a migration, and orphaned rows are the least of what it
+ * breaks.
+ */
+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 FENCED_WORK_MAX_ATTEMPT = 1;
+/**
+ * The resident-launch journal of one Durable Object instance.
+ *
+ * In-memory state here is per-instance on purpose: `journalledPids` tracks the
+ * rows THIS instance wrote, and `recovered` whether this instance has already
+ * read the journal a reset leaves behind. Rows from a previous instance are
+ * recovery's to consume, never the release path's.
+ */
+export class FencedWork {
+    storage;
+    host;
+    /**
+     * 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.
+     */
+    journalledPids = new Set();
+    /** 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. */
+    drives = new Map();
+    /** Whether this instance has already read the journal a reset leaves behind. */
+    recovered = false;
+    constructor(storage, host) {
+        this.storage = storage;
+        this.host = host;
+    }
+    /**
+     * Record a launch as in flight, so an instance that replaces this one knows
+     * 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
+     * outstanding — measured live, a launch killed in its first chunks left NO
+     * row for the replacement instance to find, which is how the recovery this
+     * feeds sat inert while its own test stayed green. `sync()` is the storage
+     * layer's durability barrier: the row is on disk before the launch performs
+     * its first byte of real work. What remains is a reset between the put and
+     * the sync's completion — and a launch that dies there has not started, so
+     * losing its row costs a retype, not a recovery.
+     */
+    async journal(record) {
+        this.journalledPids.add(record.pid);
+        try {
+            await this.storage.put(`${FENCED_WORK_KEY_PREFIX}${record.pid}`, record);
+            await this.storage.sync();
+        }
+        catch (cause) {
+            throw new Error('resident launch journal write failed', { cause });
+        }
+    }
+    /** True while this instance holds a journal row for `pid`. */
+    has(pid) {
+        return this.journalledPids.has(pid);
+    }
+    /**
+     * The journal row's one release: the process is over, nothing is owed.
+     * Synced so an instance reset moments later cannot roll the delete back and
+     * resurrect a process the user watched end.
+     */
+    async release(pid) {
+        if (!this.journalledPids.delete(pid))
+            return;
+        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) {
+        const rows = await this.storage.list({ 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() {
+        return this.storage.list({ 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, record) {
+        let inflight = this.drives.get(key);
+        if (inflight === undefined) {
+            inflight = (async () => {
+                let failed = false;
+                try {
+                    await this.host.redrive(record, record.attempt + 1);
+                }
+                catch (e) {
+                    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;
+    }
+    /**
+     * Re-drive the launches a previous instance was building when it was reset.
+     *
+     * Sited on the launch-turn pump because the pump is what an alarm calls, and
+     * a launch that was suspended has an alarm armed for it — a reset during a
+     * chunk fails that alarm, and the platform re-delivers it to the instance
+     * that replaces this one. So the first turn after a reset is already this
+     * one.
+     *
+     * 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() {
+        if (this.recovered)
+            return;
+        this.recovered = true;
+        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
+            // 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;
+            (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. `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));
+        }
+    }
+    /**
+     * 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) {
+        await this.storage.delete(key);
+        await this.storage.sync();
+    }
+}