@earendil-works/chord 1.1.0 → 1.2.0

package/dist/host.js

@@ -0,0 +1,795 @@
+import { ChildReloads, reconcileChild, runClusterReload } from "./cluster.js";
+import { Connection } from "./connection.js";
+import { bind, } from "./contract.js";
+import { ChordError, invalid, runAll } from "./errors.js";
+import { enqueue } from "./publish.js";
+import { CtxImpl, HandleImpl, makeService, RecordImpl, } from "./record.js";
+import { runReload } from "./reload.js";
+import { RemoteHandle } from "./remote.js";
+import { canonicalIdentity, canonicalJson, deepEqual, normalize } from "./schema.js";
+/** The principal of in-host code. */
+export const hostPrincipal = Object.freeze({ host: true });
+export const defineFacet = (setup, options = {}) => ({ setup, uses: options.uses });
+const isFacet = (ref) => typeof ref === "object" && !(ref instanceof URL);
+const EMPTY_TABLE = new Map();
+export function createHost(options = {}) {
+    return new HostImpl(options);
+}
+export class HostImpl {
+    name;
+    dev;
+    principal = hostPrincipal;
+    inFactory = 0;
+    failed;
+    records = new Map();
+    epochs = new Map();
+    facets = new Map();
+    eager = new Map();
+    kind;
+    connections = new Set();
+    upstream;
+    /** Remote handles this host holds (re-held after an upstream reconnect). */
+    remotes = new Set();
+    #routes = new Map();
+    #childReloads = new ChildReloads(this);
+    /** Child facet modules by host-name prefix, from every committed cluster reload (for reconciling children). */
+    remoteModules = {};
+    /** Removal tombstones also reconcile children that connected during a transaction. */
+    remoteRemoved = {};
+    /** Highest epoch the parent has retired. */
+    #retireAllowed = 0;
+    /** Roots that came over a link, by the link they came from. */
+    /** Foreign roots (started on another host), by the links they came over. */
+    #foreign = new Map();
+    /** Roots started on this host that have not ended. */
+    #local = new Set();
+    #incarnation = Math.random().toString(36).slice(2, 8);
+    /** Links each root's calls went out on. */
+    #rootLinks = new Map();
+    current;
+    previous;
+    /** The epoch a running reload will commit; new types activated during prepare install their behavior for it. */
+    pending;
+    /** Activations of these types wait (reload gate). */
+    /** Types behind a reload gate: new records of these types are rejected `upgrade_conflict` until commit/abort. */
+    gating;
+    reloading = false;
+    retired = () => { };
+    #principalKey;
+    #onError;
+    #loader;
+    #dying = new Map();
+    #touches = new Map();
+    #order = new Map();
+    #subscribers = new Map();
+    #epochSeq = 1;
+    #rootSeq = 0;
+    constructor(options) {
+        this.name = options.name ?? "host";
+        this.dev = options.dev ?? false;
+        this.#principalKey = options.principalKey ?? canonicalJson;
+        this.#onError = options.onError ?? ((error) => console.error("chord:", error));
+        this.#loader = options.loader;
+        this.current = { id: this.#epochSeq, services: new Map(), tables: new Map(), roots: new Map() };
+        this.epochs.set(this.current.id, this.current);
+        this.kind = options.kind ?? "host";
+        if (options.upstream !== undefined)
+            this.connect(options.upstream, options.upstreamOptions);
+    }
+    get epoch() {
+        return this.current.id;
+    }
+    get previousEpoch() {
+        return this.previous?.id;
+    }
+    /** Allocates the next epoch id, or adopts one issued by the coordinating server. */
+    nextEpochId(given) {
+        if (given !== undefined && given <= this.current.id)
+            throw new Error(`epoch ${given} is not newer than ${this.current.id}`);
+        this.#epochSeq = given ?? this.#epochSeq + 1;
+        return this.#epochSeq;
+    }
+    report(error) {
+        this.#onError(error);
+    }
+    // ─── serving ───
+    serve = ((type, factory, options = {}) => {
+        if (this.reloading)
+            throw new Error("host.serve during a reload; serve from a facet passed to reload()");
+        this.serveInto(this.current.services, makeService(type, factory, options, ""));
+        if (options.eager)
+            this.startEager(this.current.services.get(type.name));
+    });
+    install(facet, options = {}) {
+        if (this.reloading)
+            throw new Error("host.install during a reload");
+        if (this.facets.has(facet.name))
+            throw new Error(`facet ${facet.name} is already installed; use reload()`);
+        const added = [];
+        facet.setup(this.facetApi(((type, factory, options = {}) => {
+            const service = makeService(type, factory, options, facet.name);
+            this.serveInto(this.current.services, service);
+            added.push(service);
+        })));
+        this.facets.set(facet.name, facet);
+        const holds = added.filter((service) => service.options.eager).map((service) => this.startEager(service));
+        return options.awaitEager === false ? Promise.resolve() : this.#eagerReady(holds);
+    }
+    async load(plugins, options = {}) {
+        const facets = await this.resolve(plugins);
+        // No await between installs: an eager factory may consume a type served by a later facet.
+        await Promise.all(facets.map((facet) => this.install(facet, options)));
+    }
+    ready() {
+        return this.#eagerReady(this.eager.values());
+    }
+    #eagerReady(holds) {
+        const ready = Promise.all([...holds].map((hold) => hold.ready)).then(() => { });
+        // Ignoring install's return still reports through onError without an unhandled rejection.
+        ready.catch(() => { });
+        return ready;
+    }
+    /** Turns plugin references into facets, importing modules through the loader. */
+    async resolve(plugins) {
+        const modules = plugins.filter((ref) => !isFacet(ref));
+        if (modules.length > 0 && this.#loader === undefined) {
+            throw new Error("loading modules needs createHost({ loader }), e.g. nodeLoader from @earendil-works/chord/node");
+        }
+        const loaded = modules.length > 0 && this.#loader !== undefined ? await this.#loader(modules) : [];
+        return plugins.map((ref) => (isFacet(ref) ? ref : loaded.shift()));
+    }
+    facetApi(serve) {
+        return {
+            serve,
+            name: this.name,
+            root: (fn, options) => this.root(fn, options),
+            registry: (registry) => this.registry(registry),
+        };
+    }
+    serveInto(services, service) {
+        if (services.has(service.contract.name))
+            throw new Error(`${service.contract.name} is already served`);
+        services.set(service.contract.name, service);
+    }
+    startEager(service) {
+        const eager = service.options.eager;
+        const input = typeof eager === "object" ? eager.input : {};
+        const handle = this.acquire(service.contract, input, undefined, "host");
+        this.eager.set(service.contract.name, handle);
+        handle.ready.catch((error) => this.report(error));
+        return handle;
+    }
+    // ─── HostCore ───
+    currentEpoch() {
+        return this.current.id;
+    }
+    hasEpoch(epoch) {
+        return this.epochs.has(epoch);
+    }
+    *retainedEpochs() {
+        for (const [id, state] of this.epochs)
+            yield [id, state.services];
+        if (this.pending !== undefined)
+            yield [this.pending.id, this.pending.services];
+    }
+    pendingEpoch() {
+        return this.pending?.id;
+    }
+    /** The current code for a type; a type a running reload adds is served from the pending epoch. */
+    service(typeName) {
+        return this.current.services.get(typeName) ?? this.pending?.services.get(typeName);
+    }
+    addressOf(type, input, principal, at, candidate = false) {
+        if (at !== undefined && at !== this.name)
+            return remoteAddress(at, type, input, principal === this.principal ? undefined : principal);
+        const service = this.#bindingService(type.name, candidate);
+        if (service === undefined)
+            throw unknownType(type.name, this.name);
+        const normalized = normalize(service.contract.input, input, `${type.name} input`);
+        return this.#address(service, normalized, principal);
+    }
+    #address(service, normalized, principal) {
+        const key = principal === this.principal ? "host" : `p:${this.#principalKey(principal)}`;
+        return `${service.contract.name}\u0000${canonicalIdentity(service.contract.input, normalized)}\u0000${key}`;
+    }
+    acquire(type, input, options, owner, from, candidate = false) {
+        if (options?.at !== undefined && options.at !== this.name)
+            return this.#acquireRemote(type, input, options, owner);
+        const service = this.#bindingService(type.name, candidate);
+        if (service === undefined)
+            throw unknownType(type.name, this.name);
+        bind(service.contract, service.options.accepts, type);
+        const principal = options?.principal ?? this.principal;
+        const normalized = normalize(service.contract.input, input, `${type.name} input`);
+        const address = this.#address(service, normalized, principal);
+        let record = this.records.get(address);
+        if (from !== undefined && record !== undefined && (record === from || reaches(record, from))) {
+            throw invalid("cycle", `${from.address} -> ${address} would create a hold cycle`);
+        }
+        if (record === undefined) {
+            if (this.gating?.has(type.name)) {
+                throw new ChordError("upgrade_conflict", `${type.name} is being upgraded; retry`, { reason: "gate" });
+            }
+            const dying = this.#dying.get(address);
+            if (dying?.status === "disposed")
+                this.#dying.delete(address);
+            record = new RecordImpl(this, {
+                address,
+                typeName: type.name,
+                input: normalized,
+                principal,
+                eager: service.options.eager !== undefined && service.options.eager !== false && principal === this.principal,
+            });
+            this.records.set(address, record);
+            // A new record for an address still being disposed waits for that cleanup (exclusive resources).
+            record.start(dying?.status === "disposing" ? dying.dispose(false) : undefined);
+        }
+        const handle = new HandleImpl(record, type, owner);
+        record.addHold(handle);
+        return handle;
+    }
+    forget(record) {
+        if (this.records.get(record.address) === record)
+            this.records.delete(record.address);
+        if (record.status === "disposing")
+            this.#dying.set(record.address, record);
+    }
+    touch(rootId, record) {
+        let touched = this.#touches.get(rootId);
+        if (touched === undefined) {
+            touched = new Set();
+            this.#touches.set(rootId, touched);
+        }
+        touched.add(record);
+    }
+    // ─── roots ───
+    async root(fn, options = {}) {
+        // The incarnation keeps root ids unique across restarts of a host with the same name.
+        const rootId = `${this.name}#${this.#incarnation}:${++this.#rootSeq}`;
+        this.#local.add(rootId);
+        return this.joinRoot(rootId, options.epoch ?? this.current.id, fn, options);
+    }
+    /**
+     * Runs `fn` inside root `rootId` of `epoch`. A root counts as running here (for retirement) while any of its calls
+     * runs here. A root that started here ends when its last call here settles, even if it went out and came back
+     * over a link meanwhile. A foreign root (started elsewhere, arriving `from` a link) keeps its leases on records
+     * until every link it came over announced its end (`root_end`) or closed, so its re-entry stays grandfathered.
+     */
+    async joinRoot(rootId, epochId, fn, options = {}) {
+        const epoch = this.epochs.get(epochId);
+        if (epoch === undefined) {
+            this.#local.delete(rootId);
+            throw new ChordError("superseded", `epoch ${epochId} is not retained by ${this.name}`);
+        }
+        if (options.from !== undefined && !this.#local.has(rootId)) {
+            let links = this.#foreign.get(rootId);
+            if (links === undefined) {
+                links = new Set();
+                this.#foreign.set(rootId, links);
+            }
+            links.add(options.from);
+        }
+        epoch.roots.set(rootId, (epoch.roots.get(rootId) ?? 0) + 1);
+        const ctx = new CtxImpl(this, {
+            signal: options.signal ?? new AbortController().signal,
+            rootId,
+            epoch: epoch.id,
+            principal: options.principal ?? this.principal,
+        });
+        try {
+            return await fn(ctx);
+        }
+        finally {
+            ctx.close();
+            const count = (epoch.roots.get(rootId) ?? 1) - 1;
+            if (count > 0)
+                epoch.roots.set(rootId, count);
+            else {
+                epoch.roots.delete(rootId);
+                if (!this.#foreign.has(rootId))
+                    this.endRoot(rootId);
+                this.maybeRetire();
+            }
+        }
+    }
+    /** Remembers that calls of `rootId` went out on `connection`, which must hear when the root ends. */
+    rootSent(rootId, connection) {
+        let links = this.#rootLinks.get(rootId);
+        if (links === undefined) {
+            links = new Set();
+            this.#rootLinks.set(rootId, links);
+        }
+        links.add(connection);
+    }
+    /** A root ended (here, or announced by its origin): end its leases and tell the links it went out on. */
+    endRoot(rootId) {
+        this.#local.delete(rootId);
+        this.#foreign.delete(rootId);
+        for (const record of this.#touches.get(rootId) ?? [])
+            record.rootEnded(rootId);
+        this.#touches.delete(rootId);
+        for (const connection of this.#rootLinks.get(rootId) ?? [])
+            connection.send({ t: "root_end", rootId });
+        this.#rootLinks.delete(rootId);
+    }
+    /**
+     * `from` announced the end of a foreign root (or closed). Honored only if the root came over `from`: a peer cannot
+     * end leases of roots it never carried. The root ends when no link that brought it remains.
+     */
+    foreignRootEnded(rootId, from) {
+        const links = this.#foreign.get(rootId);
+        if (links === undefined || !links.delete(from) || links.size > 0)
+            return;
+        const running = [...this.epochs.values()].some((epoch) => epoch.roots.has(rootId));
+        // Still running here (a call in flight): the lease ends when it settles.
+        if (running)
+            this.#foreign.delete(rootId);
+        else
+            this.endRoot(rootId);
+    }
+    /**
+     * Retires the previous epoch once no local roots of it remain. A child also waits for its parent to retire it:
+     * roots span hosts, and an old root on the server may still call in.
+     */
+    maybeRetire() {
+        const previous = this.previous;
+        if (previous === undefined || previous.roots.size > 0)
+            return;
+        if (this.kind !== "client" && this.upstream !== undefined && previous.id > this.#retireAllowed)
+            return;
+        this.retire();
+    }
+    allowRetire(epoch) {
+        this.#retireAllowed = Math.max(this.#retireAllowed, epoch);
+        this.maybeRetire();
+    }
+    /** Drops the previous epoch: its behaviors and the declarations only it used. */
+    retire() {
+        const previous = this.previous;
+        if (previous === undefined)
+            return;
+        this.previous = undefined;
+        this.epochs.delete(previous.id);
+        for (const record of [...this.records.values()])
+            this.retireBehavior(record, previous.id);
+        for (const connection of this.connections) {
+            if (connection.role === "downstream" && connection.peer?.kind === "host")
+                connection.send({ t: "retire", epoch: previous.id });
+        }
+        this.retired();
+    }
+    /**
+     * Drops a record's behavior for `epoch` and what only that behavior declared, in disposal order: resources close
+     * (reverse open order) before its holds are released.
+     */
+    retireBehavior(record, epoch) {
+        const installed = record.behaviors.get(epoch);
+        record.behaviors.delete(epoch);
+        if (installed === undefined || installed.decls === record.decls)
+            return;
+        const kept = record.allDecls();
+        const keep = (pick) => new Set([...kept].flatMap((decls) => [...pick(decls)]));
+        const holds = keep((decls) => decls.holds.values());
+        const resources = keep((decls) => decls.resources.values());
+        const derives = keep((decls) => decls.derives.values());
+        for (const derived of installed.decls.derives.values())
+            if (!derives.has(derived))
+                derived.detach();
+        const closing = [...installed.decls.resources.values()]
+            .filter((resource) => !resources.has(resource))
+            .sort((a, b) => record.openOrder.indexOf(b) - record.openOrder.indexOf(a));
+        const releasing = [...installed.decls.holds.values()].filter((hold) => !holds.has(hold));
+        record.refreshSchemas();
+        runAll([
+            ...closing.map((resource) => () => resource.close(record.openOrder)),
+            ...releasing.map((hold) => () => hold.release()),
+        ], `${record.address}: retiring epoch ${epoch} failed`).catch((error) => this.report(error));
+    }
+    // ─── registries ───
+    registry(registry) {
+        const table = (ctx) => {
+            const epoch = ctx === undefined ? this.current : this.epochs.get(ctx.epoch);
+            if (epoch === undefined)
+                throw new ChordError("superseded", `epoch ${ctx?.epoch} is retired`);
+            return (epoch.tables.get(registry.name) ?? EMPTY_TABLE);
+        };
+        return {
+            table,
+            get: (key, ctx) => table(ctx).get(key),
+            subscribe: (listener) => {
+                let set = this.#subscribers.get(registry.name);
+                if (set === undefined) {
+                    set = new Set();
+                    this.#subscribers.set(registry.name, set);
+                }
+                const wrapped = listener;
+                set.add(wrapped);
+                wrapped(table(), this.current.id);
+                return () => set.delete(wrapped);
+            },
+        };
+    }
+    /** Builds registry tables from (record, declarations) pairs. Throws registry_conflict. */
+    buildTables(entries) {
+        const byRegistry = new Map();
+        for (const [record, decls] of entries) {
+            for (const { registry, key, value } of decls.registrations.values()) {
+                let entries = byRegistry.get(registry.name);
+                if (entries === undefined) {
+                    entries = new Map();
+                    byRegistry.set(registry.name, entries);
+                }
+                const existing = entries.get(key);
+                if (existing !== undefined && existing.record !== record && registry.conflict === "error") {
+                    throw invalid("registry_conflict", `${registry.name}: ${key} registered by ${existing.record.address} and ${record.address}`);
+                }
+                entries.set(key, { value, record });
+                let order = this.#order.get(registry.name);
+                if (order === undefined) {
+                    order = new Map();
+                    this.#order.set(registry.name, order);
+                }
+                if (!order.has(key))
+                    order.set(key, order.size);
+            }
+        }
+        const tables = new Map();
+        for (const [name, entries] of byRegistry) {
+            const order = this.#order.get(name);
+            const sorted = [...entries].sort(([a], [b]) => order.get(a) - order.get(b));
+            tables.set(name, new Map(sorted.map(([key, entry]) => [key, entry.value])));
+        }
+        return tables;
+    }
+    /**
+     * The service a hold binds against: the current one, or for a prepare rerun (`candidate`) the running reload's
+     * pending one, so consumer and provider of a breaking change can reload in one batch.
+     */
+    #bindingService(typeName, candidate) {
+        return (candidate ? this.pending?.services.get(typeName) : undefined) ?? this.service(typeName);
+    }
+    /** Live records with their current declarations; records waiting for a reload's commit only with `candidates`. */
+    liveDecls(candidates = false) {
+        return [...this.records.values()]
+            .filter((record) => record.status === "live" && (candidates || !record.deferredRuntime))
+            .map((record) => [record, record.decls]);
+    }
+    checkRegistrations(record, decls) {
+        if (decls.registrations.size === 0)
+            return;
+        this.buildTables([...this.liveDecls().filter(([other]) => other !== record), [record, decls]]);
+    }
+    registriesChanged(including) {
+        const entries = this.liveDecls().filter(([record]) => record !== including);
+        if (including !== undefined)
+            entries.push([including, including.decls]);
+        this.installTables(this.current, this.buildTables(entries));
+    }
+    /** A commit failed midway: from now on this host admits no work (calls fail `unavailable/host_failed`). */
+    fail(error) {
+        this.failed ??= error;
+        this.report(error);
+    }
+    /** Installs tables for `epoch`; subscribers hear about changed tables of the current epoch (all tables when `all`). */
+    installTables(epoch, tables, all = false) {
+        const before = epoch.tables;
+        epoch.tables = tables;
+        if (epoch !== this.current)
+            return;
+        for (const [name, listeners] of this.#subscribers) {
+            const next = tables.get(name) ?? EMPTY_TABLE;
+            if (!all && sameTable(before.get(name) ?? EMPTY_TABLE, next))
+                continue;
+            const current = [...listeners];
+            enqueue(() => {
+                for (const listener of current) {
+                    try {
+                        listener(next, epoch.id);
+                    }
+                    catch (error) {
+                        this.report(error);
+                    }
+                }
+            });
+        }
+    }
+    // ─── public API ───
+    get(type, input, options) {
+        return this.acquire(type, input, options, "external").proxy;
+    }
+    async invalidatePrincipal(match) {
+        const matches = typeof match === "function" ? match : (principal) => matchesPattern(match, principal);
+        const reason = new ChordError("gone", "principal invalidated");
+        // Links acting as a matching principal are re-stamped (if the acceptor can) or closed.
+        for (const connection of [...this.connections]) {
+            if (connection.role !== "downstream" || !matches(connection.principal))
+                continue;
+            // Relays under the old principal close at once, including those still resolving their route.
+            connection.revoke(connection.restamp?.(connection.principal));
+        }
+        // Patterns propagate to child hosts, which dispose their own matching records (e.g. relayed guests).
+        if (typeof match !== "function") {
+            for (const connection of this.connections) {
+                if (connection.role === "downstream" && connection.peer.kind === "host") {
+                    connection.send({ t: "invalidate", pattern: match });
+                }
+            }
+        }
+        const matching = [...this.records.values()].filter((record) => record.principal !== this.principal && matches(record.principal));
+        await disposeHoldersFirst(matching, reason, "invalidatePrincipal: disposal failed");
+    }
+    // ─── links ───
+    accept(link, options) {
+        const kind = options.kind ?? "client";
+        if (kind === "host" && options.name === undefined)
+            throw new TypeError("accepting a host link needs its name");
+        this.#addConnection(link, {
+            ...options,
+            role: "downstream",
+            principal: options.principal,
+            peer: { kind, name: kind === "host" ? options.name : undefined },
+        });
+    }
+    connect(link, options = {}) {
+        if (this.upstream?.open)
+            this.upstream.link.close("replaced");
+        const connection = this.#addConnection(link, {
+            ...options,
+            role: "upstream",
+            principal: undefined,
+            peer: { kind: "host", name: undefined },
+        });
+        this.upstream = connection;
+        // Remote handles that lost their link re-hold over the new one; state subscribers get a reset.
+        for (const handle of this.remotes)
+            if (handle.binding === undefined)
+                connection.hold(handle);
+    }
+    #addConnection(link, config) {
+        const connection = new Connection(this, link, config);
+        this.connections.add(connection);
+        return connection;
+    }
+    route(prefix, route) {
+        this.#routes.set(prefix, route);
+    }
+    /**
+     * A child host announced its epoch. In step: usable. Behind: fenced (nothing is routed to it) and reconciled by a
+     * reload of its modules to this host's epoch, never by renumbering what it runs. Ahead: impossible, refused.
+     */
+    peerHello(connection, epoch) {
+        if (epoch === this.current.id) {
+            connection.markSynced(epoch);
+            return;
+        }
+        if (epoch > this.current.id) {
+            this.report(new ChordError("invalid", `${connection.name} runs epoch ${epoch}, ahead of ${this.current.id}`));
+            connection.link.close("epoch ahead of parent");
+            return;
+        }
+        connection.peerEpoch = epoch;
+        connection.fencedEpochs.add(epoch);
+        reconcileChild(this, connection).catch((error) => {
+            this.report(error);
+            connection.link.close("reconciliation failed");
+        });
+    }
+    connectionClosed(connection) {
+        this.connections.delete(connection);
+        // Foreign roots that came over this link will never announce their end over it.
+        for (const [rootId, links] of [...this.#foreign])
+            if (links.has(connection))
+                this.foreignRootEnded(rootId, connection);
+        for (const links of this.#rootLinks.values())
+            links.delete(connection);
+        if (this.upstream === connection) {
+            this.upstream = undefined;
+            this.#childReloads.parentLost();
+        }
+    }
+    forgetRemote(handle) {
+        this.remotes.delete(handle);
+    }
+    /** A downstream host connection by its configured name (never by what a peer announced). */
+    #childNamed(name) {
+        return [...this.connections].find((connection) => connection.role === "downstream" && connection.peer.kind === "host" && connection.peer.name === name);
+    }
+    #acquireRemote(type, input, options, owner) {
+        const at = options.at;
+        if (type.scope !== "remote")
+            throw invalid("local", `${type.name} is local and cannot be reached at ${at}`);
+        const principal = options.principal === undefined || options.principal === this.principal ? undefined : options.principal;
+        const handle = new RemoteHandle(this, {
+            contract: type,
+            at,
+            input,
+            principal,
+            owner,
+            address: remoteAddress(at, type, input, principal),
+        });
+        this.remotes.add(handle);
+        const bindWhenSynced = (connection) => {
+            connection.then((target) => {
+                if (handle.status === "loading" && handle.binding === undefined)
+                    target.hold(handle);
+            }, (error) => handle.gone(error));
+        };
+        const direct = this.#childNamed(at);
+        if (this.upstream !== undefined)
+            this.upstream.hold(handle);
+        else if (direct !== undefined)
+            bindWhenSynced(direct.whenSynced().then(() => direct));
+        else {
+            const route = this.#routeFor(at);
+            if (route === undefined)
+                handle.gone(new ChordError("unavailable", `no route to ${at}`));
+            else
+                bindWhenSynced(this.#resolve(route, at, principal ?? this.principal));
+        }
+        return handle;
+    }
+    #routeFor(hostName) {
+        let best;
+        for (const entry of this.#routes) {
+            if (hostName.startsWith(entry[0]) && (best === undefined || entry[0].length > best[0].length))
+                best = entry;
+        }
+        return best?.[1];
+    }
+    /** Authorize, resolve (maybe spawn), authorize again; returns the synced connection to the host. */
+    async #resolve(route, hostName, principal, still = () => true) {
+        const refuse = () => new ChordError("forbidden", `${hostName} refused for this principal`);
+        const revoked = () => new ChordError("gone", "principal invalidated while resolving");
+        if (!(await route.authorize(principal, hostName)))
+            throw refuse();
+        if (!still())
+            throw revoked();
+        const link = await route.resolve(hostName);
+        if (!still())
+            throw revoked();
+        if (!(await route.authorize(principal, hostName)))
+            throw refuse();
+        if (!still())
+            throw revoked();
+        let connection = [...this.connections].find((candidate) => candidate.link === link);
+        connection ??= this.#addConnection(link, {
+            role: "downstream",
+            principal: route.principal?.(hostName) ?? { host: hostName },
+            peer: { kind: "host", name: hostName },
+        });
+        await connection.whenSynced();
+        if (!still())
+            throw revoked();
+        return connection;
+    }
+    /**
+     * Relays a hold from `relay.origin` to the host it names. Relaying needs a route: it is where authorization
+     * lives. The origin's authorization generation is re-checked after every await and right before forwarding, so a
+     * revocation during resolution wins.
+     */
+    async relay(relay) {
+        const at = relay.frame.at;
+        const route = this.#routeFor(at);
+        if (route === undefined) {
+            throw this.#childNamed(at) === undefined
+                ? new ChordError("unavailable", `no route to ${at}`)
+                : new ChordError("forbidden", `no route authorizes ${at}`);
+        }
+        const down = await this.#resolve(route, at, relay.principal, () => relay.current);
+        if (!relay.current)
+            return;
+        relay.open(down);
+    }
+    reload(plugins, options = {}) {
+        // Client-local facet epochs never cross the parent link; only child hosts require cluster coordination.
+        if (this.kind !== "client" && this.upstream !== undefined) {
+            return Promise.reject(new ChordError("unavailable", "reloads are coordinated by the server", { reason: "not_coordinator" }));
+        }
+        const children = [...this.connections].some((connection) => connection.role === "downstream" && connection.peer.kind === "host");
+        return children || options.remote !== undefined || options.remoteRemove !== undefined
+            ? runClusterReload(this, plugins, options)
+            : runReload(this, plugins, options);
+    }
+    onReloadFrame(connection, frame) {
+        this.#childReloads.handle(connection, frame);
+    }
+    rememberRemoteModules(remote, remove) {
+        for (const prefix of new Set([...Object.keys(remote ?? {}), ...Object.keys(remove ?? {})])) {
+            const modules = remote?.[prefix] ?? [];
+            const removed = remove?.[prefix] ?? [];
+            this.remoteModules[prefix] = [...new Set([...(this.remoteModules[prefix] ?? []), ...modules])].filter((module) => !removed.includes(module));
+            this.remoteRemoved[prefix] = [...new Set([...(this.remoteRemoved[prefix] ?? []), ...removed])].filter((module) => !modules.includes(module));
+        }
+    }
+    /** The epoch id the next reload would commit. */
+    peekNextEpoch() {
+        return this.#epochSeq + 1;
+    }
+    /**
+     * Disposes every record, holders before what they hold (a resource's `close` may still use the objects its record
+     * holds, local or remote), then closes the links.
+     */
+    async close() {
+        this.eager.clear();
+        const reason = new ChordError("gone", `host ${this.name} closed`);
+        try {
+            await disposeHoldersFirst([...this.records.values()], reason, "host close: disposal failed");
+        }
+        finally {
+            for (const connection of [...this.connections])
+                connection.link.close("host closed");
+        }
+    }
+}
+/**
+ * Force-disposes `records` in waves: a record goes once no record of the set that holds it is left, so holders are
+ * disposed (and their resources closed) while what they hold is still live. In-host holds are acyclic. Errors of
+ * every disposal are collected.
+ */
+async function disposeHoldersFirst(records, reason, message) {
+    const remaining = new Set(records);
+    const held = (record) => {
+        const result = new Set();
+        for (const decls of record.allDecls()) {
+            for (const hold of decls.holds.values())
+                if (hold.record !== undefined)
+                    result.add(hold.record);
+        }
+        return result;
+    };
+    const holds = new Map(records.map((record) => [record, held(record)]));
+    const errors = [];
+    while (remaining.size > 0) {
+        const heldByRemaining = new Set();
+        for (const record of remaining)
+            for (const target of holds.get(record) ?? [])
+                heldByRemaining.add(target);
+        let wave = [...remaining].filter((record) => !heldByRemaining.has(record));
+        // A cycle cannot happen in-host; dispose the rest together rather than loop.
+        if (wave.length === 0)
+            wave = [...remaining];
+        for (const record of wave)
+            remaining.delete(record);
+        const results = await Promise.allSettled(wave.map((record) => record.dispose(true, reason)));
+        for (const result of results)
+            if (result.status === "rejected")
+                errors.push(result.reason);
+    }
+    if (errors.length === 1)
+        throw errors[0];
+    if (errors.length > 1)
+        throw new AggregateError(errors, message);
+}
+function sameTable(a, b) {
+    if (a.size !== b.size)
+        return false;
+    const keys = [...a.keys()];
+    return [...b].every(([key, value], index) => keys[index] === key && a.get(key) === value);
+}
+const matchesPattern = (pattern, principal) => principal !== null &&
+    typeof principal === "object" &&
+    Object.entries(pattern).every(([key, value]) => deepEqual(principal[key], value));
+/** Address of a remote hold, as the consumer sees it (the provider normalizes the input). */
+const remoteAddress = (at, type, input, principal) => `@${at}\u0000${type.name}\u0000${canonicalJson(input)}\u0000${principal === undefined ? "host" : canonicalJson(principal)}`;
+const unknownType = (type, host) => new ChordError("unavailable", `${type} is not served by ${host}`, { reason: "unknown_type" });
+/** True if `from` holds `to`, directly or transitively, through record-owned holds on this host. */
+function reaches(from, to) {
+    const seen = new Set();
+    const stack = [from];
+    while (stack.length > 0) {
+        const record = stack.pop();
+        if (record === to)
+            return true;
+        if (seen.has(record))
+            continue;
+        seen.add(record);
+        // Remote holds have no record here: cycles across hosts are avoided by convention.
+        for (const decls of record.allDecls()) {
+            for (const hold of decls.holds.values())
+                if (hold.record !== undefined)
+                    stack.push(hold.record);
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=host.js.map