@dcasegr/skein 0.0.0-stage → 0.1.2

package/dist/host/router.d.ts

@@ -0,0 +1,782 @@
+import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { PrivateKey, ProtoWallet, type WalletInterface } from "@bsv/sdk";
+import { CID } from "multiformats/cid";
+import type { Stamp } from "../runtime/syscalls.ts";
+import { Broadcaster, type ArcConfig } from "./arc.ts";
+import { Feeds, type FeedSpec } from "./feeds.ts";
+import { Cron } from "./cron.ts";
+import { type DispatchRow } from "../runtime/dispatch.ts";
+import { type BootSource, type Booted } from "./boot.ts";
+import { ImageChain } from "./image-chain.ts";
+import { OverlaySync } from "./sync.ts";
+import { type AddressSeed, type DispatchSpec, type Genesis2Config, type Libp2pSpec } from "./genesis.ts";
+import { HANDLE, type HostDb, type InstanceRow } from "./instances.ts";
+import { type KernelSurface } from "./kernel.ts";
+import { type Live } from "./liveness.ts";
+import { EventStreams } from "./events.ts";
+import { P2PHost, type Beacon, type InboundAnswer, type InboundCall, type P2PHostConfig, type Subscription } from "./p2p.ts";
+import { Providers, type HttpRequest, type HttpResponse, type MailRecord, type ProviderName } from "./providers.ts";
+import { Deliverer } from "./deliver.ts";
+import { type BillingConfig, type BillingView } from "./billing.ts";
+type Named = {
+    handle: string;
+    domain: string;
+};
+export interface RouterOptions {
+    db: HostDb;
+    /** Each row's signer: the wallet its kernel's `wallet` import is answered from. */
+    walletFor(row: InstanceRow): Promise<WalletInterface> | WalletInterface;
+    /** A new agent's genesis: its owner (required to write one), the inference peer, their names. */
+    owner?: string;
+    infer?: string;
+    ownerHandle?: Named;
+    inferHandle?: Named;
+    fuelPerStep?: string;
+    /** A new genesis's extra routes — boxes (a box and its handler) and routes of any transport (#143: no sender) — and defaults (over DEFAULTS), e.g. the wallet's (#29). */
+    genesis?: {
+        subscriptions?: Array<{
+            box: string;
+            handler: CID;
+        }>;
+        defaults?: Record<string, string>;
+        feeds?: FeedSpec[];
+        libp2p?: Libp2pSpec;
+        dispatch?: DispatchSpec[];
+    };
+    /** The router-held feeds' limits (feeds.ts); the backoff is the broadcaster's subscription's too. */
+    feeds?: {
+        maxQueue?: number;
+        backoff?: {
+            min: number;
+            max: number;
+        };
+    };
+    /** The host's headers feed (#102, SKEIN_HEADERS_URL): an SSE stream of block headers every enabled instance whose dispatch table takes events in box `chain` is subscribed to. */
+    headersFeed?: string;
+    /** The host's Arcade (#58, #65, arc.ts): where the broadcast events go, the status subscription, the `status` provider. Absent: no broadcaster (a broadcast event is dropped). */
+    arc?: ArcConfig;
+    /** Tests: how the broadcaster reaches Arcade. */
+    arcFetch?: typeof fetch;
+    /** The broadcaster's queue: how soon a broadcast Arcade did not take is posted again (ms, doubling; default 1 000 → 300 000). */
+    arcRetry?: {
+        min: number;
+        max: number;
+    };
+    /** The HTTP proxy's network (#70, the `fetch` provider) for URLs that are not this host's; default: SKEIN_HTTP=fetch performs them (fetchHttp), else refused. */
+    http?(req: HttpRequest): Promise<HttpResponse>;
+    /** Stop a kernel this long after its last call (ms); 0: never (the default: instances are not stopped until resource contention appears). */
+    idleMs?: number;
+    /** How long a synchronous client waits on its request's thread (#66) before 503 + Retry-After (ms); default SKEIN_ANSWER_WAIT_MS, else two minutes. */
+    answerWaitMs?: number;
+    /** Where a new mailbox instance's store goes: <home>/instances/<handle>/runtime.db. */
+    home?: string;
+    /** SKEIN_STORE (#96): the host's LMDB environment (a directory); a new instance's store is then its set there (host.db `lmdb:<dir>`, the set its handle). Unset: a file, <home>/instances/<handle>/runtime.db. */
+    lmdbStore?: string;
+    /**
+     * SKEIN_STORE_ROCKSDB (#158): the host's RocksDB database (a directory), run by one
+     * `skein-kernel host` process this router starts (KernelHost): a new instance's store is its set
+     * there (host.db `rocksdb:<dir>`, the set its handle). Over `lmdbStore`.
+     */
+    rocksStore?: string;
+    /**
+     * SKEIN_STORE_SQLITE (the settled split, 2026-10-31): the host's one SQLite database (a file); a
+     * new instance's store is then its set there (host.db `sqlite:<path>`, the set its handle), run by
+     * the wasm kernel this process loads (wasm-kernel.ts). Over `rocksStore` and `lmdbStore`.
+     */
+    sqliteStore?: string;
+    /** An instance's origin, `{handle}` and `{port}` filled in; default http://{handle}.localhost:{port}. */
+    instanceOrigin?: string;
+    /** This host's own origin (the manifest, a genesis's resolveOrigin); default http://127.0.0.1:{port}. */
+    origin?: string;
+    /** The port it serves on, for origins named before it listens (a boot, `skein-host add`); listening sets it. */
+    port?: number;
+    /** The owner's messagebox URL for a new agent's genesis; default the owner's mailbox instance here, if there is one. */
+    ownerMessagebox?: string;
+    /** The network the whole host runs on (SKEIN_NETWORK): every genesis it makes has it as `defaults.walletNetwork`. */
+    network?: string;
+    /** How often the fuel ledger is written (ms); default 5000. */
+    ledgerMs?: number;
+    /** Tests: the clock entries are stamped with (and ticks fall due by: cron.ts). */
+    now?: () => Stamp;
+    /** The cron provider's clock (#69, cron.ts): false — this router sends no ticks (a one-shot command's router is no clock; it still keeps a schedule a step asks for, in host.db). Default true. */
+    cron?: boolean;
+    /** Lines, by source: an instance's handle, or "router". */
+    log?(source: string, line: string): void;
+    /** Kernel process settings. */
+    kernel?: {
+        command?: string;
+        env?: Record<string, string | undefined>;
+    };
+    /** The libp2p host (#51, p2p.ts): its host-wide settings (default: loopback TCP + WS, no DHT, no mDNS). */
+    libp2p?: P2PHostConfig;
+    /** An instance's libp2p peer key (signer.ts peerKey). Absent: no libp2p host; the kernels' `libp2p` is refused. */
+    peerKeyFor?(handle: string): PrivateKey;
+    /**
+     * A provider's key (#70, signer.ts providerKey: the HTTP proxy `fetch`, the
+     * `waker`, `cron`, `libp2p`, `status`), which each new genesis's address
+     * book names. Absent: keys of this router's own, made fresh (a test's; a
+     * restarted router would not be the providers its instances know).
+     */
+    providerKeyFor?(name: ProviderName): PrivateKey;
+    /**
+     * Tests: the host's own origin's BRC-169 requests (DISCOVERY) answered
+     * when the host has no host skein — a fixture resolver over host.db
+     * (testhost.ts). A host's are always the host skein's.
+     */
+    discovery?(req: RouterRequest, url: URL): Promise<RouterResponse | undefined>;
+    /** How often the libp2p host redials bootstrap peers and runs topic rendezvous (ms); default 30 000. */
+    libp2pDiscoveryMs?: number;
+    /** #130: what this host bills (billing.ts; `skein-host run`: billingConfig over the environment). Absent: it bills no one. */
+    billing?: BillingConfig;
+    /**
+     * #160, #162: a one-key host's shared key's wallet (signer.ts Signer.oneKey). With it, an instance the
+     * host creates (createInstance) with no forwarded claim is claimed by the host itself: the claim
+     * message signed by this key (its owner), appended as a forwarded claim is. Absent (a master-key
+     * host): a create needs the owner's own signed claim, as before.
+     */
+    claimer?: WalletInterface;
+    /**
+     * #162, SKEIN_MANAGER_FOR (host env): the instances besides the host skein the instance manager
+     * takes messages from — the manager in their address book at birth, as in the host skein's (not the
+     * certifier). No other instance reaches it.
+     */
+    managerFor?: string[];
+    /** SKEIN_ROOT_INSTANCE: the instance served at `/` of any hostname that is no instance's (the standalone's one app at localhost:<port>/). */
+    rootInstance?: string;
+    /** #162, SKEIN_IMAGES_DIR (default $SKEIN_HOME/images): the images a create names by name, a directory each (the layout `skein-host add --image <dir>` takes). */
+    imagesDir?: string;
+    /**
+     * #164: an application host's wiring (providers.ts `appEvent`): an emitted event whose name no
+     * stock wiring takes, from `handle`, handed over after its step's commit. Absent: logged as ignored.
+     */
+    appEvent?(handle: string, record: Record<string, unknown>): void;
+}
+interface Loaded {
+    row: InstanceRow;
+    kernel: KernelSurface;
+    identity: string;
+    wallet: WalletInterface;
+    /** The genesis (its `libp2p`), and the dispatch table's tip as the libp2p node last followed it (#72, #77). */
+    genesis: Record<string, unknown>;
+    dispatchTip?: string;
+    /** The dispatch table as last read (syncDispatch). */
+    rows?: DispatchRow[];
+    /** The apps' subscriptions (#119): folded from the log at hydrate, then followed live. */
+    subs: Subscription[];
+    /** The apps' beacons (#126): folded from the log at hydrate, then followed live; an uninstalled app's (no row left) dropped. */
+    beacons: Beacon[];
+    /** The apps' liveness (#138): folded from the log at hydrate, then followed live; an uninstalled app's (no row left) dropped. */
+    live: Live[];
+}
+/** A request as the router takes it: the full URL (its host is the Host header's), lower-cased headers, the body. */
+export interface RouterRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body: Uint8Array; /** The instance whose `http` this is (none for a socket's). */
+    from?: string;
+}
+export interface RouterResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: Uint8Array;
+}
+export { HANDLE };
+/** Handles no instance may take on this host (H3), besides the router origin's own first label (Router.reserved): `id` (the router's own in production) and `host` (the host skein's). */
+export declare const RESERVED_HANDLES: Set<string>;
+/** The registration signature (#113: the onboarding app checks it): [2, "skein register"], key ID the username, counterparty anyone, over `register <username>@<domain>`. */
+export declare const REGISTER_PROTOCOL: [2, string];
+/** The onboarding app (shruggr/skein-onboard, #90, #113): the host skein's app that serves BRC-169 on the host's own origin. */
+export declare const ONBOARD_APP = "onboard";
+/**
+ * The host's own origin's BRC-169 requests (#113) → the host skein's routes
+ * (the onboarding app's, under /onboard/): method + path → route.
+ */
+export declare const DISCOVERY: Record<string, string>;
+/** The paymail PKI (`GET /bsvalias/id/<handle>[@<domain>]`) → the app's prefix row `/onboard/bsvalias/id/…`. */
+export declare const PAYMAIL_PREFIX = "/bsvalias/id/";
+/** The BRC-169 domain a host name stands for: a dev router at a loopback address answers for `localhost`. */
+export declare const domainOf: (hostname: string) => string;
+/**
+ * The BRC-169 domain of this host (H4): its public origin's host name
+ * (SKEIN_ROUTER_ORIGIN, default the loopback: `localhost`). What a created
+ * instance, a claim and a mailbox instance record when nothing names one,
+ * and what /.well-known/skein-host answers.
+ */
+export declare const hostDomain: (origin: string) => string;
+/**
+ * SKEIN_HTTP=fetch: the HTTP proxy's requests (#70, the `fetch` provider)
+ * performed for real; `timeoutMs` (default 30 000) bounds the whole exchange,
+ * `maxBytes` (#91) the response body: reading stops past it, and the request
+ * fails.
+ */
+export declare function fetchHttp(req: HttpRequest): Promise<HttpResponse>;
+/**
+ * The warning for an agent whose genesis names no owner messagebox
+ * (`defaults.ownerMessagebox`): its sends to the owner — every answer to him —
+ * fail, since nothing else tells it where his mailbox is. Undefined if it names one.
+ */
+export declare function noOwnerMessagebox(genesis: Record<string, unknown> | null | undefined): string | undefined;
+export declare class Router {
+    readonly o: RouterOptions;
+    readonly feeds: Feeds;
+    /** The cron provider's schedules (#69). */
+    readonly cron: Cron;
+    /** The host's broadcaster (#58, #65): present when the host has an Arcade. */
+    readonly arc?: Broadcaster;
+    /** The libp2p host (#51): one node per instance whose genesis declares libp2p. */
+    readonly p2p?: P2PHost;
+    /** shruggr/skein#150: overlay sync over the libp2p node (sync.ts). */
+    readonly sync?: OverlaySync;
+    /** The host's providers (#70): what carries the instances' messages out. */
+    readonly providers: Providers;
+    /** #148: the pages' subscriptions to their apps' emitted events (GET /<app>/.events), per instance. */
+    readonly events: EventStreams;
+    /** The certifier (#100, #113): signs the BRC-169 handle certificates, for the host skein's onboarding app (the `certifier` provider). */
+    readonly certifier: ProtoWallet;
+    /** #157: the `deliver` intention's carrier (BRC-103/104, the sessions the host keeps). */
+    readonly deliverer: Deliverer;
+    readonly loaded: Map<string, Loaded>;
+    private loading;
+    /** #156: the host chain record each running instance was last sent (a `chain` event), by handle; cleared at each start. */
+    private sentChain;
+    /** Rows being created (#90): hydrated before their hostname is published (disabled until claimed). */
+    private unpublished;
+    private queues;
+    /** The libp2p nodes following their dispatch tables (#72: syncDispatch after a settle). */
+    private syncing;
+    private idleTimer?;
+    private ledgerTimer?;
+    /** The fuel of calls not yet written to the ledger: instance\0caller\0op → {calls, fuel}. */
+    private owed;
+    private stopped;
+    private closing?;
+    /** Settles when the router starts shutting down: every client still waiting on a thread is answered 503 (#66). */
+    private stopping;
+    private stopNow;
+    /** Requests being forwarded (their clients held on a thread). */
+    private inflight;
+    servers: Server[];
+    port: number;
+    /** The control socket (control.ts), while this router listens on one. */
+    private control?;
+    /** The default image (#89), with its chain part (#132): what createInstance boots a new skein from. */
+    readonly image: ImageChain;
+    /** #130: each billed instance as last read (its host row's terms, the kernel's billing state), and what this host metered since its last tick. */
+    private views;
+    private periods;
+    /** Instances a tick is on its way to; and those sent their first (billing starts with it) since this router started: the timer sends it again. */
+    private ticking;
+    private firstTicks;
+    private tickTimer?;
+    /** The host's provider keys (its billing key among them, #130). */
+    private readonly providerKey;
+    /** The one-process kernels this router holds (#158), by database directory. */
+    private kernelHosts;
+    private wasmHosts;
+    /** The wasm kernel's host over the SQLite database at `db` (the settled split): its machines, its host chain. */
+    private wasmHost;
+    /** The `skein-kernel host` process for the RocksDB database at `dir` (#158), started on first use. */
+    private kernelHost;
+    constructor(o: RouterOptions);
+    private say;
+    private now;
+    /** The router's clock, as entries are stamped. */
+    nowStamp(): Stamp;
+    /** This host's own origin. */
+    origin(): string;
+    /**
+     * The first label of the router's own origin, when its host name is a
+     * name (`id` for id.skein.nexus), else undefined: no instance may take it,
+     * so a request to the router's origin never reaches an instance (H3).
+     */
+    ownLabel(): string | undefined;
+    /** Whether `handle` is reserved on this host: `id`, `host` (RESERVED_HANDLES), or the router origin's own first label. */
+    reserved(handle: string): boolean;
+    /**
+     * The router's own label as an instance (2026-10-28, one public name): allowed only when the operator names
+     * that handle in SKEIN_MANAGER_FOR (managerFor) — the Open Exchange's config instance at the host's own
+     * origin. Its hostname then serves the instance; the router keeps /.well-known/skein-host, /skeins and
+     * /arc/callback there. Any other row named like the router's origin still never takes its requests.
+     */
+    ownLabelInstance(handle: string): boolean;
+    /** This host's BRC-169 domain: its origin's host name (hostDomain). */
+    domain(): string;
+    /** An instance's origin: where its front door is, what BRC-169 publishes as its messagebox. */
+    originOf(handle: string): string;
+    /** Hydrate every enabled row once (recovery at hydrate time: what a waiting thread awaits is handed to the providers again), then let them idle out. */
+    start(): Promise<void>;
+    /**
+     * Stop everything this router started (#61), once: the providers' (the
+     * waker's, the cron provider's), the idle reaper's and the ledger's timers
+     * (the owed fuel written first), its
+     * servers and their connections, the control socket (its file removed), the header feeds' and the broadcaster's
+     * SSE clients, the libp2p nodes, and every kernel process it spawned — one
+     * still hydrating included. Afterwards nothing of it keeps the process
+     * alive: `skein-host run`'s shutdown and every one-shot command that builds
+     * a router (`add --boot/--packet`) end with it.
+     */
+    close(): Promise<void>;
+    /** The same as `close()`. */
+    stop(): Promise<void>;
+    /**
+     * Listen on the control socket at `path` ($SKEIN_HOME/host.sock for
+     * `skein-host run`; mode 0600, no HTTP route): `skein-host event` sends its
+     * event here while this router runs, and it reaches the instance as a tick
+     * due now (cronEvent). Removed by `close()`.
+     */
+    listenControl(path: string): Promise<void>;
+    private shutdown;
+    /**
+     * `skein-host event` (#69): a message from the cron provider into `box`, as
+     * a tick due now would be — {...event, kind: event.kind ?? "cron", due:
+     * now}, signed by the provider and appended as a `local` request; the
+     * instance takes it by its subscription to the box (from the cron provider,
+     * or from anyone). The entry's CID.
+     */
+    cronEvent(handle: string, box: string, event: Record<string, unknown>): Promise<CID>;
+    /**
+     * A plain entry (#29, #65): a self-validating event from the host's wiring
+     * (a header feed, the broadcaster's proof), admitted into the instance in
+     * `box` with its record beside the entry (#164: the kernel puts it — after
+     * the door, when `box`'s event route names kernel.beef: its BEEFs decoded
+     * and checked, the bytes never stored; a BUMP that does not check, or no
+     * BEEF, is turned away: DoorAnswered, thrown, nothing written). The kernel
+     * routes it by its `subject` to the thread awaiting that record, else to
+     * `box`'s event route.
+     */
+    admitEvent(handle: string, box: string, event: Record<string, unknown>): Promise<CID>;
+    /**
+     * #157: a `deliver` intention from `handle`, carried (deliver.ts: BRC-103/104 with the instance's
+     * key) and its answer admitted in box `deliver` — it stands on its own at the door (the server's
+     * signature). No answer: nothing admitted, the thread rests (offered again at its next start).
+     */
+    deliver(handle: string, id: CID, rec: Record<string, unknown>): Promise<boolean>;
+    /**
+     * A message for an instance (#70): a provider's signed answer, a forwarded
+     * claim, or the loopback's own emit, appended as received — a `local`
+     * request entry, {kind: "message", message, body}; the front door checks it
+     * (the signature, or for the loopback the record in the store) and routes
+     * it. Nobody waits on it.
+     */
+    appendLocal(handle: string, pkg: Record<string, unknown>): Promise<CID>;
+    /**
+     * #142: a message signed outside the host (the client `skein`, with the operator's key), delivered on
+     * the host machine over the control socket: its mail record (dag-cbor) and body, appended as a `local`
+     * request (appendLocal — the path a forwarded claim takes). The front door checks the signature and
+     * admits it by the dispatch table as it would any signed message; this waits for its verdict and
+     * throws on a refusal. The host signs nothing. The entry.
+     */
+    messageLocal(handle: string, messageBytes: Uint8Array, body: Uint8Array): Promise<CID>;
+    /** Sign `data` with `handle`'s signer: [2, "metanet handles envelope"] / `send` / anyone — an intention request's signature (providers.ts), a beacon's beat (p2p.ts beaconFrame). */
+    private signAs;
+    /**
+     * An inbound libp2p message or stream frame (#51, #68): appended as
+     * received (the message with its signature; the frame), and the verdict
+     * — or the frame's answer — read off the thread the front door is stepped
+     * on, once it comes to rest (#66). The front door verifies, routes, and
+     * admits what an accept carries (the message's `p2p` event first); a
+     * redelivered message it accepted before is `ignore`. Its thread failing,
+     * or not answering within the wait, is `ignore` (no penalty). A frame a
+     * route's filter answers at the door (a read, #143: nothing written) is
+     * answered with the filter's body (#154: the overlay's sync protocol).
+     */
+    p2pInbound(handle: string, call: InboundCall): Promise<InboundAnswer>;
+    /** Until nothing is queued and every loaded kernel has processed what it was given (tests, corpus). */
+    settled(): Promise<void>;
+    /**
+     * Run `f` after everything else queued for this instance: the host's own admissions (events from its
+     * wiring, `local` messages: the waker's, the providers', the loopback, a forwarded claim) reach the
+     * kernel in the order the host made them, each after its hydrate and `closed` check, and `settled`
+     * waits on them. Not the log's order: the kernel assigns every entry's place (#163), so HTTP and
+     * libp2p arrivals, which do not queue here, need no queue.
+     */
+    serial<T>(handle: string, f: () => Promise<T>): Promise<T>;
+    /**
+     * The network the host chain is on: SKEIN_NETWORK (`network`), else the genesis defaults'
+     * `walletNetwork` (a test host's), else the kernel's default (main).
+     */
+    chainNetwork(): string | undefined;
+    /** The kernels' environment: the configured one, and the host chain's network (#156). */
+    private kernelEnv;
+    /**
+     * A run of headers from a feed for `handle` (#156): into the host chain — the one kernel
+     * process's for a RocksDB set (an instance not running is not hydrated for it: it gets the
+     * chain at its next start), the instance's own serve kernel's otherwise — then, when the
+     * record changed for it, the `chain` event.
+     */
+    chainHeaders(handle: string, box: string, raws: Uint8Array[]): Promise<void>;
+    /** The `chain` event (#156) for `handle` in `box`, unless it was sent that record already since its start. */
+    private chainEvent;
+    /**
+     * Fresh-host bootstrap (#156): the host chain empty and the instance's tree (its head `main`,
+     * an image's) carrying `chain/headers`: those imported into the host chain before the
+     * instance's first event. A tree with none, or a host chain with a tip: nothing.
+     */
+    private chainBootstrap;
+    /** At start (and once an app takes box `chain` — an install): the host chain's current record, as the `chain` event. */
+    private chainBirth;
+    /** The instance's kernel, started (and its genesis written) if it is not loaded. */
+    hydrate(handle: string): Promise<Loaded>;
+    private load;
+    /**
+     * Whether a stopped instance's route table routes an entry in `box` — an event, or (given a
+     * sender) a message: the kernel's rule (#77, #143: dispatch.zig forMail/forEvent, by the box
+     * alone; who may run the function is the gate's, when it is routed). Read from its store file,
+     * read-only, with no kernel.
+     */
+    subscribes(handle: string, box: string, sender?: string): Promise<boolean>;
+    /**
+     * Boot a row's empty store from a system tree or a checkpoint (issue #4,
+     * boot.ts) before its first hydration; the row's identity is its signer's.
+     */
+    bootRow(handle: string, src: BootSource, o?: {
+        image?: boolean;
+        manager?: boolean;
+        owner?: string;
+        appConfig?: Genesis2Config["appConfig"];
+    }): Promise<Booted>;
+    /** The owner's messagebox: configured, else its mailbox instance here. */
+    ownerMessagebox(): string | undefined;
+    /**
+     * A new agent's address book seed (#70): this host's providers — the HTTP
+     * proxy, the waker, the cron provider (#69), the libp2p node (when it runs
+     * one), the status provider (#65, when it has an Arcade) — and the owner's
+     * mailbox, when it knows it.
+     */
+    addressSeed(handle?: string): AddressSeed[];
+    /**
+     * What this host brings to an image's genesis (#89): only its own facts —
+     * the instance's identity, handle and domain, its providers in the address
+     * book, where its domain resolves, the host's defaults. No owner, no
+     * owner's mailbox, no inference peer, no names: the image is the same for
+     * everyone, and the owner is the claim's sender (#127). `manager`
+     * (#90, #113): the host skein's — the instance manager and the certifier
+     * in its address book too (no other instance's book names them).
+     */
+    imageConfig(row: Pick<InstanceRow, "handle" | "domain">, identity: string, o?: {
+        manager?: boolean;
+    }): Genesis2Config;
+    /** #162: whether SKEIN_MANAGER_FOR names `handle` (the instance manager in its address book, its messages taken). */
+    managerFor(handle: string): boolean;
+    /**
+     * #162: the image a create names, as a boot source — the built-in `default` (this host's, with its
+     * chain part), or a directory `<imagesDir>/<name>` (SKEIN_IMAGES_DIR, default $SKEIN_HOME/images;
+     * the layout `skein-host add --image <dir>` takes: with no bin/ merged over the default image as
+     * images/host is, with bin/ a complete image). Its path resolved first (a link to an app repository's
+     * image/ reads `..` beside the repository's image, not beside the link).
+     */
+    private namedImage;
+    /** #162: an image by name: its directory under imagesDir (resolved), or undefined. */
+    private imageDir;
+    /** Whether `owner` holds root on the instance (#143: the head `grants`): claimed by that key. */
+    private claimedBy;
+    /**
+     * A new instance from an image, owned by `owner` (#90: the instance
+     * manager's `create`; `skein-host init` for the host skein). In this order:
+     * the row, disabled (no hostname: nothing reaches it); its identity
+     * derived (the signer's, key ID = the handle) and its store booted from the
+     * image (only `default`, the default image, so far); its kernel started
+     * unpublished; `claim` (#127) — the owner's own signed claim, a message in
+     * box `claim` naming no recipient (it was signed before the instance
+     * existed), with its body — forwarded into it as a `local` request, its
+     * first entry after the genesis: the front door checks the signature, and
+     * the kernel takes the owner from the signer (the owner's admin rows
+     * written, the claim row removed); only then (`publish`, default true) the
+     * row enabled, which publishes its hostname. No request can reach the claim
+     * row first. The host signs nothing for the owner. With no `claim` (a bare
+     * image: `skein-host init`), the instance keeps its claim row, from anyone:
+     * the first sender of a claim owns it. `host`: the host skein — the
+     * instance manager and the certifier in its address book, and recorded as
+     * the host skein (host.db). `domain`: the handle's domain, recorded with
+     * the row (default `localhost`). A refusal throws (a bad or taken handle, a
+     * bad key, another image, a claim not `owner`'s or refused: the row is left
+     * disabled, its store kept for a look).
+     *
+     * `owned` (#164): a non-host image instance born owned as the host skein
+     * is — its genesis's `root` is `owner`, no claim (none taken, none made:
+     * the image's claim route is not seeded), no instance manager or
+     * certifier in its address book (those stay the host skein's and
+     * SKEIN_MANAGER_FOR's).
+     *
+     * Image `mailbox` (#113): a mailbox instance for `owner` — the front door
+     * and the messagebox, its owner in its genesis (no claim) — published at
+     * once (`publish`). The same owner and handle again: the same answer (it
+     * exists, enabled again if it was not, at `domain` if given); a key with
+     * another mailbox here is refused. One creation path: the manager's `create` (the onboarding app's
+     * registrations) and `skein-host add --mailbox` both come here.
+     */
+    createInstance(handle: string, owner: string, o?: {
+        image?: string;
+        host?: boolean;
+        owned?: boolean;
+        publish?: boolean;
+        domain?: string;
+        claim?: SignedClaim | unknown;
+        needsClaim?: boolean;
+        appConfig?: Genesis2Config["appConfig"];
+        topics?: string[];
+    }): Promise<{
+        handle: string;
+        identity: string;
+        url: string;
+    }>;
+    /** host.db's `store` for a new instance (#96): its set in the host's LMDB environment (SKEIN_STORE), else its own file. */
+    private newStore;
+    /** createInstance's image `mailbox` (#113). */
+    private createMailbox;
+    /**
+     * The instance manager's work (#90; providers.ts `manager`): a message from
+     * the host skein in box `create`, `start` or `stop` → the answer body. A
+     * refusal throws (the provider answers {error}).
+     */
+    private manage;
+    /**
+     * A create's `beef` (skein-amm#4): the Atomic BEEF handed into the new instance's receive row
+     * (/skein/overlay/beef/1.0.0) exactly as a catch-up's fetched BEEF is (sync.ts `deliver`), from the
+     * host's own peer, and the answer → {verdict, reason?}. No topic is named here: the instance's engine
+     * judges it under the topics its config declares. Turned away at the door (unmined, a bad BUMP): reported,
+     * not retried; the instance stays created.
+     */
+    private deliverBeef;
+    /** What this host brings to a new instance's genesis (boot.ts): the owner and its messagebox, the inference peer, their names, the host's defaults. */
+    genesisConfig(row: Pick<InstanceRow, "handle" | "domain"> & Partial<Pick<InstanceRow, "kind" | "owner">>, identity: string, code?: boolean): Genesis2Config;
+    /**
+     * The kernel counts as busy until it has processed what was just admitted
+     * (its `idle` answers after the drain); then the libp2p node and the host's
+     * headers feed follow the dispatch table (#72, #77, #102).
+     */
+    private settle;
+    /**
+     * What the host does by the instance's dispatch table (#72, #77, #102):
+     * read the table (the kernel's `dispatch` frame); when its chain's tip
+     * moved since it was last followed (or `first`), the host's headers feed
+     * subscribes or unsubscribes it (followHeaders), and its libp2p node is
+     * declared again as its genesis and the table ask (p2p.ts libp2pConfig) —
+     * started, reconfigured (topics subscribed and unsubscribed, protocols
+     * handled and unhandled) or stopped. A failure is logged, not fatal.
+     */
+    private syncDispatch;
+    /** The instance's libp2p node declared as its genesis, its table and its apps' subscriptions (#119) ask. */
+    private declareP2P;
+    /** #138: the apps' liveness, folded from the instance's log (liveness.ts livenessOf), the store file read-only. */
+    private readLiveness;
+    /** #126: the apps' beacons, folded from the instance's log (p2p.ts beaconsOf), the store file read-only. */
+    private foldBeacons;
+    /**
+     * #119: the apps' subscriptions, folded from the instance's log — the
+     * libp2p node's recovery at hydrate, by reading (p2p.ts subscriptionsOf;
+     * the store file opened read-only beside the kernel, as `subscribes` reads it).
+     */
+    private foldSubscriptions;
+    /**
+     * A `subscribe` / `unsubscribe` event from `handle` (#119, after its step's
+     * commit; the kernel checked it as it was emitted): the subscriptions
+     * change and the node is declared again — the topic subscribed, or left
+     * when no subscription, row or genesis topic takes it any more. Which app's
+     * program runs for a message on it is the kernel's (the subscription). An
+     * instance still loading reads the event from its log at hydrate; it is
+     * applied after that too (the same result).
+     */
+    private topicEvent;
+    /**
+     * A `liveness` / `unliveness` event from `handle` (#138, after its step's commit; the kernel
+     * checked its shape as it was emitted): the liveness changes and the node's liveness tool follows
+     * it (P2PHost.liveness) — the topic subscribed without admitting its messages, or left. An instance
+     * still loading reads it from its log.
+     */
+    private livenessEvent;
+    /**
+     * GET /<app>/.live/<topic> at an instance's origin (#138): the liveness tool's set for the app's
+     * liveness on the topic, served by the host — no program, no entry, nothing logged; metered as a
+     * read (bytes served). 404 when the app keeps no liveness for the topic (or the host has no libp2p).
+     */
+    private liveRead;
+    /**
+     * GET /<app>/.events at an instance's origin (#148, events.ts): the app's emitted events of the
+     * asked name and topics as a Server-Sent Events stream — the backlog folded from the log, then each
+     * as it is handed over — held open until the client goes, the app is uninstalled or the instance
+     * stops. The host's own (no program, no entry, nothing logged); each message metered as a read.
+     */
+    private eventStream;
+    /** How long a peer that beat on a topic is remembered without beating again (ms): 30 days (David to review). */
+    static readonly PEER_KEEP_MS: number;
+    /**
+     * A beat kept from `peer` on `liveTopic` at `handle` (the settled sync design): when an overlay app
+     * of the instance beats on that topic, the peer and its addresses (the node's peer store) upserted
+     * into host.db `topic_peers`, keyed by the overlay topic. What a restart asks first.
+     */
+    private rememberPeer;
+    /**
+     * At a start (hydrate): for each overlay topic the instance beats on, the peers host.db remembers
+     * (rows older than PEER_KEEP_MS pruned first) dialled, a few at a time, failures dropped silently;
+     * each that answers asked at once — the locator and the tail (sync.ts `reconnect`) — without waiting
+     * for a beat.
+     */
+    private askKnownPeers;
+    /**
+     * shruggr/skein#154: our own overlay's read, for the sync's puller (its locator and what it lacks) —
+     * the engine's function `fn` (`anchors`, `admitted`) by a kernel call (the `call` op; nothing
+     * appended, nothing logged), not through the app's http table, which an app need not publish. The
+     * program is the app record's engine (its role `overlay`); the argument is what a read route's
+     * filter is handed (docs/APPS.md "Filters": the route handler contract's fields), `match` naming the
+     * app, so the engine reads its configuration from the app record as it does for its read routes.
+     * Its answer is the read route's `{status, type, body}`: the body's JSON, or a throw on another status.
+     */
+    private overlayRead;
+    /**
+     * A `beacon` / `unbeacon` event from `handle` (#126, after its step's commit;
+     * the kernel checked its shape as it was emitted): the beacons change and
+     * the node beats them (P2PHost.beacons) — started if a beacon needs it; the
+     * topic is not subscribed. An instance still loading reads it from its log.
+     */
+    private beaconEvent;
+    /**
+     * The host's headers feed (#102) for an instance whose dispatch table is
+     * `rows`: subscribed (box `chain`) while it is enabled and a row takes
+     * events in box `chain` by name (the chain app's `event` row; dispatch.zig
+     * forEvent) — a catch-all `*` row (a mailbox instance's) is not one —
+     * else not. One line when that changes.
+     */
+    private followHeaders;
+    /** Follow the host's headers feed for an instance whose status changed (#102): its table read again. */
+    private refollowHeaders;
+    /**
+     * The waker answers every wake-me due by this router's clock, and the cron
+     * provider sends every tick due (#69) — what their timers do in real time,
+     * for a clock that is not (a script clock: tests, the corpus).
+     */
+    wake(): Promise<void>;
+    /** An instance's next wake (ms), if any (the host page): the waker's earliest, or its next tick (#69). */
+    nextWake(handle: string): number | undefined;
+    /** Stop kernels idle for `ms` with nothing queued. Their deadlines and sleeps stay with the waker, their schedules with the cron provider. */
+    private reap;
+    private charge;
+    /** Write what calls cost since the last flush (host.db, never the log). */
+    flushLedger(): void;
+    /** Why this host forwards nothing to `handle` (undefined: it forwards as usual). */
+    closed(handle: string): string | undefined;
+    /** A billed instance as this host last read it (#130). */
+    billingView(handle: string): BillingView | undefined;
+    /** A line of this host's log for `handle`'s period (#130): a request it served, a read call it made. */
+    private meter;
+    /**
+     * Read the instance's billing (#130): its host row's terms (the dispatch table) and its kernel's
+     * billing state (the head `billing`), checked against what this host supports. A skein with a host
+     * row this host has not ticked yet is ticked now; one whose unreported amounts would take its tally
+     * to its allocation, early. When it went asleep (and woke) goes to host.db (the grace).
+     */
+    private syncBilling;
+    /** Tick every billed instance this router holds (the timer, every tickMs). */
+    private tickAll;
+    /**
+     * The host's tick to `handle` (#130 decided 4): signed by its billing key, in the host row's box —
+     * {kind: "tick", at, allowance, fuel, served, log} — the period since its last tick closed, its log
+     * record kept (host.db billing_ticks: `log` is that record's CID). Not to an instance the gate
+     * holds (asleep, other terms), nor twice at once. The tick's entry, or undefined.
+     */
+    billingTick(handle: string): Promise<CID | undefined>;
+    /**
+     * A `payment` event from `handle` (#130 decided 6: its pay step's, the kernel lets no other step
+     * emit one): this host is the payee. Its wiring: the payment kept (host.db billing_payments, with
+     * whether its output pays the key the BRC-29 remittance derives from this host's billing key) and
+     * broadcast (its Arcade, once).
+     */
+    private payment;
+    /**
+     * Reclaim an instance (#130 decided 9; `skein-host reclaim`): its kernel stopped, its row and its
+     * billing removed, its store deleted. The host's call to make, after the grace; nothing here makes
+     * it on its own. Not the host skein.
+     */
+    reclaim(handle: string): Promise<void>;
+    /** Whether a URL is this host's own (answered in process: no DNS, no socket). */
+    isLocal(url: string): boolean;
+    /** Which instance a URL is for: `/@<handle>` (stripped for the routes), or a `<handle>.` host name. */
+    target(url: URL): {
+        handle: string;
+        route: string;
+    } | undefined;
+    /**
+     * The HTTP proxy's request (#70, the `fetch` provider): this host's own URLs in
+     * process, the rest as configured. A delivery (`POST …/sendMessage`, from
+     * instance `from`) is logged in one line: where it went, how, and the result.
+     */
+    http(req: HttpRequest, from?: string): Promise<HttpResponse>;
+    /** One request, whoever made it: a socket's, or an instance's own http. */
+    dispatch(req: RouterRequest): Promise<RouterResponse>;
+    /**
+     * #161, #137: an overlay request at the bare host — POST /submit (the topics its X-Topics names: a
+     * comma list or a JSON array, as the overlay reads it) or POST /lookup (its JSON body's `service`,
+     * and a `topic` beside it or in its query) — routed to the instance that serves the names:
+     *
+     *   - a token's name, `tm_color_<id>` / `ls_color_<id>` whose `<id>` is an enabled path-only
+     *     instance here: that instance (#161, the handle naming convention; checked first);
+     *   - any other name (`tm_color`, `ls_color`, …): the enabled instance whose `topics` (the
+     *     names the instance manager's create or start named, host.db) contain it. Whether the instance
+     *     has run yet does not matter. Two instances taking the same name: a problem (400, "N instances
+     *     here take <name>").
+     *
+     * Every name that maps must map to the same instance (else a problem: 400); a name mapping to no
+     * instance here beside one that does is a problem too. Nothing maps: no handle (the hostname's
+     * instance, or the bare host, as before).
+     */
+    overlayTarget(path: "/submit" | "/lookup", req: RouterRequest): {
+        handle?: string;
+    } | {
+        problem: string;
+    };
+    /**
+     * GET /skeins?key=<hex> at the host's own origin: the skeins on this host whose head `grants`
+     * (#143) names `key` among root's holders — each enabled agent row's store file read read-only,
+     * no kernel — as JSON [{handle, identity, url}]. A key's skeins are the host's to say (no token
+     * in a wallet tracks them). Unsigned, anyone; mailbox instances are not listed.
+     */
+    private skeinsHeldBy;
+    /**
+     * GET /.well-known/skein at an instance's origin (its hostname, `/@<handle>/`, or the root instance's
+     * hostname): `{handle, identity, origin, claimed}` — `claimed` whether its head `grants` names a root
+     * holder (an image instance nobody has claimed: false). Read from its store read-only, no kernel, as
+     * /skeins does. Unsigned, anyone; 404 for no instance. "Am I root" is /skeins?key=<identity>.
+     */
+    private instanceCard;
+    /** The keys an instance's head `grants` names root (#143), its store read read-only; none when it has no store yet. */
+    private rootsOf;
+    /** A forwarded request, held among the in-flight ones (shutdown answers them 503). */
+    private held;
+    /**
+     * The handle domain (#113): the host skein's onboarding app's
+     * `config.onboard.domain` (the app record, a kernel read), the one setting
+     * every handle here is at. With no host skein or no app: this router's
+     * origin's host name as a domain.
+     */
+    handleDomain(): Promise<string>;
+    /** Arcade's webhook (#58, arc.ts); 404 when the host has no Arcade. */
+    private arcRequest;
+    /**
+     * A request for an instance (#68, #66): appended as received, and the
+     * client's connection held until the thread it launched comes to rest —
+     * then its answer, signed on the session inside. Past `answerWaitMs`, or
+     * when the router shuts down, 503 + Retry-After (the thread goes on). A
+     * read's call fuel (the explorer's) is charged to the ledger.
+     */
+    private forward;
+    /** The HTTP handler: CORS, then dispatch. */
+    handler(): (req: IncomingMessage, res: ServerResponse) => void;
+    /**
+     * Listen on `port` (0: any) at each of `hosts` (default the IPv4 and IPv6
+     * loopbacks: `<handle>.localhost` resolves to either).
+     */
+    listen(port: number, hosts?: string | string[]): Promise<Server>;
+}
+/**
+ * The owner's signed claim (#127): a message in box `claim`, signed by the
+ * owner (BRC-169's signing, counterparty anyone) and naming no recipient — it
+ * was signed before the instance it claims existed — with its body (dag-cbor
+ * bytes). The host forwards it as it is (Router.createInstance).
+ */
+export interface SignedClaim {
+    message: Omit<MailRecord, "recipient"> & {
+        recipient?: undefined;
+    };
+    body: Uint8Array;
+}