@agentorg/cli 0.0.2 → 0.0.3

package/node_modules/@agentorg/hub/dist/src/router.js

@@ -0,0 +1,1022 @@
+import { hashInterface, NotConnected, OutcomeUnknown, Refused, } from "@agentorg/sdk";
+import { errorOf } from "@agentorg/sdk/client";
+import { serveOver } from "@agentorg/sdk/http";
+import { encodeFrame, eventBody, FrameError, FrameReader, GO_AWAY, HeaderError, input, parseBody, parseHeader, result, Session, wireError, YamuxError, } from "@agentorg/wire";
+import { sweepBuilds } from "./build.js";
+import { HubActor } from "./hub-actor.js";
+import { appendLog, boundedEntry } from "./logs.js";
+import { Net } from "./net.js";
+import { Processes } from "./processes.js";
+import { HUB, HubState, NET, STORAGE, } from "./state.js";
+import { Storage } from "./storage.js";
+import { Validators } from "./validate.js";
+/** Streams an admitted channel may have open at once. Before admission it may have one: hello. */
+const MAX_STREAMS = 256;
+/** Interfaces one hello may declare. */
+const MAX_DECLARED = 256;
+/**
+ * Slot notices an Actor may leave unclosed beyond one per slot it declares (one change, such as its
+ * provider closing, can unbind every slot at once). Past that its channel is closed with a
+ * protocol error: the Hub holds each until the Actor closes it, and its next hello carries the state.
+ */
+const MAX_OPEN_NOTICES = 64;
+/**
+ * Event bytes queued for a subscriber that has stopped reading, before it is cut off. Events from
+ * a provider wait for each delivery, so this bounds the hub Actor's own events.
+ */
+const MAX_QUEUED_BYTES = 4 * 1024 * 1024;
+/** Where the Hub's in-process http serving reports a handler's own failure: nowhere. */
+const QUIET = { info() { }, warn() { }, error() { } };
+const bindingKey = (b) => `${b.consumer}\0${b.slot}`;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function errorBody(error) {
+    if (error instanceof Refused)
+        return wireError("Refused", error.message, error.code);
+    if (error instanceof NotConnected)
+        return wireError("NotConnected", error.message);
+    if (error instanceof OutcomeUnknown)
+        return wireError("OutcomeUnknown", error.message);
+    if (error instanceof HeaderError || error instanceof FrameError)
+        return wireError("Refused", error.message, "invalid");
+    return wireError("Refused", "The Hub couldn't handle this stream.", "internal");
+}
+/** The outcome of a call the Hub ended itself; a provider's own error is always `refused`. */
+function outcomeOf(error) {
+    if (error.name === "NotConnected")
+        return "not_connected";
+    if (error.name === "OutcomeUnknown")
+        return "outcome_unknown";
+    return error.code === "invalid" || error.code === "bad_output" || error.code === "cancelled"
+        ? error.code
+        : "refused";
+}
+/**
+ * Read and drop whatever the opener still sends. A stream is forgotten only once both sides end
+ * and nothing is left unread, so a refused stream's leftover bytes would otherwise hold it open.
+ */
+const drain = (reader) => void reader
+    .rest()
+    .pipeTo(new WritableStream())
+    .catch(() => { });
+/** Settles when the opener resets its stream; a clean end of its side is not a reset. */
+const whenReset = (reader) => reader.next().then(() => new Promise(() => { }), () => undefined);
+/**
+ * One direction of a splice. A source that fails resets the destination, and a destination its
+ * side reset resets the source. A destination that can't take more because its channel went ends
+ * this direction only: cancelling the source would reset its whole stream, and with it the other
+ * direction, which may still carry an answer. What the source still sends is read and dropped
+ * until it ends.
+ */
+const pass = (from, to) => from.pipeTo(to.writable, { preventCancel: true }).catch((error) => {
+    to.reset();
+    if (error instanceof YamuxError && error.code === "reset")
+        return from.cancel(error).catch(() => { });
+    return from.pipeTo(new WritableStream()).catch(() => { });
+});
+/**
+ * A value as it would cross the wire: what a built-in Actor (the hub, storage) gives in-process is
+ * checked and sent as a channel provider's would be, so a property left undefined is left out,
+ * never a value that fails its schema.
+ */
+const asJson = (value) => JSON.parse(JSON.stringify(value ?? null));
+/** A body encoded for the wire; one over the frame limit becomes a refusal saying so. */
+function frameOf(body) {
+    try {
+        return { body, frame: encodeFrame(body) };
+    }
+    catch (error) {
+        const refusal = wireError("Refused", error instanceof Error ? error.message : String(error), "too_large");
+        return { body: refusal, frame: encodeFrame(refusal) };
+    }
+}
+async function answer(writer, frame) {
+    try {
+        await writer.write(frame instanceof Uint8Array ? frame : frameOf(frame).frame);
+        await writer.close();
+    }
+    catch {
+        // The other side is gone; make sure the stream is too.
+        await writer.abort().catch(() => { });
+    }
+}
+/**
+ * The core as a router. Each connected Actor has one channel, a yamux session; every stream on it
+ * starts with a header. The Hub resolves a consumer's slot through its binding, validates what
+ * crosses in both directions against the interface's JSON Schemas, opens a stream toward the
+ * provider naming its export and the caller, and audits the call. The `hub` Actor's exports are
+ * served in-process, through the same path.
+ */
+export class Hub {
+    state;
+    #actor;
+    #validators;
+    #storage;
+    #processes;
+    #net;
+    #connections = new Map();
+    /** Open subscriptions and splices by the binding they run through, ended when it goes. */
+    #live = new Map();
+    #helloTimeoutMs;
+    #answerTimeoutMs;
+    /** Every channel's session, admitted or still in hello. */
+    #sessions = new Set();
+    /** `viewSlots` listeners by Actor: each hears its view module's slot changes. */
+    #viewListeners = new Map();
+    constructor(home, options) {
+        this.#helloTimeoutMs = options.helloTimeoutMs ?? 10_000;
+        this.#answerTimeoutMs = options.answerTimeoutMs ?? 60_000;
+        this.#validators = new Validators(options.checks);
+        let actor;
+        this.state = HubState.open(home, {
+            bound: (binding) => this.#notify(binding.consumer, binding.slot, true),
+            unbound: (bindings) => {
+                for (const binding of bindings) {
+                    for (const end of [...(this.#live.get(bindingKey(binding)) ?? [])])
+                        end(errorBody(new NotConnected(binding.slot)));
+                    this.#notify(binding.consumer, binding.slot, false);
+                }
+            },
+            closed: (actorId) => {
+                this.#connections.get(actorId)?.session.close();
+                // Closing is for good: its stores go too. Unbinding keeps them.
+                this.#storage.deleteConsumer(actorId);
+            },
+            requested: (request, approvers) => actor?.requested(request, approvers),
+            decided: (request, status, approvers) => actor?.decided(request, status, approvers),
+            exportsChanged: (changed) => actor?.exportsChanged(changed),
+            actorChanged: (changed) => actor?.actorChanged(changed),
+            audited: (entry) => actor?.audited(entry),
+        });
+        this.#net = new Net(this.state, options.net);
+        // Builds a crash interrupted leave their folders; they go now.
+        sweepBuilds(home);
+        this.#processes = new Processes(this.state, (channel, admitted) => this.accept(channel, admitted), options.processes);
+        actor = this.#actor = new HubActor(this.state, this.#processes, (id) => this.connected(id));
+        try {
+            this.#storage = new Storage(home, options.storage);
+            // Stores of Actors closed while a delete couldn't run (a crash, a lock) go now.
+            this.#storage.keepOnly(new Set(this.state
+                .actors()
+                .filter((a) => a.state !== "closed")
+                .map((a) => a.actorId)));
+        }
+        catch (error) {
+            // Nothing half-open is left: the home's lock and the check workers go with it.
+            this.#validators.close();
+            this.state.close();
+            throw error;
+        }
+    }
+    /**
+     * Open the Hub in its home. The host sandbox is probed at once; when it is available, package
+     * Actors recorded as `running` get their processes back.
+     */
+    static open(home, options = {}) {
+        const hub = new Hub(home, options);
+        hub.#processes.probe().catch(() => { });
+        return hub;
+    }
+    /** Whether an Actor has a channel now. */
+    connected(actorId) {
+        return this.#connections.has(actorId);
+    }
+    /**
+     * Take a channel. Its first stream must be `hello`, and nothing else may open before it is
+     * admitted. An external client's hello carries its credential, within the hello deadline. A
+     * channel the Hub made itself, a pipe to a package Actor's process it spawned, is given with
+     * that Actor's id: its hello names that Actor and needs no credential, and its spawner keeps
+     * the deadline. The handle settles when the channel ends, and closes it.
+     */
+    accept(channel, admitted) {
+        if (admitted) {
+            const actor = this.state.actor(admitted.actorId);
+            if (actor.package === "external" || actor.package === "builtin" || actor.state === "closed")
+                throw new Refused("state", `${actor.actorId} isn't a live package Actor.`);
+        }
+        let conn;
+        let admit;
+        const admittedNow = new Promise((resolve) => {
+            admit = resolve;
+        });
+        let helloSeen = false;
+        let ended = false;
+        const options = {
+            client: false,
+            maxStreams: 1,
+            onStream: (stream) => {
+                if (conn)
+                    void this.#serve(conn, stream);
+                else if (helloSeen)
+                    stream.reset();
+                else {
+                    helloSeen = true;
+                    void this.#hello(stream, session, admitted, (actorId, replace) => {
+                        if (ended)
+                            throw new NotConnected("The channel");
+                        // Closed while its hello was on the way (a pipe made before a close, or declares
+                        // being checked): a closed Actor is never admitted.
+                        if (this.state.actor(actorId).state === "closed")
+                            throw new Refused("state", `${actorId} is closed.`);
+                        // Checked again as the channel is admitted: one may have connected while declares
+                        // were checked.
+                        if (replace === false && this.#connections.has(actorId))
+                            throw new Refused("connected", `${actorId} already has a channel to this Hub.`);
+                        conn = this.#admit(actorId, session);
+                        admit();
+                        options.maxStreams = MAX_STREAMS;
+                    });
+                }
+            },
+        };
+        const session = new Session(channel, options);
+        this.#sessions.add(session);
+        // A pipe's hello is waited for by whoever spawned its process, under its own deadline.
+        const timer = admitted
+            ? undefined
+            : setTimeout(() => {
+                if (!conn)
+                    session.close(GO_AWAY.protocolError);
+            }, this.#helloTimeoutMs);
+        const closed = session.closed.then(() => {
+            ended = true;
+            clearTimeout(timer);
+            this.#sessions.delete(session);
+            if (conn)
+                this.#dropped(conn);
+        });
+        return { admitted: admittedNow, closed, close: () => session.close() };
+    }
+    /**
+     * A call from one of a package Actor's view modules, run in this process for the gateway that
+     * shows it (step 4): through `<module>.<slot>` of the Actor, as the Actor, checked and audited
+     * like any call. A module that isn't a view of the Actor's package is refused.
+     */
+    async viewCall(actorId, module, slot, method, input) {
+        const name = this.#viewSlot(actorId, module, slot, { op: "call", method });
+        const { body } = await this.#invoke(actorId, name, method, async () => ({
+            value: input,
+            cancelled: new Promise(() => { }),
+        }));
+        if ("error" in body)
+            throw errorOf(body.error, name);
+        return body.result;
+    }
+    /**
+     * Events of a view module's slot, as `viewCall` reaches its methods. `onEvent` may return a
+     * promise: the next event waits for it. Returns how to stop; `onEnd` hears when it ended
+     * otherwise, with the reason if it wasn't a clean end.
+     */
+    viewSubscribe(actorId, module, slot, event, onEvent, onEnd) {
+        const name = this.#viewSlot(actorId, module, slot, { op: "subscribe", method: event });
+        let stopped = false;
+        let starting = true;
+        let refused;
+        const stop = this.#subscribeCore(actorId, name, event, {
+            send: async (payload) => {
+                await onEvent(payload);
+            },
+            end: (error) => {
+                if (starting)
+                    refused = error;
+                else if (!stopped)
+                    try {
+                        onEnd?.(error ? errorOf(error.error, name) : undefined);
+                    }
+                    catch {
+                        // The gateway's own trouble; other subscriptions and the unbind go on.
+                    }
+            },
+        });
+        starting = false;
+        // Refused at the start: thrown, as a module that isn't a view is.
+        if (!stop)
+            throw errorOf(refused?.error ?? { name: "NotConnected", message: name }, name);
+        return () => {
+            stopped = true;
+            stop();
+        };
+    }
+    /**
+     * A view module's slots, for the gateway's frame that shows it: `onSlot` hears each slot (named
+     * within the module, as `viewCall` takes it) that is bound now, at once, then every change:
+     * bound, unbound, and bound again when it is usable again: its provider's channel or the
+     * Actor's own comes back. Refused unless `module` is one of the view modules of the Actor's
+     * package; the Actor needn't be running. Returns how to stop, the only way a listener goes
+     * (closing the Actor unbinds each slot, which it hears, but doesn't stop it).
+     */
+    viewSlots(actorId, module, onSlot) {
+        this.#viewModule(actorId, module, { running: false });
+        const listener = { module, onSlot };
+        const listeners = this.#viewListeners.get(actorId) ?? new Set();
+        this.#viewListeners.set(actorId, listeners);
+        listeners.add(listener);
+        const prefix = `${module}.`;
+        for (const binding of this.state.bindings(actorId))
+            if (binding.consumer === actorId &&
+                binding.slot.startsWith(prefix) &&
+                listeners.has(listener))
+                this.#tellView(listener, binding.slot.slice(prefix.length), true);
+        return () => {
+            listeners.delete(listener);
+            if (!listeners.size && this.#viewListeners.get(actorId) === listeners)
+                this.#viewListeners.delete(actorId);
+        };
+    }
+    /** A slot change to an Actor's view listeners whose module holds that slot. */
+    #notifyViews(actorId, slot, bound) {
+        const listeners = this.#viewListeners.get(actorId);
+        // A copy, so a listener may stop itself or another; one stopped meanwhile hears no more.
+        for (const listener of [...(listeners ?? [])])
+            if (listeners?.has(listener) && slot.startsWith(`${listener.module}.`))
+                this.#tellView(listener, slot.slice(listener.module.length + 1), bound);
+    }
+    #tellView(listener, slot, bound) {
+        try {
+            listener.onSlot(slot, bound);
+        }
+        catch {
+            // The gateway's own trouble; other listeners and the change go on.
+        }
+    }
+    /**
+     * `<module>.<slot>` of a running package Actor, when `module` is one of its view modules. A
+     * refusal here is audited as the Actor's, as a refusal while resolving a channel's call is.
+     */
+    #viewSlot(actorId, module, slot, call) {
+        const name = `${module}.${slot}`;
+        try {
+            this.#viewModule(actorId, module, { running: true });
+            return name;
+        }
+        catch (error) {
+            if (error instanceof Refused && error.code !== "unknown")
+                this.#audit(actorId, name, undefined, {
+                    ...call,
+                    outcome: outcomeOf(errorBody(error).error),
+                });
+            throw error;
+        }
+    }
+    /** Refused unless `module` is one of the view modules of the Actor's package (and it runs). */
+    #viewModule(actorId, module, options) {
+        const actor = this.state.actor(actorId);
+        if (actor.package === "external" || actor.package === "builtin")
+            throw new Refused("forbidden", `${actorId} has no package, so no views.`);
+        if (options.running && actor.state !== "running")
+            throw new Refused("state", `${actorId} isn't running.`);
+        const { manifest } = this.state.package(actor.package);
+        if (!Object.hasOwn(manifest.modules, module) || manifest.modules[module]?.placement !== "view")
+            throw new Refused("forbidden", `${module} isn't a view module of ${actorId}'s package.`);
+    }
+    /**
+     * A line a view module logged, into its Actor's log, marked with the module. The Hub bounds it
+     * itself: a known level, the text cut to 4 KiB, at most 16 fields of 1 KiB each, and its own time.
+     * Refused `forbidden` for a module that isn't a view, `unknown` for no such Actor (or a closed
+     * one whose package is gone); the Actor may be stopped or closed. Not audited: it isn't a call.
+     * A line the disk won't take is dropped.
+     */
+    viewLog(actorId, module, line) {
+        this.#viewModule(actorId, module, { running: false });
+        try {
+            appendLog(this.state.home, actorId, boundedEntry(line.level, line.message, line.data, module));
+        }
+        catch {
+            // The disk's trouble (full, unwritable) isn't the view's: its line is lost, nothing else.
+        }
+    }
+    /** Kill every host process, close every channel, admitted or not, then the state. */
+    close() {
+        this.#processes.close();
+        for (const session of [...this.#sessions])
+            session.close();
+        this.#connections.clear();
+        this.#viewListeners.clear();
+        this.#validators.close();
+        this.#storage.close();
+        this.state.close();
+    }
+    #admit(actorId, session) {
+        const old = this.#connections.get(actorId);
+        if (old) {
+            // A newer channel for the same Actor wins; the old one is closed.
+            this.#dropped(old);
+            old.session.close();
+        }
+        const conn = { actorId, session, notices: 0 };
+        this.#connections.set(actorId, conn);
+        this.#actor.actorChanged(actorId);
+        // Its consumers' subscriptions ended when it went; a notice tells each slot it is usable again.
+        // Exports offered at run time went with the old channel, and their bindings with them. Its own
+        // channel is new and learns its slots from hello; its views, served apart and callable only
+        // while it runs, hear that each of their slots is usable again, whoever provides it.
+        for (const binding of this.state.bindings(actorId))
+            if (binding.consumer === actorId)
+                this.#notifyViews(actorId, binding.slot, true);
+            else if (this.state.declaration(actorId, "export", binding.export)?.dynamic === false)
+                this.#notify(binding.consumer, binding.slot, true);
+        return conn;
+    }
+    #dropped(conn) {
+        if (this.#connections.get(conn.actorId) !== conn)
+            return;
+        this.#connections.delete(conn.actorId);
+        this.#actor.actorChanged(conn.actorId);
+        try {
+            this.state.disconnected(conn.actorId);
+        }
+        catch {
+            // The state is closed: the Hub is shutting down.
+        }
+    }
+    async #hello(stream, session, pipe, admit) {
+        const reader = new FrameReader(stream.readable);
+        const writer = stream.writable.getWriter();
+        try {
+            const header = parseHeader(await reader.next());
+            if (header.op !== "hello")
+                throw new Refused("invalid", "A channel's first stream must be hello.");
+            if (pipe) {
+                // The pipe is the proof: it was made for this one Actor's process.
+                if (header.actorId !== pipe.actorId)
+                    throw new Refused("forbidden", `This channel is ${pipe.actorId}'s.`);
+                if (header.declares !== undefined)
+                    throw new Refused("invalid", "A package Actor declares through its manifest.");
+            }
+            else if (header.credential === undefined ||
+                !this.state.authenticate(header.actorId, header.credential))
+                throw new Refused("forbidden", "No such Actor, or the credential is wrong.");
+            if (header.replace === false && this.#connections.has(header.actorId))
+                throw new Refused("connected", `${header.actorId} already has a channel to this Hub.`);
+            if (header.declares !== undefined)
+                this.state.declareExternal(header.actorId, await this.#declares(header.actorId, header.declares));
+            admit(header.actorId, header.replace);
+            // Taken as the channel is admitted: every change after it reaches the channel as a notice.
+            const bound = this.state
+                .bindings(header.actorId)
+                .filter((b) => b.consumer === header.actorId)
+                .map((b) => b.slot);
+            await answer(writer, result({ actorId: header.actorId, bound }));
+        }
+        catch (error) {
+            await answer(writer, errorBody(error));
+            session.close(GO_AWAY.protocolError);
+        }
+    }
+    /** Tell an Actor's channel and its views' listeners that one of its slots was bound or unbound. */
+    #notify(actorId, slot, bound) {
+        this.#notifyViews(actorId, slot, bound);
+        const conn = this.#connections.get(actorId);
+        if (!conn)
+            return;
+        if (conn.notices >= this.state.slotCount(actorId) + MAX_OPEN_NOTICES)
+            return conn.session.close(GO_AWAY.protocolError);
+        try {
+            const stream = conn.session.open();
+            conn.notices++;
+            const writer = stream.writable.getWriter();
+            void writer
+                .write(encodeFrame({ op: "slot", name: slot, bound }))
+                .then(() => writer.close())
+                .catch(() => { });
+            // Nothing comes back; the Actor closing its side ends the read and frees the notice.
+            void stream.readable
+                .pipeTo(new WritableStream())
+                .catch(() => { })
+                .finally(() => {
+                conn.notices--;
+            });
+        }
+        catch {
+            // The channel is going; its next hello carries the state.
+        }
+    }
+    /** What a hello declares, checked: shapes, hashes, and schemas that compile. */
+    async #declares(actor, value) {
+        if (!isRecord(value))
+            throw new Refused("invalid", "declares must be {slots, exports}.");
+        const out = { slots: {}, exports: {} };
+        const sides = ["slots", "exports"].map((side) => {
+            const members = value[side] ?? {};
+            if (!isRecord(members))
+                throw new Refused("invalid", `declares.${side} must be an object.`);
+            return [side, Object.entries(members)];
+        });
+        // Counted before anything is compiled: an over-long hello costs the Hub no work.
+        if (sides.reduce((n, [, members]) => n + members.length, 0) > MAX_DECLARED)
+            throw new Refused("invalid", `A hello declares at most ${MAX_DECLARED} interfaces.`);
+        for (const [side, members] of sides)
+            for (const [name, iface] of members)
+                out[side][name] = await this.#described(actor, iface, `declares.${side}.${name}`);
+        return out;
+    }
+    /** A described interface from the wire: its shape, then its hash, then schemas that compile. */
+    async #described(actor, iface, where) {
+        if (!isRecord(iface) || typeof iface.id !== "string" || typeof iface.hash !== "string")
+            throw new Refused("invalid", `${where} isn't a described interface.`);
+        const { hash, ...schemas } = iface;
+        let recomputed;
+        try {
+            recomputed = hashInterface(schemas);
+        }
+        catch {
+            recomputed = undefined;
+        }
+        // The hash keys the compiled schemas, so it is checked before anything is compiled.
+        if (recomputed !== hash)
+            throw new Refused("invalid", `${iface.id}'s hash doesn't match its schemas.`);
+        await this.#validators.prepare(actor, iface);
+        return iface;
+    }
+    // ── Streams from an admitted Actor ─────────────────────────────────────────
+    async #serve(conn, stream) {
+        const reader = new FrameReader(stream.readable);
+        const writer = stream.writable.getWriter();
+        try {
+            const header = parseHeader(await reader.next());
+            switch (header.op) {
+                case "call":
+                    return await this.#call(conn, header, reader, writer);
+                case "subscribe":
+                    return await this.#subscribe(conn, header, stream, reader, writer);
+                case "open":
+                case "http":
+                    return await this.#splice(conn, header, stream, reader, writer);
+                case "offer":
+                    this.state.offer(conn.actorId, header.name, await this.#described(conn.actorId, header.interface, "interface"));
+                    await answer(writer, result({}));
+                    return drain(reader);
+                case "withdraw":
+                    this.state.withdraw(conn.actorId, header.name);
+                    await answer(writer, result({}));
+                    return drain(reader);
+                default:
+                    throw new Refused("invalid", `A ${header.op} stream can't be opened here.`);
+            }
+        }
+        catch (error) {
+            await answer(writer, errorBody(error));
+            drain(reader);
+        }
+    }
+    /** Keep an open subscription or splice under its binding, so the binding's end ends it. */
+    #track(binding, end) {
+        const key = bindingKey(binding);
+        const ends = this.#live.get(key) ?? new Set();
+        this.#live.set(key, ends);
+        ends.add(end);
+        return () => {
+            ends.delete(end);
+            if (!ends.size)
+                this.#live.delete(key);
+        };
+    }
+    // Every schema check runs in the turn of the Actor the work is for: a call's input and output in
+    // the caller's, a subscription's events in the subscriber's, a hello's or offer's compile in the
+    // declaring Actor's. A slow provider so delays only the callers using it, each in its own turn.
+    /** A consumer's slot, resolved through its binding to a live provider of the right kind. */
+    #resolve(caller, slot, kind) {
+        const resolved = this.state.resolveCall(caller, slot);
+        if (!resolved)
+            throw new NotConnected(slot);
+        const { binding, target } = resolved;
+        if (target.iface.kind !== kind)
+            throw new Refused("invalid", `${slot} is an ${target.iface.kind} slot, not ${kind}.`);
+        // The built-in Actors are served in this process; any other provider needs its channel.
+        const builtin = binding.provider === HUB || binding.provider === STORAGE || binding.provider === NET;
+        const provider = builtin ? undefined : this.#connections.get(binding.provider);
+        if (!builtin && !provider)
+            throw new NotConnected(slot);
+        return { binding, iface: target.iface, provider };
+    }
+    #audit(caller, slot, binding, call) {
+        const { consumer, provider, export: exported } = binding ?? { consumer: caller };
+        try {
+            this.state.auditCall(caller, { consumer, slot, provider, export: exported }, call);
+        }
+        catch {
+            // The state is closed: the Hub is shutting down.
+        }
+    }
+    async #call(conn, header, reader, writer) {
+        // Once the input is read, this watches the rest of the caller's stream (and so drains it).
+        let cancelled;
+        const { frame } = await this.#invoke(conn.actorId, header.slot, header.method, async () => {
+            const body = parseBody(await reader.next());
+            cancelled = whenReset(reader);
+            if (!("input" in body))
+                throw new Refused("invalid", "A call's body is {input}.");
+            return { value: body.input, cancelled };
+        });
+        await answer(writer, frame);
+        if (!cancelled)
+            drain(reader);
+    }
+    /**
+     * A call through a caller's slot, without a channel: resolve it, check the input, reach the
+     * provider, check the output, audit. `input` gives the value (and how the caller cancels) once
+     * the slot is known to have the method.
+     */
+    async #invoke(caller, slot, method, input) {
+        let binding;
+        let reply;
+        let outcome = "ok";
+        try {
+            const resolved = this.#resolve(caller, slot, "rpc");
+            binding = resolved.binding;
+            const { iface, provider } = resolved;
+            const part = { method, side: "input" };
+            if (!this.#validators.has(iface, part))
+                throw new Refused("invalid", `${iface.id} has no method ${method}.`);
+            const { value, cancelled } = await input();
+            await this.#validators.check(caller, iface, part, value, "invalid");
+            reply = provider
+                ? await this.#forward(provider, binding, caller, method, value, cancelled)
+                : await this.#builtinCall(binding, method, caller, value);
+            if ("error" in reply)
+                outcome = "refused";
+            else if ("result" in reply)
+                await this.#validators.check(caller, iface, { method, side: "output" }, reply.result, "bad_output");
+            else if (!("error" in reply))
+                throw new Refused("bad_output", "The provider's reply is neither a result nor an error.");
+        }
+        catch (error) {
+            reply = errorBody(error);
+            outcome = outcomeOf(reply.error);
+        }
+        const encoded = frameOf(reply);
+        if (encoded.body !== reply)
+            outcome = "refused";
+        this.#audit(caller, slot, binding, { op: "call", method, outcome });
+        return encoded;
+    }
+    /**
+     * `storage.admin@1`'s seed, for its caller (the installer): into a live Actor's empty store,
+     * audited with the consumer, the slot and how many entries.
+     */
+    #seed(caller, method, input) {
+        if (method !== "seed")
+            throw new Refused("unimplemented", `storage.admin@1 has no method ${method}.`);
+        if (this.state.actor(input.consumer).state === "closed")
+            throw new Refused("state", `${input.consumer} is closed.`);
+        // Only a store the consumer can reach: its slot, bound to storage's kv.
+        const bound = this.state.binding(input.consumer, input.slot);
+        if (bound?.provider !== STORAGE || bound.export !== "kv")
+            throw new Refused("invalid", `${input.consumer}.${input.slot} isn't a slot bound to storage.kv.`);
+        this.#storage.seed(input.consumer, input.slot, input.entries);
+        // The seed is done; an audit that fails now (the Hub closing) doesn't undo or hide it.
+        try {
+            this.state.auditHub("storage.seed", { consumer: input.consumer, slot: input.slot, entries: input.entries.length }, caller);
+        }
+        catch {
+            // The state is closed.
+        }
+        return {};
+    }
+    /** A call to a built-in Actor: the hub, or storage with the consumer's own store. */
+    async #builtinCall(binding, method, caller, value) {
+        try {
+            const out = binding.provider !== STORAGE
+                ? await this.#actor.call(binding.export, method, caller, value)
+                : binding.export === "admin"
+                    ? this.#seed(caller, method, value)
+                    : this.#storage.call(binding.consumer, binding.slot, method, value);
+            return result(asJson(out));
+        }
+        catch (error) {
+            return errorBody(error);
+        }
+    }
+    /** A call sent on to its provider. Once anything is sent, a lost channel is OutcomeUnknown. */
+    async #forward(provider, binding, caller, method, value, cancelled) {
+        const out = this.#openTo(provider, binding);
+        try {
+            const writer = out.writable.getWriter();
+            await writer.write(encodeFrame({
+                op: "serve",
+                kind: "call",
+                export: binding.export,
+                caller,
+                slot: binding.slot,
+                method,
+            }));
+            await writer.write(encodeFrame(input(value)));
+            await writer.close();
+        }
+        catch {
+            out.reset();
+            throw new OutcomeUnknown(`${binding.provider} went away before answering.`);
+        }
+        return this.#answerFrom(out, new FrameReader(out.readable), binding, cancelled);
+    }
+    #openTo(provider, binding) {
+        try {
+            return provider.session.open();
+        }
+        catch {
+            throw new NotConnected(binding.slot);
+        }
+    }
+    /**
+     * The one body a provider answers with, within the answer deadline. Past it, or if the provider
+     * goes, it is OutcomeUnknown; if the caller resets first, `cancelled`. Either way the provider's
+     * stream is reset.
+     */
+    async #answerFrom(out, reader, binding, cancelled) {
+        let timer;
+        const late = new Promise((resolve) => {
+            timer = setTimeout(() => resolve("late"), this.#answerTimeoutMs);
+        });
+        let first;
+        try {
+            first = await Promise.race([reader.next(), late, cancelled.then(() => "cancelled")]);
+        }
+        catch (error) {
+            out.reset();
+            if (error instanceof FrameError)
+                throw new Refused("bad_output", error.message);
+            throw new OutcomeUnknown(`${binding.provider} went away before answering.`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (first === "late" || first === "cancelled") {
+            out.reset();
+            if (first === "cancelled")
+                throw new Refused("cancelled", "The caller went away.");
+            throw new OutcomeUnknown(`${binding.provider} didn't answer in time.`);
+        }
+        if (first === undefined) {
+            out.reset();
+            throw new OutcomeUnknown(`${binding.provider} closed the stream without answering.`);
+        }
+        try {
+            return parseBody(first);
+        }
+        catch (error) {
+            out.reset();
+            throw new Refused("bad_output", error instanceof Error ? error.message : String(error));
+        }
+    }
+    /**
+     * Events from the provider, each validated, until the subscriber resets the stream, the
+     * provider ends it, or the binding goes.
+     */
+    #subscribe(conn, header, stream, reader, writer) {
+        const stop = this.#subscribeCore(conn.actorId, header.slot, header.event, {
+            send: async (_, frame) => {
+                await writer.write(frame);
+            },
+            end: (error, cutOff) => {
+                // A subscriber that stops reading is cut off, not buffered for: its stream is reset.
+                if (cutOff)
+                    return stream.reset();
+                if (error)
+                    void answer(writer, error);
+                else
+                    void writer.close().catch(() => { });
+            },
+        });
+        if (!stop)
+            return drain(reader);
+        // A reset (or anything but a clean end of its side) from the subscriber ends it.
+        reader.next().then((more) => more !== undefined && stop(wireError("Refused", "A subscriber sends nothing.", "invalid")), () => stop());
+    }
+    /**
+     * Events of a caller's slot, without a channel: each checked, then handed to `sink` in order, the
+     * next waiting for the last to be taken, until the provider ends it, the binding goes, or the
+     * returned `stop` runs. A refusal at the start ends the sink at once and returns nothing.
+     */
+    #subscribeCore(caller, slot, event, sink) {
+        let resolved;
+        const part = { event };
+        try {
+            resolved = this.#resolve(caller, slot, "rpc");
+            if (!this.#validators.has(resolved.iface, part))
+                throw new Refused("invalid", `${resolved.iface.id} has no event ${event}.`);
+        }
+        catch (error) {
+            const body = errorBody(error);
+            this.#audit(caller, slot, resolved?.binding, {
+                op: "subscribe",
+                method: event,
+                outcome: outcomeOf(body.error),
+            });
+            sink.end(body);
+            return undefined;
+        }
+        const { binding, iface, provider } = resolved;
+        this.#audit(caller, slot, binding, { op: "subscribe", method: event, outcome: "ok" });
+        let stopProvider = () => { };
+        let ended = false;
+        let queued = 0;
+        const untrack = this.#track(binding, (error) => end(error));
+        const end = (error, cutOff) => {
+            if (ended)
+                return;
+            ended = true;
+            untrack();
+            stopProvider();
+            sink.end(error, cutOff);
+        };
+        // Events are checked off-thread, so each waits its turn here to keep them in order.
+        let delivered = Promise.resolve();
+        const deliver = (payload) => {
+            if (ended)
+                return delivered;
+            const { frame } = frameOf(eventBody(payload));
+            const size = frame.length;
+            if (queued + size > MAX_QUEUED_BYTES) {
+                end(wireError("Refused", "The subscriber stopped reading.", "slow"), true);
+                return delivered;
+            }
+            queued += size;
+            delivered = delivered.then(async () => {
+                try {
+                    if (ended)
+                        return;
+                    await this.#validators.check(caller, iface, part, payload, "bad_output");
+                    if (ended)
+                        return;
+                    await sink.send(payload, frame);
+                }
+                catch (error) {
+                    // A refused event (bad_output) or the subscriber failing to take it.
+                    end(error instanceof Refused
+                        ? errorBody(error)
+                        : wireError("Refused", error instanceof Error ? error.message : String(error), "failed"));
+                }
+                finally {
+                    queued -= size;
+                }
+            });
+            return delivered;
+        };
+        if (!provider) {
+            stopProvider = this.#actor.subscribe(binding.export, event, {
+                caller,
+                emit: (payload) => {
+                    let value;
+                    try {
+                        value = asJson(payload);
+                    }
+                    catch (error) {
+                        return end(wireError("Refused", `An event that isn't JSON: ${String(error)}`, "bad_output"));
+                    }
+                    void deliver(value);
+                },
+            });
+            return end;
+        }
+        let out;
+        try {
+            out = provider.session.open();
+        }
+        catch {
+            end(errorBody(new NotConnected(slot)));
+            return end;
+        }
+        stopProvider = () => out.reset();
+        void (async () => {
+            try {
+                const upstream = out.writable.getWriter();
+                await upstream.write(encodeFrame({
+                    op: "serve",
+                    kind: "subscribe",
+                    export: binding.export,
+                    caller,
+                    slot: binding.slot,
+                    event,
+                }));
+                await upstream.close();
+                const events = new FrameReader(out.readable);
+                for (;;) {
+                    const frame = await events.next();
+                    if (frame === undefined)
+                        return end();
+                    const body = parseBody(frame);
+                    // Backpressure: the provider's next event is read once this one is delivered.
+                    if ("event" in body)
+                        await deliver(body.event);
+                    else if ("error" in body)
+                        return end(body);
+                    else
+                        return end(wireError("Refused", "A subscription carries events.", "bad_output"));
+                    if (ended)
+                        return;
+                }
+            }
+            catch (error) {
+                end(error instanceof HeaderError || error instanceof FrameError
+                    ? wireError("Refused", error.message, "bad_output")
+                    : errorBody(new NotConnected(slot)));
+            }
+        })();
+        return end;
+    }
+    /**
+     * An accepted http stream to `net`: its requests are made from this process, HTTP/1.1 over the
+     * stream's raw bytes, until either side ends it or its binding goes.
+     */
+    async #egress(consumer, binding, stream, reader, writer, untrack) {
+        try {
+            await writer.write(encodeFrame(result({})));
+        }
+        catch {
+            untrack();
+            return stream.reset();
+        }
+        writer.releaseLock();
+        await serveOver({ readable: reader.rest(), writable: stream.writable }, (request) => this.#net.handle(request, { consumer, slot: binding.slot }), QUIET);
+        untrack();
+    }
+    /**
+     * `open` and `http`: validated, then the provider accepts or refuses with one body, which the Hub
+     * passes on; after an accept, raw bytes both ways until either side ends them.
+     */
+    async #splice(conn, header, stream, reader, writer) {
+        let binding;
+        let out;
+        let upstream;
+        let answered;
+        let outcome = "ok";
+        let unbound = false;
+        let untrack = () => { };
+        /** `net`'s egress, served here: no provider stream to splice. */
+        let egress = false;
+        try {
+            const resolved = this.#resolve(conn.actorId, header.slot, header.op === "open" ? "stream" : "http");
+            binding = resolved.binding;
+            // Tracked from here, so a binding that goes while the provider decides ends it too.
+            untrack = this.#track(binding, () => {
+                unbound = true;
+                out?.reset();
+                stream.reset();
+            });
+            if (header.op === "open")
+                await this.#validators.check(conn.actorId, resolved.iface, { open: true }, header.params, "invalid");
+            if (!resolved.provider && binding.provider === NET && header.op === "http") {
+                // net's egress is served in this process: accepted here, then the stream is its.
+                egress = true;
+                answered = result({});
+            }
+            else {
+                // The hub's and storage's exports are all rpc, so #resolve refused them already.
+                if (!resolved.provider)
+                    throw new NotConnected(header.slot);
+                const opened = this.#openTo(resolved.provider, binding);
+                out = opened;
+                try {
+                    const head = opened.writable.getWriter();
+                    await head.write(encodeFrame({
+                        op: "serve",
+                        kind: header.op,
+                        export: binding.export,
+                        caller: conn.actorId,
+                        slot: binding.slot,
+                        ...(header.op === "open" ? { params: header.params } : {}),
+                    }));
+                    head.releaseLock();
+                }
+                catch {
+                    throw new OutcomeUnknown(`${binding.provider} went away before answering.`);
+                }
+                upstream = new FrameReader(opened.readable);
+                const body = await this.#answerFrom(opened, upstream, binding, new Promise(() => { }));
+                if (unbound)
+                    throw new NotConnected(header.slot);
+                if ("error" in body) {
+                    outcome = "refused";
+                    answered = body;
+                }
+                else if ("result" in body)
+                    answered = result({});
+                else
+                    throw new Refused("bad_output", "A provider answers an open with {result} or {error}.");
+            }
+        }
+        catch (error) {
+            answered = errorBody(unbound ? new NotConnected(header.slot) : error);
+            outcome = outcomeOf(answered.error);
+        }
+        this.#audit(conn.actorId, header.slot, binding, { op: header.op, outcome });
+        if (egress && binding && "result" in answered)
+            return this.#egress(conn.actorId, binding, stream, reader, writer, untrack);
+        if (!("result" in answered) || !out || !upstream) {
+            untrack();
+            out?.reset();
+            await answer(writer, answered);
+            return drain(reader);
+        }
+        const provider = out;
+        try {
+            await writer.write(encodeFrame(answered));
+        }
+        catch {
+            untrack();
+            return provider.reset();
+        }
+        writer.releaseLock();
+        await Promise.all([pass(reader.rest(), provider), pass(upstream.rest(), stream)]);
+        untrack();
+    }
+}