@dcasegr/skein 0.0.0-stage → 0.1.1

package/dist/host/providers.js

@@ -0,0 +1,565 @@
+// The host's providers (#70): recipients with identities of their own, which
+// carry an instance's messages out. A step emits a message (the kernel's
+// `emit`; unsigned since #126 step 4: the host carries what its own kernel
+// hands it); once its step is committed the kernel hands it here (the
+// serve frame `emit`: {message, body, transport, address, place?}; `place`,
+// #148: an event's place in the log, beside the record) and this module
+// delivers it by the address book's transport:
+//
+//   local    the provider named `address` on this host — handed over directly;
+//            `self` (#79): a message the instance sent itself (one of its apps to
+//            another: the wallet or an overlay to the chain app) — appended
+//            back into the same instance
+//            as a `local` request, as it is (unsigned: the front door finds the
+//            record in the instance's store, its own emit)
+//   libp2p   the instance's libp2p node: `topic:<name>` publishes the
+//            package, a peer ID gets it as one frame on /skein/message/1.0.0;
+//            the libp2p provider answers {replyTo, seqno, recipients} | {replyTo, sent: true}
+//   event    (#65, #119, #126) not a message: an event (`address` its name).
+//            `broadcast` — {kind: "broadcast", tx: <cid>, beef?}, the
+//            transaction's bytes as `body` — to the host's broadcaster (arc.ts: a
+//            durable queue, retries, one Arcade session; none: dropped with a line);
+//            `subscribe`/`unsubscribe`/`beacon`/`unbeacon` to the libp2p node,
+//            `liveness`/`unliveness` (#138) to its liveness tool (liveness.ts);
+//            `deadline`/`fetch` are intentions (#126): the host signs the request
+//            for one with the instance's key and gives it to the service it is
+//            wired to (`route`: its waker, its HTTP proxy), whose signed answer
+//            names the event and carries the request (intention, below);
+//            `payment` (#130) — the kernel's pay step's, the host's own: its
+//            billing (billing.ts, Router.payment) keeps and broadcasts it;
+//            and every event, whatever its name, to the event streams (#148,
+//            events.ts: a page's subscription to its app's events) too
+//
+//            `deliver` (#157) — a `mailbox` recipient's message, from its
+//            delivery thread: the host carries the BRC-103/104 exchange
+//            (deliver.ts) and admits the server's signed answer, which stands on
+//            its own at the door (`deliver` below)
+//
+// Every answer is a signed message from the provider to the instance — the
+// record an `emit` makes, {kind: "mail", op: "put", sender, recipient, box,
+// body, nonce}, with its `signature` (#126 step 4: a `local` package has no
+// session of the instance's to prove its sender), signed under [2, "metanet handles envelope"], key
+// "send", counterparty anyone, its body {replyTo: <the message>, …} — appended
+// as a `local` request ({kind: "message", message, body}): the instance's
+// front door checks it and routes it by `replyTo` to the thread awaiting
+// that message. The host verifies nothing of what it carries in; a provider
+// checks that a message it is asked to act on is for it (the instance's
+// message comes from the instance's own kernel: no signature, #126 step 4).
+//
+// The stock providers (box → body → answer body; every answer has `replyTo`,
+// and a failure is {replyTo, error}):
+//
+//   fetch      a `fetch` intention's signed request (#126) → {replyTo: <the event>,
+//              request, status, headers, body}; a message fetch {method, url,
+//              headers?, body?, timeoutMs?, maxBytes?} (a module before skein-sdk
+//              0.7.0) → {status, headers, body}: the HTTP proxy. A URL of this host's own
+//              is answered in process (no socket); any other goes out when the host
+//              allows it (SKEIN_HTTP=fetch, or the router's `http` option). `body`
+//              is bytes either way. `maxBytes` (#91): a response body over it is
+//              not carried in — the answer is {error} (SKEIN_HTTP=fetch stops
+//              reading at the limit)
+//   waker      a `deadline` intention's signed request (#126: a step's deadline, a
+//              shell's sleep) → at `at`: {replyTo: <the event>, request, at}; a
+//              wake-me message wake {at: ms} (a kernel before #126) → {at}
+//   cron       cron {fn: "tick", every | at, box, body?, name} → {name, next};
+//              then each tick, a message of its own (no `replyTo`) in `box`:
+//              {...body, kind: body.kind ?? "cron", name, due}
+//              cron {fn: "stop", name} → {name, stopped} (#69, cron.ts)
+//   libp2p     publish {topic, body}   → {seqno: bytes(8), recipients}
+//              dial {peer, protocol}   → {stream}; then each frame read from the
+//                                        stream, in box `frame`: {stream, body}, and
+//                                        its end: {stream, closed: true, error?}
+//              send {stream, body}     → {}
+//              close {stream}          → {}
+//   status     takes no messages (#65): it speaks first. Each status of a transaction
+//              an instance holds (but a proof: that is an event, arc.ts) is a message
+//              from it in box `chain/status` (the chain app's, #128), `subject` the
+//              transaction's CID, body {kind: "status", txid, txStatus, blockHash?,
+//              blockHeight?, extraInfo?}; an instance admits it only if it has a row from
+//              this key on `chain/status`
+//   manager    the instance manager (#89, #90): it creates, starts and stops this
+//              host's instances. It takes messages from the host skein only (the
+//              operator's instance, `skein-host init`): its entry is in the host
+//              skein's address book alone, and a message from any other instance
+//              or key is not acted on and not answered (a line in the host's log).
+//              create {handle, owner, image?, claim} → {handle, identity: bytes(33), url}:
+//                     the identity derived, the instance booted from the image
+//                     (`default`, the only one so far), `claim` — the owner's own
+//                     signed claim {message, body}, naming no recipient (#127) —
+//                     forwarded into it, then — claimed — its hostname published
+//                     and it started (Router.createInstance). Refused (an answer
+//                     {error}): a bad or taken handle, a bad owner key, another
+//                     image, no claim, another key's claim, a refused claim
+//              start {handle}   → {handle, started: true, url}: published and started
+//              stop {handle}    → {handle, stopped: true}: unpublished and stopped (off its
+//                     libp2p node too: its beacons stop, skein-amm#4)
+//              create {handle, owner, image: "mailbox", domain?} (#113): a mailbox
+//                     instance for `owner` (the front door and the messagebox,
+//                     keeping its mail), published at once; the same owner and
+//                     handle again: the same answer (it exists). `domain` (both
+//                     images): the handle's domain, recorded with the row
+//              (`list` later.) It signs no claim (#127): it forwards the owner's,
+//              as signed — but on a one-key host (#160, #162) a create with no
+//              claim is claimed by the host's own key, its owner
+//              create {…, config?} (#162): `config` the new instance's apps' config
+//                     at birth ({<app>: {…}}, merged as an install's --config);
+//                     `image` the default image, `mailbox`, or an image by name
+//                     ($SKEIN_HOME/images/<name>, SKEIN_IMAGES_DIR)
+//              create {…, beef?} (skein-amm#4): an Atomic BEEF handed into the new
+//                     instance's receive row /skein/overlay/beef/1.0.0 once it is up
+//                     (as a catch-up's fetched BEEF, from the host's own peer); the
+//                     answer gains delivered: {verdict, reason?} (turned away at the
+//                     door: reported, not retried, the instance stays created)
+//              Also for the instances SKEIN_MANAGER_FOR names (#162): the manager in
+//              their address book at birth, their messages taken as the host skein's
+//   certifier  the host's BRC-169 certifier (#100, #113): the host skein's alone,
+//              as the manager. Its key is the certifier key, the manifest's
+//              metanet.trust.publicKey (the master's child, key ID `certifier`).
+//              issue {handle, domain, subject: bytes(33), serialNumber, issuance?}
+//              → {certificate, holder: {certificate, keyringForSubject}, serialNumber,
+//              issuance?}: the handle certificate for handle@domain → subject under
+//              that serial number, signed — plaintext fields (what resolve answers)
+//              and the subject's copy with encrypted fields and its keyring (what a
+//              wallet's acquireCertificate takes) — handles.ts. It records nothing:
+//              the host skein's onboarding app records the issue
+//   billing    (#130) the host's billing key: it takes no messages and is in no address
+//              book; it signs the host's ticks to the instances whose host row names it
+//              (billing.ts) — the key an owner grants (`skein host`)
+//
+// How this host obtains the providers' keys is its own business (signer.ts:
+// children of its master secret); the instance knows them from its address
+// book (the genesis seeds them: `addressBook`, transport `local`, address the
+// provider's name — no role, #126).
+import { randomBytes } from "node:crypto";
+import { ProtoWallet } from "@bsv/sdk";
+import * as dagCbor from "@ipld/dag-cbor";
+import { encode } from "../runtime/cid.js";
+/** The signing a provider's answer and an intention's request get (BRC-169 §7.2, on skein's mail record); an emit is unsigned (#126 step 4). */
+export const MESSAGE_PROTOCOL = [2, "metanet handles envelope"];
+export const MESSAGE_KEY_ID = "send";
+/** The stream protocol a signed message travels on to a libp2p recipient. */
+export const MESSAGE_STREAM = "/skein/message/1.0.0";
+/** The stock providers' names (each one's address on this host: `local`, <name>). */
+export const PROVIDERS = ["fetch", "waker", "cron", "libp2p", "status", "manager", "certifier", "billing"];
+/** The providers only the host skein's address book names (#90, #113): they act for it alone. */
+export const HOST_SKEIN_PROVIDERS = ["manager", "certifier"];
+/** Keys no address book names (#130: the host's billing key signs its ticks; it is not reached). */
+export const UNADDRESSED = ["billing"];
+const SERVICE = { fetch: { box: "fetch", provider: "fetch" }, deadline: { box: "wake", provider: "waker" } };
+/** The events the libp2p node's wiring takes (`topicEvent`): subscriptions (#119), beacons (#126), liveness (#138), an overlay's wants (#112, #150). */
+const TOPIC_EVENTS = ["subscribe", "unsubscribe", "beacon", "unbeacon", "liveness", "unliveness", "want", "unwant"];
+const hex = (b) => Buffer.from(b).toString("hex");
+/** The fetch provider's refusal of a response over the request's `maxBytes` (#91). */
+export const tooLarge = (max) => `the response is larger than maxBytes (${max} bytes): not carried in`;
+export class Providers {
+    o;
+    wallets = new Map();
+    keys = new Map();
+    /** Messages taken (handle + CID), so a message handed over again (a kernel's start) is acted on once. */
+    taken = new Set();
+    /** The waker's timers, by handle + the wake-me's CID. */
+    timers = new Map();
+    /** Messages being carried now, and the waker's answers being appended. */
+    inflight = new Set();
+    stopped = false;
+    constructor(o) { this.o = o; }
+    say(source, line) { this.o.log?.(source, line); }
+    /** A provider's identity key (hex). */
+    key(name) {
+        let k = this.keys.get(name);
+        if (!k)
+            this.keys.set(name, (k = this.o.keyOf(name).toPublicKey().toString()));
+        return k;
+    }
+    wallet(name) {
+        let w = this.wallets.get(name);
+        if (!w)
+            this.wallets.set(name, (w = new ProtoWallet(this.o.keyOf(name))));
+        return w;
+    }
+    /** The address book entries a genesis seeds for this host's providers: key, transport `local`, address the name (#126: no role). */
+    entries(names = PROVIDERS.filter((n) => !HOST_SKEIN_PROVIDERS.includes(n) && !UNADDRESSED.includes(n))) {
+        return names.map((n) => ({ key: Uint8Array.from(Buffer.from(this.key(n), "hex")), transport: "local", address: n }));
+    }
+    /** Stop the timers; nothing more is carried. */
+    stop() {
+        this.stopped = true;
+        for (const t of this.timers.values())
+            clearTimeout(t.timer);
+        this.timers.clear();
+    }
+    /** A message (or an event, #65) from `handle` to carry out (the kernel's `emit` notice). */
+    deliver(handle, out) {
+        if (this.stopped)
+            return;
+        if (out.transport === "event")
+            return this.event(handle, out);
+        const id = encode(out.message).cid;
+        const k = `${handle} ${id}`;
+        if (this.taken.has(k))
+            return;
+        this.taken.add(k);
+        if (this.taken.size > 100_000)
+            this.taken.delete(this.taken.values().next().value);
+        const p = this.carry(handle, id, out).catch((e) => this.say(handle, `provider: message ${id.toString().slice(-8)}: ${e.message}`));
+        this.inflight.add(p);
+        void p.finally(() => this.inflight.delete(p));
+    }
+    track(p) {
+        this.inflight.add(p);
+        void p.finally(() => this.inflight.delete(p));
+    }
+    /** Whether anything is being carried now (a waker's timer is not: it is waiting). */
+    busy() { return this.inflight.size > 0; }
+    /** Until what is being carried now is done (tests, the corpus: Router.settled). */
+    async idle() {
+        while (this.inflight.size)
+            await Promise.all([...this.inflight]);
+    }
+    /**
+     * An event out (#65, #119): addressed to no one, acted on by its name —
+     * `broadcast` → the broadcaster (Arcade); `subscribe` / `unsubscribe` → the
+     * libp2p node (the topics it subscribes: p2p.ts; delivery is the kernel's, by the subscription); any other name: the application host's `appEvent` when it has one (#164), else a log
+     * line, nothing else (the step is not told). A broadcast is acted on every
+     * time it is handed over (a kernel's start hands over again what a waiting
+     * thread awaits: the queue takes a transaction once); any other event is
+     * handed over once.
+     */
+    event(handle, out) {
+        const m = out.message;
+        const p = out.place;
+        if (p && m.kind === "event" && typeof m.event === "string")
+            this.o.emitted?.(handle, m, { n: Number(p.n), seq: Number(p.seq), i: Number(p.i), thread: p.thread }); // #148
+        if (out.address === "broadcast" && m.kind === "broadcast") {
+            if (!this.o.broadcast) {
+                this.say(handle, "broadcast: this host has no Arcade (SKEIN_ARC_URL): dropped");
+                return;
+            }
+            this.o.broadcast(handle, out.body, m.beef instanceof Uint8Array ? m.beef : undefined);
+            return;
+        }
+        if ((out.address === "deadline" || out.address === "fetch") && m.kind === "event" && m.event === out.address) {
+            const k = `${handle} ${encode(m).cid}`;
+            if (this.taken.has(k))
+                return; // handed over again (a kernel's start): kept already
+            this.taken.add(k);
+            const p = this.intention(handle, out.address, m).catch((e) => { this.taken.delete(k); this.say(handle, `provider: ${out.address}: ${e.message}`); });
+            this.track(p);
+            return;
+        }
+        if (out.address === "deliver" && m.kind === "event" && m.event === "deliver") {
+            // #157: a mailbox delivery the host carries; its answer an entry.
+            if (!this.o.deliver) {
+                this.say(handle, "deliver: this host carries no deliveries: ignored");
+                return;
+            }
+            const id = encode(m).cid;
+            const k = `${handle} ${id}`;
+            if (this.taken.has(k))
+                return;
+            this.taken.add(k);
+            // No answer (or a failure): forgotten, so the instance's next start (its re-offer) carries it again — once per start.
+            this.track(this.o.deliver(handle, id, m).then((ok) => { if (!ok)
+                this.taken.delete(k); }, (e) => { this.taken.delete(k); this.say(handle, `provider: deliver: ${e.message}`); }));
+            return;
+        }
+        if (out.address === "payment" && m.kind === "event" && m.event === "payment") {
+            // #130: the payee is the host: its billing keeps it (and broadcasts it).
+            if (!this.o.payment) {
+                this.say(handle, "payment: this host bills no one: ignored");
+                return;
+            }
+            this.o.payment(handle, m);
+            return;
+        }
+        if (TOPIC_EVENTS.includes(out.address) && m.kind === "event" && m.event === out.address) {
+            if (!this.o.topicEvent) {
+                this.say(handle, `${out.address}: this host has no libp2p node: ignored`);
+                return;
+            }
+            this.o.topicEvent(handle, m);
+            return;
+        }
+        if (this.o.appEvent && m.kind === "event" && m.event === out.address) {
+            // #164: the application host's (e.g. the Open Exchange's): it acts on the names it knows.
+            try {
+                this.o.appEvent(handle, m);
+            }
+            catch (e) {
+                this.say(handle, `provider: an event ${out.address}: the host's wiring: ${e.message}`);
+            }
+            return;
+        }
+        this.say(handle, `provider: an event ${out.address} this host has no wiring for: ignored`);
+    }
+    async carry(handle, id, out) {
+        if (out.transport === "libp2p")
+            return await this.libp2pRecipient(handle, id, out);
+        if (out.transport !== "local")
+            throw new Error(`no transport ${out.transport} here`);
+        // #79: the loopback — the instance's message to itself, appended back as it is (its front door checks it).
+        if (out.address === "self") {
+            if (hex(out.message.sender) !== hex(out.message.recipient))
+                throw new Error("a loopback message is the instance's to itself");
+            await this.o.append(handle, { kind: "message", message: out.message, body: out.body });
+            return;
+        }
+        const name = out.address;
+        if (!PROVIDERS.includes(name))
+            throw new Error(`no provider ${out.address} on this host`);
+        if (hex(out.message.recipient) !== this.key(name))
+            throw new Error(`the message is not for the ${name} provider`);
+        if (HOST_SKEIN_PROVIDERS.includes(name)) {
+            // #90, #113: the host skein's alone — any other sender's message is not acted on, and not answered.
+            const host = this.o.manager?.from();
+            const may = (h) => !!h && handle === h.handle && hex(out.message.sender) === h.identity;
+            // #162: the manager also for the instances SKEIN_MANAGER_FOR names; the certifier for the host skein alone.
+            if (!may(host) && !(name === "manager" && (this.o.manager?.alsoFor?.() ?? []).some(may)))
+                throw new Error(`the ${name === "manager" ? "instance manager" : name} takes messages from the host skein only: not acted on`);
+        }
+        let body;
+        try {
+            body = dagCbor.decode(out.body);
+        }
+        catch {
+            return await this.answer(handle, name, out.message, id, { error: "the body is not dag-cbor" });
+        }
+        const box = out.message.box;
+        try {
+            switch (name) {
+                case "fetch": return await this.fetch(handle, out.message, id, box, body);
+                case "waker": return this.wake(handle, out.message, id, box, body);
+                case "libp2p": return await this.p2p(handle, out.message, id, box, body);
+                case "cron": return await this.cron(handle, out.message, id, box, body);
+                case "status": return await this.answer(handle, "status", out.message, id, { error: "the status provider takes no messages: it sends statuses to the instances that subscribe to it (box \"chain/status\")" });
+                case "manager": return await this.answer(handle, "manager", out.message, id, await this.o.manager.request(box, body));
+                case "certifier": {
+                    if (!this.o.certifier)
+                        return await this.answer(handle, "certifier", out.message, id, { error: "this host has no certifier" });
+                    return await this.answer(handle, "certifier", out.message, id, await this.o.certifier(box, body));
+                }
+                case "billing": return await this.answer(handle, "billing", out.message, id, { error: "the host's billing key takes no messages (#130: it signs the host's ticks)" });
+            }
+        }
+        catch (e) {
+            await this.answer(handle, name, out.message, id, { error: e.message });
+        }
+    }
+    /** A signed message from provider `name` to the instance that sent `to`, in `to`'s box: {replyTo, …answer}, appended. */
+    async answer(handle, name, to, id, answer, box = to.box) {
+        await this.send(handle, name, to.sender, box, { replyTo: id, ...answer }, to.subject);
+    }
+    /**
+     * A signed message from provider `name` to `recipient` (the instance
+     * `handle`), in `box`, its body `body` — an answer, a tick (#69), a status
+     * (#65) — appended there as a `local` request (what the append answers:
+     * the entry). Its own message (two like bodies are two messages:
+     * `nonce`), about `subject` if given.
+     */
+    async send(handle, name, recipient, box, body, subject) {
+        if (this.stopped)
+            return undefined;
+        const bytes = dagCbor.encode(body);
+        const unsigned = {
+            kind: "mail", op: "put", sender: Uint8Array.from(Buffer.from(this.key(name), "hex")), recipient, box, body: encode(dagCbor.decode(bytes)).cid,
+            nonce: Uint8Array.from(randomBytes(16)), ...(subject ? { subject } : {}),
+        };
+        const { signature } = await this.wallet(name).createSignature({ protocolID: MESSAGE_PROTOCOL, keyID: MESSAGE_KEY_ID, counterparty: "anyone", data: [...dagCbor.encode(unsigned)] });
+        const message = { ...unsigned, signature: Uint8Array.from(signature) };
+        return await this.o.append(handle, { kind: "message", message, body: bytes });
+    }
+    // ---------------------------------------------------------------- fetch: the HTTP proxy
+    /** A message to the fetch provider (a module on an SDK before #126: fetch was a message to it). */
+    async fetch(handle, m, id, box, b) {
+        if (box !== "fetch")
+            return await this.answer(handle, "fetch", m, id, { error: `the fetch provider takes box "fetch", not ${box}` });
+        await this.answer(handle, "fetch", m, id, await this.proxy(handle, b));
+    }
+    /** The HTTP proxy (#70, #126): one request {method, url, headers?, body?, timeoutMs?, maxBytes?} → {status, headers, body} | {error}. */
+    async proxy(handle, b) {
+        if (typeof b.method !== "string" || typeof b.url !== "string")
+            return { error: "fetch wants {method, url, headers?, body?, timeoutMs?, maxBytes?}" };
+        const num = (x) => typeof x === "number" ? x : typeof x === "bigint" ? Number(x) : undefined;
+        const maxBytes = num(b.maxBytes) !== undefined && num(b.maxBytes) >= 0 ? num(b.maxBytes) : undefined;
+        const timeoutMs = num(b.timeoutMs);
+        const headers = {};
+        if (b.headers && typeof b.headers === "object")
+            for (const [k, v] of Object.entries(b.headers))
+                if (typeof v === "string")
+                    headers[k.toLowerCase()] = v;
+        let r;
+        try {
+            r = await this.o.fetch({ method: b.method, url: b.url, headers, ...(b.body instanceof Uint8Array ? { body: b.body } : {}), ...(timeoutMs !== undefined ? { timeoutMs } : {}), ...(maxBytes !== undefined ? { maxBytes } : {}) }, handle);
+        }
+        catch (e) {
+            return { error: e.message };
+        }
+        if (maxBytes !== undefined && r.body.length > maxBytes)
+            return { error: tooLarge(maxBytes) };
+        return { status: r.status, headers: r.headers, body: r.body };
+    }
+    // ---------------------------------------------------------------- the waker
+    /**
+     * An intention a step recorded (#126: a `deadline`, a `fetch` event), handed
+     * over once its step is committed: the request is the instance's, signed by
+     * its wallet — the mail record {kind: "mail", op: "put", sender: <the
+     * instance>, recipient: <the service's key>, box, body: <the event's CID>,
+     * nonce, signature} — sent where this host is wired (`route`: its own waker
+     * or HTTP proxy, `local`). The service's answer is a signed message from its
+     * key whose body names the event (`replyTo`) and carries that request
+     * (`request`), appended as a `local` request: the front door checks its
+     * signature, the kernel the request's (scheduler.zig intentionAnswer), and
+     * the thread awaiting the event steps — `woke` at a deadline, `reply` with a
+     * fetch's response ({status, headers, body} | {error}).
+     */
+    async intention(handle, name, ev) {
+        const r = this.o.route?.[name] ?? { transport: "local", address: SERVICE[name].provider };
+        if (r.transport !== "local")
+            throw new Error(`no transport ${String(r.transport)} wired for ${name}`);
+        if (!PROVIDERS.includes(r.address))
+            throw new Error(`no provider ${r.address} on this host`);
+        const id = encode(ev).cid;
+        const identity = await this.o.identity(handle);
+        if (!identity)
+            throw new Error("the instance's identity is not known");
+        const unsigned = {
+            kind: "mail", op: "put", sender: identity, recipient: Uint8Array.from(Buffer.from(this.key(r.address), "hex")), box: SERVICE[name].box, body: id, nonce: Uint8Array.from(randomBytes(16)),
+        };
+        const request = { ...unsigned, signature: await this.o.sign(handle, dagCbor.encode(unsigned)) };
+        const reply = (answer) => this.send(handle, r.address, identity, SERVICE[name].box, { replyTo: id, request, ...answer });
+        if (name === "deadline") {
+            const at = typeof ev.at === "number" ? ev.at : typeof ev.at === "bigint" ? Number(ev.at) : NaN;
+            if (!Number.isFinite(at))
+                throw new Error("a deadline with no `at`");
+            this.timer(handle, id, at, () => this.track(reply({ at }).catch((e) => this.say(handle, `waker: ${e.message}`))));
+            return;
+        }
+        await reply(await this.proxy(handle, ev));
+    }
+    /** Run `fire` at `at` (by the clock `now`), once per (handle, id). */
+    timer(handle, id, at, fire) {
+        const k = `${handle} ${id}`;
+        if (this.timers.has(k))
+            return;
+        // A timer's longest wait is about 24.8 days; a later wake waits in steps.
+        const arm = () => this.timers.set(k, { at, handle, fire: go, timer: setTimeout(go, Math.min(2 ** 31 - 1, Math.max(0, at - this.o.now()) + 1)) });
+        const go = () => {
+            this.timers.delete(k);
+            if (this.o.now() < at) {
+                arm();
+                return;
+            }
+            fire();
+        };
+        arm();
+    }
+    /** A wake-me message (a kernel before #126: a deadline was a message to the waker), kept for such a log's waiting threads. */
+    wake(handle, m, id, box, b) {
+        if (box !== "wake" || typeof b.at !== "number") {
+            void this.answer(handle, "waker", m, id, { error: "the waker takes {at: ms} in box \"wake\"" });
+            return;
+        }
+        this.timer(handle, id, b.at, () => this.track(this.answer(handle, "waker", m, id, { at: b.at }).catch((e) => this.say(handle, `waker: ${e.message}`))));
+    }
+    /**
+     * Answer now every wake-me that is due by the clock (`now`): what the
+     * timers do in real time, for a clock that is not (a script clock: tests,
+     * the corpus). The answers are being appended when it returns (idle()).
+     */
+    wakeDue() {
+        const now = this.o.now();
+        for (const [k, t] of [...this.timers])
+            if (t.at <= now) {
+                clearTimeout(t.timer);
+                this.timers.delete(k);
+                t.fire();
+            }
+    }
+    /** The earliest wake the waker owes `handle` (ms), if any (the host page). */
+    nextWake(handle) {
+        let next;
+        for (const t of this.timers.values())
+            if (t.handle === handle && (next === undefined || t.at < next))
+                next = t.at;
+        return next;
+    }
+    // ---------------------------------------------------------------- libp2p
+    async p2p(handle, m, id, box, b) {
+        const p = this.o.p2p;
+        if (!p)
+            return await this.answer(handle, "libp2p", m, id, { error: "this host runs no libp2p" });
+        switch (box) {
+            case "publish": {
+                if (typeof b.topic !== "string" || !(b.body instanceof Uint8Array))
+                    return await this.answer(handle, "libp2p", m, id, { error: "publish wants {topic, body}" });
+                const r = await p.publish(handle, b.topic, b.body);
+                return await this.answer(handle, "libp2p", m, id, { seqno: r.seqno, recipients: r.recipients });
+            }
+            case "dial": {
+                if (typeof b.peer !== "string" || typeof b.protocol !== "string")
+                    return await this.answer(handle, "libp2p", m, id, { error: "dial wants {peer, protocol}" });
+                // Each frame, and the end, is a message in box `frame` answering the dial: the thread awaits the dial's CID.
+                let stream = -1;
+                const queue = [];
+                let ready = false;
+                const frames = (f) => {
+                    const x = { ...("body" in f ? { body: f.body } : { closed: true, ...(f.error ? { error: f.error } : {}) }) };
+                    if (!ready) {
+                        queue.push(x);
+                        return;
+                    }
+                    this.track(this.answer(handle, "libp2p", m, id, { stream, ...x }, "frame").catch((e) => this.say(handle, `libp2p: frame: ${e.message}`)));
+                };
+                stream = await p.dial(handle, b.peer, b.protocol, frames);
+                await this.answer(handle, "libp2p", m, id, { stream });
+                ready = true;
+                for (const x of queue)
+                    await this.answer(handle, "libp2p", m, id, { stream, ...x }, "frame");
+                return;
+            }
+            case "send": {
+                if (typeof b.stream !== "number" || !(b.body instanceof Uint8Array))
+                    return await this.answer(handle, "libp2p", m, id, { error: "send wants {stream, body}" });
+                await p.send(handle, b.stream, b.body);
+                return await this.answer(handle, "libp2p", m, id, {});
+            }
+            case "close": {
+                if (typeof b.stream !== "number")
+                    return await this.answer(handle, "libp2p", m, id, { error: "close wants {stream}" });
+                await p.close(handle, b.stream);
+                return await this.answer(handle, "libp2p", m, id, {});
+            }
+            default:
+                return await this.answer(handle, "libp2p", m, id, { error: `the libp2p provider takes publish, dial, send, close: not ${box}` });
+        }
+    }
+    /** A message to a libp2p recipient: its package published on the topic, or written to the peer on MESSAGE_STREAM. */
+    async libp2pRecipient(handle, id, out) {
+        const p = this.o.p2p;
+        const pkg = dagCbor.encode({ message: out.message, body: out.body });
+        const fail = (error) => this.answer(handle, "libp2p", out.message, id, { error }, "sent");
+        if (!p)
+            return await fail("this host runs no libp2p");
+        try {
+            if (out.address.startsWith("topic:")) {
+                const r = await p.publish(handle, out.address.slice("topic:".length), pkg);
+                return await this.answer(handle, "libp2p", out.message, id, { seqno: r.seqno, recipients: r.recipients }, "sent");
+            }
+            const s = await p.dial(handle, out.address, MESSAGE_STREAM, () => { });
+            await p.send(handle, s, pkg);
+            await p.close(handle, s);
+            await this.answer(handle, "libp2p", out.message, id, { sent: true }, "sent");
+        }
+        catch (e) {
+            await fail(e.message);
+        }
+    }
+    // ---------------------------------------------------------------- cron (#69)
+    async cron(handle, m, id, box, b) {
+        if (!this.o.cron)
+            return await this.answer(handle, "cron", m, id, { error: "this host keeps no schedules" });
+        if (box !== "cron")
+            return await this.answer(handle, "cron", m, id, { error: `the cron provider takes box "cron", not ${box}` });
+        await this.answer(handle, "cron", m, id, this.o.cron(handle, hex(m.sender), id.toString(), b));
+    }
+}

package/dist/host/roster.d.ts

@@ -0,0 +1,72 @@
+import { type Server } from "node:http";
+import { type TreeBlocks } from "../runtime/tree.ts";
+import { type InstanceRow } from "./instances.ts";
+export interface RosterEntry {
+    handle: string;
+    domain: string;
+    identity: string;
+    displayName: string;
+    description: string;
+    emoji?: string;
+    avatar?: string;
+    status: "live" | "idle";
+}
+export type IdentityFields = Pick<RosterEntry, "displayName" | "description" | "emoji" | "avatar">;
+/** IDENTITY.md's `- Key: value` lines (first of each wins); missing ones are "" (name, description) or absent. */
+export declare function parseIdentity(text: string): IdentityFields;
+/** The row's entry; `blocks` holds its store, if there is one to read. A tree not (yet) in the store reads as no IDENTITY.md. */
+export declare function rosterEntry(row: InstanceRow, blocks: TreeBlocks | undefined, live: boolean): Promise<RosterEntry>;
+/**
+ * IDENTITY.md's fields in the row's deployed tree: empty ones if the tree has
+ * none, undefined if there is no tree or `blocks` does not have it (yet).
+ */
+export declare function deployedIdentity(row: InstanceRow, blocks: TreeBlocks | undefined): Promise<IdentityFields | undefined>;
+/** The heading of every ROSTER.md. */
+export declare const ROSTER_HEADING = "## Colleagues";
+/**
+ * `row`'s ROSTER.md: the rows it knows among `rows` (in their order; itself
+ * never; `knows` naming no row is skipped), one line each —
+ * `- @handle@domain — Name: description` (no name: the handle; no
+ * description: no ": …"). Undefined when it knows nobody: no file.
+ */
+export declare function rosterFor(row: InstanceRow, rows: InstanceRow[], fields: (row: InstanceRow) => Promise<IdentityFields>): Promise<string | undefined>;
+/**
+ * The roster of `rows` (the caller passes the enabled ones). `open` gives a
+ * row's store to read, or undefined, and how to let go of it.
+ */
+export declare function roster(rows: InstanceRow[], open: (row: InstanceRow) => Promise<{
+    blocks?: TreeBlocks;
+    close?(): Promise<void> | void;
+}>, live: (row: InstanceRow) => boolean): Promise<RosterEntry[]>;
+/** One instance as the operator page shows it. */
+export interface HostRow {
+    handle: string;
+    domain: string;
+    identity: string;
+    status: "live" | "idle" | "not run";
+    store: string;
+    tree: string;
+    pid?: number;
+    restarts: number;
+    /** The instance's origin: a skein from the default image serves the management site there (#92). */
+    origin?: string;
+    /** The instance's next wake (ms), if it has one: the waker's earliest, or the cron provider's next tick (#69). */
+    wake?: number;
+}
+/** The router's side of the page (#40): where it is, each instance's origin, the mailbox instances. */
+export interface HostInfo {
+    router?: string;
+    originOf?(handle: string): string;
+    mailboxes?: Array<{
+        handle: string;
+        domain: string;
+        owner?: string | null;
+    }>;
+}
+/** The host's operator page (#23): read-only, one row per enabled instance, a link to each one's origin. */
+export declare function hostPage(rows: HostRow[], info?: HostInfo): string;
+/**
+ * GET /roster.json → get(), CORS *; GET / → page(), if given. Resolves once
+ * listening (port 0: any; see server.address()).
+ */
+export declare function serveRoster(port: number, get: () => Promise<RosterEntry[]>, host?: string, page?: () => Promise<string>): Promise<Server>;