@dcasegr/skein 0.0.0-stage → 0.1.1

package/dist/host/p2p.js

@@ -0,0 +1,1002 @@
+// The router's libp2p host (#43, #51): a router component, like the HTTP
+// proxy and the feeds. The runtime has no network; this is where the sockets
+// are. One js-libp2p node per peer KEY (#160) for the instances that declare
+// libp2p — in their config (the genesis's `libp2p`, from etc/config.json), or
+// by a `libp2p` row in the kernel's dispatch table (#72, #77: a topic, or a
+// `/<protocol>`) — all inside the router process: a master-key host derives a
+// key per instance, so one node per instance; a one-key host's instances share
+// the one peer key, so one node carries them all ("the host" below):
+//
+//   peer key   a secp256k1 key derived from the INSTANCE's root key with BRC-42/43
+//              (#129: [2, "skein instance"], key ID `libp2p:<handle>`, self — signer.ts
+//              peerKey): the key the instance's signer answers for getPublicKey with
+//              those arguments, so a program computes its own peer ID; a child, not
+//              the root. The peer ID is the identity
+//              multihash of the key's protobuf (type secp256k1, the 33-byte
+//              compressed key), so the key reads straight out of the peer ID.
+//   node       GossipSub (StrictSign: every message is signed by its publisher's
+//              peer key), noise + yamux, TCP and WebSocket listeners (WSS with a
+//              certificate), Kademlia DHT off | client | server, mDNS on/off,
+//              bootstrap peers kept connected, circuit relays.
+//   topics     the instance's `libp2p.topics`, its dispatch table's libp2p
+//              rows' topics (libp2pConfig) and the topics its apps subscribed
+//              (#119: `subscribe {topic, program, fn}` / `unsubscribe {topic}`,
+//              emitted by an app's installed program; the subscriptions folded
+//              from the log, subscriptionsOf, then followed live): subscribed; each message is judged
+//              by the async topic validator, which makes one front-door call
+//              (`inbound`) and returns its verdict to GossipSub (accept: admit +
+//              forward; reject: drop + penalise the delivering peer; ignore: drop).
+//              A redelivered message already admitted (its `p2p` event record is
+//              in the kernel's `unique` map) is refused at admit, nothing written:
+//              ignore.
+//              A topic only an app's liveness takes (#138, liveness.ts) is
+//              subscribed too, but its messages are never admitted: each is
+//              judged by the liveness tool alone (a beat whose instance
+//              signature verifies is kept and accepted, a bad one rejected).
+//              With the DHT on, each topic name is a rendezvous: provide the
+//              CID v1 raw sha2-256 of the name and dial the providers found
+//              (go-libp2p's RoutingDiscovery, as go-p2p-message-bus uses it).
+//   protocols  the instance's `libp2p.protocols` and its dispatch table's
+//              libp2p rows' protocols (`/…`): for each inbound stream the
+//              router reads length-prefixed frames (unsigned varint), makes one
+//              front-door call per frame and writes the answer's body back.
+//              Every node also serves /skein/message/1.0.0 (#70): a frame there is
+//              a signed message to the instance, its package {message, body}; the
+//              front door checks and routes it, no route needed.
+//   changes    `declare` again with the instance's config as it now stands (the
+//              router does when the dispatch table changed: an install or an
+//              uninstall added or removed libp2p rows, #72/#77): new topics are
+//              subscribed and new protocols handled; gone ones unsubscribed and
+//              unhandled; no topic or protocol left: the node stops. No restart.
+//   outbound   the `libp2p` provider's work (#70, providers.ts): publish, dial,
+//              send, close for the messages an instance emits to it, and each frame
+//              read from a dialled stream handed back (`frames`) to become a
+//              message to the instance — the next frame arrives as an entry.
+//
+// Host-wide settings (hostP2PConfig): SKEIN_LIBP2P_LISTEN, _BOOTSTRAP, _RELAYS
+// (comma-separated multiaddrs), _DHT (off | client | server), _MDNS (on | off),
+// _TLS_CERT / _TLS_KEY (PEM files: the WebSocket listener serves TLS, so
+// browsers can dial /tls/ws); from the environment, else $SKEIN_HOME/host.env.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { noise } from "@chainsafe/libp2p-noise";
+import { yamux } from "@chainsafe/libp2p-yamux";
+import { circuitRelayTransport } from "@libp2p/circuit-relay-v2";
+import { privateKeyFromRaw } from "@libp2p/crypto/keys";
+import { gossipsub, TopicValidatorResult } from "@libp2p/gossipsub";
+import { identify } from "@libp2p/identify";
+import { kadDHT, passthroughMapper, removePrivateAddressesMapper } from "@libp2p/kad-dht";
+import { mdns } from "@libp2p/mdns";
+import { peerIdFromPrivateKey, peerIdFromString } from "@libp2p/peer-id";
+import { ping } from "@libp2p/ping";
+import { tcp } from "@libp2p/tcp";
+import { isPrivate, lpStream } from "@libp2p/utils";
+import { webSockets } from "@libp2p/websockets";
+import { multiaddr } from "@multiformats/multiaddr";
+import * as dagCbor from "@ipld/dag-cbor";
+import { createLibp2p } from "libp2p";
+import { CID } from "multiformats/cid";
+import { sha256 } from "multiformats/hashes/sha2";
+import { MESSAGE_KEY_ID, MESSAGE_PROTOCOL as SIGN_PROTOCOL } from "./providers.js";
+import { verifyAnyone } from "../runtime/identity.js";
+import { Liveness } from "./liveness.js";
+/** The default listeners: loopback TCP and WebSocket, ports chosen by the OS (plain WS on loopback: dev only). */
+export const DEFAULT_LISTEN = ["/ip4/127.0.0.1/tcp/0", "/ip4/127.0.0.1/tcp/0/ws"];
+/** The stream protocol a signed message travels on to an instance (#70). */
+export const MESSAGE_PROTOCOL = "/skein/message/1.0.0";
+/**
+ * The overlay's receive row (skein-overlay etc/app.json; the settled sync design, David 2026-10-30):
+ * the host's OWN entry for the BEEFs it fetched (sync.ts `deliver` → Router.p2pInbound), never served
+ * to peers ("not a good door to have": a node takes BEEFs only from paths it chose). Whatever rows an
+ * instance declares, no node handles it inbound.
+ */
+export const RECEIVE_PROTOCOL = "/skein/overlay/beef/1.0.0";
+/** Whether a node handles `protocol` inbound for its handles' rows: not the receive row, not the host's own. */
+const inboundRow = (protocol, host) => protocol !== MESSAGE_PROTOCOL && protocol !== RECEIVE_PROTOCOL && !(protocol in host);
+// ---------------------------------------------------------------- keys and IDs
+/** A bsv secp256k1 key as a libp2p private key. */
+export function libp2pKey(k) {
+    return privateKeyFromRaw(Uint8Array.from(k.toArray("be", 32)));
+}
+/** The peer ID of a key: the identity multihash of its protobuf (secp256k1, compressed). */
+export function peerIdOf(k) {
+    return peerIdFromPrivateKey(libp2pKey(k));
+}
+/** The compressed secp256k1 key a peer ID embeds (hex), or undefined for another kind. */
+export function keyOfPeerId(id) {
+    const b = typeof id === "string" ? peerIdFromString(id).toMultihash().bytes : id;
+    // identity multihash (0x00, 0x25) over protobuf {1: KeyType = 2 (secp256k1), 2: 33 bytes}
+    if (b.length !== 39 || b[0] !== 0x00 || b[1] !== 0x25 || b[2] !== 0x08 || b[3] !== 0x02 || b[4] !== 0x12 || b[5] !== 0x21)
+        return undefined;
+    return Buffer.from(b.subarray(6)).toString("hex");
+}
+/** A topic name's rendezvous CID: v1 raw over sha2-256 of the name (go-libp2p's nsToCid). */
+export async function topicCid(topic) {
+    return CID.createV1(0x55, await sha256.digest(new TextEncoder().encode(topic)));
+}
+// ---------------------------------------------------------------- config
+const list = (s) => (s ?? "").split(/[,\s]+/).map((x) => x.trim()).filter(Boolean);
+/** The host-wide settings: the environment's SKEIN_LIBP2P_*, else $SKEIN_HOME/host.env's. */
+export function hostP2PConfig(vars, home) {
+    const file = {};
+    const envFile = home ? join(home, "host.env") : undefined;
+    if (envFile && existsSync(envFile)) {
+        for (const line of readFileSync(envFile, "utf8").split("\n")) {
+            const m = /^\s*(?:export\s+)?(SKEIN_LIBP2P_[A-Z_]+)=(.*)$/.exec(line);
+            if (m)
+                file[m[1]] = m[2].trim().replace(/^(["'])(.*)\1$/, "$2");
+        }
+    }
+    const get = (k) => vars[k] ?? file[k];
+    const dht = (get("SKEIN_LIBP2P_DHT") || "off").toLowerCase();
+    if (dht !== "off" && dht !== "client" && dht !== "server")
+        throw new Error(`SKEIN_LIBP2P_DHT: off | client | server, not ${dht}`);
+    const cert = get("SKEIN_LIBP2P_TLS_CERT"), key = get("SKEIN_LIBP2P_TLS_KEY");
+    const listen = list(get("SKEIN_LIBP2P_LISTEN"));
+    return {
+        listen: listen.length ? listen : DEFAULT_LISTEN,
+        bootstrap: list(get("SKEIN_LIBP2P_BOOTSTRAP")),
+        dht,
+        relays: list(get("SKEIN_LIBP2P_RELAYS")),
+        mdns: /^(on|1|true|yes)$/i.test(get("SKEIN_LIBP2P_MDNS") ?? ""),
+        ...(cert && key ? { tls: { cert: readFileSync(cert, "utf8"), key: readFileSync(key, "utf8") } } : {}),
+    };
+}
+/** The libp2p config a genesis carries (`libp2p: {topics?, protocols?, listen?}`), or undefined: no node. */
+export function libp2pOf(g) {
+    const c = g?.libp2p;
+    if (!c || typeof c !== "object")
+        return undefined;
+    const strs = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string" && x.length > 0) : [];
+    const listen = strs(c.listen);
+    return { topics: strs(c.topics), protocols: strs(c.protocols), ...(listen.length ? { listen } : {}) };
+}
+/**
+ * An instance's libp2p config as it stands (#72, #77): the genesis's
+ * (libp2pOf: a tree names what its node subscribes in `config.libp2p`),
+ * plus the topics and protocols named by the dispatch table's `libp2p`
+ * rows added since the genesis (an app's install; address: a topic) — a
+ * genesis topic row alone subscribes nothing, as a route alone did not — and
+ * every stream protocol a `libp2p` row names (`/<protocol>`), whatever
+ * installed it, the genesis included (#155: an image-born instance serves its
+ * sync row; the overlay's receive row stays unserved, P2PHost), plus the
+ * topics the apps subscribed (#119, `subscribed`).
+ * `beacons` (#126): an app's beacon (or its liveness, #138: P2PHost.liveness
+ * subscribes those topics itself) needs the node, and adds no topic.
+ * Undefined: no node — the genesis declares none and nothing needs one.
+ */
+export function libp2pConfig(g, rows, subscribed = [], beacons = false) {
+    const base = libp2pOf(g);
+    const seeded = new Set((g?.dispatch ?? []).filter((r) => r.transport === "libp2p").map((r) => String(r.address)));
+    // #155: a stream protocol is declared whatever installed its row; a topic row from the genesis alone subscribes nothing.
+    const names = rows.filter((r) => r.transport === "libp2p" && (String(r.address).startsWith("/") || !seeded.has(String(r.address)))).map((r) => r.address).filter((p) => typeof p === "string" && p.length > 0);
+    // #126: a beacon needs the node (to publish), not a subscription of its topic.
+    if (!base && !names.length && !subscribed.length && !beacons)
+        return undefined;
+    const add = (xs, ys) => [...new Set([...xs, ...ys])];
+    return {
+        topics: add(add(base?.topics ?? [], names.filter((n) => !n.startsWith("/"))), subscribed),
+        protocols: add(base?.protocols ?? [], names.filter((n) => n.startsWith("/"))),
+        ...(base?.listen ? { listen: base.listen } : {}),
+    };
+}
+export const isTopic = (t) => typeof t === "string" && t.length > 0 && !/[\s\0]/.test(t) && !t.startsWith("/");
+/** A `subscribe` / `unsubscribe` event record, read (subscriptions.zig eventOf); or why it is not one this host follows. */
+export function subscriptionEvent(rec) {
+    const event = rec.event;
+    if (rec.kind !== "event" || (event !== "subscribe" && event !== "unsubscribe"))
+        return { refused: "not a subscribe or unsubscribe event" };
+    if (typeof rec.app !== "string" || !rec.app)
+        return { refused: "it names no app (its program record is not installed): ignored" };
+    if (!isTopic(rec.topic))
+        return { refused: `${JSON.stringify(rec.topic)} is not a topic (text, no space; a /protocol is not subscribed)` };
+    if (event === "unsubscribe")
+        return { event, app: rec.app, topic: rec.topic };
+    if (typeof rec.program !== "string" || !rec.program || typeof rec.fn !== "string" || !rec.fn)
+        return { refused: "a subscribe names its program and fn" };
+    return { event, sub: { app: rec.app, topic: rec.topic, program: rec.program, fn: rec.fn, ...(typeof rec.filter === "string" ? { filter: rec.filter } : {}) } };
+}
+/** Fold subscription events in order (subscriptions.zig apply). */
+export function foldSubscriptions(events, into = []) {
+    for (const e of events) {
+        const [app, topic] = e.event === "subscribe" ? [e.sub.app, e.sub.topic] : [e.app, e.topic];
+        const i = into.findIndex((s) => s.app === app && s.topic === topic);
+        if (e.event === "subscribe") {
+            if (i >= 0)
+                into[i] = e.sub;
+            else
+                into.push(e.sub);
+        }
+        else if (i >= 0)
+            into.splice(i, 1);
+    }
+    return into;
+}
+/** The topics the subscriptions take (each once): what the node subscribes for the apps. */
+export const subscribedTopics = (subs) => [...new Set(subs.map((s) => s.topic))];
+/**
+ * The subscriptions, folded from the store's log (#119, the host's recovery
+ * at hydrate; subscriptions.zig fold): the `subscribe` / `unsubscribe`
+ * records each step's update lists in `emitted`, in log order — by the entry
+ * the step processed (`input`'s `n`), the step's time, its thread's start,
+ * the thread's CID, its place in the thread and in `emitted`. Read only.
+ */
+export async function subscriptionsOf(store) {
+    return foldSubscriptions(await emittedEvents(store, (rec) => { const e = subscriptionEvent(rec); return "refused" in e ? undefined : e; }));
+}
+/**
+ * The beacons standing (#126), folded from the store's log as the
+ * subscriptions are: the `beacon` / `unbeacon` records the steps' updates
+ * list, in log order, keyed by (app, topic). Read only.
+ */
+export async function beaconsOf(store) {
+    return foldBeacons(await emittedEvents(store, (rec) => { const e = beaconEvent(rec); return "refused" in e ? undefined : e; }));
+}
+/** The event records the steps' updates list in `emitted` that `read` takes, in log order (the kernel's fold order, subscriptions.zig); `read` gets each one's place too. */
+export async function emittedEvents(store, read) {
+    const ns = new Map();
+    const nOf = async (input) => {
+        if (!isCid(input))
+            return -1;
+        const k = input.toString();
+        let n = ns.get(k);
+        if (n === undefined) {
+            const e = await store.get(input).catch(() => undefined);
+            n = typeof e?.n === "number" ? e.n : -1;
+            ns.set(k, n);
+        }
+        return n;
+    };
+    const found = [];
+    for await (const origin of store.edges.query({ kind: "thread" })) {
+        const o = await store.get(origin);
+        const thread = origin, threadBytes = origin.bytes;
+        let seq = 0;
+        for await (const c of store.chains.history(origin)) {
+            if (c.equals(origin))
+                continue;
+            seq++;
+            const u = await store.get(c);
+            if (!Array.isArray(u.emitted) || !u.emitted.length)
+                continue;
+            for (const [i, x] of u.emitted.entries()) {
+                if (!isCid(x))
+                    continue;
+                const rec = await store.get(x).catch(() => undefined);
+                if (rec?.kind !== "event")
+                    continue;
+                const n = await nOf(u.input), at = Number(u.at ?? 0);
+                const e = read(rec, { n, at, thread, seq, i, record: x });
+                if (e === undefined)
+                    continue;
+                found.push({ key: [n, at, Number(o.at ?? 0), seq, i], thread: threadBytes, e });
+            }
+        }
+    }
+    const cmp = (x, y) => {
+        for (let i = 0; i < 3; i++)
+            if (x.key[i] !== y.key[i])
+                return x.key[i] - y.key[i];
+        const t = Buffer.compare(x.thread, y.thread);
+        if (t)
+            return t;
+        for (let i = 3; i < x.key.length; i++)
+            if (x.key[i] !== y.key[i])
+                return x.key[i] - y.key[i];
+        return 0;
+    };
+    found.sort(cmp);
+    return found.map((f) => f.e);
+}
+/** What a beat's signature covers. */
+export function beaconPreimage(topic, b) {
+    return dagCbor.encode({ kind: "beacon", topic, body: b.body, at: b.at, sender: b.sender });
+}
+/** A beat's frame for `topic`, signed by `sign` (the instance's signer). */
+export async function beaconFrame(topic, body, at, sender, sign) {
+    const signature = await sign(beaconPreimage(topic, { body, at, sender }));
+    return dagCbor.encode({ body, at, sender, signature });
+}
+/** A beat read from a frame on `topic`, its signature checked against its sender; or why it is not one. */
+export function beaconBeat(topic, frame) {
+    let v;
+    try {
+        v = dagCbor.decode(frame);
+    }
+    catch {
+        return { problem: "not dag-cbor" };
+    }
+    if (!v || typeof v !== "object")
+        return { problem: "not a map" };
+    const { body, at, sender, signature } = v;
+    if (!(body instanceof Uint8Array) || typeof at !== "number" || !(sender instanceof Uint8Array) || sender.length !== 33 || !(signature instanceof Uint8Array))
+        return { problem: "want {body: bytes, at: int, sender: bytes(33), signature: bytes}" };
+    const b = { body, at, sender, signature };
+    if (!verifyAnyone(Buffer.from(sender).toString("hex"), SIGN_PROTOCOL, MESSAGE_KEY_ID, beaconPreimage(topic, b), signature))
+        return { problem: "the signature is not the sender's" };
+    return b;
+}
+/** A `beacon` / `unbeacon` event record, read; or why it is not one this host follows. */
+export function beaconEvent(rec) {
+    const event = rec.event;
+    if (rec.kind !== "event" || (event !== "beacon" && event !== "unbeacon"))
+        return { refused: "not a beacon or unbeacon event" };
+    if (typeof rec.app !== "string" || !rec.app)
+        return { refused: "it names no app (its program record is not installed): ignored" };
+    if (!isTopic(rec.topic))
+        return { refused: `${JSON.stringify(rec.topic)} is not a topic` };
+    if (event === "unbeacon")
+        return { event, app: rec.app, topic: rec.topic };
+    const every = typeof rec.every === "number" ? rec.every : typeof rec.every === "bigint" ? Number(rec.every) : NaN;
+    if (!Number.isFinite(every) || every < 1000)
+        return { refused: "a beacon beats every second or slower (`every`, ms)" };
+    if (!(rec.body instanceof Uint8Array))
+        return { refused: "a beacon has a body (bytes)" };
+    return { event, beacon: { app: rec.app, topic: rec.topic, every, body: rec.body } };
+}
+/** Fold beacon events in order: a beacon replaces the app's own on the topic, an unbeacon removes it. */
+export function foldBeacons(events, into = []) {
+    for (const e of events) {
+        const [app, topic] = e.event === "beacon" ? [e.beacon.app, e.beacon.topic] : [e.app, e.topic];
+        const i = into.findIndex((b) => b.app === app && b.topic === topic);
+        if (e.event === "beacon") {
+            if (i >= 0)
+                into[i] = e.beacon;
+            else
+                into.push(e.beacon);
+        }
+        else if (i >= 0)
+            into.splice(i, 1);
+    }
+    return into;
+}
+const isCid = (x) => CID.asCID(x) !== null;
+/** Stream IDs unique across restarts (a thread's recorded stream never names a later stream). */
+let nextStream = Date.now() * 1000;
+const u64 = (n) => { const b = new Uint8Array(8); new DataView(b.buffer).setBigUint64(0, n, false); return b; };
+/** The answer to a stream whose first frame names no topic where several instances declare its protocol (#160). */
+export const TOPIC_REQUIRED = "topic required";
+export class P2PHost {
+    o;
+    /** The liveness tool's state (#138): the apps' liveness and the beats kept, in memory. */
+    live = new Liveness();
+    /** The nodes, by peer ID (#160: one per key). */
+    nodes = new Map();
+    /** Each handle's node. */
+    byHandle = new Map();
+    /** Each handle's peer ID, as derived (keyOf). */
+    ids = new Map();
+    /** Each key's declares, in order (one at a time). */
+    starting = new Map();
+    stopped = false;
+    constructor(o) {
+        this.o = o;
+        if (o.beat)
+            this.live.kept = (h, topic, b) => { if (b.from !== this.peerId(h))
+                o.beat(h, topic, b); };
+    }
+    say(source, line) { this.o.log?.(source, line); }
+    /** A node's name in a log line: its one handle (as before #160), else its first. */
+    nameOf(n) { return n.handles.keys().next().value ?? n.id; }
+    /** The node of an instance, if it has one. */
+    node(handle) { return this.byHandle.get(handle)?.node; }
+    /** An instance's peer ID (derived: whether or not its node runs). */
+    peerId(handle) {
+        let id = this.ids.get(handle);
+        if (!id)
+            this.ids.set(handle, (id = peerIdOf(this.o.keyOf(handle)).toString()));
+        return id;
+    }
+    /** The handles on `handle`'s node (#160: one in a master-key host; every one sharing its key in a one-key host). */
+    handlesOn(handle) { return [...(this.byHandle.get(handle)?.handles.keys() ?? [])]; }
+    /** How many nodes run (#160: one per key). */
+    nodeCount() { return this.nodes.size; }
+    /** Where an instance's node listens (with /p2p/<id>). */
+    addrs(handle) { return this.node(handle)?.getMultiaddrs().map((m) => m.toString()) ?? []; }
+    /**
+     * `handle`'s libp2p config is this: its key's node started (once) with its peer key, the handle's
+     * topics subscribed with the validator, its protocols handled. Declared again, the handle is brought
+     * to the new config. No config: the handle leaves its node; the node stops with its last handle.
+     */
+    async declare(handle, config) {
+        if (this.stopped)
+            return;
+        const key = this.byHandle.get(handle)?.id ?? this.peerId(handle);
+        const prev = this.starting.get(key) ?? Promise.resolve();
+        // The previous declare's failure went to its own caller (it awaited it); this one runs regardless.
+        const next = prev.catch(() => { }).then(async () => {
+            if (this.stopped)
+                return;
+            if (!config)
+                return this.drop(handle);
+            const n = this.byHandle.get(handle) ?? this.nodes.get(key);
+            if (n)
+                return this.reconfigure(n, handle, config);
+            await this.start(key, handle, config);
+        });
+        this.starting.set(key, next);
+        // Only clears the slot: the error reaches this call's caller through `await next` below.
+        void next.catch(() => { }).finally(() => { if (this.starting.get(key) === next)
+            this.starting.delete(key); });
+        await next;
+    }
+    /** The topics and protocols an instance's node serves for it now. */
+    served(handle) {
+        const h = this.byHandle.get(handle)?.handles.get(handle);
+        return h && { topics: [...h.config.topics], protocols: [...h.config.protocols] };
+    }
+    /** Bring `handle` on a running node to `config` (joining it if it is new there): subscribe and handle what is new, unsubscribe and unhandle what no handle takes any more. */
+    async reconfigure(n, handle, config) {
+        let h = n.handles.get(handle);
+        const joined = !h;
+        if (!h) {
+            n.handles.set(handle, (h = { config: { topics: [], protocols: [] }, streams: new Map(), beats: new Map() }));
+            this.byHandle.set(handle, n);
+            if (config.listen?.length)
+                this.say(handle, `libp2p: its listen ${config.listen.join(" ")} not honoured: its key's node (${n.id}) carries ${n.handles.size} instances and listens on ${n.node.getMultiaddrs().map(String).join(" ") || "(nothing)"} (#160)`);
+        }
+        const was = h.config;
+        const added = config.topics.filter((t) => !was.topics.includes(t));
+        const removed = was.topics.filter((t) => !config.topics.includes(t));
+        const addedP = config.protocols.filter((p) => !was.protocols.includes(p) && !this.hostServed(p));
+        const removedP = was.protocols.filter((p) => !config.protocols.includes(p) && !this.hostServed(p));
+        h.config = { ...config, listen: joined ? undefined : was.listen };
+        if (!joined && !added.length && !removed.length && !addedP.length && !removedP.length)
+            return;
+        const sub = this.resubscribe(n);
+        await this.rehandle(n);
+        const list = (xs) => xs.join(", ") || "none";
+        if (joined)
+            this.say(handle, `libp2p: on the node of its key ${n.id} (${n.handles.size} instances); topics ${list(config.topics)}; protocols ${list(config.protocols)}`);
+        else
+            this.say(handle, `libp2p: topics ${list(config.topics)} (+${list(added)} −${list(removed)}); protocols ${list(config.protocols)} (+${list(addedP)} −${list(removedP)})`);
+        if (added.length || sub.added.length)
+            setTimeout(() => void this.discover(n).catch((e) => this.say(this.nameOf(n), `libp2p: discovery: ${e.message}`)), 200);
+    }
+    subscribe(n, topic) {
+        const ps = this.pubsub(n);
+        ps.topicValidators.set(topic, (from, msg) => this.validate(n, topic, from, msg));
+        ps.subscribe(topic);
+        n.subscribed.add(topic);
+    }
+    /** The topics `handle` takes: its config's and its apps' liveness topics (#138). */
+    takes(handle, h) { return [...h.config.topics, ...this.live.topics(handle)]; }
+    /** Subscribe what the handles' configs and liveness tools (#138) take, unsubscribe the rest: the topics added and removed. */
+    resubscribe(n) {
+        const want = new Set([...n.handles].flatMap(([handle, h]) => this.takes(handle, h)));
+        const ps = this.pubsub(n);
+        const removed = [...n.subscribed].filter((t) => !want.has(t));
+        const added = [...want].filter((t) => !n.subscribed.has(t));
+        for (const t of removed) {
+            ps.unsubscribe(t);
+            ps.topicValidators.delete(t);
+            n.subscribed.delete(t);
+        }
+        for (const t of added)
+            this.subscribe(n, t);
+        return { added, removed };
+    }
+    /** Handle the protocols the handles declare, unhandle those none declares any more (the host's own aside). */
+    async rehandle(n) {
+        const host = this.o.hostProtocols ?? {};
+        const want = new Set([...n.handles.values()].flatMap((h) => h.config.protocols).filter((p) => inboundRow(p, host)));
+        for (const p of [...n.handled])
+            if (!want.has(p)) {
+                n.handled.delete(p);
+                await n.node.unhandle(p);
+            }
+        for (const p of want)
+            if (!n.handled.has(p)) {
+                n.handled.add(p);
+                await this.handleProtocol(n, p);
+            }
+    }
+    /** The topics `handle`'s node subscribes for it now: its config's and its apps' liveness topics (#138). */
+    listening(handle) {
+        const n = this.byHandle.get(handle);
+        const h = n?.handles.get(handle);
+        return n && h ? [...new Set(this.takes(handle, h))].filter((t) => n.subscribed.has(t)) : [];
+    }
+    /**
+     * The liveness `handle`'s apps keep (#138, liveness.ts): the tool keeps it, and the node subscribes
+     * each topic (not admitting its messages) and leaves those no liveness nor config takes. One line
+     * when a topic is taken or left. No node: kept for when it starts.
+     */
+    liveness(handle, lives) {
+        this.live.set(handle, lives);
+        const n = this.byHandle.get(handle);
+        if (!n)
+            return;
+        const { added, removed } = this.resubscribe(n);
+        for (const t of added)
+            this.say(handle, `libp2p: liveness ${t} (app ${lives.filter((l) => l.topic === t).map((l) => l.app).join(", ")})`);
+        for (const t of removed)
+            this.say(handle, `libp2p: ${t} left`);
+        if (added.length)
+            setTimeout(() => void this.discover(n).catch((e) => this.say(this.nameOf(n), `libp2p: discovery: ${e.message}`)), 200);
+    }
+    /** Whether the host serves `protocol` on every node itself (/skein/message/1.0.0, `hostProtocols`). */
+    hostServed(protocol) { return protocol === MESSAGE_PROTOCOL || protocol in (this.o.hostProtocols ?? {}); }
+    async handleHostProtocol(n, protocol, f) {
+        await n.node.handle(protocol, (stream, connection) => {
+            void (async () => {
+                const lp = lpStream(stream);
+                try {
+                    for (;;) {
+                        let frame;
+                        try {
+                            frame = (await lp.read()).subarray();
+                        }
+                        catch {
+                            break;
+                        }
+                        // The router names no host protocol (#154); a node's first handle answers for it.
+                        await lp.write(await f(this.nameOf(n), connection.remotePeer, frame));
+                    }
+                    await stream.close().catch(() => { });
+                }
+                catch (e) {
+                    this.say(this.nameOf(n), `libp2p: ${protocol} from ${connection.remotePeer}: ${e.message}`);
+                    stream.abort(e);
+                }
+            })();
+        }, { runOnLimitedConnection: true });
+    }
+    async handleProtocol(n, protocol) {
+        await n.node.handle(protocol, (stream, connection) => { void this.serve(n, protocol, stream, connection.remotePeer); }, { runOnLimitedConnection: true });
+    }
+    async start(key, handle, config) {
+        const h = this.o.host;
+        const n = { id: key, node: undefined, handles: new Map([[handle, { config, streams: new Map(), beats: new Map() }]]), seqnos: new Map(), subscribed: new Set(), handled: new Set() };
+        const listen = [...(config.listen ?? h.listen), ...h.relays.map((r) => `${r.replace(/\/+$/, "")}/p2p-circuit`)];
+        // An address that does not parse counts as private here; start() reports it when it is dialled or listened on.
+        const privateDev = [...h.bootstrap, ...listen].every((a) => { try {
+            return isPrivateAddr(multiaddr(a));
+        }
+        catch {
+            return true;
+        } });
+        const services = {
+            identify: identify(),
+            ping: ping(),
+            pubsub: gossipsub({
+                globalSignaturePolicy: "StrictSign",
+                allowPublishToZeroTopicPeers: true,
+                emitSelf: false,
+                // The default id (the publisher's key ‖ seqno), and publish's seqno caught by the data object.
+                msgIdFn: async (msg) => {
+                    if (msg.type !== "signed")
+                        throw new Error("unsigned message");
+                    if (n.seqnos.has(msg.data))
+                        n.seqnos.set(msg.data, msg.sequenceNumber);
+                    const key = (msg.from.publicKey ?? msg.key);
+                    const { publicKeyToProtobuf } = await import("@libp2p/crypto/keys");
+                    const k = publicKeyToProtobuf(key);
+                    const out = new Uint8Array(k.length + 8);
+                    out.set(k, 0);
+                    out.set(u64(msg.sequenceNumber), k.length);
+                    return out;
+                },
+            }),
+        };
+        if (h.dht !== "off")
+            services.dht = kadDHT({ clientMode: h.dht === "client", peerInfoMapper: privateDev ? passthroughMapper : removePrivateAddressesMapper });
+        const node = await createLibp2p({
+            privateKey: libp2pKey(this.o.keyOf(handle)),
+            addresses: { listen },
+            transports: [tcp(), webSockets(h.tls ? { https: { cert: h.tls.cert, key: h.tls.key } } : {}), ...(h.relays.length ? [circuitRelayTransport()] : [])],
+            connectionEncrypters: [noise()],
+            streamMuxers: [yamux()],
+            peerDiscovery: h.mdns ? [mdns()] : [],
+            services: services,
+        });
+        n.node = node;
+        if (this.stopped) {
+            await node.stop();
+            return undefined;
+        }
+        this.nodes.set(key, n);
+        this.byHandle.set(handle, n);
+        if (h.mdns)
+            node.addEventListener("peer:discovery", (e) => { void node.dial(e.detail.id).catch((err) => this.say(this.nameOf(n), `libp2p: mDNS peer ${e.detail.id}: ${err.message}`)); });
+        this.resubscribe(n);
+        const host = this.o.hostProtocols ?? {};
+        for (const protocol of config.protocols.filter((p) => inboundRow(p, host))) {
+            n.handled.add(protocol);
+            await this.handleProtocol(n, protocol);
+        }
+        await this.handleProtocol(n, MESSAGE_PROTOCOL);
+        for (const [protocol, f] of Object.entries(host))
+            await this.handleHostProtocol(n, protocol, f);
+        this.say(handle, `libp2p: peer ${node.peerId} listening on ${node.getMultiaddrs().map(String).join(" ") || "(nothing)"}; topics ${config.topics.join(", ") || "none"}; protocols ${config.protocols.join(", ") || "none"}`);
+        const discover = () => void this.discover(n).catch((e) => this.say(this.nameOf(n), `libp2p: discovery: ${e.message}`));
+        setTimeout(discover, 200);
+        n.timer = setInterval(discover, this.o.discoveryMs ?? 30_000);
+        return n;
+    }
+    // ---------------------------------------------------------------- discovery
+    /** Keep the bootstrap peers connected; with the DHT on, advertise each topic and dial its providers. */
+    async discover(n) {
+        const node = n.node;
+        const name = this.nameOf(n);
+        const connected = new Set(node.getConnections().map((c) => c.remotePeer.toString()));
+        for (const a of this.o.host.bootstrap) {
+            let ma;
+            try {
+                ma = multiaddr(a);
+            }
+            catch {
+                this.say(name, `libp2p: bad bootstrap address ${a}`);
+                continue;
+            }
+            const id = ma.getComponents().find((c) => c.name === "p2p")?.value;
+            if (id === node.peerId.toString() || (id && connected.has(id)))
+                continue;
+            await node.dial(ma).catch((e) => this.say(name, `libp2p: bootstrap ${a}: ${e.message}`));
+        }
+        if (this.o.host.dht === "off" || !node.services.dht)
+            return;
+        for (const topic of [...n.subscribed]) {
+            const cid = await topicCid(topic);
+            await node.contentRouting.provide(cid, { signal: AbortSignal.timeout(20_000) }).catch((e) => { if (!timedOut(e))
+                this.say(name, `libp2p: provide ${topic}: ${e.message}`); });
+            try {
+                for await (const p of node.contentRouting.findProviders(cid, { signal: AbortSignal.timeout(20_000) })) {
+                    if (p.id.equals(node.peerId) || node.getConnections(p.id).length)
+                        continue;
+                    await node.dial(p.multiaddrs.length ? p.multiaddrs : p.id).catch((e) => this.say(name, `libp2p: ${topic} provider ${p.id}: ${e.message}`));
+                }
+            }
+            catch (e) {
+                if (!timedOut(e))
+                    this.say(name, `libp2p: find providers ${topic}: ${e.message}`);
+            } // timed out: next round
+        }
+    }
+    // ---------------------------------------------------------------- inbound
+    pubsub(n) {
+        return n.node.services.pubsub;
+    }
+    /**
+     * The topic validator: for every handle on the node that takes the topic, one front-door call (or,
+     * for a topic only its apps' liveness takes, #138, the liveness tool's verdict alone: nothing
+     * admitted); GossipSub's verdict (async: forwarding waits on it) is Accept if any handle accepts,
+     * Reject only if every one rejects, else Ignore (#160).
+     */
+    async validate(n, topic, _source, msg) {
+        if (msg.type !== "signed")
+            return TopicValidatorResult.Reject;
+        const takers = [...n.handles].filter(([handle, h]) => h.config.topics.includes(topic) || this.live.takes(handle, topic));
+        if (!takers.length)
+            return TopicValidatorResult.Ignore;
+        const verdicts = await Promise.all(takers.map(([handle, h]) => this.validateFor(handle, h, topic, msg)));
+        if (verdicts.includes(TopicValidatorResult.Accept))
+            return TopicValidatorResult.Accept;
+        if (verdicts.every((v) => v === TopicValidatorResult.Reject))
+            return TopicValidatorResult.Reject;
+        return TopicValidatorResult.Ignore;
+    }
+    /** One handle's verdict on a topic message (the validator as it was per node before #160). */
+    async validateFor(handle, h, topic, msg) {
+        const live = this.live.takes(handle, topic) ? this.live.observe(handle, topic, msg.data, msg.from.toString()) : undefined;
+        if (!h.config.topics.includes(topic))
+            return live === "accept" ? TopicValidatorResult.Accept : live === "reject" ? TopicValidatorResult.Reject : TopicValidatorResult.Ignore;
+        try {
+            const a = await this.o.inbound(handle, {
+                transport: "libp2p", topic, from: msg.from.toMultihash().bytes, seqno: u64(msg.sequenceNumber), signature: msg.signature, body: msg.data,
+            });
+            return a.verdict === "accept" ? TopicValidatorResult.Accept : a.verdict === "reject" ? TopicValidatorResult.Reject : TopicValidatorResult.Ignore;
+        }
+        catch (e) {
+            // The host failing is not the message's fault: no penalty.
+            this.say(handle, `libp2p: ${topic}: validation failed: ${e.message}`);
+            return TopicValidatorResult.Ignore;
+        }
+    }
+    /**
+     * Which handle an inbound stream on `protocol` is for (#160), by its first frame: the handles that
+     * declare the protocol (every handle declares /skein/message/1.0.0); the frame's `topic` (dag-cbor
+     * {topic, …}) picks the one among them that takes it; a frame naming none, or a topic none of them
+     * takes, goes to the one handle that declares the protocol; with several, a problem.
+     */
+    streamHandle(n, protocol, first) {
+        const declaring = [...n.handles].filter(([, h]) => protocol === MESSAGE_PROTOCOL || h.config.protocols.includes(protocol)).map(([handle]) => handle);
+        if (declaring.length === 1)
+            return { handle: declaring[0] };
+        if (!declaring.length)
+            return { problem: `no instance here declares ${protocol}` };
+        let topic;
+        try {
+            const v = dagCbor.decode(first);
+            topic = v && typeof v === "object" ? v.topic : undefined;
+        }
+        catch { /* not dag-cbor: it names no topic */ }
+        if (typeof topic !== "string" || !topic)
+            return { problem: TOPIC_REQUIRED };
+        // A topic several declaring instances take (a discovery instance beside a token instance, #137): the first declared of them.
+        const taker = declaring.find((handle) => n.handles.get(handle).config.topics.includes(topic));
+        return taker ? { handle: taker } : { problem: `no instance here takes ${topic}` };
+    }
+    /** An inbound stream on a handled protocol: its first frame picks the handle (#160); each frame one front-door call, its answer's body written back. */
+    async serve(n, protocol, stream, remote) {
+        const lp = lpStream(stream);
+        let handle = this.nameOf(n);
+        try {
+            let first;
+            try {
+                first = (await lp.read()).subarray();
+            }
+            catch { /* the remote closed before a frame: nothing owed */ }
+            if (first) {
+                const to = this.streamHandle(n, protocol, first);
+                if ("problem" in to) {
+                    this.say(handle, `libp2p: ${protocol} from ${remote}: ${to.problem}: answered and closed`);
+                    await lp.write(dagCbor.encode({ kind: "error", message: to.problem }));
+                    await stream.close().catch(() => { });
+                    return;
+                }
+                handle = to.handle;
+                for (let frame = first;;) {
+                    const a = await this.o.inbound(handle, { transport: "libp2p", protocol, from: remote.toMultihash().bytes, body: frame });
+                    if (a.body)
+                        await lp.write(a.body);
+                    if (a.close || a.verdict === "reject")
+                        break;
+                    try {
+                        frame = (await lp.read()).subarray();
+                    }
+                    catch {
+                        break;
+                    } // the remote closed or reset its side: the stream is over either way, and nothing here is owed an answer
+                }
+            }
+            await stream.close().catch(() => { }); // a stream the remote already closed or reset cannot be closed again; every frame was answered
+        }
+        catch (e) {
+            this.say(handle, `libp2p: ${protocol} from ${remote}: ${e.message}`);
+            stream.abort(e);
+        }
+    }
+    // ---------------------------------------------------------------- outbound (the libp2p provider's, #70)
+    nodeOf(handle) {
+        const n = this.byHandle.get(handle);
+        if (!n)
+            throw new Error("this instance has no libp2p node (its config names no libp2p)");
+        return n;
+    }
+    /**
+     * The beacons `handle`'s node beats (#126): each a new frame (beaconFrame:
+     * the body, the beat's time, the instance's signature) published on its topic
+     * every `every` ms — the topic not subscribed; nothing logged per beat (a
+     * failed beat is dropped: the next one is the retry). The FIRST beacon on a
+     * topic publishes at once. A beacon REPLACING one (the same app and topic, a
+     * new body and/or `every`; the settled sync design, David 2026-10-30) swaps
+     * what the next beat carries and leaves the timer alone — no publish now, no
+     * reset — unless `every` changed, when the timer is reset to the new
+     * interval (still no publish now). One line when a beacon starts or stops.
+     * No node: nothing beats.
+     */
+    beacons(handle, beacons) {
+        const n = this.byHandle.get(handle);
+        const hs = n?.handles.get(handle);
+        if (!n || !hs)
+            return;
+        const want = new Map(beacons.map((b) => [`${b.app} ${b.topic}`, b]));
+        // Each beat a new frame: the entry's body as it stands then, now, signed by the instance's signer (beaconFrame).
+        const beatOf = (k) => () => {
+            const x = hs.beats.get(k);
+            if (!x || this.byHandle.get(handle) !== n || n.handles.get(handle) !== hs)
+                return;
+            const b = x.beacon;
+            const { sign, identity } = this.o;
+            if (!sign || !identity)
+                return;
+            void (async () => {
+                const sender = await identity(handle);
+                if (!sender)
+                    return;
+                const frame = await beaconFrame(b.topic, b.body, Date.now(), sender, (d) => sign(handle, d));
+                await this.publish(handle, b.topic, frame);
+                // #138: the node's own beat into its liveness set (gossip does not echo it).
+                if (this.live.takes(handle, b.topic))
+                    this.live.observe(handle, b.topic, frame, n.node.peerId.toString());
+            })().catch(() => { });
+        };
+        for (const [k, x] of hs.beats) {
+            const b = want.get(k);
+            if (b) {
+                if (b.every !== x.beacon.every) {
+                    clearInterval(x.timer);
+                    x.timer = setInterval(beatOf(k), b.every);
+                }
+                x.beacon = b; // the next beat carries it
+                continue;
+            }
+            clearInterval(x.timer);
+            hs.beats.delete(k);
+            this.say(handle, `libp2p: beacon ${x.beacon.topic} (app ${x.beacon.app}) stopped`);
+        }
+        for (const [k, b] of want) {
+            if (hs.beats.has(k))
+                continue;
+            hs.beats.set(k, { beacon: b, timer: setInterval(beatOf(k), b.every) });
+            beatOf(k)();
+            this.say(handle, `libp2p: beacon ${b.topic} (app ${b.app}) every ${b.every} ms, ${b.body.length} bytes`);
+        }
+    }
+    /** Publish `body` on `topic` from `handle`'s node (signed with its peer key): the message's seqno, and how many peers took it. */
+    async publish(handle, topic, body) {
+        const n = this.nodeOf(handle);
+        const data = Uint8Array.from(body); // a fresh object: the key msgIdFn catches the seqno by
+        n.seqnos.set(data, -1n);
+        try {
+            const r = await this.pubsub(n).publish(topic, data);
+            const seq = n.seqnos.get(data);
+            if (seq < 0n)
+                throw new Error("publish: no seqno");
+            return { seqno: u64(seq), recipients: r.recipients.length };
+        }
+        finally {
+            n.seqnos.delete(data);
+        }
+    }
+    /** Open a stream from `handle`'s node to a peer (a peer ID, or a multiaddr with /p2p/<id>): its id; each frame read from it, and its end, to `frames`. */
+    async dial(handle, peer, protocol, frames) {
+        const n = this.nodeOf(handle);
+        const hs = n.handles.get(handle);
+        const target = peer.startsWith("/") ? multiaddr(peer) : peerIdFromString(peer);
+        const stream = await n.node.dialProtocol(target, protocol, { signal: AbortSignal.timeout(15_000) });
+        const id = ++nextStream;
+        const s = { stream, lp: lpStream(stream) };
+        hs.streams.set(id, s);
+        void (async () => {
+            for (;;) {
+                try {
+                    frames({ body: (await s.lp.read()).subarray() });
+                }
+                catch (e) {
+                    const name = e.name;
+                    const clean = name === "UnexpectedEOFError" || name === "StreamClosedError" || name === "StreamResetError";
+                    if (hs.streams.get(id) === s)
+                        frames({ closed: true, ...(clean ? {} : { error: e.message }) });
+                    return;
+                }
+            }
+        })();
+        return id;
+    }
+    /**
+     * One request to a peer on `protocol` (a host protocol, shruggr/skein#150): a stream opened, one
+     * frame written, one frame read back, the stream closed. → the answer's bytes.
+     */
+    async request(handle, peer, protocol, body, timeoutMs = 15_000) {
+        const n = this.nodeOf(handle);
+        const signal = AbortSignal.timeout(timeoutMs);
+        const stream = await n.node.dialProtocol(peerIdFromString(peer), protocol, { signal });
+        try {
+            const lp = lpStream(stream);
+            await lp.write(body, { signal });
+            const answer = (await lp.read({ signal })).subarray();
+            await stream.close().catch(() => { });
+            return answer;
+        }
+        catch (e) {
+            stream.abort(e);
+            throw e;
+        }
+    }
+    /** The protocols `handle`'s node handles inbound now (the libp2p node's own registry: its rows', the host's, /skein/message/1.0.0). */
+    handledProtocols(handle) { return this.byHandle.get(handle)?.node.getProtocols() ?? []; }
+    /** The addresses `handle`'s node knows for `peer` (its peer store), as multiaddr strings. */
+    async peerAddrs(handle, peer) {
+        const n = this.byHandle.get(handle);
+        if (!n)
+            return [];
+        try {
+            return (await n.node.peerStore.get(peerIdFromString(peer))).addresses.map((a) => a.multiaddr.toString());
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Dial `peer` from `handle`'s node, at `addrs` when given (a start's persisted peers), else as the peer store knows it. */
+    async connect(handle, peer, addrs = []) {
+        const n = this.nodeOf(handle);
+        const id = peerIdFromString(peer);
+        if (n.node.getConnections(id).length)
+            return;
+        const mas = addrs.flatMap((a) => { try {
+            const m = multiaddr(a);
+            return [m.getComponents().some((c) => c.name === "p2p") ? m : m.encapsulate(`/p2p/${peer}`)];
+        }
+        catch {
+            return [];
+        } });
+        await n.node.dial(mas.length ? mas : id, { signal: AbortSignal.timeout(15_000) });
+    }
+    /** The peers `handle`'s node knows subscribe `topic` (GossipSub's view), as peer ID strings. */
+    subscribers(handle, topic) {
+        const n = this.byHandle.get(handle);
+        return n ? this.pubsub(n).getSubscribers(topic).map((p) => p.toString()) : [];
+    }
+    /** Write one length-prefixed frame on a dialled stream. */
+    async send(handle, id, body) {
+        const s = this.nodeOf(handle).handles.get(handle).streams.get(id);
+        if (!s)
+            throw new Error(`send: no stream ${id}`);
+        await s.lp.write(body);
+    }
+    /** Close a dialled stream (our side), and forget it. */
+    async close(handle, id) {
+        const hs = this.nodeOf(handle).handles.get(handle);
+        const s = hs.streams.get(id);
+        if (!s)
+            throw new Error(`close: no stream ${id}`);
+        hs.streams.delete(id);
+        await s.stream.close().catch(() => s.stream.abort(new Error("closed")));
+    }
+    // ---------------------------------------------------------------- lifecycle
+    /** `handle` leaves its node (its beats stopped, its liveness forgotten); the node stops with its last handle, else follows the handles left. */
+    async drop(handle) {
+        const n = this.byHandle.get(handle);
+        if (!n)
+            return;
+        const hs = n.handles.get(handle);
+        n.handles.delete(handle);
+        this.byHandle.delete(handle);
+        for (const b of hs?.beats.values() ?? [])
+            clearInterval(b.timer);
+        hs?.beats.clear();
+        this.live.drop(handle);
+        if (n.handles.size) {
+            this.resubscribe(n);
+            await this.rehandle(n).catch((e) => this.say(handle, `libp2p: leaving its key's node: ${e.message}`));
+            this.say(handle, `libp2p: left the node of its key ${n.id} (${n.handles.size} instances on it)`);
+            return;
+        }
+        this.nodes.delete(n.id);
+        clearInterval(n.timer);
+        try {
+            await n.node.stop();
+        }
+        catch (e) {
+            this.say(handle, `libp2p: stop: ${e.message}`);
+        } // dropped either way
+    }
+    async stop() {
+        this.stopped = true;
+        await Promise.all([...this.starting.values()].map((p) => p.catch(() => { }))); // each declare's failure went to its caller: this waits for them to settle
+        // Every node stopped at once, its handles with it (nothing to follow on a node that stops).
+        await Promise.all([...this.nodes.values()].map(async (n) => {
+            for (const [handle, hs] of n.handles) {
+                for (const b of hs.beats.values())
+                    clearInterval(b.timer);
+                this.byHandle.delete(handle);
+                this.live.drop(handle);
+            }
+            n.handles.clear();
+            this.nodes.delete(n.id);
+            clearInterval(n.timer);
+            try {
+                await n.node.stop();
+            }
+            catch (e) {
+                this.say(n.id, `libp2p: stop: ${e.message}`);
+            } // dropped either way
+        }));
+    }
+}
+/** A multiaddr on a loopback or private network (dev: the DHT keeps such addresses). */
+function isPrivateAddr(ma) {
+    const c = ma.getComponents().find((x) => x.name.startsWith("dns"));
+    if (c?.value)
+        return c.value === "localhost" || c.value.endsWith(".localhost");
+    try {
+        return isPrivate(ma);
+    }
+    catch {
+        return true;
+    } // an address isPrivate cannot classify (no IP component) counts as private, as a dev address
+}
+/** An AbortSignal.timeout's abort: the DHT's 20-second rounds end this way, and the next round tries again. */
+const timedOut = (e) => e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError");