@nimbus-sh/fabric 0.1.0 → 0.2.0

package/dist/outbox.js

@@ -0,0 +1,355 @@
+/**
+ * outbox.ts — a durable retry outbox over a Durable Object's own SQLite.
+ *
+ * Proteus built this discipline twice by hand and says so: its email outbox
+ * (`cf-backend/src/email/outbox.ts:7` — "The discipline mirrors the peer
+ * outbox", 8 attempts from a 30s base) and its peer transport
+ * (`core/src/events/ingress/peer.ts` — 8 attempts from a 5s base, per-receiver
+ * ordering, an ask/reply waiter over the same rows). Both carry the same
+ * mechanism: a write-ahead intent row in `state='pending'`, an
+ * `attempt_count`, a `next_attempt_at` with a partial index over pending rows,
+ * backoff `next = now + base * 2**(attempts-1)`, and a `nextRetryAt()` folded
+ * into the object's single alarm. This module is that mechanism once.
+ *
+ * What the consumers proved and this keeps:
+ *   - WRITE-AHEAD. The row commits before send runs. On a Durable Object the
+ *     output gate orders it: an outbound message cannot leave before the
+ *     writes of its turn are durable, so no explicit sync is needed here.
+ *   - DISPOSITION, not a boolean. peer.ts:476-526 separates three failures: a
+ *     RESOLVED refusal is permanent (dlq now), a THROWN send is transport
+ *     trouble (backoff), a malformed row is poison (dlq now, no send). A
+ *     boolean cannot carry that, and retrying a refusal re-offends.
+ *   - ORDERING per key. Rows drain in id order. A transient failure blocks
+ *     later rows with the same order key until the head clears (peer.ts:465
+ *     head-of-line set); a dead-lettered head does not block, and keyless rows
+ *     never block each other (the email outbox has no ordering at all).
+ *   - IDEMPOTENCY. A dedupe key already queued or sent is refused with the
+ *     existing id, and a sent key never reaches send again.
+ *
+ * What the consumers lacked and this adds:
+ *   - The drain registers with `timers` (one reason in the shared map) instead
+ *     of owning an alarm, and the dispatch-side handler re-arms through its
+ *     RETURN value — calling schedule() from inside the dispatcher's chain
+ *     would deadlock on the chain that serializes the reason map. A host
+ *     whose alarm belongs to another framework (the Agents SDK, agent-core's
+ *     reconciler) uses the scheduler-seam form instead: fabric hands every
+ *     next due time to the policy's `schedule` and touches no timer storage.
+ *   - The drain is turn-bounded through a {@link TurnBudget}: both consumer
+ *     drains iterate every due row in one turn, which is the same
+ *     thread-holding shape the pacer exists to end.
+ *
+ * ADOPTION IS A DATA MIGRATION for a live consumer. The rows live in
+ * fabric's own table (`outbox_<name>`), and nothing moves itself: a consumer
+ * with pending intents or a sent-key dedupe history in its old table keeps
+ * them there. The ported EmailOutbox went from `email_outbox` to
+ * `outbox_email` — deployed live without a migration, its pending mail would
+ * never send and every sent key would deliver a second time.
+ */
+import { z } from 'zod/v4';
+import { timers } from './timers.js';
+const PendingRowSchema = z.object({
+    id: z.string(),
+    message: z.string(),
+    order_key: z.string().nullable(),
+    attempt_count: z.number(),
+    next_attempt_at: z.number(),
+});
+const DlqRowSchema = z.object({
+    id: z.string(),
+    message: z.string(),
+    dedupe_key: z.string().nullable(),
+    attempt_count: z.number(),
+    last_error: z.string().nullable(),
+});
+const RecordRowSchema = z.object({
+    id: z.string(),
+    state: z.enum(['pending', 'sent', 'dlq']),
+    message: z.string(),
+    dedupe_key: z.string().nullable(),
+    attempt_count: z.number(),
+    last_error: z.string().nullable(),
+});
+const NAME_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;
+export function outbox(...args) {
+    if (args.length === 4) {
+        const [host, ctx, name, policy] = args;
+        return new Outbox(ctx, name, policy, { kind: 'timers', host, ctx });
+    }
+    const [ctx, name, policy] = args;
+    return new Outbox(ctx, name, policy, { kind: 'schedule', schedule: (at) => policy.schedule(at) });
+}
+export class Outbox {
+    ctx;
+    policy;
+    scheduling;
+    /** The timer reason this outbox arms in the shared map. */
+    reason;
+    table;
+    schemaReady = false;
+    draining = false;
+    /** Largest id ever seen, so a replacement instance mints above it. */
+    lastId = '';
+    seq = 0;
+    constructor(ctx, name, policy, scheduling) {
+        this.ctx = ctx;
+        this.policy = policy;
+        this.scheduling = scheduling;
+        if (!NAME_PATTERN.test(name)) {
+            throw new Error(`fabric: outbox name '${name}' must match ${NAME_PATTERN}`);
+        }
+        this.table = `outbox_${name}`;
+        this.reason = `outbox:${name}`;
+    }
+    ensureSchema() {
+        if (this.schemaReady)
+            return;
+        const sql = this.ctx.storage.sql;
+        sql.exec(`CREATE TABLE IF NOT EXISTS ${this.table} (
+      id              TEXT    PRIMARY KEY,
+      dedupe_key      TEXT,
+      order_key       TEXT,
+      message         TEXT    NOT NULL,
+      state           TEXT    NOT NULL DEFAULT 'pending'
+                              CHECK (state IN ('pending', 'sent', 'dlq')),
+      attempt_count   INTEGER NOT NULL DEFAULT 0,
+      next_attempt_at INTEGER NOT NULL,
+      created_at      INTEGER NOT NULL,
+      sent_at         INTEGER,
+      last_error      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 recovery read (`nextRetryAt`, the drain) must not table-scan sent
+        // history, which only grows — the same reason both consumer schemas carry
+        // exactly this partial index.
+        sql.exec(`CREATE INDEX IF NOT EXISTS idx_${this.table}_pending
+      ON ${this.table} (next_attempt_at) WHERE state = 'pending'`);
+        const rows = [...sql.exec(`SELECT MAX(id) AS id FROM ${this.table}`)];
+        this.lastId = rows[0]?.id ?? '';
+        this.schemaReady = true;
+    }
+    /**
+     * Ids order the drain, so they must grow: time-prefixed, tie-broken by a
+     * per-instance counter, and forced above the largest stored id so a
+     * replacement instance with a lagging clock cannot mint into the past.
+     */
+    mintId(now) {
+        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;
+    }
+    /**
+     * Write the intent ahead of any send. Returns `admitted: false` with the
+     * existing id when the dedupe key is already queued, sent, or dead-lettered
+     * — a sent key never reaches send again (the email outbox's short-circuit).
+     *
+     * `onDuplicate: 'retry-now'` treats a re-ask for an UNSENT key as new
+     * intent: the row's retry instant is clamped to `now` and a dead letter
+     * returns to 'pending', its attempt count kept — so every re-ask buys one
+     * more delivery attempt, past the attempt budget. The monitor's alert-once
+     * contract needs exactly this: a failed alert is retried by each sweep
+     * until it lands. A sent key stays final either way.
+     *
+     * Arms the scheduler at `now`, so delivery is owed by the alarm even
+     * when the caller never drains inline.
+     */
+    async queue(message, opts = {}) {
+        this.ensureSchema();
+        const now = opts.now ?? Date.now();
+        const sql = this.ctx.storage.sql;
+        if (opts.dedupeKey !== undefined) {
+            const existing = [...sql.exec(`SELECT id, state FROM ${this.table} WHERE dedupe_key = ?`, opts.dedupeKey)];
+            if (existing.length > 0) {
+                if (opts.onDuplicate === 'retry-now' && existing[0].state !== 'sent') {
+                    sql.exec(`UPDATE ${this.table} SET state = 'pending', next_attempt_at = ? WHERE id = ?`, now, existing[0].id);
+                    await this.arm(now);
+                }
+                return { id: existing[0].id, admitted: false };
+            }
+        }
+        const id = this.mintId(now);
+        sql.exec(`INSERT INTO ${this.table} (id, dedupe_key, order_key, message, next_attempt_at, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`, id, opts.dedupeKey ?? null, this.policy.orderBy?.(message) ?? null, JSON.stringify(message), now, now);
+        await this.arm(now);
+        return { id, admitted: true };
+    }
+    /** Hand a due time to whichever scheduler this outbox was built on. */
+    async arm(at) {
+        if (this.scheduling.kind === 'timers') {
+            await timers(this.scheduling.host, this.scheduling.ctx).schedule(this.reason, at);
+        }
+        else {
+            await this.scheduling.schedule(at);
+        }
+    }
+    /** The single-alarm fold: the earliest pending deadline, or null. */
+    nextRetryAt() {
+        this.ensureSchema();
+        const rows = [...this.ctx.storage.sql.exec(`SELECT MIN(next_attempt_at) AS next FROM ${this.table} WHERE state = 'pending'`)];
+        return rows[0]?.next ?? null;
+    }
+    /** The row queue() named, by its id. Null when no such row exists. */
+    status(id) {
+        return this.record('id', id);
+    }
+    /** The row a dedupe key admitted, whatever its state. Null when none. */
+    find(dedupeKey) {
+        return this.record('dedupe_key', dedupeKey);
+    }
+    record(column, value) {
+        this.ensureSchema();
+        const rows = [...this.ctx.storage.sql.exec(`SELECT id, state, message, dedupe_key, attempt_count, last_error
+       FROM ${this.table} WHERE ${column} = ?`, value)];
+        if (rows.length === 0)
+            return null;
+        const row = RecordRowSchema.parse(rows[0]);
+        let message = null;
+        try {
+            message = JSON.parse(row.message);
+        }
+        catch { /* poison-parse row */ }
+        return {
+            id: row.id,
+            state: row.state,
+            message,
+            dedupeKey: row.dedupe_key,
+            attemptCount: row.attempt_count,
+            lastError: row.last_error,
+        };
+    }
+    /** Dead-lettered rows, for inspection. Terminal: nothing retries out. */
+    dlq() {
+        this.ensureSchema();
+        const rows = [...this.ctx.storage.sql.exec(`SELECT id, message, dedupe_key, attempt_count, last_error FROM ${this.table} WHERE state = 'dlq' ORDER BY id`)].map((row) => DlqRowSchema.parse(row));
+        return rows.map((row) => {
+            let message = null;
+            try {
+                message = JSON.parse(row.message);
+            }
+            catch { /* poison-parse row */ }
+            return {
+                id: row.id,
+                message,
+                dedupeKey: row.dedupe_key,
+                attemptCount: row.attempt_count,
+                lastError: row.last_error ?? '',
+            };
+        });
+    }
+    /**
+     * Deliver every due pending row, in id order, honouring per-key blocking.
+     * Reentrancy-guarded: the alarm and an inline post-queue drain overlap on
+     * the same activation (peer.ts:452 carries the same guard).
+     *
+     * `budget` bounds the turn: the drain spends each processed row's payload
+     * size and suspends when a chunk is full, so a large backlog crosses turns
+     * instead of holding the actor's only thread.
+     *
+     * `context` is handed to every `send` this drain makes — the seam for
+     * per-call state such as a transport binding resolved by the caller.
+     */
+    async drain(now = Date.now(), ...rest) {
+        const opts = rest[0] ?? {};
+        const result = { sent: 0, retried: 0, deadLettered: 0 };
+        if (this.draining)
+            return result;
+        this.draining = true;
+        try {
+            this.ensureSchema();
+            const sql = this.ctx.storage.sql;
+            const rows = [...sql.exec(`SELECT id, message, order_key, attempt_count, next_attempt_at
+         FROM ${this.table} WHERE state = 'pending' ORDER BY id`)].map((row) => PendingRowSchema.parse(row));
+            const blocked = new Set();
+            for (const row of rows) {
+                if (row.order_key !== null && blocked.has(row.order_key))
+                    continue;
+                if (row.next_attempt_at > now) {
+                    // A backed-off head still blocks the rows queued behind it.
+                    if (row.order_key !== null)
+                        blocked.add(row.order_key);
+                    continue;
+                }
+                let message;
+                try {
+                    message = JSON.parse(row.message);
+                }
+                catch (e) {
+                    // Unparseable is poison: it can never succeed, so it never blocks.
+                    this.deadLetter(row.id, row.attempt_count, `outbox row does not parse: ${errorText(e)}`);
+                    result.deadLettered++;
+                    continue;
+                }
+                const attempt = row.attempt_count + 1;
+                let disposition;
+                try {
+                    disposition = await this.policy.send(message, { id: row.id, attempt }, opts.context);
+                }
+                catch (e) {
+                    disposition = { status: 'retry', reason: errorText(e) };
+                }
+                if (disposition.status === 'sent') {
+                    sql.exec(`UPDATE ${this.table} SET state = 'sent', attempt_count = ?, sent_at = ?, last_error = NULL WHERE id = ?`, attempt, now, row.id);
+                    result.sent++;
+                }
+                else if (disposition.status === 'poison') {
+                    this.deadLetter(row.id, attempt, disposition.reason);
+                    result.deadLettered++;
+                }
+                else if (attempt >= this.policy.maxAttempts) {
+                    this.deadLetter(row.id, attempt, `undeliverable after ${attempt} attempts: ${disposition.reason}`);
+                    result.deadLettered++;
+                }
+                else {
+                    const next = now + this.policy.baseMs * 2 ** (attempt - 1);
+                    sql.exec(`UPDATE ${this.table} SET attempt_count = ?, next_attempt_at = ?, last_error = ? WHERE id = ?`, attempt, next, disposition.reason, row.id);
+                    result.retried++;
+                    if (row.order_key !== null)
+                        blocked.add(row.order_key);
+                }
+                // Code-unit length: equal to UTF-8 bytes for the ASCII JSON the rows
+                // hold, an undercount otherwise — the bound names where a turn ends,
+                // it is not an admission ceiling (same reading as budgets.ts).
+                await opts.budget?.spend(row.message.length);
+            }
+            // A seam-scheduled outbox re-arms itself: there is no dispatcher whose
+            // return value could, and the ported consumer re-armed by hand after
+            // every drain — delivery stays owed either way.
+            if (this.scheduling.kind === 'schedule') {
+                const next = this.nextRetryAt();
+                if (next !== null)
+                    await this.scheduling.schedule(next);
+            }
+            return result;
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+    deadLetter(id, attempts, error) {
+        this.ctx.storage.sql.exec(`UPDATE ${this.table} SET state = 'dlq', attempt_count = ?, last_error = ? WHERE id = ?`, attempts, error, id);
+    }
+    /**
+     * The dispatch-side entry for the embedder's timer handler map. Re-arms
+     * through the RETURN value: the dispatcher runs handlers inside the chain
+     * that serializes the reason map, so a schedule() call from here would
+     * deadlock on its own chain.
+     *
+     * An alarm fires with no caller, so a policy that declares a drain context
+     * receives it here once, closed over every alarm-driven drain.
+     */
+    handler(...context) {
+        if (this.scheduling.kind === 'schedule') {
+            throw new Error(`fabric: outbox '${this.reason}' uses a scheduler seam — there is no timer dispatcher to hand this handler to`);
+        }
+        return async (now) => {
+            await this.drain(now, ...[{ context: context[0] }]);
+            const next = this.nextRetryAt();
+            return next === null ? undefined : { rearmAt: next };
+        };
+    }
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/process-fabric.d.ts

@@ -5,7 +5,7 @@
  * Every long-lived process Nimbus runs — node servers, python/ruby socket
  * servers, an agent TUI and its headless server — runs as a **DO Facet**:
  * a named child actor whose class comes from a dynamic worker, opened by
- * `openResidentFacet` in `workerd-facet-host.ts`.
+ * `processes(ctx, env).spawn` in `workerd-facet-host.ts`.
  *
  *   ctx.facets.get(`proc-${pid}`, () => ({
  *     class: env.LOADER.get(workerKey, buildConfig)
@@ -141,18 +141,6 @@ export type ResidentBootSpec = {
     kind: 'code';
     code: ResidentCodeSpec;
 };
-/**
- * Assemble a complete Worker Loader config from a staged-artifact spec. The
- * embedder supplies this: a stage names artifact sources only the embedder
- * knows how to fetch (Nimbus's largest staged artifact is a ~23 MB module map from
- * ASSETS), and the assembler runs inside the loader's cache-miss callback so
- * those sources are materialized only while the facet actually loads.
- * `env` is whichever hosting actor's env the facet is opened with.
- */
-export type StagedBootAssembler = (env: unknown, stage: unknown) => Promise<object>;
-/** Registered once at composition time, first-write-wins. */
-export declare function setStagedBootAssembler(assembler: StagedBootAssembler): void;
-export declare function requireStagedBootAssembler(): StagedBootAssembler;
 /**
  * Where a generated module source is materialized so a boot spec can name it.
  *
@@ -324,7 +312,7 @@ export interface ProcessImageDelivery {
      * ends: the source exists and is populated before, the destination is
      * non-empty after. A blocklist of bad names would pass a typo straight
      * through and wipe a process's filesystem while returning ok. Enforced by
-     * `cloneFacetStorage` in the workerd host, which is the one way the fabric
+     * `cloneStorage` in the workerd host, which is the one way the fabric
      * calls clone.
      */
     readonly reflink: 'same-object' | 'impossible';

package/dist/process-fabric.d.ts.map

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

package/dist/process-fabric.js

@@ -5,7 +5,7 @@
  * Every long-lived process Nimbus runs — node servers, python/ruby socket
  * servers, an agent TUI and its headless server — runs as a **DO Facet**:
  * a named child actor whose class comes from a dynamic worker, opened by
- * `openResidentFacet` in `workerd-facet-host.ts`.
+ * `processes(ctx, env).spawn` in `workerd-facet-host.ts`.
  *
  *   ctx.facets.get(`proc-${pid}`, () => ({
  *     class: env.LOADER.get(workerKey, buildConfig)
@@ -131,20 +131,11 @@ export function residentBootSpecSchema(stageSchema) {
         z.object({ kind: z.literal('code'), code: ResidentCodeSpecSchema }),
     ]);
 }
-let _stagedBootAssembler = null;
-/** Registered once at composition time, first-write-wins. */
-export function setStagedBootAssembler(assembler) {
-    if (_stagedBootAssembler)
-        return;
-    _stagedBootAssembler = assembler;
-}
-export function requireStagedBootAssembler() {
-    if (!_stagedBootAssembler) {
-        throw new Error('fabric: no staged-boot assembler registered; a \'staged\' boot spec '
-            + 'cannot be assembled without one (setStagedBootAssembler)');
-    }
-    return _stagedBootAssembler;
-}
+// ── Staged boots ────────────────────────────────────────────────────────────
+//
+// A 'staged' boot spec assembles through the embedder's composed
+// StagedBootAssembler — see composition.ts. What a stage IS belongs to
+// whoever composed the assembler.
 // ── Boot-image store ────────────────────────────────────────────────────────
 /**
  * Where a generated module source is materialized so a boot spec can name it.

package/dist/process-host.d.ts

@@ -9,7 +9,7 @@
  *   peer  — the process is a named child actor of a SIBLING session DO, and
  *           the coordinator reaches it over one held-open RPC.
  *
- * Both call the same `openResidentFacet`. The peer leg is not a second process
+ * Both call the same `processes(ctx, env).spawn`. The peer leg is not a second process
  * implementation; it is the same call made on a different actor, which is why
  * the runner, the boot spec, the class name, the writer handshake, the start
  * contract and the lifecycle are shared code rather than parallel paths.

package/dist/process-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-host.d.ts","sourceRoot":"","sources":["../src/process-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAKH,OAAO,EAGL,KAAK,WAAW,EAIhB,KAAK,kBAAkB,EAExB,MAAM,qBAAqB,CAAC;AAU7B,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,CAAC;AAE/C;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,eAAe,EACrB,GAAG,EAAE,kBAAkB,EACvB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,kBAAkB,GAC7B,WAAW,CAIb;AAgFD,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC5B,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC5B,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;CAC7B;AA2BD;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,8BAA8B,CAAC;AACvE,eAAO,MAAM,kCAAkC,yCAAyC,CAAC;AA0RzF;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAWhE"}
+{"version":3,"file":"process-host.d.ts","sourceRoot":"","sources":["../src/process-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAKH,OAAO,EAGL,KAAK,WAAW,EAIhB,KAAK,kBAAkB,EAExB,MAAM,qBAAqB,CAAC;AAS7B,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,CAAC;AAE/C;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,eAAe,EACrB,GAAG,EAAE,kBAAkB,EACvB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,kBAAkB,GAC7B,WAAW,CAIb;AA8ED,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC5B,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC5B,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;CAC7B;AA2BD;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,8BAA8B,CAAC;AACvE,eAAO,MAAM,kCAAkC,yCAAyC,CAAC;AAwRzF;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAWhE"}

package/dist/process-host.js

@@ -9,7 +9,7 @@
  *   peer  — the process is a named child actor of a SIBLING session DO, and
  *           the coordinator reaches it over one held-open RPC.
  *
- * Both call the same `openResidentFacet`. The peer leg is not a second process
+ * Both call the same `processes(ctx, env).spawn`. The peer leg is not a second process
  * implementation; it is the same call made on a different actor, which is why
  * the runner, the boot spec, the class name, the writer handshake, the start
  * contract and the lifecycle are shared code rather than parallel paths.
@@ -63,10 +63,11 @@
  * {@link HOSTED_WEBSOCKET_KEY_HEADER} — and a per-process capability makes
  * that pair unforgeable by anything that did not open the process.
  */
-import { disposeRpcResource } from '@nimbus-sh/core/_shared/rpc-dispose.js';
-import { isTransientDoReset } from '@nimbus-sh/core/observability/oom-classify.js';
-import { PEER_RETRY_BACKOFF_MS, PEER_TRANSIENT_RESET_RETRIES } from './fanout-pool.js';
-import { DYNAMIC_WORKER_CODE_LIMIT_BYTES, openResidentFacet, residentFacetName, runOneShotWorker, } from './workerd-facet-host.js';
+import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
+import { isTransientDoReset } from '@nimbus-sh/platform/oom-classify.js';
+import { PEER_RETRY_BACKOFF_MS, PEER_TRANSIENT_RESET_RETRIES } from './fanout.js';
+import { DYNAMIC_WORKER_CODE_LIMIT_BYTES } from './budgets.js';
+import { processes, residentFacetName, } from './workerd-facet-host.js';
 import { BindingError } from './vendor/errors.js';
 /**
  * The substrate for this deployment, resolved once. The mode arrives already
@@ -105,7 +106,7 @@ class FacetProcessHost {
         this.coordDoId = ctx.id.toString();
     }
     runOnce(params, consume) {
-        return runOneShotWorker(this.ctx, this.env, { doId: this.coordDoId, pid: params.pid, writerId: params.writerId }, params, consume);
+        return processes(this.ctx, this.env).run({ doId: this.coordDoId, pid: params.pid, writerId: params.writerId }, params, consume);
     }
     async open(params) {
         const supervisor = {
@@ -113,7 +114,7 @@ class FacetProcessHost {
             pid: params.pid,
             writerId: params.writerId,
         };
-        const { slot, ...facet } = openResidentFacet(this.ctx, this.env, this.disk, supervisor, params);
+        const { slot, ...facet } = processes(this.ctx, this.env).spawn(this.disk, supervisor, params);
         return {
             ...facet,
             describe: () => `facet '${residentFacetName(slot)}' (pid ${params.pid})`
@@ -231,7 +232,7 @@ class PeerProcessHost {
      * worker of the coordinator here exactly as it does on `facet`.
      */
     runOnce(params, consume) {
-        return runOneShotWorker(this.ctx, this.env, { doId: this.coordDoId, pid: params.pid, writerId: params.writerId }, params, consume);
+        return processes(this.ctx, this.env).run({ doId: this.coordDoId, pid: params.pid, writerId: params.writerId }, params, consume);
     }
     async open(params) {
         const placement = await this._place(params.pid);
@@ -273,7 +274,7 @@ class PeerProcessHost {
         catch (error) {
             this.tokensInUse.delete(params.pid);
             // Awaited, not fired off: a spawn that rejects must mean nothing was
-            // left running, which is what a throw from `openResidentFacet` means on
+            // left running, which is what a throw from `processes().spawn` means on
             // the other substrate.
             try {
                 await this._cancel(params.workerKey, placement.peerName);

package/dist/sealed.d.ts

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

package/dist/sealed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealed.d.ts","sourceRoot":"","sources":["../src/sealed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAY1D;AAYD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,SAAS,MAAM,EACpD,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,IAAI,CAON;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,iHAQvB,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,upBAuB3B,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,0GAKxB,CAAC"}