import { contractFromDescription, LOCAL_VARIANT, resolveHost } from "./contract.ts";
import { type Encoder, encoder } from "./delta/index.ts";
import { ChordError, invalid } from "./errors.ts";
import type { HostImpl } from "./host.ts";
import { type Link, Packed, unpack } from "./link.ts";
import { type CtxImpl, RefImpl, variantOf } from "./object.ts";
import type { RemoteBinding, RemoteChannel } from "./remote.ts";
import { assertValid } from "./schema.ts";
import type { Ctx, Readable, Shape, StateEvent } from "./types.ts";
import { type Frame, fromWireError, isFrame, PROTOCOL_VERSION, type RootRef, toWireError } from "./wire.ts";

export interface LinkOptions {
	/** Milliseconds between pings (default 15000). */
	readonly pingInterval?: number;
	/** Close the link when nothing arrived for this long (default 45000). Everything held through it is released. */
	readonly pingTimeout?: number;
	/**
	 * Unacknowledged frame bytes (JSON text length) beyond which state frames wait for the peer (default 256 KiB). Only
	 * applies when both ends acknowledge frames and the link reports sizes; `Infinity` never holds state back.
	 */
	readonly window?: number;
	/**
	 * Bytes of state ops that may wait for the peer on this link (default 4 windows). Beyond, the oldest waiting streams
	 * are replaced by their current value (a reset), so memory stays bounded however long the peer stalls.
	 */
	readonly pendingCap?: number;
	/**
	 * The peer speaks another link protocol version (`peer`: undefined if it did not say): the link closes, and should
	 * not be reconnected with the same code. A browser reloads its page, for instance.
	 */
	readonly onProtocolMismatch?: (versions: { readonly local: number; readonly peer: number | undefined }) => void;
}

const DEFAULT_WINDOW = 256 * 1024;
/** The default cap of waiting state ops per link, in windows. */
const PENDING_WINDOWS = 4;

type StateFrame = Extract<Frame, { t: "state" }>;

/**
 * How a waiting stream recovers when its ops must be dropped: the provider resends the current value as a reset at
 * flush; a relay (which has no value) asks downstream for one.
 */
type Overflow = { readonly resend: () => void } | { readonly resync: () => void };

/**
 * What waits on a link. A unit slot is lazy: the shape and snapshots are built from the current values when it is sent.
 * A state slot keeps a snapshot, reset or error (`base`) and encoded ops to apply after it, in order (as they arrived;
 * the receiving decoder validates them), or, once `lazy`, only the promise of a reset built at flush.
 */
type Slot =
	| { readonly kind: "unit"; readonly hold: number; readonly flush: () => void }
	| {
			readonly kind: "state";
			readonly hold: number;
			readonly m: string;
			base: StateFrame | undefined;
			ops: (readonly unknown[])[];
			size: number;
			lazy: boolean;
			readonly overflow: Overflow;
	  };

export interface AcceptOptions<P = unknown> extends LinkOptions {
	/** The principal of whatever connects, from the app's authenticator. Every request on the link acts as it. */
	readonly principal: P;
	/**
	 * What the peer is, decided here and never by its `hello`: `client` (default; a browser: no roots, no code versions,
	 * not a reload participant, not addressable) or `host` (a child host; needs `name`).
	 */
	readonly kind?: "host" | "client";
	/** A child host's name: its hello must match, and it is reachable `at` this name. */
	readonly name?: string;
	/** On `invalidatePrincipal`: a new principal keeps the link, `undefined` closes it (default: close). */
	restamp?(principal: P): P | undefined;
	/**
	 * Calls the peer may have in progress on this link (default: no limit). Further ones never run: they are answered
	 * at once with `unavailable` (reason `too_many_calls`), and the link stays open.
	 */
	readonly maxCalls?: number;
}

export interface Peer {
	readonly kind: "host" | "client";
	/** Configured (downstream hosts) or announced by the trusted parent (upstream). */
	readonly name: string | undefined;
}

/** A state member's stream to the consumer: its subscription and delta encoder. */
interface Feed {
	unsubscribe: () => void;
	encoder: Encoder;
	/** Events that arrived while a unit or reset was being built (replayed after it is sent). */
	buffer: StateEvent<unknown>[] | undefined;
}

/** A hold the peer made on this host and serves locally. */
interface ServedLocal {
	readonly kind: "local";
	readonly id: number;
	readonly ref: RefImpl;
	readonly principal: unknown;
	/** The client connection it comes from (see `Frame` hold `origin`); undefined for a host's own holds. */
	readonly origin: string | undefined;
	/** The consumer wants state (hold without `state: false`, or `sub`). */
	wantsState: boolean;
	/** The consumer had values before (re-hold): its first unit waits for the window like any other. */
	readonly again: boolean;
	/** A unit was sent. */
	unitSent: boolean;
	/** The members whose snapshot the consumer has, with their streams. */
	readonly feeds: Map<string, Feed>;
}

/** A hold the peer made on this host: served locally or relayed to another link. */
type Served = ServedLocal | { readonly kind: "relay"; readonly relay: RelayRef };

type Pending = { readonly resolve: (value: unknown) => void; readonly reject: (error: unknown) => void };

const unavailable = (message: string): ChordError => 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 {
	readonly origin: Connection;
	readonly frame: Extract<Frame, { t: "hold" }>;
	readonly principal: unknown;
	/** The client connection the hold comes from (forwarded downstream); undefined for a host's own holds. */
	readonly originTag: string | undefined;
	/** The origin's authorization generation when the hold arrived; a revocation bumps it. */
	readonly generation: number;
	down: Connection | undefined;
	downId = 0;
	closed = false;
	/** The origin wants state (forwarded as `state: false`, `sub`, `unsub`). */
	stateWanted: boolean;
	/** The members of the first unit, still to forward past the origin's window. */
	urgent: Set<string> | undefined;
	#shaped = false;
	/** Members whose ops this relay dropped: downstream ops are ignored until their reset arrives. */
	readonly awaiting = new Set<string>();
	readonly calls = new Map<number, RelayCall>();
	readonly #waiters = new Set<Pending>();

	constructor(
		origin: Connection,
		frame: Extract<Frame, { t: "hold" }>,
		principal: unknown,
		originTag: string | undefined,
	) {
		this.origin = origin;
		this.frame = frame;
		this.principal = principal;
		this.originTag = originTag;
		this.stateWanted = frame.state !== false;
		this.generation = origin.generation;
	}

	get originId(): number {
		return this.frame.id;
	}

	get client(): boolean {
		return this.originTag !== undefined;
	}

	/** Still authorized as it was when it arrived. */
	get current(): boolean {
		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(): Promise<Connection> {
		if (this.closed) return Promise.reject(new ChordError("gone", "relayed hold closed"));
		if (this.down !== undefined) return Promise.resolve(this.down);
		return new Promise<Connection>((resolve, reject) => {
			this.#waiters.add({ resolve: resolve as (value: unknown) => void, reject });
		});
	}

	/** Forwards the hold to `down`. */
	open(down: Connection): void {
		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 as const }),
			...(this.frame.again === true ? { again: true as const } : {}),
		});
		for (const waiter of this.#waiters) waiter.resolve(down);
		this.#waiters.clear();
	}

	/** The origin starts or stops the hold's state. */
	wantState(wanted: boolean): void {
		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: string): void {
		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: Extract<Frame, { t: "shape" }>): void {
		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: StateFrame): void {
		if (this.closed) return;
		const m = frame.m;
		if (this.awaiting.has(m)) {
			if (frame.as === "ops") return;
			this.awaiting.delete(m);
		}
		const out: StateFrame = { ...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: unknown, options: { readonly releaseDown: boolean; readonly notify: boolean }): void {
		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 {
	readonly relay: RelayRef;
	readonly originId: number;
	readonly downId: number;
	readonly #pending: Pending;
	#settled = false;

	constructor(relay: RelayRef, originId: number, downId: number, pending: 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: unknown, value?: unknown): void {
		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: unknown, forward: boolean): void {
		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 implements RemoteChannel {
	readonly host: HostImpl;
	readonly link: Link;
	/** `upstream`: the link to this host's parent. `downstream`: a link this host accepted. */
	readonly role: "upstream" | "downstream";
	readonly peer: Peer;
	/** A client connection's opaque id: holds that come over it (directly or relayed) carry it as their `origin`. */
	readonly originId: string | undefined;
	principal: unknown;
	readonly restamp: ((principal: unknown) => unknown | undefined) | undefined;
	/** 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: number | undefined;
	/** A downstream host peer is usable once it runs this host's current code version (see `HostImpl.peerHello`). */
	synced: boolean;
	/** Code versions this child announced while behind this host (fenced): this host never ran them. */
	readonly fencedCodeVersions = new Set<number>();
	/** Roots of fenced code versions, by the code version of this host they were admitted in. */
	readonly #admitted = new Map<string, number>();
	#parentName: string | undefined;
	readonly #syncWaiters = new Set<Pending>();
	#nextId = 1;
	#lastSeen = Date.now();
	#pinger: ReturnType<typeof setInterval> | undefined;
	readonly #maxCalls: number;
	// flow control (see the class comment)
	readonly #window: number;
	readonly #pendingCap: number;
	/** Whether the peer acknowledges frames; until its hello is here, frames are counted in case it does. */
	#peerAcks: boolean | undefined;
	#sent = 0;
	#acked = 0;
	/** Sizes of the frames sent after the last acknowledged one. */
	#unacked: number[] = [];
	#unackedBytes = 0;
	readonly #pending = new Map<string, Slot>();
	/** Bytes of ops waiting in `#pending`. */
	#pendingBytes = 0;
	#received = 0;
	#ackTimer: ReturnType<typeof setTimeout> | undefined;
	readonly #onProtocolMismatch: LinkOptions["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
	readonly remotes = new Map<number, RemoteBinding>();
	readonly calls = new Map<number, Pending>();
	// provider side: what the peer asked of this host
	readonly served = new Map<number, Served>();
	readonly incoming = new Map<number, AbortController>();
	// downstream side of relays: ids this host used on this link
	readonly relayedRefs = new Map<number, RelayRef>();
	readonly relayedCalls = new Map<number, RelayCall>();
	/** Reload votes awaited from this (child) peer. */
	readonly votes = new Map<number, Pending>();

	constructor(
		host: HostImpl,
		link: Link,
		config: {
			readonly role: "upstream" | "downstream";
			readonly principal: unknown;
			readonly peer: Peer;
			readonly originId?: string;
			readonly restamp?: (principal: unknown) => unknown | undefined;
			readonly maxCalls?: number;
		} & LinkOptions,
	) {
		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(): boolean {
		return !this.link.closed;
	}

	/** The peer's name: configured for downstream hosts, announced by the parent upstream. */
	get name(): string | undefined {
		return this.role === "upstream" ? this.#parentName : this.peer.name;
	}

	send(frame: Frame): void {
		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: StateFrame, overflow: Overflow): void {
		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: number, current: Extract<Slot, { kind: "state" }>): void {
		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: Extract<Slot, { kind: "state" }>): void {
		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: number, m: string, resend: () => void): void {
		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: number, flush: () => void): void {
		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: number, m: string): void {
		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: number): void {
		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(): { readonly slots: number; readonly bytes: number } {
		return { slots: this.#pending.size, bytes: this.#pendingBytes };
	}

	get #full(): boolean {
		return this.#peerAcks === true && this.#unackedBytes >= this.#window;
	}

	#onAck(n: number): void {
		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(): void {
		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(): void {
		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(): number {
		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(): Promise<void> {
		if (!this.open) return Promise.reject(unavailable(`link to ${this.name ?? "peer"} closed`));
		if (this.synced) return Promise.resolve();
		return new Promise<void>((resolve, reject) => this.#syncWaiters.add({ resolve: resolve as () => void, reject }));
	}

	markSynced(codeVersion: number): void {
		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: unknown | undefined): void {
		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: number | undefined, close = true): void {
		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: string): void {
		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: RemoteBinding, again: boolean): number {
		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 as const }),
			...(again ? { again: true as const } : {}),
		});
		return id;
	}

	release(id: number): void {
		this.remotes.delete(id);
		this.send({ t: "release", id });
	}

	wantState(hold: number, wanted: boolean): void {
		if (this.remotes.has(hold)) this.send({ t: wanted ? "sub" : "unsub", hold });
	}

	call(hold: number, member: string, args: unknown, root: RootRef | undefined, signal: AbortSignal): Promise<unknown> {
		const id = this.nextId();
		return new Promise<unknown>((resolve, reject) => {
			if (signal.aborted) {
				reject(new ChordError("aborted", "call aborted"));
				return;
			}
			const onAbort = (): void => {
				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 = (): void => 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: unknown): void {
		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: Frame): void {
		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: unknown) => 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: Extract<Frame, { t: "hello" }>): void {
		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: { readonly principal?: unknown }): unknown {
		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: { readonly origin?: string }): string | undefined {
		return this.role === "downstream" ? this.originId : frame.origin;
	}

	#onHold(frame: Extract<Frame, { t: "hold" }>): void {
		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: unknown) => relay.close(error, { releaseDown: true, notify: true }));
			return;
		}
		let ref: RefImpl;
		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: ServedLocal = {
			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: RefImpl, shape: Shape): string[] {
		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: ServedLocal): void {
		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: ServedLocal): void {
		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: StateFrame[] = [];
		const attached: (readonly [string, Feed])[] = [];
		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: ServedLocal,
		name: string,
		as: "snap" | "reset" = "snap",
	): { readonly frame: StateFrame; readonly feed: Feed } | undefined {
		const readable = served.ref.member(name) as Readable<unknown> | undefined;
		if (readable === undefined || typeof readable.events !== "function") return undefined;
		const feed: Feed = { unsubscribe: () => {}, encoder: encoder(), buffer: [] };
		let first: StateEvent<unknown> | undefined;
		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: ServedLocal, name: string, feed: Feed): void {
		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: ServedLocal, name: string, as: "snap" | "reset", value: unknown): StateFrame {
		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: ServedLocal, name: string, feed: Feed, event: StateEvent<unknown>): void {
		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: ServedLocal, name: string): void {
		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: number, wanted: boolean): void {
		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: number, m: string): void {
		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: number, release: boolean): void {
		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: Extract<Frame, { t: "call" }>): void {
		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: Ctx) => served.ref.object.call(served.ref, frame.member, unpack(frame.args), ctx as CtxImpl)
				: (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: unknown) => 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: RootRef | undefined): RootRef | undefined {
		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: Extract<Frame, { t: "shape" | "gone" }>): void {
		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: Extract<Frame, { t: "result" }>): void {
		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: unknown;
		try {
			value = unpack(frame.value);
		} catch (error) {
			pending?.reject(error);
			return;
		}
		pending?.resolve(value);
	}

	#onState(frame: StateFrame): void {
		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: unknown;
		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: string): void {
		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: number, m: string): string => `s${hold}\u0000${m}`;
const unitKey = (hold: number): string => `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: RelayRef,
	frame: Extract<Frame, { t: "call" }>,
	root: RootRef,
	signal: AbortSignal,
	host: HostImpl,
): Promise<unknown> {
	const abortError = (): ChordError => new ChordError("aborted", "call cancelled", { cause: signal.reason });
	if (signal.aborted) throw abortError();
	let onAbort = (): void => {};
	let onCancel = (): void => {};
	const aborted = new Promise<never>((_, 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<unknown>((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: RefImpl, member: string, value: unknown): void {
	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: unknown): unknown {
	if (error instanceof ChordError && error.code === "contract_mismatch") {
		return new ChordError("upgrade_required", error.message, { cause: error });
	}
	return error;
}