@earendil-works/chord 1.5.0 → 1.5.1

package/dist/connection.js

@@ -1,1216 +0,0 @@
-import { contractFromDescription, LOCAL_VARIANT, resolveHost } from "./contract.js";
-import { encoder } from "./delta/index.js";
-import { ChordError, invalid } from "./errors.js";
-import { Packed, unpack } from "./link.js";
-import { RefImpl, variantOf } from "./object.js";
-import { assertValid } from "./schema.js";
-import { fromWireError, isFrame, PROTOCOL_VERSION, toWireError } from "./wire.js";
-const DEFAULT_WINDOW = 256 * 1024;
-/** The default cap of waiting state ops per link, in windows. */
-const PENDING_WINDOWS = 4;
-const unavailable = (message) => new ChordError("unavailable", message);
-// ─── relay ───────────────────────────────────────────────────────────────────
-/**
- * A hold relayed from an origin link to a downstream link. It owns everything done through it: state and calls queued
- * while the route resolves, and the downstream twins once forwarded. `close` undoes all of it exactly once (cancels
- * calls downstream, drops what waits for the origin, releases the downstream hold, rejects waiters).
- */
-export class RelayRef {
-    origin;
-    frame;
-    principal;
-    /** The client connection the hold comes from (forwarded downstream); undefined for a host's own holds. */
-    originTag;
-    /** The origin's authorization generation when the hold arrived; a revocation bumps it. */
-    generation;
-    down;
-    downId = 0;
-    closed = false;
-    /** The origin wants state (forwarded as `state: false`, `sub`, `unsub`). */
-    stateWanted;
-    /** The members of the first unit, still to forward past the origin's window. */
-    urgent;
-    #shaped = false;
-    /** Members whose ops this relay dropped: downstream ops are ignored until their reset arrives. */
-    awaiting = new Set();
-    calls = new Map();
-    #waiters = new Set();
-    constructor(origin, frame, principal, originTag) {
-        this.origin = origin;
-        this.frame = frame;
-        this.principal = principal;
-        this.originTag = originTag;
-        this.stateWanted = frame.state !== false;
-        this.generation = origin.generation;
-    }
-    get originId() {
-        return this.frame.id;
-    }
-    get client() {
-        return this.originTag !== undefined;
-    }
-    /** Still authorized as it was when it arrived. */
-    get current() {
-        return !this.closed && this.origin.open && this.origin.generation === this.generation;
-    }
-    /** The downstream connection once the route resolved; rejects if the relay closes first. */
-    ready() {
-        if (this.closed)
-            return Promise.reject(new ChordError("gone", "relayed hold closed"));
-        if (this.down !== undefined)
-            return Promise.resolve(this.down);
-        return new Promise((resolve, reject) => {
-            this.#waiters.add({ resolve: resolve, reject });
-        });
-    }
-    /** Forwards the hold to `down`. */
-    open(down) {
-        if (this.closed)
-            return;
-        this.down = down;
-        this.downId = down.nextId();
-        down.relayedRefs.set(this.downId, this);
-        const { at, token, input } = this.frame;
-        down.send({
-            t: "hold",
-            id: this.downId,
-            at,
-            token,
-            input,
-            principal: this.principal,
-            ...(this.originTag === undefined ? {} : { origin: this.originTag }),
-            ...(this.stateWanted ? {} : { state: false }),
-            ...(this.frame.again === true ? { again: true } : {}),
-        });
-        for (const waiter of this.#waiters)
-            waiter.resolve(down);
-        this.#waiters.clear();
-    }
-    /** The origin starts or stops the hold's state. */
-    wantState(wanted) {
-        if (this.closed || wanted === this.stateWanted)
-            return;
-        this.stateWanted = wanted;
-        if (!wanted) {
-            this.origin.dropHoldState(this.originId);
-            this.awaiting.clear();
-        }
-        this.down?.send({ t: wanted ? "sub" : "unsub", hold: this.downId });
-    }
-    /**
-     * The origin could not keep up and dropped what waited for member `m` (or asked for it again): ask downstream for a
-     * reset, and ignore its ops until the reset arrives.
-     */
-    resync(m) {
-        if (this.closed)
-            return;
-        this.awaiting.add(m);
-        this.down?.send({ t: "resync", hold: this.downId, m });
-    }
-    /** A shape from downstream: forwarded at once; the members of the first unit then skip the origin's window. */
-    shape(frame) {
-        if (this.closed)
-            return;
-        if (!this.#shaped) {
-            this.#shaped = true;
-            if (this.frame.again !== true)
-                this.urgent = new Set(frame.state);
-        }
-        this.origin.send({ ...frame, id: this.originId });
-    }
-    /** A state frame from downstream. */
-    state(frame) {
-        if (this.closed)
-            return;
-        const m = frame.m;
-        if (this.awaiting.has(m)) {
-            if (frame.as === "ops")
-                return;
-            this.awaiting.delete(m);
-        }
-        const out = { ...frame, hold: this.originId };
-        if (this.urgent?.delete(m) === true) {
-            this.origin.send(out);
-            return;
-        }
-        this.origin.sendState(out, { resync: () => this.resync(m) });
-    }
-    /**
-     * Closes the relay. `releaseDown`: the downstream hold is still there (origin released, disconnected, or was
-     * revoked): cancel its calls and release it. `notify`: tell the origin the hold is gone.
-     */
-    close(error, options) {
-        if (this.closed)
-            return;
-        this.closed = true;
-        for (const call of [...this.calls.values()])
-            call.cancel(error, options.releaseDown);
-        this.origin.dropHoldState(this.originId);
-        if (this.origin.served.get(this.originId)?.kind === "relay")
-            this.origin.served.delete(this.originId);
-        if (this.down !== undefined) {
-            this.down.relayedRefs.delete(this.downId);
-            if (options.releaseDown)
-                this.down.send({ t: "release", id: this.downId });
-        }
-        for (const waiter of this.#waiters)
-            waiter.reject(error);
-        this.#waiters.clear();
-        if (options.notify)
-            this.origin.send({ t: "gone", id: this.originId, error: toWireError(error) });
-    }
-}
-/** One relayed call: settles once, by result, cancellation or the relay closing; removes both mappings. */
-export class RelayCall {
-    relay;
-    originId;
-    downId;
-    #pending;
-    #settled = false;
-    constructor(relay, originId, downId, pending) {
-        this.relay = relay;
-        this.originId = originId;
-        this.downId = downId;
-        this.#pending = pending;
-        relay.calls.set(originId, this);
-        relay.down?.relayedCalls.set(downId, this);
-    }
-    finish(error, value) {
-        if (this.#settled)
-            return;
-        this.#settled = true;
-        this.relay.calls.delete(this.originId);
-        this.relay.down?.relayedCalls.delete(this.downId);
-        if (error === undefined)
-            this.#pending.resolve(value);
-        else
-            this.#pending.reject(error);
-    }
-    /** Cancels downstream (when the downstream hold still exists) and settles with `error`. */
-    cancel(error, forward) {
-        if (this.#settled)
-            return;
-        if (forward)
-            this.relay.down?.send({ t: "cancel", id: this.downId });
-        this.finish(error);
-    }
-}
-// ─── connection ──────────────────────────────────────────────────────────────
-/**
- * One end of a link on a host: consumer of remote references, provider for the peer's holds, and relay.
- *
- * State
- * -----
- *
- * A hold implies the state of its variant (unless it says `state: false`). The provider answers with a unit: the shape,
- * then a snapshot of each state member the consumer does not have yet (`shape.state` lists them), then the members'
- * ops and resets. A reload or a variant change sends another unit with the members that are new; members that left the
- * variant stop. The consumer applies a shape once its snapshots are here (`RemoteBinding`).
- *
- * Flow control
- * ------------
- *
- * Problem: state is pushed as fast as it changes, but a peer may read slowly (a phone behind a relay), and a relay may
- * hide that: Cloudflare forwards to browsers without backpressure. Everything sent then queues in front of the next
- * call result. Example: a browser opens three long transcripts (500 KiB of snapshots each) over a 5 Mbit/s path; a
- * result sent next waits 2.4 s, and the snapshot of a transcript the user already left is still sent in full.
- *
- * Solution: the peer acknowledges what it processed (`ack`, a cumulative frame count), and the sender counts the sizes
- * of the frames not yet acknowledged. While they exceed the window, state waits here in slots, flushed in creation
- * order as acknowledgements come:
- * - a member's stream has one slot: ops are appended (encoded batches of one stream may be concatenated, see
- *   `encoder`), a snapshot, reset or error replaces it;
- * - a hold's unit has one slot, built lazily from the current values when it is sent, so a newer unit merges into it;
- *   while it waits, the members it introduces have no stream yet.
- *
- * The first unit of a hold that is not a re-hold (`again`) is sent at once, past the window: a `get` waits for it, and
- * must not wait behind other holds' state. Results, shapes, gone, reload control and pings are sent at once too: they
- * are bounded by the requests the peer makes. Hence the one ordering exception of a link: while state waits, a result
- * can arrive before state changes made before it. Frames of one stream stay in order.
- *
- * Waiting ops are capped per link (`pendingCap`): beyond, the oldest streams are replaced by their current value (a
- * reset built at flush), or, on a relay, by a reset asked of the provider (`resync`), so memory stays bounded however
- * long the peer stalls. The window bounds what is unacknowledged when a frame is sent, so one frame (a large snapshot)
- * may exceed it. Both hellos must announce `acks`; with an older peer nothing is acknowledged and nothing waits. Links
- * that do not report sizes (IPC) never fill the window.
- */
-export class Connection {
-    host;
-    link;
-    /** `upstream`: the link to this host's parent. `downstream`: a link this host accepted. */
-    role;
-    peer;
-    /** A client connection's opaque id: holds that come over it (directly or relayed) carry it as their `origin`. */
-    originId;
-    principal;
-    restamp;
-    /** Bumped when the stamped principal is revoked or re-stamped: relays from before are refused. */
-    generation = 0;
-    /** The code version a downstream host peer runs (from its hello, then from commits). */
-    peerCodeVersion;
-    /** A downstream host peer is usable once it runs this host's current code version (see `HostImpl.peerHello`). */
-    synced;
-    /** Code versions this child announced while behind this host (fenced): this host never ran them. */
-    fencedCodeVersions = new Set();
-    /** Roots of fenced code versions, by the code version of this host they were admitted in. */
-    #admitted = new Map();
-    #parentName;
-    #syncWaiters = new Set();
-    #nextId = 1;
-    #lastSeen = Date.now();
-    #pinger;
-    #maxCalls;
-    // flow control (see the class comment)
-    #window;
-    #pendingCap;
-    /** Whether the peer acknowledges frames; until its hello is here, frames are counted in case it does. */
-    #peerAcks;
-    #sent = 0;
-    #acked = 0;
-    /** Sizes of the frames sent after the last acknowledged one. */
-    #unacked = [];
-    #unackedBytes = 0;
-    #pending = new Map();
-    /** Bytes of ops waiting in `#pending`. */
-    #pendingBytes = 0;
-    #received = 0;
-    #ackTimer;
-    #onProtocolMismatch;
-    /** The peer speaks another protocol version: nothing it sends is processed any more. */
-    #mismatched = false;
-    // consumer side: what this host asked of the peer
-    remotes = new Map();
-    calls = new Map();
-    // provider side: what the peer asked of this host
-    served = new Map();
-    incoming = new Map();
-    // downstream side of relays: ids this host used on this link
-    relayedRefs = new Map();
-    relayedCalls = new Map();
-    /** Reload votes awaited from this (child) peer. */
-    votes = new Map();
-    constructor(host, link, config) {
-        this.host = host;
-        this.link = link;
-        this.role = config.role;
-        this.peer = config.peer;
-        this.originId = config.originId;
-        this.principal = config.principal;
-        this.restamp = config.restamp;
-        this.synced = !(this.role === "downstream" && this.peer.kind === "host");
-        this.#window = config.window ?? DEFAULT_WINDOW;
-        this.#pendingCap = config.pendingCap ?? this.#window * PENDING_WINDOWS;
-        this.#maxCalls = config.maxCalls ?? Number.POSITIVE_INFINITY;
-        this.#onProtocolMismatch = config.onProtocolMismatch;
-        link.onClose((reason) => this.#closed(reason));
-        link.receive((frame) => this.#receive(frame));
-        this.send({
-            t: "hello",
-            protocol: PROTOCOL_VERSION,
-            name: host.name,
-            kind: host.kind,
-            codeVersion: host.current.id,
-            acks: true,
-        });
-        const interval = config.pingInterval ?? 15_000;
-        const timeout = config.pingTimeout ?? 45_000;
-        // A link that was already closed closed this connection above; it needs no keepalive.
-        if (link.closed)
-            return;
-        let n = 0;
-        this.#pinger = setInterval(() => {
-            if (Date.now() - this.#lastSeen > timeout)
-                link.close("ping timeout");
-            else
-                this.send({ t: "ping", n: ++n });
-        }, interval);
-        this.#pinger.unref?.();
-    }
-    get open() {
-        return !this.link.closed;
-    }
-    /** The peer's name: configured for downstream hosts, announced by the parent upstream. */
-    get name() {
-        return this.role === "upstream" ? this.#parentName : this.peer.name;
-    }
-    send(frame) {
-        const size = this.link.send(frame) ?? 0;
-        if (this.#peerAcks === false)
-            return;
-        this.#sent++;
-        this.#unacked.push(size);
-        this.#unackedBytes += size;
-    }
-    /** Sends a state frame, or keeps it waiting (see the class comment). */
-    sendState(frame, overflow) {
-        const key = stateKey(frame.hold, frame.m);
-        let slot = this.#pending.get(key);
-        if (slot === undefined && !this.#full) {
-            this.send(frame);
-            return;
-        }
-        if (slot?.kind === "unit")
-            return;
-        if (slot === undefined) {
-            slot = {
-                kind: "state",
-                hold: frame.hold,
-                m: frame.m,
-                base: undefined,
-                ops: [],
-                size: 0,
-                lazy: false,
-                overflow,
-            };
-            this.#pending.set(key, slot);
-        }
-        if (frame.as !== "ops") {
-            this.#pendingBytes -= slot.size;
-            slot.base = frame;
-            slot.ops = [];
-            slot.size = 0;
-            slot.lazy = false;
-            return;
-        }
-        // A reset built at flush already covers these ops.
-        if (slot.lazy)
-            return;
-        const size = JSON.stringify(frame.ops).length;
-        if (this.#pendingBytes + size > this.#pendingCap)
-            this.#makeRoom(size, slot);
-        if (slot.lazy || this.#pending.get(key) !== slot)
-            return;
-        for (const op of frame.ops ?? [])
-            slot.ops.push(op);
-        slot.size += size;
-        this.#pendingBytes += size;
-    }
-    /** Replaces the oldest waiting streams by resets until `size` more bytes fit; `current` last, if needed. */
-    #makeRoom(size, current) {
-        for (const slot of [...this.#pending.values()]) {
-            if (this.#pendingBytes + size <= this.#pendingCap)
-                return;
-            if (slot.kind === "state" && slot !== current && slot.size > 0)
-                this.#drop(slot);
-        }
-        if (this.#pendingBytes + size > this.#pendingCap)
-            this.#drop(current);
-    }
-    /** Drops what waits for a stream: a lazy reset replaces it (provider), or the relay asks downstream for one. */
-    #drop(slot) {
-        this.#pendingBytes -= slot.size;
-        slot.base = undefined;
-        slot.ops = [];
-        slot.size = 0;
-        if ("resend" in slot.overflow) {
-            slot.lazy = true;
-            return;
-        }
-        this.#pending.delete(stateKey(slot.hold, slot.m));
-        slot.overflow.resync();
-    }
-    /** Sends member `m` of a served hold again as a reset, through the window (`resync`). */
-    #resetLater(hold, m, resend) {
-        const key = stateKey(hold, m);
-        let slot = this.#pending.get(key);
-        if (slot?.kind === "unit")
-            return;
-        if (slot === undefined) {
-            slot = { kind: "state", hold, m, base: undefined, ops: [], size: 0, lazy: true, overflow: { resend } };
-            this.#pending.set(key, slot);
-        }
-        else {
-            this.#pendingBytes -= slot.size;
-            slot.base = undefined;
-            slot.ops = [];
-            slot.size = 0;
-            slot.lazy = true;
-        }
-        this.#flush();
-    }
-    /** Queues a hold's lazy unit (a waiting one already covers this one), and sends what the window allows. */
-    #queueUnit(hold, flush) {
-        const key = unitKey(hold);
-        if (!this.#pending.has(key))
-            this.#pending.set(key, { kind: "unit", hold, flush });
-        this.#flush();
-    }
-    /** Forgets what waits for a stream that ended. */
-    dropState(hold, m) {
-        const slot = this.#pending.get(stateKey(hold, m));
-        if (slot?.kind !== "state")
-            return;
-        this.#pendingBytes -= slot.size;
-        this.#pending.delete(stateKey(hold, m));
-    }
-    /** Forgets everything that waits for a hold (released, closed, or its state stopped). */
-    dropHoldState(hold) {
-        for (const [key, slot] of this.#pending) {
-            if (slot.hold !== hold)
-                continue;
-            if (slot.kind === "state")
-                this.#pendingBytes -= slot.size;
-            this.#pending.delete(key);
-        }
-    }
-    /** What waits for the peer: slots and bytes of ops (for tests and diagnostics). */
-    get waiting() {
-        return { slots: this.#pending.size, bytes: this.#pendingBytes };
-    }
-    get #full() {
-        return this.#peerAcks === true && this.#unackedBytes >= this.#window;
-    }
-    #onAck(n) {
-        if (this.#peerAcks !== true || n < this.#acked || n > this.#sent) {
-            this.#violation(`ack ${n} outside ${this.#acked}..${this.#sent}`);
-            return;
-        }
-        for (const size of this.#unacked.splice(0, n - this.#acked))
-            this.#unackedBytes -= size;
-        this.#acked = n;
-        this.#flush();
-    }
-    /** Sends waiting slots in creation order while the window allows. */
-    #flush() {
-        for (const [key, slot] of this.#pending) {
-            if (this.#full)
-                return;
-            this.#pending.delete(key);
-            if (slot.kind === "unit") {
-                slot.flush();
-                continue;
-            }
-            this.#pendingBytes -= slot.size;
-            if (slot.lazy) {
-                if ("resend" in slot.overflow)
-                    slot.overflow.resend();
-                continue;
-            }
-            if (slot.base !== undefined)
-                this.send(slot.base);
-            if (slot.ops.length > 0)
-                this.send({ t: "state", hold: slot.hold, m: slot.m, as: "ops", ops: slot.ops });
-        }
-    }
-    /** Acknowledges once the frames that arrived together are processed: one ack per burst, not per frame. */
-    #scheduleAck() {
-        if (this.#peerAcks !== true || this.#ackTimer !== undefined || !this.open)
-            return;
-        this.#ackTimer = setTimeout(() => {
-            this.#ackTimer = undefined;
-            this.link.send({ t: "ack", n: this.#received });
-        }, 0);
-        this.#ackTimer.unref?.();
-    }
-    nextId() {
-        return this.#nextId++;
-    }
-    /** Resolves once the peer is usable (a host peer runs this host's code version); rejects if the link closes first. */
-    whenSynced() {
-        if (!this.open)
-            return Promise.reject(unavailable(`link to ${this.name ?? "peer"} closed`));
-        if (this.synced)
-            return Promise.resolve();
-        return new Promise((resolve, reject) => this.#syncWaiters.add({ resolve: resolve, reject }));
-    }
-    markSynced(codeVersion) {
-        this.peerCodeVersion = codeVersion;
-        this.synced = true;
-        for (const waiter of this.#syncWaiters)
-            waiter.resolve(undefined);
-        this.#syncWaiters.clear();
-    }
-    /** Revokes the stamped principal: relays made under it close at once (also those still resolving a route). */
-    revoke(next) {
-        this.generation++;
-        const error = new ChordError("gone", "principal invalidated");
-        for (const served of [...this.served.values()]) {
-            if (served.kind === "relay")
-                served.relay.close(error, { releaseDown: true, notify: true });
-        }
-        if (next === undefined)
-            this.link.close("principal invalidated");
-        else
-            this.principal = next;
-    }
-    /**
-     * Stops talking to a peer of another protocol version: reports it and closes the link. The close reason tells the
-     * peer this side's version (`protocol-version <n>`); a peer that noticed first told us the same way (`#closed`).
-     */
-    #protocolMismatch(peer, close = true) {
-        if (this.#mismatched)
-            return;
-        this.#mismatched = true;
-        try {
-            this.#onProtocolMismatch?.({ local: PROTOCOL_VERSION, peer });
-        }
-        catch (error) {
-            this.host.report(error);
-        }
-        if (close)
-            this.link.close(`protocol-version ${PROTOCOL_VERSION}`);
-    }
-    /** A protocol violation: the peer cannot be trusted with anything on this link any more. */
-    #violation(reason) {
-        this.host.report(new ChordError("invalid", `link to ${this.name ?? "peer"}: ${reason}`, { reason: "protocol" }));
-        this.link.close(`protocol error: ${reason}`);
-    }
-    // ─── consumer side (RemoteChannel) ───
-    hold(binding, again) {
-        const id = this.nextId();
-        this.remotes.set(id, binding);
-        binding.bound(this, id);
-        const principal = binding.principal;
-        this.send({
-            t: "hold",
-            id,
-            at: binding.at,
-            token: binding.contract.description,
-            input: binding.input,
-            ...(principal === undefined ? {} : { principal }),
-            ...(binding.stateOn ? {} : { state: false }),
-            ...(again ? { again: true } : {}),
-        });
-        return id;
-    }
-    release(id) {
-        this.remotes.delete(id);
-        this.send({ t: "release", id });
-    }
-    wantState(hold, wanted) {
-        if (this.remotes.has(hold))
-            this.send({ t: wanted ? "sub" : "unsub", hold });
-    }
-    call(hold, member, args, root, signal) {
-        const id = this.nextId();
-        return new Promise((resolve, reject) => {
-            if (signal.aborted) {
-                reject(new ChordError("aborted", "call aborted"));
-                return;
-            }
-            const onAbort = () => {
-                this.calls.delete(id);
-                this.send({ t: "cancel", id });
-                reject(new ChordError("aborted", "call aborted", { cause: signal.reason }));
-            };
-            signal.addEventListener("abort", onAbort, { once: true });
-            const done = () => signal.removeEventListener("abort", onAbort);
-            this.calls.set(id, {
-                resolve: (value) => {
-                    done();
-                    resolve(value);
-                },
-                reject: (error) => {
-                    done();
-                    reject(error);
-                },
-            });
-            // Clients never carry roots or code versions: the server starts roots for them.
-            const carried = root !== undefined && this.host.kind === "host";
-            if (carried)
-                this.host.rootSent(root.rootId, this);
-            this.send({ t: "call", id, hold, member, args, ...(carried ? { root } : {}) });
-        });
-    }
-    // ─── receiving ───
-    #receive(frame) {
-        if (this.#mismatched)
-            return;
-        this.#lastSeen = Date.now();
-        if (!isFrame(frame)) {
-            this.#violation("malformed frame");
-            return;
-        }
-        if (frame.t === "ack") {
-            this.#onAck(frame.n);
-            return;
-        }
-        this.#received++;
-        try {
-            this.#dispatch(frame);
-        }
-        catch (error) {
-            this.host.report(error);
-        }
-        this.#scheduleAck();
-    }
-    #dispatch(frame) {
-        switch (frame.t) {
-            case "hello":
-                this.#onHello(frame);
-                return;
-            case "ping":
-                this.send({ t: "pong", n: frame.n });
-                return;
-            case "pong":
-            case "bye":
-            case "ack":
-                return;
-            case "hold":
-                this.#onHold(frame);
-                return;
-            case "release":
-                this.#dropServed(frame.id, true);
-                return;
-            case "call":
-                this.#onCall(frame);
-                return;
-            case "cancel":
-                this.incoming.get(frame.id)?.abort(new ChordError("aborted", "cancelled by caller"));
-                return;
-            case "sub":
-            case "unsub":
-                this.#onWantState(frame.hold, frame.t === "sub");
-                return;
-            case "resync":
-                this.#onResync(frame.hold, frame.m);
-                return;
-            case "shape":
-            case "gone":
-                this.#onHoldReply(frame);
-                return;
-            case "result":
-                this.#onResult(frame);
-                return;
-            case "state":
-                this.#onState(frame);
-                return;
-            case "root_end":
-                // Honored only from the link the root came over (see HostImpl.foreignRootEnded).
-                this.#admitted.delete(frame.rootId);
-                this.host.foreignRootEnded(frame.rootId, this);
-                return;
-            case "invalidate":
-            case "prepare":
-            case "commit":
-            case "abort":
-            case "retire":
-                // Control frames only from the parent.
-                if (this.role !== "upstream") {
-                    this.#violation(`${frame.t} from a child`);
-                    return;
-                }
-                if (frame.t === "invalidate") {
-                    this.host.invalidatePrincipal(frame.pattern).catch((error) => this.host.report(error));
-                }
-                else if (frame.t === "retire")
-                    this.host.allowRetire(frame.codeVersion);
-                else
-                    this.host.onReloadFrame(this, frame);
-                return;
-            case "vote": {
-                if (this.role !== "downstream" || this.peer.kind !== "host") {
-                    this.#violation("vote from a non-participant");
-                    return;
-                }
-                const vote = this.votes.get(frame.reload);
-                this.votes.delete(frame.reload);
-                if (frame.error === undefined)
-                    vote?.resolve(frame.report);
-                else
-                    vote?.reject(fromWireError(frame.error));
-                return;
-            }
-        }
-    }
-    /**
-     * The peer's hello must agree with what this side decided about it. A downstream host announces its code version:
-     * the host either finds it in step or fences and reconciles it (never renumbers).
-     */
-    #onHello(frame) {
-        if ((frame.protocol ?? 1) !== PROTOCOL_VERSION) {
-            this.#protocolMismatch(frame.protocol ?? 1);
-            return;
-        }
-        if (this.#peerAcks === undefined) {
-            this.#peerAcks = frame.acks === true;
-            if (!this.#peerAcks) {
-                this.#unacked = [];
-                this.#unackedBytes = 0;
-            }
-        }
-        if (this.role === "upstream") {
-            if (frame.kind !== "host") {
-                this.#violation("parent is not a host");
-                return;
-            }
-            this.#parentName ??= frame.name;
-            return;
-        }
-        if (frame.kind !== this.peer.kind || (this.peer.name !== undefined && frame.name !== this.peer.name)) {
-            this.#violation(`hello ${frame.kind} ${frame.name} does not match the accepted ${this.peer.kind} ${this.peer.name ?? ""}`);
-            return;
-        }
-        if (this.peer.kind === "host")
-            this.host.peerHello(this, frame.codeVersion);
-    }
-    /**
-     * Principal stamping: a downstream link acts as the principal it was accepted with, whatever the frame says. Only
-     * the parent may forward a principal (relayed requests); its own requests act as the principal given to `connect`.
-     */
-    #principalOf(frame) {
-        if (this.role === "downstream")
-            return this.principal;
-        return frame.principal ?? this.principal;
-    }
-    /**
-     * The client connection a hold comes from: this link's own id for a client link (whatever the frame says), the id
-     * the parent forwarded for a relayed hold, none for a host's own holds.
-     */
-    #originOf(frame) {
-        return this.role === "downstream" ? this.originId : frame.origin;
-    }
-    #onHold(frame) {
-        if (this.served.has(frame.id)) {
-            this.#violation(`duplicate hold id ${frame.id}`);
-            return;
-        }
-        const principal = this.#principalOf(frame);
-        const origin = this.#originOf(frame);
-        const client = origin !== undefined;
-        if (frame.at !== this.host.name) {
-            if (this.role === "upstream") {
-                this.send({ t: "gone", id: frame.id, error: toWireError(unavailable(`${this.host.name} does not relay`)) });
-                return;
-            }
-            const relay = new RelayRef(this, frame, principal, origin);
-            this.served.set(frame.id, { kind: "relay", relay });
-            this.host.relay(relay).catch((error) => relay.close(error, { releaseDown: true, notify: true }));
-            return;
-        }
-        let ref;
-        try {
-            const token = contractFromDescription(frame.token);
-            if (token.scope !== "remote")
-                throw invalid("token", `${token.name} is local; only remote types cross links`);
-            // Addressed here, so the input must place it here (also by this host's contract, checked when acquiring).
-            if (resolveHost(token.name, token.description.host, frame.input) !== this.host.name)
-                throw invalid("placement", `${token.name} with this input does not live on ${this.host.name}`);
-            const acquired = this.host.acquire(token, frame.input, { principal }, client ? "client" : "connection");
-            if (!(acquired instanceof RefImpl))
-                throw unavailable("not a local reference");
-            ref = acquired;
-        }
-        catch (error) {
-            this.send({ t: "gone", id: frame.id, error: toWireError(client ? clientError(error) : error) });
-            return;
-        }
-        const served = {
-            kind: "local",
-            id: frame.id,
-            ref,
-            principal,
-            origin,
-            wantsState: frame.state !== false,
-            again: frame.again === true,
-            unitSent: false,
-            feeds: new Map(),
-        };
-        this.served.set(frame.id, served);
-        ref.onShape(() => this.#unit(served));
-        ref.goneListeners.add((error) => {
-            if (this.served.get(frame.id) !== served)
-                return;
-            this.#dropServed(frame.id, false);
-            this.send({ t: "gone", id: frame.id, error: toWireError(error) });
-        });
-        if (ref.status === "live")
-            this.#unit(served);
-    }
-    /** The state members of `shape` the consumer's contract knows. */
-    #stateMembers(ref, shape) {
-        return shape.members.filter((name) => ref.describe(shape.variant, name)?.kind === "state");
-    }
-    /**
-     * The shape changed (live, reload, variant) or state was asked for: members that left lose their stream, and a unit
-     * goes out with the shape and the members the consumer lacks. The first unit of a hold (not a re-hold) is urgent.
-     */
-    #unit(served) {
-        if (this.served.get(served.id) !== served)
-            return;
-        const shape = served.ref.shape;
-        if (shape === undefined)
-            return;
-        const members = new Set(served.wantsState ? this.#stateMembers(served.ref, shape) : []);
-        for (const [name, feed] of served.feeds) {
-            if (members.has(name))
-                continue;
-            feed.unsubscribe();
-            served.feeds.delete(name);
-            this.dropState(served.id, name);
-        }
-        const urgent = served.feeds.size === 0 && !(served.again && !served.unitSent);
-        if (urgent)
-            this.#sendUnit(served);
-        else
-            this.#queueUnit(served.id, () => this.#sendUnit(served));
-    }
-    /** Builds and sends a unit from the current shape and values. */
-    #sendUnit(served) {
-        this.#pending.delete(unitKey(served.id));
-        if (this.served.get(served.id) !== served)
-            return;
-        const shape = served.ref.shape;
-        if (shape === undefined)
-            return;
-        served.unitSent = true;
-        const members = served.wantsState ? this.#stateMembers(served.ref, shape) : [];
-        const listed = members.filter((name) => !served.feeds.has(name));
-        const snaps = [];
-        const attached = [];
-        for (const name of listed) {
-            const attachment = this.#attach(served, name);
-            if (attachment === undefined)
-                continue;
-            snaps.push(attachment.frame);
-            attached.push([name, attachment.feed]);
-        }
-        this.send({
-            t: "shape",
-            id: served.id,
-            ...(shape.variant === undefined ? {} : { variant: shape.variant }),
-            members: shape.members,
-            contract: shape.contract,
-            state: snaps.map((frame) => frame.m),
-        });
-        for (const frame of snaps)
-            this.send(frame);
-        for (const [name, feed] of attached)
-            this.#replay(served, name, feed);
-    }
-    /**
-     * Subscribes member `name` for the consumer: its snapshot (as a frame of type `as`), and a feed whose later events
-     * wait in its buffer until the snapshot is sent (`#replay`). Undefined if the member is not readable state.
-     */
-    #attach(served, name, as = "snap") {
-        const readable = served.ref.member(name);
-        if (readable === undefined || typeof readable.events !== "function")
-            return undefined;
-        const feed = { unsubscribe: () => { }, encoder: encoder(), buffer: [] };
-        let first;
-        feed.unsubscribe = readable.events((event) => {
-            if (first === undefined)
-                first = event;
-            else if (feed.buffer !== undefined)
-                feed.buffer.push(event);
-            else
-                this.#feedEvent(served, name, feed, event);
-        });
-        served.feeds.set(name, feed);
-        return { frame: this.#snapshot(served, name, as, first?.value), feed };
-    }
-    /** Sends the events that arrived while the snapshot was built, now that it is sent. */
-    #replay(served, name, feed) {
-        const buffered = feed.buffer ?? [];
-        feed.buffer = undefined;
-        for (const event of buffered)
-            this.#feedEvent(served, name, feed, event);
-    }
-    /** A member's state frame for a snapshot or reset: validated against the schema the consumer is promised. */
-    #snapshot(served, name, as, value) {
-        try {
-            validateSnapshot(served.ref, name, value);
-        }
-        catch (error) {
-            return { t: "state", hold: served.id, m: name, as: "error", error: toWireError(error) };
-        }
-        return { t: "state", hold: served.id, m: name, as, ...(value === undefined ? {} : { value }) };
-    }
-    /** A later event of a member's stream: ops are encoded, a reset starts a new stream. */
-    #feedEvent(served, name, feed, event) {
-        if (served.feeds.get(name) !== feed)
-            return;
-        const overflow = { resend: () => this.#resend(served, name) };
-        if (event.type === "ops") {
-            this.sendState({ t: "state", hold: served.id, m: name, as: "ops", ops: feed.encoder.encode(event.ops) }, overflow);
-            return;
-        }
-        feed.encoder = encoder();
-        this.sendState(this.#snapshot(served, name, "reset", event.value), overflow);
-    }
-    /** Sends member `name` again, now, as a reset from its current value (a lazy slot is flushed, or `resync`). */
-    #resend(served, name) {
-        const feed = served.feeds.get(name);
-        if (feed === undefined || this.served.get(served.id) !== served)
-            return;
-        feed.unsubscribe();
-        served.feeds.delete(name);
-        const attachment = this.#attach(served, name, "reset");
-        if (attachment === undefined)
-            return;
-        this.send(attachment.frame);
-        this.#replay(served, name, attachment.feed);
-    }
-    /** The consumer starts (`sub`) or stops (`unsub`) the state of a hold. */
-    #onWantState(hold, wanted) {
-        const served = this.served.get(hold);
-        if (served === undefined)
-            return;
-        if (served.kind === "relay") {
-            served.relay.wantState(wanted);
-            return;
-        }
-        if (served.wantsState === wanted)
-            return;
-        served.wantsState = wanted;
-        if (wanted) {
-            this.#unit(served);
-            return;
-        }
-        for (const feed of served.feeds.values())
-            feed.unsubscribe();
-        served.feeds.clear();
-        this.dropHoldState(hold);
-    }
-    /** The consumer (a relay that dropped ops) asks for member `m` again as a reset. */
-    #onResync(hold, m) {
-        const served = this.served.get(hold);
-        if (served === undefined)
-            return;
-        if (served.kind === "relay") {
-            served.relay.resync(m);
-            return;
-        }
-        if (!served.feeds.has(m))
-            return;
-        this.#resetLater(hold, m, () => this.#resend(served, m));
-    }
-    /** Forgets a served hold: unsubscribes its feeds and releases it (locally or downstream). */
-    #dropServed(id, release) {
-        const served = this.served.get(id);
-        if (served === undefined)
-            return;
-        this.served.delete(id);
-        if (served.kind === "relay") {
-            served.relay.close(new ChordError("released", "relayed hold released"), {
-                releaseDown: release,
-                notify: false,
-            });
-            return;
-        }
-        for (const feed of served.feeds.values())
-            feed.unsubscribe();
-        served.feeds.clear();
-        this.dropHoldState(id);
-        if (release)
-            served.ref.release();
-    }
-    #onCall(frame) {
-        if (this.incoming.has(frame.id)) {
-            this.#violation(`duplicate call id ${frame.id}`);
-            return;
-        }
-        if (this.incoming.size >= this.#maxCalls) {
-            const error = new ChordError("unavailable", `Too many calls in progress on this connection (${this.#maxCalls}); wait for earlier ones to finish`, { reason: "too_many_calls" });
-            this.send({ t: "result", id: frame.id, error: toWireError(error) });
-            return;
-        }
-        const served = this.served.get(frame.hold);
-        if (served === undefined) {
-            this.send({ t: "result", id: frame.id, error: toWireError(new ChordError("gone", "unknown hold")) });
-            return;
-        }
-        const controller = new AbortController();
-        this.incoming.set(frame.id, controller);
-        // Roots are honored from hosts only; a request without one (or from a client) starts one here.
-        const root = this.peer.kind === "host" ? this.#admitRoot(frame.root) : undefined;
-        const principal = served.kind === "local" ? served.principal : served.relay.principal;
-        const options = { principal, signal: controller.signal };
-        const run = served.kind === "local"
-            ? (ctx) => served.ref.object.call(served.ref, frame.member, unpack(frame.args), ctx)
-            : (ctx) => relayCall(served.relay, frame, { rootId: ctx.rootId, codeVersion: ctx.codeVersion }, 
-            // The root's signal: a cancel from the origin and the root's code version retiring both reach it.
-            ctx.signal, this.host);
-        const result = root === undefined
-            ? this.host.root(run, options)
-            : this.host.joinRoot(root.rootId, root.codeVersion, run, { ...options, from: this });
-        result
-            .then((value) => this.send({ t: "result", id: frame.id, value }), (error) => this.send({ t: "result", id: frame.id, error: toWireError(error) }))
-            .finally(() => this.incoming.delete(frame.id));
-    }
-    /**
-     * A child that connected behind this host runs roots of a code version this host never had (it was fenced and is
-     * being, or was, reconciled). Such a root is admitted in this host's current code version at its first call here,
-     * and keeps that code version for its later calls (`superseded` once this host retired it). Other unknown code
-     * versions stay `superseded`.
-     */
-    #admitRoot(root) {
-        if (root === undefined || this.role !== "downstream" || !this.fencedCodeVersions.has(root.codeVersion))
-            return root;
-        if (this.host.hasCodeVersion(root.codeVersion))
-            return root;
-        let codeVersion = this.#admitted.get(root.rootId);
-        if (codeVersion === undefined) {
-            codeVersion = this.host.current.id;
-            this.#admitted.set(root.rootId, codeVersion);
-        }
-        return { rootId: root.rootId, codeVersion };
-    }
-    #onHoldReply(frame) {
-        const relay = this.relayedRefs.get(frame.id);
-        if (relay !== undefined) {
-            if (frame.t === "gone")
-                relay.close(fromWireError(frame.error), { releaseDown: false, notify: true });
-            else
-                relay.shape(frame);
-            return;
-        }
-        const binding = this.remotes.get(frame.id);
-        if (binding === undefined)
-            return;
-        if (frame.t === "gone") {
-            this.remotes.delete(frame.id);
-            binding.gone(fromWireError(frame.error));
-            return;
-        }
-        binding.shaped({ variant: frame.variant, members: frame.members, contract: frame.contract }, frame.state);
-    }
-    #onResult(frame) {
-        const relayed = this.relayedCalls.get(frame.id);
-        if (relayed !== undefined) {
-            relayed.finish(frame.error === undefined ? undefined : fromWireError(frame.error), frame.value);
-            return;
-        }
-        const pending = this.calls.get(frame.id);
-        this.calls.delete(frame.id);
-        if (frame.error !== undefined) {
-            pending?.reject(fromWireError(frame.error));
-            return;
-        }
-        let value;
-        try {
-            value = unpack(frame.value);
-        }
-        catch (error) {
-            pending?.reject(error);
-            return;
-        }
-        pending?.resolve(value);
-    }
-    #onState(frame) {
-        const relay = this.relayedRefs.get(frame.hold);
-        if (relay !== undefined) {
-            relay.state(frame);
-            return;
-        }
-        const binding = this.remotes.get(frame.hold);
-        if (binding === undefined)
-            return;
-        if (!(frame.value instanceof Packed)) {
-            binding.state(frame.m, frame);
-            return;
-        }
-        let value;
-        try {
-            value = unpack(frame.value);
-        }
-        catch (error) {
-            binding.state(frame.m, { as: "error", error: toWireError(error) });
-            return;
-        }
-        binding.state(frame.m, { ...frame, value });
-    }
-    // ─── lifetime ───
-    #closed(reason) {
-        const told = /^protocol-version (\d+)$/.exec(reason);
-        if (told !== null && Number(told[1]) !== PROTOCOL_VERSION)
-            this.#protocolMismatch(Number(told[1]), false);
-        if (this.#pinger !== undefined)
-            clearInterval(this.#pinger);
-        if (this.#ackTimer !== undefined)
-            clearTimeout(this.#ackTimer);
-        this.#pending.clear();
-        this.#pendingBytes = 0;
-        const error = unavailable(`link to ${this.name ?? "peer"} closed: ${reason}`);
-        // As origin: everything the peer held here, relayed or not, is released (downstream calls cancelled).
-        for (const id of [...this.served.keys()])
-            this.#dropServed(id, true);
-        for (const controller of this.incoming.values())
-            controller.abort(error);
-        this.incoming.clear();
-        for (const pending of this.calls.values())
-            pending.reject(error);
-        this.calls.clear();
-        for (const vote of this.votes.values())
-            vote.reject(error);
-        this.votes.clear();
-        for (const waiter of this.#syncWaiters)
-            waiter.reject(error);
-        this.#syncWaiters.clear();
-        // As downstream of relays: their origins lose the hold.
-        for (const relay of [...this.relayedRefs.values()])
-            relay.close(error, { releaseDown: false, notify: true });
-        this.relayedRefs.clear();
-        this.relayedCalls.clear();
-        const bindings = [...this.remotes.values()];
-        this.remotes.clear();
-        for (const binding of bindings) {
-            // An upstream link may be replaced (reconnect); a downstream host that went away is gone.
-            if (this.role === "upstream")
-                binding.detached();
-            else
-                binding.gone(error);
-        }
-        this.host.connectionClosed(this);
-    }
-}
-const stateKey = (hold, m) => `s${hold}\u0000${m}`;
-const unitKey = (hold) => `u${hold}`;
-/**
- * A call through a relay: waits for the route, then forwards with the root it runs in. It settles exactly once; a
- * cancel (or the origin going away) is forwarded downstream and removes both mappings.
- */
-async function relayCall(relay, frame, root, signal, host) {
-    const abortError = () => new ChordError("aborted", "call cancelled", { cause: signal.reason });
-    if (signal.aborted)
-        throw abortError();
-    let onAbort = () => { };
-    let onCancel = () => { };
-    const aborted = new Promise((_, reject) => {
-        onAbort = () => reject(abortError());
-        signal.addEventListener("abort", onAbort, { once: true });
-    });
-    aborted.catch(() => { });
-    try {
-        const down = await Promise.race([relay.ready(), aborted]);
-        if (relay.closed)
-            throw new ChordError("gone", "relayed hold closed");
-        return await new Promise((resolve, reject) => {
-            const call = new RelayCall(relay, frame.id, down.nextId(), { resolve, reject });
-            onCancel = () => call.cancel(abortError(), true);
-            signal.addEventListener("abort", onCancel, { once: true });
-            host.rootSent(root.rootId, down);
-            down.send({ t: "call", id: call.downId, hold: relay.downId, member: frame.member, args: frame.args, root });
-        });
-    }
-    finally {
-        signal.removeEventListener("abort", onAbort);
-        signal.removeEventListener("abort", onCancel);
-    }
-}
-/**
- * Validates a snapshot against the schema the consumer is promised: the provider's own schema for a direct binding,
- * the consumer's contract for one through an `accepts` adapter (the adapter's view is what the consumer gets).
- */
-function validateSnapshot(ref, member, value) {
-    if (value === undefined)
-        return;
-    const installed = ref.object.currentInstalled();
-    if (installed === undefined)
-        return;
-    const view = ref.currentView();
-    const variant = view === undefined ? variantOf(installed.implementation) : variantOf(view);
-    const description = view !== undefined && view !== installed.implementation
-        ? ref.contract.description.variants[variant ?? LOCAL_VARIANT]?.[member]
-        : installed.service.contract.description.variants[variantOf(installed.implementation) ?? LOCAL_VARIANT]?.[member];
-    if (description?.kind === "state")
-        assertValid("state", `${ref.address}.${member}`, description.schema, value);
-}
-/** Clients (browsers) holding an outdated contract are told to reload their code. */
-function clientError(error) {
-    if (error instanceof ChordError && error.code === "contract_mismatch") {
-        return new ChordError("upgrade_required", error.message, { cause: error });
-    }
-    return error;
-}
-//# sourceMappingURL=connection.js.map