@bandeira-tech/b3nd-save 0.8.1

package/esm/deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/rig/rig.js

@@ -0,0 +1,898 @@
+/**
+ * @module
+ * Rig — the universal harness for b3nd.
+ *
+ * Single object that wires up backends, identity, and serving.
+ * Two core actions: send (outward to the network) and receive
+ * (inward from external sources). Everything else is observation.
+ *
+ * Supports per-operation client routing, synchronous hooks
+ * (pre/post), async events, and URI-pattern reactions.
+ */
+import { resolveHooks, runAfter, runBefore, runOnError } from "./hooks.js";
+import { RigEventEmitter } from "./events.js";
+import { ReactionRegistry } from "./reactions.js";
+import { OperationHandleImpl } from "./operation-handle.js";
+/**
+ * Rig — pure orchestration for b3nd.
+ *
+ * The rig is identity-free — it routes, validates, and dispatches.
+ * For authenticated operations, use `Identity.sign()` + `message()` +
+ * `rig.send()` directly.
+ *
+ * @example Unsigned operations
+ * ```typescript
+ * const local = connection(client, ["**"]);
+ * const rig = new Rig({
+ *   routes: { receive: [local], read: [local], observe: [local] },
+ * });
+ * const results = await rig.receive([["mutable://open/app/x", data]]);
+ * ```
+ *
+ * @example Authenticated send
+ * ```typescript
+ * // With messageDataHandler registered, the rig decomposes the
+ * // envelope into outputs + null-payload deletions for inputs.
+ * const id = await Identity.fromSeed("my-secret");
+ * const auth = [await id.sign({ inputs: [], outputs })];
+ * const envelope = await message({ auth, inputs: [], outputs });
+ * await rig.send([envelope]);
+ * ```
+ *
+ * @example With programs, hooks, events, and reactions
+ * ```typescript
+ * const local = connection(client, ["**"]);
+ * const rig = new Rig({
+ *   routes: { receive: [local], read: [local], observe: [local] },
+ *   programs,
+ *   handlers,
+ *   hooks: {
+ *     beforeReceive: (ctx) => { rateLimit(ctx.uri); },
+ *     afterRead: (ctx, result) => { audit(ctx.uri, result); },
+ *   },
+ *   on: {
+ *     "send:success": [audit],
+ *   },
+ *   reactions: {
+ *     "mutable://app/users/*": async (out, _read) => {
+ *       const id = out[0].split("/").pop();
+ *       return [[`notify://email/${id}`, { kind: "user-updated" }]];
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export class Rig {
+    // ── Internal state ──
+    _receiveRoutes;
+    _readRoutes;
+    _observeRoutes;
+    _dispatch;
+    _programs;
+    _handlers;
+    _hooks;
+    _events;
+    _reactors;
+    constructor(config) {
+        const routes = config.routes;
+        const receive = routes?.receive ?? [];
+        const read = routes?.read ?? [];
+        const observe = routes?.observe ?? [];
+        if (receive.length === 0 && read.length === 0 && observe.length === 0) {
+            throw new Error("Rig: `routes` must declare at least one of `receive`, `read`, or `observe`.");
+        }
+        this._receiveRoutes = Object.freeze([...receive]);
+        this._readRoutes = Object.freeze([...read]);
+        this._observeRoutes = Object.freeze([...observe]);
+        this._dispatch = createRouteDispatch({
+            receive: this._receiveRoutes,
+            read: this._readRoutes,
+            observe: this._observeRoutes,
+        });
+        this._programs = config.programs ?? null;
+        this._handlers = config.handlers ?? null;
+        this._hooks = resolveHooks(config.hooks);
+        // Build event emitter
+        this._events = new RigEventEmitter();
+        if (config.on) {
+            for (const [name, handlers] of Object.entries(config.on)) {
+                if (handlers) {
+                    for (const handler of handlers) {
+                        this._events.on(name, handler);
+                    }
+                }
+            }
+        }
+        // Build react registry
+        this._reactors = new ReactionRegistry();
+        if (config.reactions) {
+            for (const [pattern, handler] of Object.entries(config.reactions)) {
+                this._reactors.add(pattern, handler);
+            }
+        }
+    }
+    /**
+     * Raw composite client — bypasses hooks, events, and react.
+     *
+     * Prefer passing the Rig itself (it satisfies `ProtocolInterfaceNode`).
+     * This getter exists for third-party code that requires a plain object.
+     */
+    get client() {
+        const d = this._dispatch;
+        return {
+            receive: (msgs) => d.receive(msgs),
+            read: (urls) => d.read(urls),
+            observe: (urls, signal) => d.observe(urls, signal),
+            status: () => d.status(),
+        };
+    }
+    // ── Core actions ──
+    /**
+     * Send tuples — the host application acting as the origin.
+     *
+     * Returns an `OperationHandle` that:
+     *   - Awaits to `ReceiveResult[]` once the pipeline (process →
+     *     handle) finishes. Pipeline-stage ack only — broadcast may
+     *     still be in flight.
+     *   - Fires per-stage events (`process:done`, `handle:emit`,
+     *     `route:success`/`route:error`, `settled`) scoped to this call.
+     *
+     * Dispatch to connections runs in the background; per-route outcomes
+     * arrive as events. Wait for `op.settled` for read-after-write
+     * guarantees across replicas.
+     *
+     * Use this when the host is the origin of the content (a button
+     * click, a worker emitting state, a signed envelope from
+     * `Identity.sign()` + `message()`). Use `receive()` when content arrives from
+     * elsewhere (a peer, a webhook, an upstream sync).
+     *
+     * @example
+     * ```typescript
+     * const op = rig.send([["mutable://app/state", { value: 42 }]]);
+     * op.on("route:error", (e) => retry(e.emission));
+     * const [result] = await op;             // pipeline ack
+     * await op.settled;                       // routes fully settled
+     * ```
+     */
+    send(outs) {
+        return this._pipeline(outs, "send");
+    }
+    /**
+     * Receive tuples — the host application accepting state from elsewhere.
+     *
+     * Same shape as `send()` but fires `beforeReceive`/`afterReceive`
+     * hooks and `receive:*` global events. Returns an `OperationHandle`
+     * with the same scoped per-stage events.
+     *
+     * @example
+     * ```typescript
+     * const [result] = await rig.receive([
+     *   ["mutable://open/external", { source: "webhook" }],
+     * ]);
+     * ```
+     */
+    receive(outs) {
+        return this._pipeline(outs, "receive");
+    }
+    /**
+     * Same as `receive()` but throws if any input tuple is rejected at
+     * the pipeline stage. Convenience for callers that don't want to
+     * inspect `accepted`.
+     */
+    async receiveOrThrow(outs) {
+        const results = await this.receive(outs);
+        const failed = results.find((r) => !r.accepted);
+        if (failed)
+            throw new Error(failed.error ?? "rig.receive: rejected");
+        return results;
+    }
+    /** Same as `send()` but throws on any pipeline-stage rejection. */
+    async sendOrThrow(outs) {
+        const results = await this.send(outs);
+        const failed = results.find((r) => !r.accepted);
+        if (failed)
+            throw new Error(failed.error ?? "rig.send: rejected");
+        return results;
+    }
+    /**
+     * Classify a batch of tuples — runs registered programs.
+     *
+     * For each output, finds the program with the longest matching URI
+     * prefix and invokes it. Tuples whose URI matches no registered
+     * program get a default `{ code: "ok" }` classification (so the
+     * default-dispatch path persists them as-is).
+     *
+     * Pure: returns one `ProgramResult` per input tuple. No side effects.
+     */
+    async process(outs) {
+        const readFn = this._readFn();
+        const results = [];
+        for (const out of outs) {
+            const program = this._findProgram(out[0]);
+            results.push(program ? await program(out, undefined, readFn) : { code: "ok" });
+        }
+        return results;
+    }
+    /**
+     * Run the handler for a classified tuple — returns the emissions.
+     *
+     * If no handler is registered for the result's code, the input tuple
+     * is returned as-is (default-persist). Handlers themselves return the
+     * `Output[]` they want the Rig to dispatch; this method surfaces that
+     * return for callers that want to compose the pipeline manually.
+     *
+     * Pure: no dispatch happens here. Use `send()` / `receive()` for the
+     * full pipeline including dispatch and reactions.
+     */
+    async handle(out, result) {
+        const handler = this._handlers?.[result.code];
+        if (!handler)
+            return [out];
+        return await handler(out, result, this._readFn());
+    }
+    /**
+     * The pipeline body shared by `send()` and `receive()`.
+     *
+     * Returns an `OperationHandle` synchronously. The pipeline runs
+     * asynchronously inside; awaiting the handle resolves to the
+     * pipeline-stage `ReceiveResult[]` (process + handle outcome only).
+     * Per-route dispatch runs in the background; route outcomes arrive
+     * as events on the handle. `op.settled` resolves once every route
+     * has answered.
+     *
+     * Reactions fire after each emission's routes settle — once per
+     * emission, only if at least one route accepted. Their emissions
+     * spawn a fresh `rig.send(...)` operation, independent of this one.
+     */
+    _pipeline(outs, direction) {
+        const handle = new OperationHandleImpl();
+        // Run the pipeline asynchronously. The handle is returned now;
+        // pipeline-ack and route events fire as work completes.
+        void this._runPipeline(outs, direction, handle);
+        return handle;
+    }
+    /** Internal: pipeline body driven against an OperationHandleImpl. */
+    async _runPipeline(outs, direction, handle) {
+        try {
+            // Before-hook per tuple — throw to reject.
+            const finalOuts = [];
+            for (const out of outs) {
+                const [uri, payload] = out;
+                if (direction === "receive") {
+                    const ctx = { uri, data: payload };
+                    const recvCtx = await runBefore(this._hooks.beforeReceive, ctx);
+                    finalOuts.push([recvCtx.uri, recvCtx.data]);
+                }
+                else {
+                    const ctx = { message: out };
+                    const sendCtx = await runBefore(this._hooks.beforeSend, ctx);
+                    finalOuts.push(sendCtx.message);
+                }
+            }
+            const results = [];
+            const broadcastPromises = [];
+            for (let i = 0; i < finalOuts.length; i++) {
+                const out = finalOuts[i];
+                const [uri, payload] = out;
+                // ── process — classify the tuple, isolated so a thrown
+                // program doesn't fail the whole batch. ──
+                let programResult;
+                try {
+                    programResult = await this._processOne(out);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    handle._emit("process:error", {
+                        input: out,
+                        error: message,
+                        cause: err,
+                    });
+                    await runOnError(this._hooks.onError, {
+                        phase: "process",
+                        input: out,
+                        error: message,
+                        cause: err,
+                    });
+                    const result = { accepted: false, error: message };
+                    results.push(result);
+                    this._events.emit(`${direction}:error`, {
+                        op: direction,
+                        uri,
+                        error: message,
+                        ts: Date.now(),
+                    });
+                    await this._runAfterFor(direction, out, payload, result);
+                    continue;
+                }
+                handle._emit("process:done", { input: out, result: programResult });
+                // Structural pre-check: if no connection accepts this URI for
+                // receive, the rig has no topology to dispatch through.
+                const hasRoute = this._receiveRoutes.some((c) => c.accepts(uri));
+                if (!hasRoute) {
+                    const error = `No connection accepts receive for ${uri}`;
+                    handle._emit("process:error", { input: out, error });
+                    await runOnError(this._hooks.onError, {
+                        phase: "process",
+                        input: out,
+                        error,
+                    });
+                    const result = { accepted: false, error };
+                    results.push(result);
+                    this._events.emit(`${direction}:error`, {
+                        op: direction,
+                        uri,
+                        error,
+                        ts: Date.now(),
+                    });
+                    await this._runAfterFor(direction, out, payload, result);
+                    continue;
+                }
+                if (programResult.error) {
+                    const error = programResult.error;
+                    handle._emit("process:error", { input: out, error });
+                    await runOnError(this._hooks.onError, {
+                        phase: "process",
+                        input: out,
+                        error,
+                    });
+                    const result = { accepted: false, error };
+                    results.push(result);
+                    this._events.emit(`${direction}:error`, {
+                        op: direction,
+                        uri,
+                        error,
+                        ts: Date.now(),
+                    });
+                    await this._runAfterFor(direction, out, payload, result);
+                    continue;
+                }
+                // ── handle — run the registered handler. ──
+                let emissions;
+                try {
+                    emissions = await this.handle(out, programResult);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    handle._emit("handle:error", {
+                        input: out,
+                        classification: programResult,
+                        error: message,
+                        cause: err,
+                    });
+                    await runOnError(this._hooks.onError, {
+                        phase: "handle",
+                        input: out,
+                        classification: programResult,
+                        error: message,
+                        cause: err,
+                    });
+                    const result = { accepted: false, error: message };
+                    results.push(result);
+                    this._events.emit(`${direction}:error`, {
+                        op: direction,
+                        uri,
+                        error: message,
+                        ts: Date.now(),
+                    });
+                    await this._runAfterFor(direction, out, payload, result);
+                    continue;
+                }
+                handle._emit("handle:emit", {
+                    input: out,
+                    classification: programResult,
+                    emissions,
+                });
+                // Pipeline accepted — record success now, dispatch in background.
+                const result = { accepted: true };
+                results.push(result);
+                this._events.emit(`${direction}:success`, {
+                    op: direction,
+                    uri,
+                    data: payload,
+                    result,
+                    ts: Date.now(),
+                });
+                // Schedule per-route dispatch — fire-and-forget for the pipeline.
+                broadcastPromises.push(this._dispatchRouteAware(emissions, handle, out));
+                await this._runAfterFor(direction, out, payload, result);
+            }
+            // Resolve pipeline-ack. Caller's `await op` returns now.
+            handle._pipelineDone(results);
+            // Wait for all routes to settle (and their reactions to fire),
+            // then emit the `settled` event.
+            await Promise.all(broadcastPromises);
+            handle._emit("settled", { results });
+        }
+        catch (err) {
+            handle._pipelineError(err);
+        }
+    }
+    /**
+     * Run process for a single output. Isolated so a thrown program
+     * doesn't fail the whole batch.
+     */
+    async _processOne(out) {
+        const program = this._findProgram(out[0]);
+        if (!program)
+            return { code: "ok" };
+        return await program(out, undefined, this._readFn());
+    }
+    /** Run the direction-appropriate after-hook with the standard payload. */
+    async _runAfterFor(direction, out, payload, result) {
+        if (direction === "receive") {
+            await runAfter(this._hooks.afterReceive, { uri: out[0], data: payload }, result);
+        }
+        else {
+            await runAfter(this._hooks.afterSend, { message: out }, result);
+        }
+    }
+    /**
+     * Per-emission, per-connection dispatch with route events.
+     *
+     * For each emission: find every connection in `routes.receive` that
+     * accepts the URI, dispatch the emission to each independently, emit
+     * `route:success` / `route:error` per (emission, connection). Once
+     * all routes for an emission settle, fire reactions if any route
+     * accepted. Reactions' returned tuples spawn a fresh `rig.send`
+     * operation (independent of this one).
+     *
+     * `input` is the original tuple that drove this dispatch — passed
+     * through so the `onError` hook can correlate route failures back
+     * to the input that triggered them.
+     */
+    async _dispatchRouteAware(emissions, handle, input) {
+        if (emissions.length === 0)
+            return;
+        const reactionPromises = [];
+        for (const emission of emissions) {
+            const [uri] = emission;
+            const matching = this._receiveRoutes.filter((c) => c.accepts(uri));
+            if (matching.length === 0) {
+                const error = `No connection accepts receive for ${uri}`;
+                handle._emit("route:error", { emission, connectionId: "", error });
+                await runOnError(this._hooks.onError, {
+                    phase: "route",
+                    input,
+                    emission,
+                    connectionId: "",
+                    error,
+                });
+                continue;
+            }
+            const perConnection = matching.map((conn) => conn.client.receive([emission]).then(async (results) => {
+                const r = results[0];
+                if (r.accepted) {
+                    handle._emit("route:success", {
+                        emission,
+                        connectionId: conn.id,
+                    });
+                    return true;
+                }
+                handle._emit("route:error", {
+                    emission,
+                    connectionId: conn.id,
+                    error: r.error,
+                    errorDetail: r.errorDetail,
+                });
+                await runOnError(this._hooks.onError, {
+                    phase: "route",
+                    input,
+                    emission,
+                    connectionId: conn.id,
+                    error: r.error ?? "route rejected",
+                    errorDetail: r.errorDetail,
+                });
+                return false;
+            }, async (err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                handle._emit("route:error", {
+                    emission,
+                    connectionId: conn.id,
+                    error: message,
+                });
+                await runOnError(this._hooks.onError, {
+                    phase: "route",
+                    input,
+                    emission,
+                    connectionId: conn.id,
+                    error: message,
+                    cause: err,
+                });
+                return false;
+            }));
+            // Once all routes for this emission settle, fire reactions
+            // (only if at least one route accepted).
+            reactionPromises.push(Promise.all(perConnection).then((flags) => this._fireReactionsForEmission(emission, flags.some((a) => a), handle, input)));
+        }
+        await Promise.all(reactionPromises);
+    }
+    /**
+     * Fire reactions for a successfully-dispatched emission. Reaction
+     * returns are dispatched through a fresh `rig.send(...)` — that
+     * spawned operation has its own OperationHandle and is unrelated
+     * to the one that triggered it. Loops are usage error.
+     */
+    async _fireReactionsForEmission(emission, anyAccepted, handle, input) {
+        if (!anyAccepted || this._reactors.size === 0)
+            return;
+        const readFn = this._readFn();
+        const matches = this._reactors.matches(emission[0]);
+        if (matches.length === 0)
+            return;
+        const collected = [];
+        for (const { handler, pattern } of matches) {
+            try {
+                const emitted = await handler(emission, readFn);
+                collected.push(...emitted);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                handle._emit("reaction:error", {
+                    emission,
+                    pattern,
+                    error: message,
+                    cause: err,
+                });
+                await runOnError(this._hooks.onError, {
+                    phase: "reaction",
+                    input,
+                    emission,
+                    pattern,
+                    error: message,
+                    cause: err,
+                });
+            }
+        }
+        if (collected.length > 0) {
+            // Spawn a fresh send operation — fire-and-forget at this level.
+            // The spawned op has its own handle for any caller that wants it.
+            const spawn = this.send(collected);
+            // Swallow rejections: reactions are observers, not blockers.
+            Promise.resolve(spawn).catch((err) => {
+                console.warn("[rig] reaction-emitted send error:", err);
+            });
+        }
+    }
+    /** Internal read helper bound to the dispatch read interface. */
+    _readFn() {
+        return async (u) => {
+            const results = await this._dispatch.read([u]);
+            // Read is 1:1; the slot is always present. Whatever the payload
+            // is — including a protocol-defined miss representation — is
+            // surfaced as-is.
+            return results[0];
+        };
+    }
+    /**
+     * Find the program with the longest matching URI prefix.
+     */
+    _findProgram(uri) {
+        if (!this._programs)
+            return null;
+        let bestMatch = null;
+        for (const prefix of Object.keys(this._programs)) {
+            if (uri === prefix || uri.startsWith(prefix + "/")) {
+                if (!bestMatch || prefix.length > bestMatch.length) {
+                    bestMatch = prefix;
+                }
+            }
+        }
+        return bestMatch ? this._programs[bestMatch] : null;
+    }
+    // ── Observation ──
+    /**
+     * Read a batch of locators. Each locator goes to the first connection
+     * whose route pattern accepts it. Locators are opaque strings; the
+     * executing client owns any grammar interpretation.
+     */
+    async read(urls) {
+        // Before-hook per url. The hook sees just `{ url }`; locators are
+        // opaque to the framework, so if a hook wants to inspect the
+        // grammar it brings its own parser. Returning `{ ctx: { url:
+        // newUrl } }` rewrites; otherwise the url passes through unchanged.
+        const finalUrls = [];
+        for (const url of urls) {
+            const ctx = await runBefore(this._hooks.beforeRead, { url });
+            finalUrls.push(ctx.url);
+        }
+        // Execute
+        let outputs;
+        try {
+            outputs = await this._dispatch.read(finalUrls);
+        }
+        catch (err) {
+            for (const url of finalUrls) {
+                this._events.emit("read:error", {
+                    op: "read",
+                    uri: url,
+                    error: err instanceof Error ? err.message : String(err),
+                    ts: Date.now(),
+                });
+            }
+            throw err;
+        }
+        // After-hook + event per Output. Option-A doesn't have per-result
+        // failures (those throw); every Output is a success.
+        for (const output of outputs) {
+            const [uri] = output;
+            await runAfter(this._hooks.afterRead, { url: uri }, output);
+            this._events.emit("read:success", {
+                op: "read",
+                uri,
+                result: output,
+                ts: Date.now(),
+            });
+        }
+        return outputs;
+    }
+    // ── Observe (client-backed streaming) ──
+    /**
+     * Observe changes matching a URI pattern.
+     *
+     * Routes to the first connection that accepts `observe` for the pattern,
+     * then delegates to the client's native transport (SSE, internal events, etc).
+     *
+     * @example
+     * ```typescript
+     * const abort = new AbortController();
+     * for await (const uris of rig.observe(["mutable://data/market/**"], abort.signal)) {
+     *   for (const uri of uris) console.log(uri);
+     * }
+     * ```
+     */
+    async *observe(urls, signal) {
+        yield* this._dispatch.observe(urls, signal);
+    }
+    // ── Inspection ──
+    /**
+     * Get a snapshot of this rig's current state.
+     *
+     * Pure local inspection, no network calls.
+     *
+     * @example
+     * ```typescript
+     * const info = rig.info();
+     * console.log(info.behavior.hooks);
+     * console.log(info.behavior.reactors);
+     * ```
+     */
+    info() {
+        const hooks = [];
+        const h = this._hooks;
+        if (h.beforeSend)
+            hooks.push("beforeSend");
+        if (h.afterSend)
+            hooks.push("afterSend");
+        if (h.beforeReceive)
+            hooks.push("beforeReceive");
+        if (h.afterReceive)
+            hooks.push("afterReceive");
+        if (h.beforeRead)
+            hooks.push("beforeRead");
+        if (h.afterRead)
+            hooks.push("afterRead");
+        return {
+            behavior: {
+                hooks,
+                events: this._events.counts(),
+                reactors: this._reactors.size,
+            },
+        };
+    }
+    // ── Infrastructure ──
+    /**
+     * Status — health + schema.
+     * Aggregates client status across all connections.
+     */
+    async status() {
+        return await this._dispatch.status();
+    }
+    /**
+     * Return any in-flight event handler promises and clear the queue.
+     */
+    drain() {
+        return this._events.pending();
+    }
+    // ── Runtime API: events, react ──
+    // Hooks are immutable after init — see createHookChains().
+    /**
+     * Register an event handler at runtime. Returns an unsubscribe function.
+     *
+     * @example
+     * ```typescript
+     * const unsub = rig.on("send:success", (event) => {
+     *   console.log(`Sent to ${event.uri}`);
+     * });
+     *
+     * // Later:
+     * unsub();
+     * ```
+     */
+    on(event, handler) {
+        return this._events.on(event, handler);
+    }
+    /** Remove a specific event handler. */
+    off(event, handler) {
+        this._events.off(event, handler);
+    }
+    /**
+     * Register a react pattern at runtime. Returns an unsubscribe function.
+     *
+     * Fires on successful `send()` or `receive()` when the written URI
+     * matches the pattern. Fire-and-forget — errors are caught and logged.
+     *
+     * Reactions return `Output[]` — those tuples flow back through
+     * `rig.send` (full pipeline). See chapter 7 of RFC 001 for the
+     * productive-observation model.
+     *
+     * @example
+     * ```typescript
+     * const unsub = rig.reaction(
+     *   "mutable://app/users/*",
+     *   async (out, _read) => {
+     *     const id = out[0].split("/").pop();
+     *     return [[`notify://email/${id}`, { kind: "user-updated" }]];
+     *   },
+     * );
+     *
+     * // Later:
+     * unsub();
+     * ```
+     */
+    reaction(pattern, handler) {
+        return this._reactors.add(pattern, handler);
+    }
+}
+// ── Init helpers ──
+/**
+ * Merge a set of `AsyncIterable`s into one stream. Aborts when `signal`
+ * fires; per-stream errors are swallowed (one broken peer should not
+ * tear down the merged stream).
+ */
+async function* mergeStreams(streams, signal) {
+    if (streams.length === 0)
+        return;
+    const queue = [];
+    let wake = null;
+    const forwarders = streams.map(async (s) => {
+        try {
+            for await (const r of s) {
+                queue.push(r);
+                const w = wake;
+                if (w) {
+                    wake = null;
+                    w();
+                }
+            }
+        }
+        catch {
+            // intentional
+        }
+    });
+    const onAbort = () => {
+        const w = wake;
+        if (w) {
+            wake = null;
+            w();
+        }
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    try {
+        while (true) {
+            while (queue.length > 0)
+                yield queue.shift();
+            if (signal.aborted)
+                return;
+            await new Promise((resolve) => {
+                wake = resolve;
+            });
+        }
+    }
+    finally {
+        signal.removeEventListener("abort", onAbort);
+        await Promise.allSettled(forwarders);
+    }
+}
+/**
+ * Build dispatch from per-op route arrays.
+ *
+ * Each operation flows through its dedicated route list:
+ * - `receive`: broadcast to ALL matching connections in the receive route.
+ * - `read`: per url, first connection that accepts the routing key gets
+ *   the request — sequential, no aggregation. Aggregation across
+ *   sources is the job of an aggregating client (e.g. memcache+shards),
+ *   not the rig.
+ * - `observe`: per url, first connection that accepts wins.
+ * - `status`: aggregate across unique clients seen on any route.
+ */
+function createRouteDispatch(routes) {
+    const { receive, read, observe } = routes;
+    return {
+        async receive(msgs) {
+            const results = [];
+            for (const msg of msgs) {
+                const [uri] = msg;
+                const matching = receive.filter((s) => s.accepts(uri));
+                if (matching.length === 0) {
+                    results.push({
+                        accepted: false,
+                        error: `No receive route accepts ${uri}`,
+                    });
+                    continue;
+                }
+                // Broadcast to every matching receive-route connection
+                const writeResults = await Promise.all(matching.map((s) => s.client.receive([msg]).then((r) => r[0])));
+                const failed = writeResults.find((r) => !r.accepted);
+                results.push(failed ?? writeResults[0]);
+            }
+            return results;
+        },
+        async read(urls) {
+            // 1:1 with input. Each url is routed to its accepting connection;
+            // we ask that connection for that single url and place the
+            // resulting Output<T> in the matching slot.
+            const out = new Array(urls.length);
+            await Promise.all(urls.map(async (url, i) => {
+                const conn = read.find((s) => s.accepts(url));
+                if (!conn) {
+                    // Programmer error — this rig isn't configured for this url.
+                    throw new Error(`No read route accepts ${url}`);
+                }
+                const [r] = await conn.client.read([url]);
+                out[i] = r;
+            }));
+            return out;
+        },
+        async *observe(urls, signal) {
+            // Group urls by the first connection that accepts them so each
+            // connection sees the subset it owns. No aggregation across
+            // connections — that is the aggregating client's job.
+            const groups = new Map();
+            for (const url of urls) {
+                const conn = observe.find((c) => c.accepts(url));
+                if (!conn)
+                    continue;
+                const arr = groups.get(conn) ?? [];
+                arr.push(url);
+                groups.set(conn, arr);
+            }
+            const streams = [...groups.entries()].map(([c, us]) => c.client.observe(us, signal));
+            yield* mergeStreams(streams, signal);
+        },
+        async status() {
+            const seen = new Set();
+            const unique = [];
+            for (const list of [receive, read, observe]) {
+                for (const s of list) {
+                    if (!seen.has(s.client)) {
+                        seen.add(s.client);
+                        unique.push(s.client);
+                    }
+                }
+            }
+            const results = await Promise.all(unique.map((c) => c.status()));
+            const allSchema = new Set();
+            const allFns = new Set();
+            for (const r of results) {
+                if (r.schema) {
+                    for (const k of r.schema)
+                        allSchema.add(k);
+                }
+                if (r.fns) {
+                    for (const f of r.fns)
+                        allFns.add(f);
+                }
+            }
+            const fns = allFns.size > 0 ? [...allFns] : undefined;
+            const unhealthy = results.find((r) => r.status === "unhealthy");
+            if (unhealthy)
+                return { ...unhealthy, schema: [...allSchema], fns };
+            const degraded = results.find((r) => r.status === "degraded");
+            if (degraded)
+                return { ...degraded, schema: [...allSchema], fns };
+            return { status: "healthy", schema: [...allSchema], fns };
+        },
+    };
+}
+// Compile-time: Rig structurally satisfies ProtocolInterfaceNode.
+null;