@dcasegr/skein 0.0.0-stage → 0.1.2

package/dist/host/kernel.js

@@ -0,0 +1,603 @@
+// One instance's kernel as the router holds it (#33): a `skein-kernel serve`
+// process spoken to over its stdin/stdout — length-prefixed dag-cbor frames
+// (kernel-zig/src/ipc.zig). This is the kernel's whole surface:
+//
+//   the router asks      tip · get · put · has · putblock · restore · append · genesis · boxes · byEnvelope ·
+//                        admit (the one call in that writes: a request as received, #68, a feed's or a
+//                        proof's event) · answer (#66: wait on the thread a request entry launched; its answer once it
+//                        comes to rest, or its state at the wait's bound) · call (#40: a program's function
+//                        over the state, no entry, no writes: host-side reads only) · idle · start · running
+//   the kernel asks      wallet (a BRC-100 wire frame → its answer: the signer, #67; #157: nothing
+//                        else — the in-step authfetch and its `http` frame are gone)
+//   the host chain       headers {raws} · chain-import {set, root} · chain (#156: the header chain the
+//                        host keeps once, in the kernel process — a serve instance's in its own store —
+//                        → {root, height, hash, added?, replaced?} | null)
+//   the kernel tells     emit (#70: a signed message for the host to carry out — {message, body,
+//                        transport, address}, a `local` provider's or the libp2p node's, the answer
+//                        coming back as an entry; #65: a broadcast event, transport `event`) · stop
+//
+// Nothing here keeps an instance's time (#69, #126): a step's deadline and a
+// shell's sleep are `deadline` events the host's waker keeps.
+//
+// `Kernel` offers `store` (get/put/log), `admit`, `answer`, `invoke` (the call),
+// `boxes`, `idle`. Log lines (stderr) go to `log`.
+//
+// Two ways to run kernels (#158): `Kernel` is one `skein-kernel serve`
+// process per instance (a SQLite file or an LMDB set); `KernelHost` is the one
+// `skein-kernel host` process of a host whose instances are sets of a RocksDB
+// database (SKEIN_STORE_ROCKSDB), every frame tagged with the instance's
+// handle `h`, and `HostedKernel` its per-instance view with the same surface
+// (`KernelSurface`): hydrate = `open`, stop = `close`. The router holds either.
+// The settled split (2026-10-31): a third, `WasmKernel` (wasm-kernel.ts) — the
+// kernel as a wasm module the host LOADS, one per active instance on a worker
+// thread of this process, over a set of the host's one SQLite database
+// (`sqlite:<path>`); what the npm package runs. These two are the native host,
+// kept for file, LMDB and RocksDB stores.
+import { spawn } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { WalletWireProcessor } from "@bsv/sdk";
+import { decode, encode } from "../runtime/cid.js";
+import { parseLmdbSpec, parseRocksSpec } from "../runtime/index-store.js";
+import { now as clockNow } from "./clock.js";
+import { NotFound, Rejected } from "../runtime/store.js";
+const ROOT = resolvePath(dirname(fileURLToPath(import.meta.url)), "../..");
+/** The kernel binary: $SKEIN_KERNEL_BIN, else kernel-zig's release build. */
+export const KERNEL_BIN = process.env.SKEIN_KERNEL_BIN || join(ROOT, "kernel-zig/zig-out/bin/skein-kernel");
+export { DoorAnswered, doorAnswer } from "./door-answer.js";
+import { DoorAnswered, doorAnswer } from "./door-answer.js";
+/**
+ * What the router holds of an instance's kernel, whichever process runs it (#158): the frames
+ * above, as calls. `call` is the transport's; the rest is built on it.
+ */
+export class KernelSurface {
+    /** Pending calls in both directions: the router stops a kernel only when this is 0. */
+    busy = 0;
+    last = Date.now();
+    gone = false;
+    store = {
+        get: async (cid) => { const v = await this.call("get", cid); if (v === null || v === undefined)
+            throw new NotFound(cid.toString()); return v; },
+        put: async (value) => await this.call("put", value),
+        has: async (cid) => (await this.call("get", cid)) != null,
+        log: {
+            tip: async () => await this.call("tip") ?? undefined,
+            byEnvelope: async (envelope) => await this.call("byEnvelope", envelope) ?? undefined,
+            append: async (entry) => await this.call("append", entry),
+        },
+    };
+    /** Any block, whatever its codec. */
+    async hasBlock(cid) { return await this.call("has", cid) === true; }
+    /** A block minted elsewhere (git-raw, raw, dag-cbor, bitcoin-*), hash-checked by the kernel (#4: the loader's pre-fill). */
+    async putBlock(cid, bytes) { await this.call("putblock", { cid, bytes }); }
+    /** Adopt a checkpoint's state record (its blocks put first) as this empty store's state (#4). */
+    async restore(state) { await this.call("restore", state); }
+    async boxes() { return await this.call("boxes"); }
+    /** The dispatch table as it stands (#77): its chain's tip (the change key; null before the genesis is processed) and its rows. */
+    async dispatch() { return await this.call("dispatch"); }
+    async genesis() { return await this.call("genesis"); }
+    /**
+     * Admit an arrival (#163): its entry's body and its stamp (`time`, the host's clock at
+     * admission; default now) — the kernel appends it, assigning `prev` and `n` from its own tip.
+     * A request's record beside it (#121: the kernel puts it, after the door), an event's likewise
+     * (#164: through the door when its box's route names kernel.beef), else put first. A request
+     * or event the door turns away or answers writes no entry (#143): DoorAnswered. The entry's CID.
+     */
+    async admit(body, records = {}, time = clockNow()) {
+        const r = await this.call("admit", { entry: { ...body, time }, ...(records.body ? { body: records.body } : {}), ...(records.request ? { request: records.request } : {}), ...(records.event ? { event: records.event } : {}) });
+        const answered = r?.answered;
+        if (answered && typeof answered === "object" && !(r instanceof Uint8Array))
+            throw new DoorAnswered(doorAnswer(answered));
+        return r;
+    }
+    /**
+     * The kernel's `call` (#40): a program's function (by CID, or a genesis
+     * program's name) over the current state — no entry, no writes, the signer
+     * and http answered but not recorded; fuel-limited (`callFuelLimit`). The
+     * result is what the program wrote to stdout; `fuel` is reported either way
+     * (the router's ledger). On a hosted kernel (#158) it reads the state as
+     * committed, beside a step that may be running.
+     */
+    async invoke(program, fn, arg, o = {}) {
+        return await this.call("call", { program, fn, arg, ...(o.caller ? { caller: o.caller } : {}), now: o.now ?? Date.now() });
+    }
+    /**
+     * A synchronous client's wait (#66): the answer of the thread a request
+     * entry launched (the middleware stepped on it), once that thread has come
+     * to rest for good — finished (`answer`: the middleware's dag-cbor answer)
+     * or errored — or, `waitMs` on, its state as it stands (`waiting`; or
+     * `pending`: the entry not processed yet). The kernel keeps the bound, so
+     * this always settles.
+     */
+    async answer(entry, waitMs) {
+        return await this.call("answer", { entry, wait: Math.max(0, Math.floor(waitMs)) });
+    }
+    async idle() { await this.call("idle"); }
+    async start() { await this.call("start"); }
+    /** #156: a run of headers (parents first) into the host chain this instance reads; its record and tip after. */
+    async chainHeaders(raws) { return tipOf(await this.call("headers", { raws })); }
+    /** #156: an image's chain/headers (the tree `root`, held by this instance) into the empty host chain. */
+    async chainImport(root) { return tipOf(await this.call("chain-import", { set: this.o.handle, root })); }
+    /** #156: the host chain as it stands, or undefined (empty). */
+    async chainTip() { const v = await this.call("chain"); return v == null ? undefined : tipOf(v); }
+    async tip() { return this.store.log.tip(); }
+}
+function tipOf(v) {
+    const o = v;
+    return { root: o.root, height: Number(o.height), hash: o.hash, ...(o.added !== undefined ? { added: Number(o.added) } : {}), ...(o.replaced !== undefined ? { replaced: Number(o.replaced) } : {}) };
+}
+/**
+ * The kernel's own request (`wallet`, `http`) or notice (`emit`, `stop`), answered for instance `o`
+ * through `answer`/`fail` — the same for a serve process and a hosted instance.
+ */
+async function kernelRequest(k, wire, f, answer, fail) {
+    const o = k.o;
+    k.busy++;
+    k.last = Date.now();
+    try {
+        switch (f.op) {
+            case "wallet":
+                if (!wire)
+                    throw new Error("no wallet");
+                return answer(Uint8Array.from(await wire.transmitToWallet([...f.v])));
+            case "emit":
+                // A signed message (#70) or an event (#65) to carry out, its step committed: nothing goes back.
+                o.emit?.(f.v);
+                return;
+            case "stop": return;
+        }
+    }
+    catch (e) {
+        if (f.id !== undefined)
+            fail(e);
+        else
+            o.log?.(`router: ${String(f.op)}: ${e.message}`);
+    }
+    finally {
+        k.busy--;
+        k.last = Date.now();
+    }
+}
+/** Length-prefixed dag-cbor frames out of a byte stream (ipc.zig). */
+class FrameReader {
+    buf = Buffer.alloc(0);
+    onFrame;
+    constructor(onFrame) { this.onFrame = onFrame; }
+    push(d) {
+        this.buf = Buffer.concat([this.buf, d]);
+        while (this.buf.length >= 4) {
+            const n = this.buf.readUInt32BE(0);
+            if (this.buf.length < 4 + n)
+                break;
+            const f = decode(this.buf.subarray(4, 4 + n));
+            this.buf = this.buf.subarray(4 + n);
+            this.onFrame(f);
+        }
+    }
+}
+function frameBytes(v) {
+    const body = encode(v).bytes;
+    const h = Buffer.alloc(4);
+    h.writeUInt32BE(body.length);
+    return Buffer.concat([h, body]);
+}
+/** Lines of a child's stderr, whole. */
+function lines(stream, each) {
+    let partial = "";
+    stream.on("data", (d) => {
+        const s = partial + d.toString();
+        const ls = s.split("\n");
+        partial = ls.pop();
+        for (const l of ls)
+            each(l);
+    });
+}
+export class Kernel extends KernelSurface {
+    o;
+    proc;
+    nextId = 1;
+    waiting = new Map();
+    reader;
+    wire;
+    done;
+    constructor(o) {
+        super();
+        this.o = o;
+        if (o.wallet)
+            this.wire = new WalletWireProcessor(o.wallet);
+        if (parseRocksSpec(o.db))
+            throw new Error(`kernel ${o.handle}: a RocksDB set (${o.db}) runs in the host's one kernel process (KernelHost), not in serve`);
+        // #96: an LMDB set's kernel gets SKEIN_STORE (its set is its handle); a file's gets SKEIN_DB and never a SKEIN_STORE.
+        const env = { ...process.env, ...o.env, SKEIN_HANDLE: `${o.handle}@${o.domain}` };
+        const lmdb = parseLmdbSpec(o.db);
+        if (lmdb && lmdb.set !== o.handle)
+            throw new Error(`kernel ${o.handle}: its LMDB set is its handle, not ${lmdb.set}`);
+        if (lmdb) {
+            env.SKEIN_STORE = lmdb.dir;
+            delete env.SKEIN_DB;
+        }
+        else {
+            env.SKEIN_DB = o.db;
+            delete env.SKEIN_STORE;
+        }
+        this.proc = spawn(o.command ?? KERNEL_BIN, ["serve"], {
+            env,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        lines(this.proc.stderr, (l) => o.log?.(l));
+        this.reader = new FrameReader((f) => void this.onFrame(f));
+        this.proc.stdout.on("data", (d) => this.reader.push(d));
+        this.proc.stdin.on("error", () => { }); // EPIPE once it is gone
+        this.done = new Promise((resolve) => this.proc.once("close", (code, signal) => {
+            this.gone = true;
+            for (const w of this.waiting.values())
+                w.reject(new Error(`kernel ${o.handle}: exited (${signal ?? code})`));
+            this.waiting.clear();
+            o.exited?.(code, signal);
+            resolve();
+        }));
+        this.proc.on("error", (e) => o.log?.(`kernel: ${e.message}`));
+    }
+    get pid() { return this.proc.pid; }
+    // ---------------------------------------------------------------- frames
+    write(v) {
+        if (this.gone)
+            throw new Error(`kernel ${this.o.handle}: not running`);
+        this.proc.stdin.write(frameBytes(v));
+    }
+    call(op, v) {
+        const id = this.nextId++;
+        this.busy++;
+        this.last = Date.now();
+        return new Promise((resolve, reject) => {
+            this.waiting.set(id, { resolve, reject });
+            try {
+                this.write({ id, op, v });
+            }
+            catch (e) {
+                this.waiting.delete(id);
+                reject(e);
+            }
+        }).finally(() => { this.busy--; this.last = Date.now(); });
+    }
+    async onFrame(f) {
+        if (typeof f.re === "number") {
+            const w = this.waiting.get(f.re);
+            if (!w)
+                return;
+            this.waiting.delete(f.re);
+            settle(w, f);
+            return;
+        }
+        // A process that is gone is reported by its exit; any other write failure (a frame that does not encode) is logged.
+        const unwritten = (x) => { if (!this.gone)
+            this.o.log?.(`the answer to the kernel's ${String(f.op)} frame not written: ${x.message ?? String(x)}`); };
+        await kernelRequest(this, this.wire, f, (ok) => { try {
+            this.write({ re: f.id, ok });
+        }
+        catch (x) {
+            unwritten(x);
+        } }, (e) => { try {
+            this.write({ re: f.id, error: e.message ?? String(e) });
+        }
+        catch (x) {
+            unwritten(x);
+        } });
+    }
+    /** Print the ready line (`skein runtime <identity> (<handle>@<domain>) · pid …`). */
+    async running(identity) { this.write({ op: "running", v: identity }); }
+    /** Close the channel; the kernel stops at EOF. SIGTERM after `killAfterMs`, SIGKILL after twice that. */
+    async stop(killAfterMs = 10_000) {
+        if (this.gone)
+            return;
+        this.proc.stdin.end();
+        const t = setTimeout(() => this.proc.kill("SIGTERM"), killAfterMs);
+        const k = setTimeout(() => this.proc.kill("SIGKILL"), 2 * killAfterMs);
+        await this.done;
+        clearTimeout(t);
+        clearTimeout(k);
+    }
+    exited() { return this.done; }
+}
+function settle(w, f) {
+    if (typeof f.rejected === "string")
+        w.reject(new Rejected(f.rejected, String(f.error)));
+    else if (typeof f.error === "string")
+        w.reject(new Error(f.error));
+    else
+        w.resolve(f.ok);
+}
+/**
+ * The host's one `skein-kernel host` process over the RocksDB database at `dir` (#158): every
+ * instance of the host in it, each a `HostedKernel`. One per database per node process
+ * (`KernelHost.acquire`, counted: the routers and one-shot boots of a process share it; the last
+ * `release` stops it). The process is started at acquire; if it dies, every instance's view is
+ * gone (their `exited` called) and the next `open` starts it again (the router hydrates on demand,
+ * replay at hydrate as for serve).
+ */
+export class KernelHost {
+    static all = new Map();
+    /** The process for the database at `dir`, started if this node process has none. */
+    static acquire(dir, o = {}) {
+        let h = KernelHost.all.get(dir);
+        if (!h) {
+            h = new KernelHost(dir, o);
+            KernelHost.all.set(dir, h);
+        }
+        h.holders++;
+        h.ensure();
+        return h;
+    }
+    /** Whether this node process runs the kernel process for `dir` (stores.ts waits for its socket then). */
+    static running(dir) { const h = KernelHost.all.get(dir); return !!h?.proc && !h.dead; }
+    dir;
+    o;
+    proc;
+    holders = 0;
+    nextId = 1;
+    waiting = new Map();
+    views = new Map();
+    /** A handle's close in flight: its next open waits for it. */
+    closing = new Map();
+    done;
+    dead = false;
+    /** #156: the last `headers` runs asked for (their answers shared). */
+    recent = new Map();
+    constructor(dir, o) { this.dir = dir; this.o = o; }
+    ensure() {
+        if (this.proc && !this.dead)
+            return;
+        mkdirSync(this.dir, { recursive: true });
+        const proc = spawn(this.o.command ?? KERNEL_BIN, ["host"], {
+            env: { ...process.env, ...this.o.env, SKEIN_STORE_ROCKSDB: this.dir },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.proc = proc;
+        this.dead = false;
+        lines(proc.stderr, (l) => {
+            // An instance's line: `@<handle> <line>` (host.zig sayFor) → that instance's log.
+            const m = /^@(\S+) (.*)$/s.exec(l);
+            const v = m ? this.views.get(m[1]) : undefined;
+            if (v)
+                v.o.log?.(m[2]);
+            else
+                this.o.log?.(l);
+        });
+        const reader = new FrameReader((f) => void this.onFrame(f));
+        proc.stdout.on("data", (d) => reader.push(d));
+        proc.stdin.on("error", () => { });
+        this.done = new Promise((resolve) => proc.once("close", (code, signal) => {
+            this.dead = true;
+            if (this.proc === proc)
+                this.proc = undefined;
+            if (code !== 0)
+                this.o.log?.(`skein-kernel host exited (${signal ?? `code ${code}`})`);
+            for (const w of this.waiting.values())
+                w.reject(new Error(`skein-kernel host: exited (${signal ?? code})`));
+            this.waiting.clear();
+            const views = [...this.views.values()];
+            this.views.clear();
+            this.closing.clear();
+            for (const v of views)
+                v.lost(code, signal);
+            resolve();
+        }));
+        proc.on("error", (e) => this.o.log?.(`skein-kernel host: ${e.message}`));
+    }
+    write(v) {
+        if (!this.proc || this.dead)
+            throw new Error("skein-kernel host: not running");
+        this.proc.stdin.write(frameBytes(v));
+    }
+    /** A frame to the process (`h`: an instance's, else a host-level op) and its answer. */
+    request(h, op, v) {
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.waiting.set(id, { resolve, reject });
+            try {
+                this.write({ id, op, ...(h !== undefined ? { h } : {}), v });
+            }
+            catch (e) {
+                this.waiting.delete(id);
+                reject(e);
+            }
+        });
+    }
+    /** A frame that wants no answer. */
+    tell(h, op, v) { this.write({ op, h, v }); }
+    async onFrame(f) {
+        if (typeof f.re === "number") {
+            const w = this.waiting.get(f.re);
+            if (!w)
+                return;
+            this.waiting.delete(f.re);
+            settle(w, f);
+            return;
+        }
+        const v = typeof f.h === "string" ? this.views.get(f.h) : undefined;
+        const unwritten = (x) => { if (!this.dead)
+            this.o.log?.(`the answer to the kernel's ${String(f.op)} frame not written: ${x.message ?? String(x)}`); };
+        const answer = (ok) => { try {
+            this.write({ re: f.id, ...(typeof f.h === "string" ? { h: f.h } : {}), ok });
+        }
+        catch (x) {
+            unwritten(x);
+        } };
+        const fail = (e) => { try {
+            this.write({ re: f.id, ...(typeof f.h === "string" ? { h: f.h } : {}), error: e.message ?? String(e) });
+        }
+        catch (x) {
+            unwritten(x);
+        } };
+        if (!v) {
+            if (f.op === "stop")
+                return;
+            if (f.id !== undefined)
+                fail(new Error(`no instance ${String(f.h)} open here`));
+            return;
+        }
+        await v.onKernelFrame(f, answer, fail);
+    }
+    /** Hydrate an instance (#158 `open`): its set opened in the process, its runtime built (replay at hydrate). */
+    async open(o) {
+        const p = parseRocksSpec(o.db);
+        if (!p)
+            throw new Error(`kernel ${o.handle}: ${o.db} is not a RocksDB set`);
+        if (p.set !== o.handle)
+            throw new Error(`kernel ${o.handle}: its RocksDB set is its handle, not ${p.set}`);
+        if (p.dir !== this.dir)
+            throw new Error(`kernel ${o.handle}: its database is ${p.dir}, this process's ${this.dir}`);
+        await this.closing.get(o.handle)?.catch(() => { });
+        if (this.views.has(o.handle))
+            throw new Error(`kernel ${o.handle}: open already`);
+        this.ensure();
+        const v = new HostedKernel(this, o);
+        this.views.set(o.handle, v);
+        try {
+            await this.request(o.handle, "open", { domain: o.domain, db: o.db });
+        }
+        catch (e) {
+            if (this.views.get(o.handle) === v)
+                this.views.delete(o.handle);
+            v.lost(null, null, true);
+            throw e;
+        }
+        return v;
+    }
+    /** Dehydrate (#158 `close`): after its inbox drains, its runtime freed. */
+    async close(v) {
+        if (this.views.get(v.o.handle) !== v)
+            return;
+        const p = this.request(v.o.handle, "close");
+        this.closing.set(v.o.handle, p);
+        try {
+            await p;
+        }
+        finally {
+            if (this.closing.get(v.o.handle) === p)
+                this.closing.delete(v.o.handle);
+            if (this.views.get(v.o.handle) === v)
+                this.views.delete(v.o.handle);
+        }
+    }
+    /** The instances open in the process (#158 `instances`). */
+    async instances() { return await this.request(undefined, "instances"); }
+    /** The host reads (#158): a block by CID — through `set`'s gate if named, else whichever set holds it; a set's committed state pointer. */
+    async get(cid, set) { return await this.hostRead("get", cid, set) ?? undefined; }
+    async has(cid, set) { return await this.hostRead("has", cid, set) === true; }
+    /** A host read, through `set`'s gate when one is named. */
+    hostRead(op, cid, set) {
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.waiting.set(id, { resolve, reject });
+            try {
+                this.write({ id, op, ...(set !== undefined ? { set } : {}), v: cid });
+            }
+            catch (e) {
+                this.waiting.delete(id);
+                reject(e);
+            }
+        });
+    }
+    async state(set) { return await this.request(set, "state") ?? undefined; }
+    /**
+     * #156: a run of headers into the host chain (the frame `headers`, run in order on the process's
+     * chain thread). The same run asked for again while it is in flight or just answered (every
+     * instance subscribed to one feed asks for the same SSE event) is one frame: its answer shared.
+     */
+    chainHeaders(raws) {
+        const key = raws.map((r) => Buffer.from(r).toString("hex")).join("");
+        const had = this.recent.get(key);
+        if (had)
+            return had;
+        const p = this.request(undefined, "headers", { raws }).then(tipOf);
+        this.recent.set(key, p);
+        p.catch(() => this.recent.delete(key));
+        while (this.recent.size > 64)
+            this.recent.delete(this.recent.keys().next().value);
+        return p;
+    }
+    /** #156: an image's chain/headers (the tree `root`, whose blocks the set `set` holds) into the empty host chain. */
+    async chainImport(set, root) { return tipOf(await this.request(undefined, "chain-import", { set, root })); }
+    /** #156: the host chain as it stands, or undefined (empty). */
+    async chainTip() { const v = await this.request(undefined, "chain"); return v == null ? undefined : tipOf(v); }
+    /** One holder less; the last one's release stops the process (every instance closed, the database flushed). */
+    async release() {
+        if (--this.holders > 0)
+            return;
+        KernelHost.all.delete(this.dir);
+        await this.shutdown();
+    }
+    /** `stop`: the process finishes what runs, closes every instance and the database, exits. */
+    async shutdown(killAfterMs = 30_000) {
+        const proc = this.proc;
+        if (!proc || this.dead)
+            return;
+        const t = setTimeout(() => proc.kill("SIGTERM"), killAfterMs);
+        const k = setTimeout(() => proc.kill("SIGKILL"), 2 * killAfterMs);
+        try {
+            await this.request(undefined, "stop");
+        }
+        catch { /* it exited */ }
+        proc.stdin.end();
+        await this.done;
+        clearTimeout(t);
+        clearTimeout(k);
+    }
+    /** Until the process has exited. */
+    exited() { return this.done ?? Promise.resolve(); }
+}
+/** One instance of the host's one kernel process (#158): the `Kernel` surface over frames tagged `h`. */
+export class HostedKernel extends KernelSurface {
+    o;
+    host;
+    wire;
+    resolveDone;
+    done = new Promise((r) => { this.resolveDone = r; });
+    constructor(host, o) {
+        super();
+        this.host = host;
+        this.o = o;
+        if (o.wallet)
+            this.wire = new WalletWireProcessor(o.wallet);
+    }
+    get pid() { return this.host.proc?.pid; }
+    call(op, v) {
+        if (this.gone)
+            return Promise.reject(new Error(`kernel ${this.o.handle}: not running`));
+        this.busy++;
+        this.last = Date.now();
+        return this.host.request(this.o.handle, op, v).finally(() => { this.busy--; this.last = Date.now(); });
+    }
+    async onKernelFrame(f, answer, fail) {
+        await kernelRequest(this, this.wire, f, answer, fail);
+    }
+    async running(identity) { this.host.tell(this.o.handle, "running", identity); }
+    /** #156: the host chain is the process's, not the instance's: its host-level frames. */
+    chainHeaders(raws) { return this.host.chainHeaders(raws); }
+    chainImport(root) { return this.host.chainImport(this.o.handle, root); }
+    chainTip() { return this.host.chainTip(); }
+    /** Close the instance in the process (its inbox drained first); the process keeps running. */
+    async stop() {
+        if (this.gone)
+            return;
+        try {
+            await this.host.close(this);
+        }
+        catch (e) {
+            this.o.log?.(`kernel: close: ${e.message}`);
+        }
+        this.lost(0, null);
+    }
+    /** Gone: closed, or the process exited (code/signal), or its open failed (`quiet`: no exited). */
+    lost(code, signal, quiet = false) {
+        if (this.gone)
+            return;
+        this.gone = true;
+        if (!quiet)
+            this.o.exited?.(code, signal);
+        this.resolveDone();
+    }
+    exited() { return this.done; }
+}

package/dist/host/liveness.d.ts

@@ -0,0 +1,65 @@
+import type { Store } from "../runtime/store.ts";
+/** A window's bounds (ms): a second, a day (subscriptions.zig LIVENESS_MIN_MS / _MAX_MS). */
+export declare const LIVENESS_MIN_MS = 1000;
+export declare const LIVENESS_MAX_MS = 86400000;
+/** One app's liveness for a topic: how long a beat stays live (ms). */
+export interface Live {
+    app: string;
+    topic: string;
+    window: number;
+}
+export type LivenessEvent = {
+    event: "liveness";
+    live: Live;
+} | {
+    event: "unliveness";
+    app: string;
+    topic: string;
+};
+/** A `liveness` / `unliveness` event record, read (subscriptions.zig livenessEventOf); or why it is not one this host follows. */
+export declare function livenessEvent(rec: Record<string, unknown>): LivenessEvent | {
+    refused: string;
+};
+/** Fold liveness events in order: a liveness replaces the app's own on the topic, an unliveness removes it. */
+export declare function foldLiveness(events: Iterable<LivenessEvent>, into?: Live[]): Live[];
+/** The liveness standing, folded from the store's log as the subscriptions and beacons are (p2p.ts subscriptionsOf). Read only. */
+export declare function livenessOf(store: Pick<Store, "get" | "chains" | "edges">): Promise<Live[]>;
+/** A beat kept: the sender's identity key (hex), the beat's time, its body, the peer that published it (peer ID). */
+export interface LiveBeat {
+    sender: string;
+    at: number;
+    body: Uint8Array;
+    from: string;
+}
+/** A message's verdict for GossipSub: a verified beat is accepted (forwarded), a bad one rejected, a stale one ignored. */
+export type LiveVerdict = "accept" | "reject" | "ignore";
+/** The tool's state: per instance, the apps' liveness and the beats kept per topic (in memory). */
+export declare class Liveness {
+    private lives;
+    /** handle → topic → sender → the latest beat. */
+    private beats;
+    private readonly now;
+    /** Told each beat newly kept (shruggr/skein#150: the overlay's sync reads a peer's tip anchor from it). */
+    kept?: (handle: string, topic: string, beat: LiveBeat) => void;
+    constructor(now?: () => number);
+    /** `handle`'s apps keep this liveness now: the beats of topics none keeps any more are dropped. */
+    set(handle: string, lives: Live[]): void;
+    /** The topics `handle`'s apps keep liveness for (each once). */
+    topics(handle: string): string[];
+    /** Whether an app of `handle` keeps liveness for `topic`. */
+    takes(handle: string, topic: string): boolean;
+    /** The longest window on `topic` among `handle`'s apps (ms), or undefined. */
+    private windowOf;
+    /**
+     * A message on `topic` at `handle`'s node, published by peer `from`: kept when it is a beat whose
+     * instance signature verifies (beaconBeat) and is newer than the longest window on the topic — the
+     * sender's latest replaces an older one. Nothing logged.
+     */
+    observe(handle: string, topic: string, frame: Uint8Array, from: string): LiveVerdict;
+    /** The beats live for `app`'s liveness on `topic` (newer than its window), newest first; undefined: the app keeps no liveness for the topic. */
+    read(handle: string, app: string, topic: string): LiveBeat[] | undefined;
+    /** Every beat live on `topic` at `handle` (newer than the longest window on it), whichever app keeps it. */
+    live(handle: string, topic: string): LiveBeat[];
+    /** Forget `handle`: its liveness and its beats. */
+    drop(handle: string): void;
+}