@dcasegr/skein 0.0.0-stage → 0.1.2

package/dist/runtime/log.d.ts

@@ -0,0 +1,62 @@
+import type { WalletProtocol } from "@bsv/sdk";
+import { CID } from "multiformats/cid";
+import { type Genesis } from "./records.ts";
+import type { LogEntry, Store } from "./store.ts";
+import { type Stamp } from "./syscalls.ts";
+import type { Ms } from "./types.ts";
+/** What an entry admits: exactly one of these (log.zig isLogEntry). */
+export type EntryBody = {
+    genesis: CID;
+} | {
+    request: CID;
+    transport: string;
+} | {
+    mail: CID;
+} | {
+    event: CID;
+    box: string;
+};
+/** A log entry in format 8. */
+export type Entry = {
+    kind: "log";
+    prev: CID | null;
+    n: number;
+    time: Stamp;
+} & EntryBody;
+/** A stamp as the `at` (ms) of the records written while processing its entry. */
+export declare const stampMs: (s: Stamp) => Ms;
+/**
+ * A format-8 entry, as log.zig's isLogEntry has it: `kind: "log"`, a number
+ * `n`, exactly one of genesis | mail | event | request, a non-empty `box` with
+ * an event and only with it, a non-empty `transport` with a request and only
+ * with it, and none of the older formats' fields (`sig`, `wake`,
+ * `envelope`, `body`, `outcome`).
+ */
+export declare function isLogEntry(x: unknown): x is Entry;
+/**
+ * The next entry: extending the tip, stamped `time` (raised to the tip's
+ * stamp if earlier). The host builds only the genesis this way (#163); the
+ * kernel keeps the same rule for every entry it appends.
+ */
+export declare function nextEntry(store: Store, body: EntryBody, time: Stamp): Promise<Entry>;
+export declare const LOG_PROTOCOL: WalletProtocol;
+export declare const LOG_KEY_ID = "1";
+/** A format-1 entry's signed bytes: its dag-cbor with `sig` removed. */
+export declare function entryBytes(e: LogEntry | Omit<LogEntry, "sig"> | Entry): Uint8Array;
+/**
+ * `fuelPerStep` (issue #5): the one limit on a step's fuel (wasm instructions)
+ * in the Zig kernel, which records every step's fuel on its update; a step
+ * that runs out ends `errored`, "fuel exhausted". 10^12, generous until
+ * something hits it.
+ */
+export declare const FUEL_PER_STEP = "1000000000000";
+export declare const DEFAULTS: Record<string, string>;
+/** The log as records, in order. */
+export declare function readLog(store: Store): Promise<Array<{
+    cid: CID;
+    entry: LogEntry;
+}>>;
+/** The genesis a log starts with. */
+export declare function genesisOf(store: Store): Promise<Genesis>;
+/** Short form for log lines. */
+export declare const short: (c: CID | string) => string;

package/dist/runtime/log.js

@@ -0,0 +1,104 @@
+// The input log (docs/VM.md, docs/MESSAGES.md "The log, format 8"): every
+// input, in order, as a hash chain of log-entry records. The kernel
+// (kernel-zig/src/log.zig) is authoritative: it refuses an entry that is
+// malformed or does not extend its tip. This is the host's mirror of the
+// shape, for building the genesis entry (src/host/genesis.ts over nextEntry)
+// and reading entries. Every other entry the kernel appends (#163: the host
+// hands over the body and its stamp, Kernel.admit; the kernel assigns prev
+// and n).
+//
+//   { kind: "log", prev: <entry | null>, n, time: [sec, nsec],
+//     genesis: <cid>                       n = 0: the starting state
+//   | request: <cid>, transport: <name>    a package as a transport carried it in (#68):
+//                                          the record of an http request, a libp2p message
+//                                          or frame, or a provider's signed message (`local`)
+//   | mail: <cid>                          a message the host admits directly (#40, #70)
+//   | event: <cid>, box: <name> }          a record from the host's wiring (a header, a
+//                                          proof), routed by box or subject (#29, #65)
+//
+// No signature (format 2, #33): the sender signed its request, `prev` fixes
+// the order, and the stamp is the host's word. The tip entry's CID is the
+// instance's **state hash**. `time` is the host's clock at admission, never
+// before the previous entry's; everything inside the machine derives time
+// from these stamps (syscalls.ts).
+import { CID } from "multiformats/cid";
+import { encode } from "./cid.js";
+import { isGenesis } from "./records.js";
+import { maxStamp } from "./syscalls.js";
+/** A stamp as the `at` (ms) of the records written while processing its entry. */
+export const stampMs = (s) => s[0] * 1000 + Math.floor(s[1] / 1_000_000);
+const isCid = (x) => CID.asCID(x) !== null;
+const isName = (x) => typeof x === "string" && x.length > 0;
+/**
+ * A format-8 entry, as log.zig's isLogEntry has it: `kind: "log"`, a number
+ * `n`, exactly one of genesis | mail | event | request, a non-empty `box` with
+ * an event and only with it, a non-empty `transport` with a request and only
+ * with it, and none of the older formats' fields (`sig`, `wake`,
+ * `envelope`, `body`, `outcome`).
+ */
+export function isLogEntry(x) {
+    const e = x;
+    if (!e || typeof e !== "object" || e.kind !== "log" || typeof e.n !== "number")
+        return false;
+    if (["sig", "wake", "envelope", "body", "outcome"].some((k) => e[k] !== undefined))
+        return false;
+    if (["genesis", "mail", "event", "request"].filter((k) => e[k] !== undefined).length !== 1)
+        return false;
+    if (e.event !== undefined ? !isCid(e.event) || !isName(e.box) : e.box !== undefined)
+        return false;
+    if (e.request !== undefined ? !isCid(e.request) || !isName(e.transport) : e.transport !== undefined)
+        return false;
+    if (e.mail !== undefined && !isCid(e.mail))
+        return false;
+    return true;
+}
+/**
+ * The next entry: extending the tip, stamped `time` (raised to the tip's
+ * stamp if earlier). The host builds only the genesis this way (#163); the
+ * kernel keeps the same rule for every entry it appends.
+ */
+export async function nextEntry(store, body, time) {
+    const tipCid = await store.log.tip();
+    const tip = tipCid ? await store.get(tipCid) : undefined;
+    return { kind: "log", prev: tipCid ?? null, n: tip ? tip.n + 1 : 0, time: tip ? maxStamp(time, tip.time) : time, ...body };
+}
+// ---------------------------------------------------------------- format 1
+// Before format 2 (#33) an entry was the host's statement, signed by the
+// host: protocol [2, "skein log"], key "1", counterparty anyone, over the
+// entry's dag-cbor without `sig`. The kernel refuses such a store; these are
+// kept for what makes one to check that (kernel-zig/equiv/old-store.ts) and
+// for the signature fixtures (kernel-zig/test/fixtures.ts).
+export const LOG_PROTOCOL = [2, "skein log"];
+export const LOG_KEY_ID = "1";
+/** A format-1 entry's signed bytes: its dag-cbor with `sig` removed. */
+export function entryBytes(e) {
+    const { sig: _, ...rest } = e;
+    return encode(rest).bytes;
+}
+/**
+ * `fuelPerStep` (issue #5): the one limit on a step's fuel (wasm instructions)
+ * in the Zig kernel, which records every step's fuel on its update; a step
+ * that runs out ends `errored`, "fuel exhausted". 10^12, generous until
+ * something hits it.
+ */
+export const FUEL_PER_STEP = "1000000000000";
+export const DEFAULTS = { model: "ripper/qwen38", thinking: "off", fuelPerStep: FUEL_PER_STEP };
+/** The log as records, in order. */
+export async function readLog(store) {
+    const out = [];
+    for await (const x of store.log.entries())
+        out.push(x);
+    return out;
+}
+/** The genesis a log starts with. */
+export async function genesisOf(store) {
+    for await (const { entry } of store.log.entries()) {
+        const g = entry.genesis ? await store.get(entry.genesis) : undefined;
+        if (!isGenesis(g))
+            throw new Error("log: entry 0 is not a genesis");
+        return g;
+    }
+    throw new Error("log: empty");
+}
+/** Short form for log lines. */
+export const short = (c) => c.toString().slice(-8);

package/dist/runtime/programs.d.ts

@@ -0,0 +1,30 @@
+import { CID } from "multiformats/cid";
+export declare const RAW = 85;
+/** CIDv1(raw, sha2-256) of a module's bytes: how modules are stored and named. */
+export declare function rawCid(bytes: Uint8Array): CID;
+/** The modules as committed under wasm/ (see wasm/README.md). A test checks these against the files. */
+export declare const MODULES: {
+    readonly wallet: CID<unknown, number, number, import("multiformats/cid").Version>;
+};
+/** The wallet program record's description (also the default image's bin/wallet.json: the same record, #116). */
+export declare const WALLET_DESCRIPTION = "The wallet (#29, #79, #116: core): its own records under wallet/ over the chain app's chain/state. A message's body {op: internalize|createAction|signAction|list, \u2026} (BRC-100's; every transaction ingested at the chain app); the kernel's pay step, args {pay: {to, x, checkpoint}} (#130: X sats, or all it has if less, to the host, the state record committed in a 0-sat OP_RETURN output, emitted as the event `payment`). Prints the result record's CID.";
+/**
+ * The wallet's state as records (issue #29; docs/WALLET.md): the `wallet`
+ * box's handler, written in Zig (programs/wallet, over the SDK's wallet library). In the default image
+ * by CID (#116, #130: images/default/bin/wallet.cid and wallet.json — this very record): every skein made
+ * from it pays its host from it. A code genesis has none: an instance that wants it subscribes a box to
+ * its record's CID (an owner's box).
+ */
+export declare const WALLET: import("./records.ts").Program;
+/** A wasm binary's kind by its preamble: a core module, a component (#34), or neither. */
+export declare function wasmKind(b: Uint8Array): "module" | "component" | undefined;
+/**
+ * The program record for bin/<name>.wasm or bin/<name>.cid (its module's CID),
+ * with bin/<name>.json's {inputs, services, description} if the tree has one:
+ * what a boot puts, and what an app install (install.ts, #72) sends.
+ */
+export declare function programRecord(name: string, module: CID, meta?: {
+    inputs?: unknown;
+    services?: string[];
+    description?: string;
+}): Record<string, unknown>;

package/dist/runtime/programs.js

@@ -0,0 +1,61 @@
+// The pinned modules as the node host names them: the wallet, by the CID of
+// its bytes under wasm/. `skein-dev install` puts them into a store file (the
+// bootstrap side door, docs/OPEN.md). The kernel's pins are the truth
+// (kernel-zig/src/programs.zig, which also pins the handler programs: the
+// front door, the messagebox, resolve); a test checks these against the
+// committed files. The shell is not pinned (#83): its modules are the shell
+// app's (shruggr/skein-shell), installed like any app's, and its program
+// record is written by that install (src/host/install.ts shellProgram).
+import { createHash } from "node:crypto";
+import { CID } from "multiformats/cid";
+import * as Digest from "multiformats/hashes/digest";
+import { program } from "./records.js";
+export const RAW = 0x55;
+/** CIDv1(raw, sha2-256) of a module's bytes: how modules are stored and named. */
+export function rawCid(bytes) {
+    return CID.createV1(RAW, Digest.create(0x12, createHash("sha256").update(bytes).digest()));
+}
+/** The modules as committed under wasm/ (see wasm/README.md). A test checks these against the files. */
+export const MODULES = {
+    // The wallet's state inside the VM (issue #29): Zig, wasm32-wasi (programs/wallet over the SDK's wallet library, built by scripts/build-programs.sh).
+    "wallet": CID.parse("bafkreifmo2fz45wn3vukhcf226bpnfh6klu7w5m43of76mx6olgghnzqkq"),
+};
+/** The wallet program record's description (also the default image's bin/wallet.json: the same record, #116). */
+export const WALLET_DESCRIPTION = "The wallet (#29, #79, #116: core): its own records under wallet/ over the chain app's chain/state. A message's body {op: internalize|createAction|signAction|list, …} (BRC-100's; every transaction ingested at the chain app); the kernel's pay step, args {pay: {to, x, checkpoint}} (#130: X sats, or all it has if less, to the host, the state record committed in a 0-sat OP_RETURN output, emitted as the event `payment`). Prints the result record's CID.";
+/**
+ * The wallet's state as records (issue #29; docs/WALLET.md): the `wallet`
+ * box's handler, written in Zig (programs/wallet, over the SDK's wallet library). In the default image
+ * by CID (#116, #130: images/default/bin/wallet.cid and wallet.json — this very record): every skein made
+ * from it pays its host from it. A code genesis has none: an instance that wants it subscribes a box to
+ * its record's CID (an owner's box).
+ */
+export const WALLET = program({
+    name: "wallet",
+    code: { wasm: MODULES.wallet },
+    inputs: { envelope: "cid", body: "cid", box: "string", sender: "identity", event: "cid" },
+    services: ["wallet", "http"],
+    description: WALLET_DESCRIPTION,
+});
+/** A wasm binary's kind by its preamble: a core module, a component (#34), or neither. */
+export function wasmKind(b) {
+    if (b.length < 8 || b[0] !== 0 || b[1] !== 0x61 || b[2] !== 0x73 || b[3] !== 0x6d)
+        return undefined;
+    if (b[4] === 1 && b[5] === 0 && b[6] === 0 && b[7] === 0)
+        return "module";
+    if (b[4] === 0x0d && b[5] === 0 && b[6] === 1 && b[7] === 0)
+        return "component";
+    return undefined;
+}
+/** A handler program's record inputs when bin/<name>.json gives none (the kernel's handler inputs). */
+const HANDLER_INPUTS = { message: "cid", body: "cid", box: "string", sender: "identity" };
+/**
+ * The program record for bin/<name>.wasm or bin/<name>.cid (its module's CID),
+ * with bin/<name>.json's {inputs, services, description} if the tree has one:
+ * what a boot puts, and what an app install (install.ts, #72) sends.
+ */
+export function programRecord(name, module, meta = {}) {
+    return {
+        kind: "program", name, code: { wasm: module },
+        inputs: meta.inputs ?? HANDLER_INPUTS, services: meta.services ?? [], description: meta.description ?? `${name} (from the system tree)`,
+    };
+}

package/dist/runtime/records.d.ts

@@ -0,0 +1,135 @@
+import { CID } from "./cid.ts";
+import type { Ms, Ref } from "./types.ts";
+import type { Signer } from "./identity.ts";
+import type { DispatchRow } from "./dispatch.ts";
+export type * from "./types.ts";
+/** A compressed secp256k1 public key, hex. */
+export type Identity = string;
+export declare const isIdentity: (x: unknown) => x is Identity;
+export type Message = {
+    kind: "message";
+    from: Identity;
+    to?: string;
+    seq: number;
+    at: Ms;
+    body: unknown;
+    refs: Ref[];
+    sig: Uint8Array;
+};
+export type UnsignedMessage = Omit<Message, "sig">;
+/** The signed bytes: dag-cbor of the record with `sig` removed (every other field is covered). */
+export declare function messageBytes(m: UnsignedMessage | Message): Uint8Array;
+/** What ECDSA signs: sha256(messageBytes(m)). */
+export declare function messageDigest(m: UnsignedMessage | Message): Uint8Array;
+export declare function signMessage(signer: Signer, m: {
+    to?: string;
+    seq: number;
+    body: unknown;
+    refs?: Ref[];
+    at: Ms;
+}): Promise<Message>;
+export declare function isMessage(x: unknown): x is Message;
+/** Shape plus signature against `from`. Synchronous for the store's transactions; see verifyMessage. */
+export declare function verifyMessageSync(m: unknown): m is Message;
+export declare function verifyMessage(m: unknown): Promise<boolean>;
+export type Program = {
+    kind: "program";
+    name: string;
+    code: {
+        ts: string;
+    } | {
+        wasm: CID;
+    };
+    inputs: unknown;
+    services: string[];
+    description: string;
+};
+export declare function program(p: Omit<Program, "kind">): Program;
+export declare function isProgram(x: unknown): x is Program;
+/**
+ * A route of the route table (#77, #143; dispatch.ts, docs/MESSAGES.md "The
+ * dispatch table"): the kernel's rule for a route (dispatch.zig `problem`).
+ * `program` is a program record's CID, "kernel" for an admin operation named
+ * by `fn`, or absent for a read route (http only: its filters answer). No
+ * `sender` (#143: routing only).
+ */
+export declare function isDispatchRow(x: unknown): x is DispatchRow;
+/** What a kernel route may name (its `fn`): the admin operations (#143: `grant` among them), the claim (#89: an image's one route; root to the claimant, the route removed), and the host's tick (#130). */
+export declare const KERNEL_OPS: readonly string[];
+/**
+ * An instance's starting state: the record the first log entry names. Its
+ * `identity` is the instance wallet's identity key, which its outbound
+ * envelopes are signed by; `host` is the identity of the host that delivers
+ * its inputs (format 1 only: format 2 dropped it); `owner` is the identity
+ * it acted for (format 1-8: #143 replaced it with `root`); `programs` are the programs it starts with, by name;
+ * `dispatch` is the seed of its dispatch table (dispatch.ts): written as the
+ * table's chain's first updates when the entry is processed, never read for
+ * routing; `scopes` are the heads each genesis-wired program may advance
+ * (program name → head names, a prefix ending in `/`).
+ */
+export type Genesis = {
+    kind: "genesis";
+    identity: Identity;
+    handle: string;
+    domain: string;
+    /** #143: the initial root holders; absent in an image (#89: root comes with the claim). */
+    root?: Identity[];
+    /** #143: what gates the genesis's own programs' functions: {<role>: ["<program>.<fn>"]}. */
+    roles?: Record<string, string[]>;
+    host?: Identity;
+    programs: Record<string, CID>;
+    dispatch: DispatchRow[];
+    scopes?: Record<string, string[]>;
+    /** Peers by role, e.g. `infer`: the identity a program sends that kind of request to. */
+    peers?: Record<string, Identity>;
+    /** Defaults programs fall back on, e.g. `model` for the loop. */
+    defaults?: Record<string, string>;
+    /** Handles of identities programs send to whose envelopes may not name them (the owner, the peers): an outbound envelope's `recipient`. */
+    names?: Record<Identity, {
+        handle: string;
+        domain: string;
+    }>;
+    /** Boxes the delivery provider collects besides the dispatched ones: replies (e.g. `completions`), routed only by `replyTo`. */
+    collect?: string[];
+};
+export declare function isGenesis(x: unknown): x is Genesis;
+/**
+ * What a handler emits: an outbound message to `to` in `box`. `envelope` is the
+ * complete BRC-169 envelope (signed metadata and BRC-78 content), which the
+ * program sealed through the instance wallet; `body` is its plaintext content,
+ * a record. The kernel checks the envelope before accepting it.
+ */
+export type Emit = {
+    kind: "emit";
+    to: Identity;
+    box: string;
+    body: CID;
+    envelope: Record<string, unknown> & {
+        content: string;
+    };
+};
+export declare function isEmit(x: unknown): x is Emit;
+/**
+ * A signer call's record (format 6, #67: the one call a step makes out
+ * mid-step): a BRC-100 wire request frame and its result frame, at (thread,
+ * step, i). Referenced, in order, from the step's update (`calls`); on replay
+ * the answer is served from here, not a wallet. (Before format 6 these were
+ * `attested` records, with `http` and `libp2p` calls beside the wallet's.)
+ * The record's kind is still the string `oracle`, the signer's old name: it
+ * is part of the format, so the rename left it as it was.
+ */
+export type SignerCall = {
+    kind: "oracle";
+    thread: CID;
+    step: number;
+    i: number;
+    request: Uint8Array;
+    result: Uint8Array;
+};
+export declare function isSignerCall(x: unknown): x is SignerCall;
+/**
+ * Wallet wire calls a program may make (BRC-100 call codes): key derivation
+ * and crypto only — no actions, no certificates (the kernel's scheduler.zig
+ * `wallet_calls`). By code, for showing a signer call.
+ */
+export declare const WALLET_CALLS: ReadonlyMap<number, string>;

package/dist/runtime/records.js

@@ -0,0 +1,149 @@
+// v2 record kinds (docs/VM.md): message, program, genesis (with its dispatch rows).
+// Types, not interfaces, so they satisfy Block's index signature.
+// Thread/node shapes stay in types.ts and are re-exported so v2 code has one
+// import. Validators are structural; a message is only trusted once
+// verifyMessage passes, which needs nothing but the record itself.
+import { isFilterRef } from "./dispatch.js";
+import { createHash } from "node:crypto";
+import { PublicKey, Signature } from "@bsv/sdk";
+import { CID, decode, encode, isCID } from "./cid.js";
+const IDENTITY = /^0[23][0-9a-f]{64}$/;
+export const isIdentity = (x) => typeof x === "string" && IDENTITY.test(x);
+/** The signed bytes: dag-cbor of the record with `sig` removed (every other field is covered). */
+export function messageBytes(m) {
+    const { sig: _, ...rest } = m;
+    return encode(rest).bytes;
+}
+/** What ECDSA signs: sha256(messageBytes(m)). */
+export function messageDigest(m) {
+    return new Uint8Array(createHash("sha256").update(messageBytes(m)).digest());
+}
+export async function signMessage(signer, m) {
+    // Round-trip through dag-cbor so the record we return is exactly what gets
+    // stored and re-encoded at verify time (undefined dropped, CIDs canonical).
+    const unsigned = decode(encode({
+        kind: "message", from: signer.identity, to: m.to, seq: m.seq, at: m.at, body: m.body, refs: m.refs ?? [],
+    }).bytes);
+    if (!isMessage({ ...unsigned, sig: new Uint8Array() }))
+        throw new TypeError("signMessage: malformed message");
+    return { ...unsigned, sig: await signer.sign(messageBytes(unsigned)) };
+}
+export function isMessage(x) {
+    if (!isObj(x) || x.kind !== "message")
+        return false;
+    return isIdentity(x.from)
+        && (x.to === undefined || typeof x.to === "string")
+        && Number.isSafeInteger(x.seq) && x.seq >= 0
+        && typeof x.at === "number"
+        && x.body !== undefined
+        && Array.isArray(x.refs) && x.refs.every(isRef)
+        && x.sig instanceof Uint8Array;
+}
+/** Shape plus signature against `from`. Synchronous for the store's transactions; see verifyMessage. */
+export function verifyMessageSync(m) {
+    if (!isMessage(m))
+        return false;
+    try {
+        // PublicKey.verify hashes with sha256 itself, so this checks the signature over messageDigest(m).
+        return PublicKey.fromString(m.from).verify([...messageBytes(m)], Signature.fromDER([...m.sig]));
+    }
+    catch {
+        return false; // not a curve point, not DER
+    }
+}
+export async function verifyMessage(m) {
+    return verifyMessageSync(m);
+}
+export function program(p) {
+    const out = { kind: "program", ...p };
+    if (!isProgram(out))
+        throw new TypeError("program: malformed");
+    return out;
+}
+export function isProgram(x) {
+    if (!isObj(x) || x.kind !== "program")
+        return false;
+    const code = x.code;
+    const codeOk = isObj(code) && (typeof code.ts === "string") !== isCID(code.wasm);
+    return typeof x.name === "string" && x.name !== "" && codeOk
+        && x.inputs !== undefined
+        && Array.isArray(x.services) && x.services.every((s) => typeof s === "string")
+        && typeof x.description === "string";
+}
+// ---------------------------------------------------------------- dispatch row
+/**
+ * A route of the route table (#77, #143; dispatch.ts, docs/MESSAGES.md "The
+ * dispatch table"): the kernel's rule for a route (dispatch.zig `problem`).
+ * `program` is a program record's CID, "kernel" for an admin operation named
+ * by `fn`, or absent for a read route (http only: its filters answer). No
+ * `sender` (#143: routing only).
+ */
+export function isDispatchRow(x) {
+    if (!isObj(x))
+        return false;
+    const t = x.transport;
+    if (t !== "mailbox" && t !== "event" && t !== "http" && t !== "libp2p" && t !== "local")
+        return false;
+    if (x.sender !== undefined)
+        return false;
+    if (typeof x.address !== "string" || x.address === "" || /[ \0]/.test(x.address))
+        return false;
+    if (x.prefix !== undefined && x.prefix !== null && x.prefix !== false && !(x.prefix === true && t === "http"))
+        return false;
+    const filters = x.filters === undefined || x.filters === null ? [] : x.filters;
+    if (!Array.isArray(filters) || !filters.every(isFilterRef))
+        return false;
+    if (filters.length && (t === "local" || (t === "event" && !(filters.length === 1 && filters[0] === "kernel.beef"))))
+        return false;
+    if (x.fn !== undefined && x.fn !== null && typeof x.fn !== "string")
+        return false;
+    // A read route (#143): http, or a libp2p stream protocol (#154: `/…`; a topic carries no answer).
+    if (x.program === undefined)
+        return (t === "http" || (t === "libp2p" && x.address.startsWith("/"))) && filters.length > 0 && x.fn === undefined;
+    if (x.program === "kernel")
+        return t === "mailbox" && filters.length === 0 && typeof x.fn === "string" && KERNEL_OPS.includes(x.fn);
+    return isCID(x.program);
+}
+/** What a kernel route may name (its `fn`): the admin operations (#143: `grant` among them), the claim (#89: an image's one route; root to the claimant, the route removed), and the host's tick (#130). */
+export const KERNEL_OPS = ["objects", "head", "dispatch", "peers", "grant", "claim", "tick"];
+export function isGenesis(x) {
+    return isObj(x) && x.kind === "genesis" && isIdentity(x.identity) && x.owner === undefined && (x.root === undefined || (Array.isArray(x.root) && x.root.every(isIdentity))) && (x.host === undefined || isIdentity(x.host))
+        && (x.roles === undefined || (isObj(x.roles) && Object.values(x.roles).every((v) => Array.isArray(v) && v.every((f) => typeof f === "string"))))
+        && typeof x.handle === "string" && typeof x.domain === "string"
+        && isObj(x.programs) && Object.values(x.programs).every(isCID)
+        && Array.isArray(x.dispatch) && x.dispatch.every(isDispatchRow)
+        && (x.scopes === undefined || (isObj(x.scopes) && Object.values(x.scopes).every((v) => Array.isArray(v) && v.every((h) => typeof h === "string" && h !== ""))))
+        && (x.peers === undefined || (isObj(x.peers) && Object.values(x.peers).every(isIdentity)))
+        && (x.defaults === undefined || (isObj(x.defaults) && Object.values(x.defaults).every((v) => typeof v === "string")))
+        && (x.names === undefined || (isObj(x.names) && Object.entries(x.names).every(([k, v]) => isIdentity(k) && isObj(v) && typeof v.handle === "string" && typeof v.domain === "string")))
+        && (x.collect === undefined || (Array.isArray(x.collect) && x.collect.every((b) => typeof b === "string" && b !== "")));
+}
+export function isEmit(x) {
+    return isObj(x) && x.kind === "emit" && isIdentity(x.to) && typeof x.box === "string" && x.box !== "" && isCID(x.body)
+        && isObj(x.envelope) && typeof x.envelope.content === "string";
+}
+export function isSignerCall(x) {
+    return isObj(x) && x.kind === "oracle" && isCID(x.thread) && typeof x.step === "number" && typeof x.i === "number"
+        && x.request instanceof Uint8Array && x.result instanceof Uint8Array;
+}
+/**
+ * Wallet wire calls a program may make (BRC-100 call codes): key derivation
+ * and crypto only — no actions, no certificates (the kernel's scheduler.zig
+ * `wallet_calls`). By code, for showing a signer call.
+ */
+export const WALLET_CALLS = new Map([
+    [8, "getPublicKey"], [11, "encrypt"], [12, "decrypt"], [13, "createHmac"], [14, "verifyHmac"], [15, "createSignature"], [16, "verifySignature"],
+]);
+function isObj(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v) && !isCID(v) && !(v instanceof Uint8Array);
+}
+function isPlain(v) {
+    if (!isObj(v))
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+function isRef(r) {
+    return isObj(r) && (isCID(r.to) || typeof r.to === "string") && typeof r.rel === "string"
+        && (r.locator === undefined || typeof r.locator === "string");
+}

package/dist/runtime/sqlite.d.ts

@@ -0,0 +1,33 @@
+import { type SQLOutputValue } from "node:sqlite";
+import { CID } from "./cid.ts";
+import { type Store } from "./store.ts";
+import type { Ref } from "./types.ts";
+type Obj = Record<string, unknown>;
+export interface EdgeRow {
+    to: string;
+    rel: string;
+    locator: string | null;
+}
+/** The SQLite store adds prefix lookup over origins (for the CLI's short CIDs). */
+export interface SqliteStore extends Store {
+    findByPrefix(prefix: string): Promise<CID[]>;
+}
+/**
+ * `readOnly`: open an existing file for reading only (the explorer beside a
+ * live runtime): no schema, no migration, no journal change; writes throw.
+ */
+export declare function openStore(path: string, o?: {
+    readOnly?: boolean;
+}): SqliteStore;
+export declare function originEdges(b: Obj): EdgeRow[];
+export declare function updateEdges(u: Obj): EdgeRow[];
+/**
+ * The edges an update's kept records declare (#37, the Zig kernel's
+ * index.zig `updateEdgesWithKept`): each kept record with `refs: [{to, rel,
+ * locator?}]` gives an edge with the record's own rel, after the update's own
+ * edges. `kept` is the update's kept records, resolved (undefined: not held
+ * or not a dag-cbor map). Readers of a Zig store use it.
+ */
+export declare function keptEdges(kept: unknown[]): EdgeRow[];
+export declare function toRef(to: CID | string, rel: string, locator: SQLOutputValue): Ref;
+export {};