@dcasegr/skein 0.0.0-stage → 0.1.2

package/dist/host/kernel.d.ts

@@ -0,0 +1,246 @@
+import type { DispatchRow } from "../runtime/dispatch.ts";
+import { type ChildProcess } from "node:child_process";
+import { type WalletInterface } from "@bsv/sdk";
+import type { CID } from "multiformats/cid";
+import type { EntryBody } from "../runtime/log.ts";
+import type { Stamp } from "../runtime/syscalls.ts";
+import { type Store } from "../runtime/store.ts";
+import type { Outgoing } from "./providers.ts";
+/** The kernel binary: $SKEIN_KERNEL_BIN, else kernel-zig's release build. */
+export declare const KERNEL_BIN: string;
+type Frame = Record<string, unknown>;
+/** A request thread's answer (#66, the `answer` frame): at rest (finished | errored), or not yet at the wait's bound. */
+export type RequestAnswer = {
+    thread?: CID;
+    state: "finished";
+    answer: Uint8Array;
+} | {
+    thread?: CID;
+    state: "errored";
+    error: string;
+} | {
+    thread?: CID;
+    state: "waiting" | "running" | "new" | "pending";
+};
+export { DoorAnswered, doorAnswer, type DoorAnswer } from "./door-answer.ts";
+/** The host chain as the kernel answers it (#156): its record's CID and tip; `headers`/`chain-import` also count. */
+export type HostChainTip = {
+    root: CID;
+    height: number;
+    hash: string;
+    added?: number;
+    replaced?: number;
+};
+/** A kernel call's answer (#40): the program's stdout, or its error; the fuel it used either way. */
+export type CallAnswer = {
+    ok: true;
+    result: Uint8Array;
+    fuel: number;
+} | {
+    ok: false;
+    error: string;
+    fuel: number;
+};
+export interface KernelOptions {
+    /** The store file, or a set of the host's LMDB environment, `lmdb:<env dir>#<handle>` (#96: the kernel gets SKEIN_STORE). */
+    db: string;
+    handle: string;
+    domain: string;
+    /** Answers the kernel's `wallet` frames: the instance's signer. Absent: every wallet call fails. */
+    wallet?: WalletInterface;
+    /** A message (#70) or an event (#65) the kernel hands over to carry out (the `emit` notice): a `local` provider's, the libp2p node's, the broadcaster's (providers.ts). Absent: dropped. */
+    emit?(o: Outgoing): void;
+    /** Log lines (the kernel's stderr and this side's notes). */
+    log?(line: string): void;
+    /** The process exited (code or signal). */
+    exited?(code: number | null, signal: string | null): void;
+    /** Environment for the process, added to this one's. */
+    env?: Record<string, string | undefined>;
+    command?: string;
+}
+/**
+ * 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 declare abstract class KernelSurface {
+    abstract readonly o: KernelOptions;
+    /** Pending calls in both directions: the router stops a kernel only when this is 0. */
+    busy: number;
+    last: number;
+    gone: boolean;
+    /** The kernel process's pid (a hosted instance's: the host process's). */
+    abstract get pid(): number | undefined;
+    abstract call(op: string, v?: unknown): Promise<unknown>;
+    /** Print the ready line (`skein runtime <identity> (<handle>@<domain>) · pid …`). */
+    abstract running(identity: string): Promise<void>;
+    abstract stop(killAfterMs?: number): Promise<void>;
+    abstract exited(): Promise<void>;
+    readonly store: Store;
+    /** Any block, whatever its codec. */
+    hasBlock(cid: CID): Promise<boolean>;
+    /** A block minted elsewhere (git-raw, raw, dag-cbor, bitcoin-*), hash-checked by the kernel (#4: the loader's pre-fill). */
+    putBlock(cid: CID, bytes: Uint8Array): Promise<void>;
+    /** Adopt a checkpoint's state record (its blocks put first) as this empty store's state (#4). */
+    restore(state: CID): Promise<void>;
+    boxes(): Promise<string[]>;
+    /** The dispatch table as it stands (#77): its chain's tip (the change key; null before the genesis is processed) and its rows. */
+    dispatch(): Promise<{
+        tip: CID | null;
+        rows: DispatchRow[];
+    }>;
+    genesis(): Promise<Record<string, unknown>>;
+    /**
+     * 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.
+     */
+    admit(body: EntryBody, records?: {
+        body?: Uint8Array;
+        request?: Record<string, unknown>;
+        event?: Record<string, unknown>;
+    }, time?: Stamp): Promise<CID>;
+    /**
+     * 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.
+     */
+    invoke(program: CID | string, fn: string, arg: Uint8Array, o?: {
+        caller?: Uint8Array;
+        now?: number;
+    }): Promise<CallAnswer>;
+    /**
+     * 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.
+     */
+    answer(entry: CID, waitMs: number): Promise<RequestAnswer>;
+    idle(): Promise<void>;
+    start(): Promise<void>;
+    /** #156: a run of headers (parents first) into the host chain this instance reads; its record and tip after. */
+    chainHeaders(raws: Uint8Array[]): Promise<HostChainTip>;
+    /** #156: an image's chain/headers (the tree `root`, held by this instance) into the empty host chain. */
+    chainImport(root: CID): Promise<HostChainTip>;
+    /** #156: the host chain as it stands, or undefined (empty). */
+    chainTip(): Promise<HostChainTip | undefined>;
+    tip(): Promise<CID | undefined>;
+}
+export declare class Kernel extends KernelSurface {
+    readonly o: KernelOptions;
+    readonly proc: ChildProcess;
+    private nextId;
+    private waiting;
+    private reader;
+    private wire?;
+    private done;
+    constructor(o: KernelOptions);
+    get pid(): number | undefined;
+    private write;
+    call(op: string, v?: unknown): Promise<unknown>;
+    private onFrame;
+    /** Print the ready line (`skein runtime <identity> (<handle>@<domain>) · pid …`). */
+    running(identity: string): Promise<void>;
+    /** Close the channel; the kernel stops at EOF. SIGTERM after `killAfterMs`, SIGKILL after twice that. */
+    stop(killAfterMs?: number): Promise<void>;
+    exited(): Promise<void>;
+}
+export interface KernelHostOptions {
+    command?: string;
+    /** Environment for the process, added to this one's (SKEIN_WORKERS, SKEIN_HOME…). */
+    env?: Record<string, string | undefined>;
+    /** The process's own lines (not an instance's). */
+    log?(line: string): void;
+}
+/**
+ * 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 declare class KernelHost {
+    private static all;
+    /** The process for the database at `dir`, started if this node process has none. */
+    static acquire(dir: string, o?: KernelHostOptions): KernelHost;
+    /** Whether this node process runs the kernel process for `dir` (stores.ts waits for its socket then). */
+    static running(dir: string): boolean;
+    readonly dir: string;
+    readonly o: KernelHostOptions;
+    proc?: ChildProcess;
+    private holders;
+    private nextId;
+    private waiting;
+    private views;
+    /** A handle's close in flight: its next open waits for it. */
+    private closing;
+    private done?;
+    private dead;
+    /** #156: the last `headers` runs asked for (their answers shared). */
+    private recent;
+    private constructor();
+    private ensure;
+    private write;
+    /** A frame to the process (`h`: an instance's, else a host-level op) and its answer. */
+    request(h: string | undefined, op: string, v?: unknown): Promise<unknown>;
+    /** A frame that wants no answer. */
+    tell(h: string, op: string, v?: unknown): void;
+    private onFrame;
+    /** Hydrate an instance (#158 `open`): its set opened in the process, its runtime built (replay at hydrate). */
+    open(o: KernelOptions): Promise<HostedKernel>;
+    /** Dehydrate (#158 `close`): after its inbox drains, its runtime freed. */
+    close(v: HostedKernel): Promise<void>;
+    /** The instances open in the process (#158 `instances`). */
+    instances(): Promise<string[]>;
+    /** 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. */
+    get(cid: CID, set?: string): Promise<Uint8Array | undefined>;
+    has(cid: CID, set?: string): Promise<boolean>;
+    /** A host read, through `set`'s gate when one is named. */
+    private hostRead;
+    state(set: string): Promise<CID | 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: Uint8Array[]): Promise<HostChainTip>;
+    /** #156: an image's chain/headers (the tree `root`, whose blocks the set `set` holds) into the empty host chain. */
+    chainImport(set: string, root: CID): Promise<HostChainTip>;
+    /** #156: the host chain as it stands, or undefined (empty). */
+    chainTip(): Promise<HostChainTip | undefined>;
+    /** One holder less; the last one's release stops the process (every instance closed, the database flushed). */
+    release(): Promise<void>;
+    /** `stop`: the process finishes what runs, closes every instance and the database, exits. */
+    shutdown(killAfterMs?: number): Promise<void>;
+    /** Until the process has exited. */
+    exited(): Promise<void>;
+}
+/** One instance of the host's one kernel process (#158): the `Kernel` surface over frames tagged `h`. */
+export declare class HostedKernel extends KernelSurface {
+    readonly o: KernelOptions;
+    readonly host: KernelHost;
+    private wire?;
+    private resolveDone;
+    private done;
+    constructor(host: KernelHost, o: KernelOptions);
+    get pid(): number | undefined;
+    call(op: string, v?: unknown): Promise<unknown>;
+    onKernelFrame(f: Frame, answer: (ok: unknown) => void, fail: (e: unknown) => void): Promise<void>;
+    running(identity: string): Promise<void>;
+    /** #156: the host chain is the process's, not the instance's: its host-level frames. */
+    chainHeaders(raws: Uint8Array[]): Promise<HostChainTip>;
+    chainImport(root: CID): Promise<HostChainTip>;
+    chainTip(): Promise<HostChainTip | undefined>;
+    /** Close the instance in the process (its inbox drained first); the process keeps running. */
+    stop(): Promise<void>;
+    /** Gone: closed, or the process exited (code/signal), or its open failed (`quiet`: no exited). */
+    lost(code: number | null, signal: string | null, quiet?: boolean): void;
+    exited(): Promise<void>;
+}