@nimbus-sh/fabric 0.1.0 → 0.3.0

package/src/{loader-pool.ts → isolate-pool.ts}

@@ -1,5 +1,5 @@
 /**
- * loader-pool.ts — Nimbus loader-isolate pool based on cloudflare-parallel.
+ * isolate-pool.ts — Nimbus loader-isolate pool based on cloudflare-parallel.
  *
  * Adds Nimbus-specific behavior to the upstream pool design:
  *   1. **Stable-slot isolate reuse**. Upstream's #counter++ gives every
@@ -14,7 +14,7 @@
  *      reach https://registry.npmjs.org without a proxy binding).
  *   3. **Supervisor autoinjection**. The pool grabs the embedder's
  *      registered supervisor entrypoint stub (see `supervisorEntrypoint` in
- *      ctx-exports.ts) and forwards it as `env.SUPERVISOR` to every facet,
+ *      composition.ts) and forwards it as `env.SUPERVISOR` to every facet,
  *      same pattern as git-network-facet.ts. Callers can add more bindings
  *      via `extraBindings`.
  *   4. **Fail-loud defaults**: timeout 60s, retries 0, onError 'throw'.
@@ -25,13 +25,13 @@
  */
 
 import { CF_COMPAT_DATE } from '@nimbus-sh/core/constants.js';
-import { supervisorEntrypoint } from './ctx-exports.js';
-import { disposeRpcResource } from '@nimbus-sh/core/_shared/rpc-dispose.js';
+import { supervisorEntrypoint } from './composition.js';
+import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
 import { serializeFunction, hashSource } from './vendor/serialize.js';
-import { beginLoaderFetch, recordLoaderId, withDynamicWorkerCapNamed } from './loader-ledger.js';
-import { assertModuleMapWithinCodeLimit } from './workerd-facet-host.js';
-import { recordFailure, setLastFacetId, getLastRpcFrame } from '@nimbus-sh/core/observability/oom-discriminator.js';
-import { classifyError } from '@nimbus-sh/core/observability/oom-classify.js';
+import { beginLoaderFetch, recordLoaderId, withDynamicWorkerCapNamed } from './budgets.js';
+import { assertModuleMapWithinCodeLimit } from './budgets.js';
+import { recordFailure, setLastFacetId, getLastRpcFrame } from '@nimbus-sh/platform/oom-discriminator.js';
+import { classifyError } from '@nimbus-sh/platform/oom-classify.js';
 import {
   BindingError,
   ExecutionError,
@@ -55,12 +55,12 @@ export type FacetTaskFn<A, R> = {
 }['task'];
 
 /** The one binding a pool needs off whichever env its host hands it. */
-export interface LoaderPoolEnv {
+export interface IsolatePoolEnv {
   LOADER?: WorkerLoader;
 }
 
-/** Options handed to LoaderPool's constructor. */
-export interface LoaderPoolOptions {
+/** Options handed to IsolatePool's constructor. */
+export interface IsolatePoolOptions {
   /** Maximum concurrent in-flight facets. Default 4. */
   concurrency?: number;
   /** Per-task timeout in ms. Default 60_000. */
@@ -97,8 +97,8 @@ export interface LoaderPoolOptions {
    * Override the `doId` baked into the auto-injected SUPERVISOR binding.
    * Default: `ctx.id.toString()` (the DO that constructs the pool).
    *
-   * Used by FanoutPool's peer-DO branch (peer-DO fanout): peer DOs
-   * construct their per-task LoaderPool from inside
+   * Used by Fanout's peer-DO branch (peer-DO fanout): peer DOs
+   * construct their per-task IsolatePool from inside
    * `_rpcFanoutExecute`, where `ctx` is the PEER DO's ctx. Without this
    * override the peer's auto-injected SUPERVISOR routes back to the
    * peer DO itself — so writes (e.g. install-batch-facet's
@@ -170,7 +170,7 @@ export interface LoaderPoolOptions {
 }
 
 /** Per-call override (merged with pool defaults). */
-export interface LoaderCallOptions {
+export interface IsolateCallOptions {
   timeoutMs?: number;
   retries?: number;
   /**
@@ -206,7 +206,7 @@ export interface LoaderCallOptions {
 }
 
 /** Per-map override. Adds onError strategy for partial failures. */
-export interface LoaderMapOptions extends LoaderCallOptions {
+export interface IsolateMapOptions extends IsolateCallOptions {
   /** Concurrency override for this call. Defaults to pool's concurrency. */
   concurrency?: number;
   /**
@@ -327,7 +327,7 @@ export function assembleLoaderWorkerModuleSource(
  *
  * Typical use:
  *
- *   const pool = new LoaderPool(env, ctx, {
+ *   const pool = new IsolatePool(env, ctx, {
  *     concurrency: 4,
  *     tag: 'npm-install',
  *   });
@@ -336,9 +336,9 @@ export function assembleLoaderWorkerModuleSource(
  *     toFetch,
  *   );
  */
-export class LoaderPool {
+export class IsolatePool {
   private readonly loader: WorkerLoader;
-  /** The hosting actor, as the loader-ledger's per-DO key. */
+  /** The hosting actor, as the loader budget ledger's per-DO key. */
   private readonly ctx: DurableObjectState;
   private readonly concurrency: number;
   private readonly defaultTimeoutMs: number;
@@ -351,7 +351,7 @@ export class LoaderPool {
   private readonly preambleHash: string;
   /**
    * WASM modules to ship in the LOADER `modules` map. See
-   * LoaderPoolOptions.wasmModules for the rationale. Stored in
+   * IsolatePoolOptions.wasmModules for the rationale. Stored in
    * insertion order so the per-import preamble we generate matches
    * across pool dispatches (cache-key stability).
    */
@@ -384,14 +384,14 @@ export class LoaderPool {
   constructor(
     env: unknown,
     ctx: DurableObjectState,
-    opts?: LoaderPoolOptions,
+    opts?: IsolatePoolOptions,
   ) {
     // A host hands its whole env over; the binding is claimed here and the
     // claim is checked on the next line.
-    const loader = (env as LoaderPoolEnv | null | undefined)?.LOADER;
+    const loader = (env as IsolatePoolEnv | null | undefined)?.LOADER;
     if (!loader || typeof loader.get !== 'function') {
       throw new BindingError(
-        'LoaderPool: env.LOADER binding missing or invalid. ' +
+        'IsolatePool: env.LOADER binding missing or invalid. ' +
           'Add a [[worker_loaders]] entry to wrangler.jsonc.',
       );
     }
@@ -423,14 +423,14 @@ export class LoaderPool {
           // value is whatever it really was rather than the ArrayBuffer here.
           const got = (bytes as { constructor?: { name?: string } } | null | undefined)?.constructor?.name;
           throw new BindingError(
-            `LoaderPool: wasmModules['${name}'] must be ArrayBuffer ` +
+            `IsolatePool: wasmModules['${name}'] must be ArrayBuffer ` +
             `(got ${got || typeof bytes}).`,
           );
         }
         const id = name.replace(/[^A-Za-z0-9_]/g, '_').replace(/^[^A-Za-z_]/, '_');
         if (seenIds.has(id)) {
           throw new BindingError(
-            `LoaderPool: wasmModules key '${name}' collides with another after ` +
+            `IsolatePool: wasmModules key '${name}' collides with another after ` +
             `identifier-sanitisation (id='${id}'). Pick distinct module names.`,
           );
         }
@@ -488,7 +488,7 @@ export class LoaderPool {
     return this.concurrency;
   }
 
-  #resolve(opts?: LoaderCallOptions): ResolvedResilience {
+  #resolve(opts?: IsolateCallOptions): ResolvedResilience {
     return {
       timeoutMs: Math.max(0, opts?.timeoutMs ?? this.defaultTimeoutMs),
       retries: Math.max(0, opts?.retries ?? this.defaultRetries),
@@ -515,21 +515,21 @@ export class LoaderPool {
       if (!(bytes instanceof ArrayBuffer)) {
         const got = (bytes as { constructor?: { name?: string } } | null | undefined)?.constructor?.name;
         throw new BindingError(
-          `LoaderPool: per-call wasmModules['${name}'] must be ` +
+          `IsolatePool: per-call wasmModules['${name}'] must be ` +
             `ArrayBuffer (got ${got || typeof bytes}).`,
         );
       }
       const id = name.replace(/[^A-Za-z0-9_]/g, '_').replace(/^[^A-Za-z_]/, '_');
       if (ctorIds.has(id)) {
         throw new BindingError(
-          `LoaderPool: per-call wasmModules key '${name}' (sanitised ` +
+          `IsolatePool: per-call wasmModules key '${name}' (sanitised ` +
             `id='${id}') collides with a constructor-time wasm module. ` +
             `Per-call modules cannot shadow pool-defaults. Pick a distinct name.`,
         );
       }
       if (seen.has(id)) {
         throw new BindingError(
-          `LoaderPool: per-call wasmModules key '${name}' (sanitised ` +
+          `IsolatePool: per-call wasmModules key '${name}' (sanitised ` +
             `id='${id}') collides with another per-call key. Pick distinct names.`,
         );
       }
@@ -620,7 +620,7 @@ export class LoaderPool {
     // re-import (the user fn is serialized via fn.toString and doesn't
     // carry import statements).
     //
-    // Per-call entries (passed via LoaderCallOptions.wasmModules
+    // Per-call entries (passed via IsolateCallOptions.wasmModules
     // — used by the wasm-runner shell command) are appended to the same
     // table. Naming collision with constructor entries is rejected
     // upstream in #materialisePerCallWasm so the import block here
@@ -843,7 +843,7 @@ export class LoaderPool {
   async submit<T, R>(
     fn: FacetTaskFn<T, R>,
     arg: T,
-    opts?: LoaderCallOptions,
+    opts?: IsolateCallOptions,
   ): Promise<Awaited<R>> {
     const { fnSource, fnHash } = this.#prepare(fn);
     const resilience = this.#resolve(opts);
@@ -866,7 +866,7 @@ export class LoaderPool {
   async map<T, R>(
     fn: FacetTaskFn<T, R>,
     items: T[],
-    opts?: LoaderMapOptions,
+    opts?: IsolateMapOptions,
   ): Promise<Array<Awaited<R> | null>> {
     if (items.length === 0) return [];
 
@@ -877,7 +877,7 @@ export class LoaderPool {
   /**
    * Same shape as `map`, but accepts a pre-serialized function source
    * string instead of a live function reference. Used by
-   * `FanoutPool`'s peer-DO leg, where the function was already
+   * `Fanout`'s peer-DO leg, where the function was already
    * serialized on the coordinator side and forwarded over RPC.
    *
    * The fnSource MUST be the output of `serializeFunction(fn)`
@@ -894,7 +894,7 @@ export class LoaderPool {
   async mapSource<T, R>(
     fnSource: string,
     items: T[],
-    opts?: LoaderMapOptions,
+    opts?: IsolateMapOptions,
   ): Promise<Array<Awaited<R> | null>> {
     if (items.length === 0) return [];
     const fnHash = hashSource(fnSource);
@@ -905,7 +905,7 @@ export class LoaderPool {
     fnSource: string,
     fnHash: string,
     items: T[],
-    opts?: LoaderMapOptions,
+    opts?: IsolateMapOptions,
   ): Promise<Array<Awaited<R> | null>> {
     const resilience = this.#resolve(opts);
     const concurrency = Math.max(

package/src/journal.ts

@@ -0,0 +1,242 @@
+/**
+ * journal.ts — an append-only event journal with dedupe and delivery leases,
+ * over a Durable Object's own SQLite.
+ *
+ * Modeled on Proteus's EventLog (`core/src/events/hub/log.ts`), which proved
+ * the contract this keeps:
+ *
+ *   - `publish` returns `{ id, admitted }` — a dedupe hit returns the
+ *     EXISTING id with `admitted: false` (log.ts:53-58), and the dedupe is
+ *     storage-level: a unique partial index over non-null keys, because its
+ *     schema comment calls the indexes "mandatory — without them recovery
+ *     scans regress to table-scans on the hot path" (hub/schema.ts:6-7).
+ *   - pending reads are priority-ordered: higher priority first, arrival
+ *     order within a priority.
+ *
+ * Where this deliberately differs: Proteus binds a delivery by writing
+ * `consumed_at` and then needs a cold-start sweep (`unbindStale`, 10 minutes,
+ * orchestrator.ts:196) to recover rows a dead activation left bound. Here a
+ * claim takes a LEASE that expires on its own — expiry alone re-pends the
+ * row, so recovery needs no sweep and no cold-start hook. A lease that
+ * expired and was re-claimed is fenced by a per-claim nonce: the dead
+ * holder's `done`/`defer`/`dismiss` returns false instead of clobbering the
+ * new claimant.
+ *
+ * Everything here is synchronous — DO SQLite is — so the journal is safe to
+ * touch from a constructor without awaiting on the init gate.
+ *
+ * The index set is derived from this module's own query set, not copied from
+ * the consumer's nine: the claim scan gets a partial index over pending rows
+ * in claim order, and the dedupe probe gets the unique partial index. No
+ * other query here repeats on a hot path.
+ */
+
+import { z } from 'zod/v4';
+
+/** Synchronous DO SQLite, as the journal uses it. */
+export interface JournalSqlExec {
+  exec(query: string, ...bindings: Array<string | number | null>): Iterable<unknown>;
+}
+
+export interface JournalContext {
+  storage: { sql: JournalSqlExec };
+}
+
+export interface JournalPublishResult {
+  /** The event id — the existing one when the publish was a duplicate. */
+  id: string;
+  /** False when the dedupe key already existed; nothing was written. */
+  admitted: boolean;
+}
+
+/** One claimed delivery: the record, and the lease that settles it. */
+export interface JournalClaim<P> {
+  id: string;
+  payload: P;
+  priority: number;
+  receivedAt: number;
+  lease: JournalLease;
+}
+
+/**
+ * One delivery lease. Every settle returns whether THIS lease still held the
+ * row — false means the lease expired and another claim owns it now, and
+ * nothing was written.
+ */
+export interface JournalLease {
+  /** The event is handled; it never delivers again. */
+  done(): boolean;
+  /** Release the lease and hide the event until `at`. */
+  defer(at: number): boolean;
+  /** The event is refused for good; it never delivers again. */
+  dismiss(reason: string): boolean;
+}
+
+const ClaimRowSchema = z.object({
+  id: z.string(),
+  payload: z.string(),
+  priority: z.number(),
+  received_at: z.number(),
+});
+
+const NAME_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;
+
+/** One named journal on one hosting actor. Cheap accessor, like `timers()`. */
+export function journal<P>(ctx: JournalContext, name: string): Journal<P> {
+  return new Journal(ctx, name);
+}
+
+export class Journal<P> {
+  private readonly table: string;
+  private schemaReady = false;
+  private lastId = '';
+  private seq = 0;
+  private leaseSeq = 0;
+
+  constructor(private readonly ctx: JournalContext, name: string) {
+    if (!NAME_PATTERN.test(name)) {
+      throw new Error(`fabric: journal name '${name}' must match ${NAME_PATTERN}`);
+    }
+    this.table = `journal_${name}`;
+  }
+
+  private ensureSchema(): void {
+    if (this.schemaReady) return;
+    const sql = this.ctx.storage.sql;
+    sql.exec(`CREATE TABLE IF NOT EXISTS ${this.table} (
+      id             TEXT    PRIMARY KEY,
+      payload        TEXT    NOT NULL,
+      dedupe_key     TEXT,
+      priority       INTEGER NOT NULL DEFAULT 0,
+      state          TEXT    NOT NULL DEFAULT 'pending'
+                             CHECK (state IN ('pending', 'done', 'dismissed')),
+      received_at    INTEGER NOT NULL,
+      not_before     INTEGER NOT NULL DEFAULT 0,
+      lease_id       TEXT,
+      lease_until    INTEGER,
+      done_at        INTEGER,
+      dismiss_reason TEXT
+    )`);
+    sql.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_${this.table}_dedupe
+      ON ${this.table} (dedupe_key) WHERE dedupe_key IS NOT NULL`);
+    // The claim scan in its own order, over pending rows only — done history
+    // grows without bound and must never be what recovery reads through.
+    sql.exec(`CREATE INDEX IF NOT EXISTS idx_${this.table}_pending
+      ON ${this.table} (priority DESC, id) WHERE state = 'pending'`);
+    const rows = [...sql.exec(`SELECT MAX(id) AS id FROM ${this.table}`)] as Array<{ id: string | null }>;
+    this.lastId = rows[0]?.id ?? '';
+    this.schemaReady = true;
+  }
+
+  /** Same shape as the outbox's: time-ordered, forced above every stored id. */
+  private mintId(now: number): string {
+    let id = `${now.toString(36).padStart(9, '0')}-${(this.seq++).toString(36).padStart(6, '0')}`;
+    if (this.lastId !== '' && id <= this.lastId) id = `${this.lastId}0`;
+    this.lastId = id;
+    return id;
+  }
+
+  /**
+   * Append one event. A dedupe key that already exists — pending, done, or
+   * dismissed — refuses the append and names the existing id.
+   */
+  publish(payload: P, opts: { dedupeKey?: string; priority?: number; now?: number } = {}): JournalPublishResult {
+    this.ensureSchema();
+    const now = opts.now ?? Date.now();
+    const sql = this.ctx.storage.sql;
+    if (opts.dedupeKey !== undefined) {
+      const existing = [...sql.exec(
+        `SELECT id FROM ${this.table} WHERE dedupe_key = ?`, opts.dedupeKey,
+      )] as Array<{ id: string }>;
+      if (existing.length > 0) return { id: existing[0].id, admitted: false };
+    }
+    const id = this.mintId(now);
+    sql.exec(
+      `INSERT INTO ${this.table} (id, payload, dedupe_key, priority, received_at, not_before)
+       VALUES (?, ?, ?, ?, ?, 0)`,
+      id, JSON.stringify(payload), opts.dedupeKey ?? null, opts.priority ?? 0, now,
+    );
+    return { id, admitted: true };
+  }
+
+  /**
+   * Claim deliverable events under a lease: pending, at or past their
+   * revisit time, and not held by a live lease. Higher priority first,
+   * arrival order within a priority. Expiry alone re-pends a row a dead
+   * holder left leased — that is the whole recovery path.
+   */
+  claim(opts: { leaseMs: number; minPriority?: number; limit?: number; now?: number }): Array<JournalClaim<P>> {
+    this.ensureSchema();
+    const now = opts.now ?? Date.now();
+    const sql = this.ctx.storage.sql;
+    const rows = [...sql.exec(
+      `SELECT id, payload, priority, received_at FROM ${this.table}
+       WHERE state = 'pending'
+         AND priority >= ?
+         AND not_before <= ?
+         AND (lease_until IS NULL OR lease_until <= ?)
+       ORDER BY priority DESC, id
+       LIMIT ?`,
+      opts.minPriority ?? -2147483648, now, now, opts.limit ?? 50,
+    )].map((row) => ClaimRowSchema.parse(row));
+    const claims: Array<JournalClaim<P>> = [];
+    for (const row of rows) {
+      const leaseId = `${now.toString(36)}-${(this.leaseSeq++).toString(36)}`;
+      sql.exec(
+        `UPDATE ${this.table} SET lease_id = ?, lease_until = ? WHERE id = ?`,
+        leaseId, now + opts.leaseMs, row.id,
+      );
+      claims.push({
+        id: row.id,
+        payload: JSON.parse(row.payload) as P,
+        priority: row.priority,
+        receivedAt: row.received_at,
+        lease: this.lease(row.id, leaseId),
+      });
+    }
+    return claims;
+  }
+
+  /**
+   * The settle ops all share one fence: they write only while the row is
+   * still pending under THIS lease's nonce. An expired-and-reclaimed row has
+   * a different nonce, so the dead holder's settle is a refused no-op —
+   * synchronous SQL makes the check-then-write atomic on the actor thread.
+   */
+  private lease(id: string, leaseId: string): JournalLease {
+    const sql = this.ctx.storage.sql;
+    const holds = (): boolean => {
+      const rows = [...sql.exec(
+        `SELECT 1 AS held FROM ${this.table} WHERE id = ? AND state = 'pending' AND lease_id = ?`,
+        id, leaseId,
+      )];
+      return rows.length > 0;
+    };
+    return {
+      done: (): boolean => {
+        if (!holds()) return false;
+        sql.exec(
+          `UPDATE ${this.table} SET state = 'done', done_at = ?, lease_id = NULL, lease_until = NULL WHERE id = ?`,
+          Date.now(), id,
+        );
+        return true;
+      },
+      defer: (at: number): boolean => {
+        if (!holds()) return false;
+        sql.exec(
+          `UPDATE ${this.table} SET not_before = ?, lease_id = NULL, lease_until = NULL WHERE id = ?`,
+          at, id,
+        );
+        return true;
+      },
+      dismiss: (reason: string): boolean => {
+        if (!holds()) return false;
+        sql.exec(
+          `UPDATE ${this.table} SET state = 'dismissed', dismiss_reason = ?, lease_id = NULL, lease_until = NULL WHERE id = ?`,
+          reason, id,
+        );
+        return true;
+      },
+    };
+  }
+}

package/src/node-async-hooks.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Minimal typing for the one node builtin fabric uses. The repo compiles
+ * against workers-types only (no @types/node), and pulling all of
+ * @types/node for one class would let untyped node surface leak into
+ * workerd code. workerd ships AsyncLocalStorage under `nodejs_compat`
+ * (probe-verified 2026-05-04, see core's real-node-imports.ts matrix);
+ * bun and node ship it natively.
+ */
+declare module 'node:async_hooks' {
+  export class AsyncLocalStorage<T> {
+    run<R>(store: T, callback: () => R): R;
+    getStore(): T | undefined;
+  }
+}