@dcasegr/skein 0.0.0-stage → 0.1.1

package/dist/host/billing.js

@@ -0,0 +1,167 @@
+// Billing (#130), the host's side. The kernel meters what is in its log and
+// prepays the host block by block from the instance's own wallet
+// (kernel-zig/src/billing.zig, scheduler.zig billingAfter); the host:
+//
+//   terms     its key (a child of the master secret: provider key `billing`) and what it supports
+//             — X, the rates, its free allowance per skein, its tick interval, its grace — published
+//             at /.well-known/skein-host (`billing`). The owner grants them as the host row, a kernel
+//             row of the skein's dispatch table (`skein host`): no row, nothing is billed, the
+//             skein is served as before; a row naming another key or lower rates (or X) than this
+//             host's: it stops serving (the gate).
+//   meter     what never reaches the log: the fuel of the read calls it makes (the explorer's reads,
+//             frontdoor.ts) and the bytes it serves, per instance, since its last tick; each a line
+//             of its log for the period.
+//   tick      every tickMs (and at once for a skein whose host row it has not ticked yet, and early
+//             when what it holds unreported would take the tally to the allocation): a message
+//             signed by its key, in the host row's box — {kind: "tick", at, allowance, fuel, served,
+//             log: <the CID of its log record for the period>} — the period's record kept in host.db.
+//   payment   the wallet's `payment` event (the pay step's): kept in host.db and broadcast (its
+//             Arcade), the output checked against the BRC-29 key the remittance derives.
+//   the gate  asleep (the kernel's billing state says so: consumed ≥ allocation and nothing paid) or
+//             the terms not this host's: nothing is forwarded to the instance — a request is 402,
+//             a libp2p message ignored, a provider's answer, a feed's event dropped — but its own
+//             messages to itself (the loopback: its wallet's ingest at the chain app). No tick is sent;
+//             the tally is frozen in the kernel.
+//   grace     when it went asleep is in host.db; past the grace the host may reclaim it
+//             (`skein-host reclaim`): disabled, its row and store removed. Nothing does it on its own.
+//
+// Amounts: X, the allowance and payments in satoshis; the tally in nanosatoshis (a bigint here).
+import { encode } from "../runtime/cid.js";
+/** The kernel's head (billing.zig HEAD). */
+export const BILLING_HEAD = "billing";
+/** The host row's kernel operation. */
+export const TICK_OP = "tick";
+/** The host row's box by convention (the row's address is what a tick goes to). */
+export const BILLING_BOX = "billing";
+export const NSAT = 1000000000n;
+export const RATE_NAMES = ["fuel", "storage", "served", "fetch", "authfetch", "publish"];
+/** Small dev defaults (#130 decided, "Numbers": configuration; real numbers later). */
+export const DEV_BILLING = {
+    x: 1_000,
+    rates: { fuel: 1, storage: 1, served: 1, fetch: 1, authfetch: 1, publish: 1 },
+    allowance: 10_000,
+    tickMs: 60_000,
+    graceMs: 7 * 86_400_000,
+};
+/**
+ * The host's billing from its environment: SKEIN_BILLING=off for none; else DEV_BILLING with
+ * SKEIN_BILLING_X, SKEIN_BILLING_RATES (JSON {fuel, storage, served, fetch, authfetch, publish}),
+ * SKEIN_BILLING_ALLOWANCE, SKEIN_BILLING_TICK_MS, SKEIN_BILLING_GRACE_MS over it.
+ */
+export function billingConfig(v) {
+    if (v.SKEIN_BILLING === "off" || v.SKEIN_BILLING === "0")
+        return undefined;
+    const num = (name, d) => {
+        const s = v[name];
+        if (s === undefined || s === "")
+            return d;
+        const n = Number(s);
+        if (!Number.isSafeInteger(n) || n < 0)
+            throw new Error(`${name}: a whole number, not ${s}`);
+        return n;
+    };
+    let rates = DEV_BILLING.rates;
+    if (v.SKEIN_BILLING_RATES) {
+        const r = JSON.parse(v.SKEIN_BILLING_RATES);
+        rates = { ...rates };
+        for (const [k, x] of Object.entries(r)) {
+            if (!RATE_NAMES.includes(k) || typeof x !== "number" || !Number.isSafeInteger(x) || x < 0)
+                throw new Error(`SKEIN_BILLING_RATES: ${k}: a rate is one of ${RATE_NAMES.join(", ")}, a whole number of sats`);
+            rates[k] = x;
+        }
+    }
+    const x = num("SKEIN_BILLING_X", DEV_BILLING.x);
+    if (x < 1)
+        throw new Error("SKEIN_BILLING_X: at least 1 sat");
+    return { x, rates, allowance: num("SKEIN_BILLING_ALLOWANCE", DEV_BILLING.allowance), tickMs: Math.max(1, num("SKEIN_BILLING_TICK_MS", DEV_BILLING.tickMs)), graceMs: num("SKEIN_BILLING_GRACE_MS", DEV_BILLING.graceMs) };
+}
+const hexOf = (k) => k instanceof Uint8Array ? Buffer.from(k).toString("hex") : typeof k === "string" && /^0[23][0-9a-f]{64}$/.test(k) ? k : undefined;
+const whole = (n) => typeof n === "number" && Number.isSafeInteger(n) && n >= 0 ? n : typeof n === "bigint" && n >= 0n && n <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(n) : undefined;
+/** The host row (billing.zig termsOf): the first kernel route whose fn is `tick`, in table order; #143: the host's key its `host` setting. */
+export function termsOf(rows) {
+    for (const r of rows) {
+        if (r.program !== "kernel" || r.fn !== TICK_OP)
+            continue;
+        const host = hexOf(r.host);
+        const x = whole(r.x);
+        if (!host || !x)
+            return undefined;
+        const rates = Object.fromEntries(RATE_NAMES.map((n) => [n, 0]));
+        const given = r.rates;
+        if (given && typeof given === "object")
+            for (const n of RATE_NAMES) {
+                const v = whole(given[n]);
+                if (v !== undefined)
+                    rates[n] = v;
+            }
+        return { host, x, rates, address: r.address };
+    }
+    return undefined;
+}
+/** Why the terms are not what this host (key `host`) supports (undefined: they are): another key, X or a rate below its own. */
+export function mismatch(cfg, host, t) {
+    if (t.host !== host)
+        return `the host row names ${t.host.slice(0, 8)}…, not this host's key ${host.slice(0, 8)}…`;
+    if (t.x < cfg.x)
+        return `x ${t.x} is below this host's ${cfg.x}`;
+    for (const n of RATE_NAMES)
+        if (t.rates[n] < cfg.rates[n])
+            return `the ${n} rate ${t.rates[n]} is below this host's ${cfg.rates[n]}`;
+    return undefined;
+}
+const big = (n) => typeof n === "bigint" ? n : typeof n === "number" && Number.isSafeInteger(n) ? BigInt(n) : undefined;
+export function stateOf(rec) {
+    const r = rec;
+    if (!r || r.kind !== "billing")
+        return undefined;
+    const host = hexOf(r.host);
+    const [allowance, paid, tally] = [big(r.allowance), big(r.paid), big(r.tally)];
+    if (!host || allowance === undefined || paid === undefined || tally === undefined || typeof r.asleep !== "boolean")
+        return undefined;
+    return { host, allowance, paid, tally, lastTick: Number(r.lastTick), ticks: Number(r.ticks), bytes: Number(r.bytes), payments: Number(r.payments), asleep: r.asleep };
+}
+/** What the instance may consume (nanosats). */
+export const allocation = (s) => (s.allowance + s.paid) * NSAT;
+/** The host's amounts at the rates (nanosats): billing.zig priceHost. */
+export const priceHost = (r, fuel, served) => BigInt(fuel) * BigInt(r.fuel) + BigInt(served) * BigInt(r.served) * 1000n;
+/** What the host has metered for an instance since its last tick. */
+export class Period {
+    since;
+    fuel = 0;
+    served = 0;
+    lines = [];
+    constructor(since) { this.since = since; }
+    add(l) {
+        this.fuel += l.fuel;
+        this.served += l.bytes;
+        this.lines.push(l);
+    }
+    get empty() { return this.lines.length === 0; }
+}
+/**
+ * The period's record — {kind: "host-log", instance: <its identity>, from, to, lines: [{at, op,
+ * caller?, fuel, bytes}]} — and its CID, which the tick commits to (`log`): the host keeps the
+ * record (host.db billing_ticks), so it can show what it charged.
+ */
+export function periodRecord(identity, p, to) {
+    const record = {
+        kind: "host-log", instance: Uint8Array.from(Buffer.from(identity, "hex")), from: p.since, to,
+        lines: p.lines.map((l) => ({ at: l.at, op: l.op, ...(l.caller ? { caller: Uint8Array.from(Buffer.from(l.caller, "hex")) } : {}), fuel: l.fuel, bytes: l.bytes })),
+    };
+    const b = encode(record);
+    return { record, bytes: b.bytes, cid: b.cid };
+}
+/** A tick's body (billing.zig tickOf). */
+export function tickBody(at, cfg, p, log) {
+    return { kind: "tick", at, allowance: cfg.allowance, fuel: p.fuel, served: p.served, log };
+}
+/** Why the host forwards nothing to the instance (undefined: it forwards as usual). */
+export function closedBy(v) {
+    if (!v?.terms)
+        return undefined;
+    if (v.mismatch)
+        return `this host does not serve these terms: ${v.mismatch}`;
+    if (v.state?.asleep && v.state.host === v.terms.host)
+        return `asleep: its allocation is consumed and its wallet paid nothing`;
+    return undefined;
+}

package/dist/host/boot.d.ts

@@ -0,0 +1,246 @@
+import { CID } from "multiformats/cid";
+import { programRecord, RAW, rawCid, wasmKind } from "../runtime/programs.ts";
+import type { Stamp } from "../runtime/syscalls.ts";
+import { type Entry, type TreeBlocks } from "../runtime/tree.ts";
+import { type ScanOptions } from "../dev/scan.ts";
+import type { DispatchRow } from "../runtime/dispatch.ts";
+import { type ConfigSpec, type DispatchSpec, type Genesis2Config, type System } from "./genesis.ts";
+import type { KernelSurface as Kernel } from "./kernel.ts";
+export declare const DAG_CBOR = 113;
+export { programRecord, RAW, rawCid, wasmKind };
+export declare const BIN = "bin";
+export declare const CONFIG = "etc/config.json";
+export declare const DISPATCH = "etc/dispatch.json";
+/** The forms before #77 and #115, refused (#143: they spoke of senders). */
+export declare const GONE: string[];
+/** #141, #152: the apps an image installs at birth, and root's own routes (ImageApps). */
+export declare const APPS = "etc/apps.json";
+/** Blocks by CID, from wherever a source keeps them. */
+export interface Objects {
+    get(cid: CID): Promise<Uint8Array | undefined>;
+}
+/** Blocks in memory: what a scanned directory or a verified packet becomes. */
+export declare class MemBlocks implements Objects, TreeBlocks {
+    readonly map: Map<string, {
+        cid: CID;
+        bytes: Uint8Array;
+    }>;
+    get(cid: CID): Promise<Uint8Array<ArrayBufferLike> | undefined>;
+    bytes(cid: CID): Promise<Uint8Array<ArrayBufferLike>>;
+    has(cid: CID): Promise<boolean>;
+    putBlock(cid: CID, bytes: Uint8Array): Promise<void>;
+}
+/** A git object's body if it is a `<type>` object. */
+export declare function gitBody(object: Uint8Array, type: "blob" | "tree"): Uint8Array | undefined;
+/** Source A: a directory on disk, hashed into git objects in memory (scan.ts). */
+export declare function dirSource(dir: string, o?: ScanOptions): Promise<{
+    root: CID;
+    objects: MemBlocks;
+}>;
+export interface ProgramSpec {
+    name: string;
+    module: CID;
+    record: Record<string, unknown>;
+}
+export interface SystemTree {
+    root: CID;
+    /** Every git object under the root, in walk order. */
+    objects: Array<{
+        cid: CID;
+        bytes: Uint8Array;
+    }>;
+    programs: ProgramSpec[];
+    /** Modules named by bin/<name>.wasm (with their bytes) or bin/<name>.cid (bytes if the source has them). */
+    modules: Array<{
+        cid: CID;
+        bytes?: Uint8Array;
+        name: string;
+    }>;
+    config: ConfigSpec;
+    /** etc/dispatch.json (#77, #143): the routes. Required. */
+    dispatch: DispatchSpec[];
+    /** etc/apps.json (#141): the apps installed at birth, and the trees of those inside the image (appKey → tree CID). */
+    apps?: ImageApps;
+    appTrees?: Record<string, CID>;
+}
+/**
+ * etc/apps.json (#141, #143, #152): what an image installs at birth — `install`, in order, each app
+ * a directory (a path relative to the image: a directory of its tree, or one beside it, `..`, read
+ * when the image is read from its directory) or a release tarball `{url, hash}` (`hash`: the git id
+ * of the app's tree, 40 hex — the tag's tree, `git rev-parse <tag>^{tree}`), which the host fetches
+ * and checks; `routes`, root's own routes (no app: an app's upgrade or uninstall leaves them), as
+ * the kernel takes them. The genesis carries what installing them as messages would have written:
+ * the app's objects and records (pre-filled), the routes (with `app`) and the heads `<app>/app`
+ * (plan.ts planInstall, planRootRoute).
+ */
+export interface ImageApps {
+    install: ImageApp[];
+    routes?: DispatchSpec[];
+}
+export type ImageApp = string | {
+    url: string;
+    hash: string;
+};
+/** An entry's key: its path, or its tarball's tree id. */
+export declare const appKey: (a: ImageApp) => string;
+/** Every git object reachable from `root` (trees, blobs, gitlinked records), each checked against its id. */
+export declare function treeObjects(objects: Objects, root: CID): Promise<Array<{
+    cid: CID;
+    bytes: Uint8Array;
+    entries?: Entry[];
+}>>;
+/** Read a system tree out of `objects` (docs/BOOTSTRAP.md): its objects, programs, modules, config and subscriptions. */
+export declare function readSystemTree(objects: Objects, root: CID): Promise<SystemTree>;
+/** etc/apps.json's shape (#141, #152), refused with what it wants. */
+export declare function checkImageApps(apps: ImageApps | undefined): void;
+export type BootSource = 
+/** No tree: the stock system in code (the live agents). */
+{
+    kind: "code";
+}
+/**
+ * A system tree whose objects are in `objects` (a scanned directory, a store, a verified packet). `apps` (#152):
+ * the trees of the apps its etc/apps.json names by a directory outside the image, by appKey, read with the image
+ * from its directory (their objects in `objects`).
+ */
+ | {
+    kind: "tree";
+    root: CID;
+    objects: Objects;
+    apps?: Record<string, CID>;
+}
+/** A checkpoint (#30): the state record and every block it reaches, verified; restored, not replayed. */
+ | {
+    kind: "checkpoint";
+    state: CID;
+    blocks: Array<{
+        cid: CID;
+        bytes: Uint8Array;
+    }>;
+};
+export interface Booted {
+    entry?: CID;
+    tree?: CID;
+    state?: CID;
+    objects: number;
+    programs: string[]; /** #141: the apps the image installed at birth. */
+    apps?: Array<{
+        name: string;
+        version: string;
+        notes: string[];
+    }>;
+}
+/**
+ * Boot an empty store through its kernel: pre-fill and write the genesis (a
+ * tree, or the stock system), or restore a checkpoint. The kernel processes
+ * the genesis when it starts (the dispatch rows; `main` → the tree).
+ */
+export declare function boot(k: Kernel, src: BootSource, c: Genesis2Config, time?: Stamp): Promise<Booted>;
+/**
+ * #141, #152: the apps an image installs at birth (etc/apps.json), each a directory install — the
+ * app's tree (in the image; a directory beside it, `resolved` by the source; a tarball fetched and
+ * checked, appTarball), its objects put — planned as an install by messages would be (plan.ts:
+ * readStoredApp over the app's tree, planInstall) against the instance as its genesis will stand —
+ * the same records, routes and heads — and root's own routes (planRootRoute). An app's config given
+ * at creation (`appConfig`) is merged over its manifest's, as an install's `--config` is. Their
+ * objects and records are put into the store; the routes and heads go into the genesis.
+ */
+export declare function installAtBirth(k: Pick<Kernel, "hasBlock" | "putBlock">, imageObjects: Objects, t: SystemTree, s: System, c: Genesis2Config, resolved?: Record<string, CID>): Promise<{
+    rows: DispatchRow[];
+    heads: Record<string, CID>;
+    put: number;
+    apps: Array<{
+        name: string;
+        version: string;
+        notes: string[];
+    }>;
+}>;
+/** The program records' CIDs a tree's bin/ yields (as `boot` puts them), without a kernel. */
+export declare function programCid(record: Record<string, unknown>): CID;
+/** The stock system as files (`skein-host system <dir>`): bin/*.cid + bin/*.json from the kernel's records, etc/. */
+export declare function stockSystemFiles(k: Kernel): Promise<Record<string, string>>;
+/**
+ * Boot a store file that no router holds yet (`skein-host add --boot/--packet`,
+ * tests): start its kernel, `boot`, stop it. The router then hydrates it as
+ * any other store; the kernel processes the genesis at that first start.
+ */
+export declare function bootStore(o: {
+    db: string;
+    handle: string;
+    domain: string;
+    command?: string;
+    env?: Record<string, string | undefined>;
+    log?(line: string): void;
+}, src: BootSource, c: Genesis2Config, time?: Stamp): Promise<Booted>;
+/** Blocks out of a store (a store file opened read-only, or anything with `bytes`). */
+export declare function storeObjects(s: {
+    bytes(cid: CID): Promise<Uint8Array>;
+}): Objects;
+/** The first source that has the block. */
+export declare function anyOf(...sources: Objects[]): Objects;
+/** The modules in a wasm directory (the repo's wasm/: the pinned builds), by their raw CIDs; hashed on first use. */
+export declare function wasmDirObjects(dir: string): Objects;
+/** The repo's pinned modules (wasm/): what a system tree's `bin/*.cid` names. */
+export declare const WASM_DIR: string;
+/** The default image (#89): a user skein's — no root in it, a claim route. */
+export declare const DEFAULT_IMAGE: string;
+/** The host image's own part (#142): merged over the default image (mergeImages), the host skein's image. */
+export declare const HOST_IMAGE: string;
+/**
+ * Two image trees merged (#142: images are starting trees that merge): every path of `over` added to
+ * `base`. A directory in both is merged; a file in both must be the same blob — except `etc/apps.json`,
+ * whose `install` and `routes` lists are joined (an app in both, by appKey, is refused; a root route of
+ * `over` at the same transport, address and prefix as one of `base`'s replaces it, #147). Any other path in both is a
+ * collision, refused with its path. The installer's own checks (boxes, heads, paths) run when the merged
+ * image's apps are installed at birth (installAtBirth). The new trees and the merged apps.json go into
+ * `out`; every other object stays where it was.
+ */
+export declare function mergeImages(objects: Objects, base: CID, over: CID, out: MemBlocks): Promise<CID>;
+/**
+ * #152: an image directory with no `bin/` is an overlay — it carries what it adds (an app repository's
+ * `image/`: `etc/apps.json` alone) and is merged over the default image before boot, as images/host is;
+ * one with `bin/` is a complete image of its own.
+ */
+export declare function isOverlayImage(dir: string): boolean;
+/** An image's static part: its tree, its objects, the apps it names beside it (imageDir). */
+export interface ImageStatic {
+    root: CID;
+    objects: Objects;
+    apps: Record<string, CID>;
+}
+/**
+ * #142, #152: an overlay image directory (`dir`: images/host, an app repository's `image/`) merged over
+ * `base` (mergeImages: an app in both refused, a root route at the same place replaced, any other path in
+ * both refused unless it is the same blob). The apps each names beside it are kept, by appKey.
+ */
+export declare function overlayImage(base: ImageStatic, dir: string): Promise<ImageStatic>;
+/**
+ * An image as a boot source (#89, #90): a directory (default: the default
+ * image), its objects with the repo's pinned modules beside them, and the
+ * apps it names by a directory outside it (imageDir).
+ */
+export declare function imageSource(dir?: string): Promise<BootSource & {
+    kind: "tree";
+}>;
+/**
+ * #152: an image directory scanned, and each app its etc/apps.json names by a directory outside it
+ * (`..`, `../<dir>`, an absolute path) scanned from there as `skein install <dir>` reads it
+ * (install.ts appIgnore): the trees by appKey (BootSource `apps`), their objects with the image's.
+ */
+export declare function imageDir(dir: string): Promise<{
+    root: CID;
+    objects: MemBlocks;
+    apps: Record<string, CID>;
+}>;
+/**
+ * #152: an app by release tarball, `hash` its tree's git id: the tree the image's objects hold
+ * already, else fetched from `url` (gzip or plain tar), unpacked (a tarball holding one directory,
+ * as a tag's archive does, is that directory), scanned into `into` as `skein install <dir>` reads
+ * a directory (install.ts appIgnore), and refused unless its tree is `hash`.
+ */
+export declare function appTarball(a: {
+    url: string;
+    hash: string;
+}, have: Objects, into: MemBlocks, get?: typeof fetch): Promise<CID>;
+/** Source B: a packet file, verified (packet.ts) — a system tree to boot, or a checkpoint to restore. */
+export declare function packetSource(bytes: Uint8Array, o?: import("./packet.ts").ReadOptions): Promise<BootSource>;