@dcasegr/skein 0.0.0-stage → 0.1.2

package/dist/host/image-chain.d.ts

@@ -0,0 +1,127 @@
+import type { Store } from "../runtime/store.ts";
+import { type BootSource } from "./boot.ts";
+import type { HostDb } from "./instances.ts";
+/** Headers per block (skein-sdk `image.per_block`). */
+export declare const PER_BLOCK = 2016;
+export declare const blockName: (first: number) => string;
+/** Why a header (80 bytes) is not one the chain app takes on its own: an unusable target, or a hash that misses it. */
+export declare function headerProblem(raw: Uint8Array): string | undefined;
+export interface ImageChainOptions {
+    db: HostDb;
+    /** The chaintracks headers endpoint (`…/chaintracks/v2/headers`): history by height. */
+    history?: string;
+    /** Headers per history request (default 100 800: 50 blocks). */
+    page?: number;
+    /** The static part (default: the repo's images/default). */
+    dir?: string;
+    /** The host image's own part (#142, default: the repo's images/host), merged over the static part. */
+    hostDir?: string;
+    fetch?: typeof fetch;
+    log?(line: string): void;
+}
+/** The history endpoint beside a chaintracks tip stream (`…/tip/stream` → `…/headers`), if the URL is one. */
+export declare function historyOf(feed: string | undefined): string | undefined;
+/** The image names (#152): `default`, and `host` (images/host merged over it, #142). */
+export declare const IMAGE_NAMES: readonly ["default", "host"];
+export declare class ImageChain {
+    readonly o: ImageChainOptions;
+    /** chain/headers' blocks, in height order. */
+    private blocks;
+    /** The last block's headers (raw). */
+    private last;
+    private queue;
+    private stat?;
+    /** #142, #152: the overlay images' static parts (images/host, a directory with no `bin/`), each merged over the default image once. */
+    private merged;
+    /** Settles once the first sync (start) is done: what a creation waits for. */
+    ready: Promise<void>;
+    constructor(o: ImageChainOptions);
+    private say;
+    private object;
+    /** A block's headers (the one read last kept: a search below the tip reads one block many times). */
+    private blob;
+    private read?;
+    /** The tip's height (-1: no chain part). */
+    height(): number;
+    tip(): {
+        height: number;
+        hash: string;
+    } | undefined;
+    /** The header at a height (raw), from its block. */
+    private at;
+    /** One at a time: every change to the chain part goes through here. */
+    private serial;
+    /**
+     * Put `raws` at `height` (at most the tip + 1): the headers held from there
+     * that differ are replaced (a reorg), the ones that match are kept, the
+     * rest appended; a new tree. Whether anything changed. Refused: a gap, a
+     * header that does not link to the one before it, one the chain app would
+     * refuse on its own.
+     */
+    put(height: number, raws: Uint8Array[]): Promise<boolean>;
+    private write;
+    /** The static part: the image directory, scanned once (boot.ts imageDir: the apps it names beside it too). */
+    private static;
+    /**
+     * #142, #152: an overlay image's static part — its directory (images/host, or one with no `bin/`) merged
+     * over the default image (boot.ts overlayImage, mergeImages), once per directory.
+     */
+    private overlayStatic;
+    /** The image's root: the static part's entries, `chain` among them. */
+    private rootWith;
+    /**
+     * The current image as a boot source (#89, #132): the static part with the
+     * chain part at `chain/`; with no chain part, the static part alone (the
+     * repo's images/default, as before). `host` / `image: "host"`: the host
+     * image; `overlay` (#152): a directory with no `bin/`, merged over the
+     * default image as the host image is, with the same chain part. Its
+     * objects: host.db's, the scan's, the repo's pinned modules.
+     */
+    source(o?: {
+        host?: boolean;
+        image?: string;
+        overlay?: string;
+    }): Promise<BootSource>;
+    /**
+     * Headers from the stream (feeds.ts, in order): each appended at the tip
+     * when it links there; one that links to a header a little below the tip
+     * replaces from there (a reorg); otherwise the history fills in (a gap,
+     * a deeper reorg), or, with none, it is dropped.
+     */
+    headers(raws: Uint8Array[]): Promise<void>;
+    /** Fill in from the history (#132): from genesis once, then from a little below the tip. */
+    sync(): Promise<void>;
+    private syncNow;
+    /**
+     * #141: the headers a skein whose tip is `tip` lacks, from the image's chain, in order — what the
+     * host pushes it on (re)subscribing, before the live stream. From the header after its tip when
+     * the image holds that tip; a tip the image does not hold at its height (a fork) from a little
+     * below it; none when the skein is at or past the image's tip, or has no tip (no chain part).
+     * Run in turn with the chain part's writes: every header the feed brought before this call is in.
+     */
+    after(tip: {
+        height: number;
+        hash: string;
+    } | undefined): Promise<Uint8Array[]>;
+    /** Start: the first sync, which creations wait for (`ready`). */
+    start(): Promise<void>;
+}
+/**
+ * shruggr/skein#150: the chain app's best-chain header at `height` (the head `chain/state`, map
+ * `headers`: the MST height (u32 big-endian) → header): its hash (display hex) and merkle root
+ * (display hex); undefined when the chain state holds none there.
+ */
+export declare function chainHeader(store: Store, height: number): Promise<{
+    hash: string;
+    root: string;
+} | undefined>;
+/**
+ * #141: a skein's chain tip as its store holds it: the chain app's state (the head `chain/state`,
+ * {kind: "chain-state", maps: {headers}} — the MST height (u32 big-endian) → header, skein-sdk
+ * chain.zig; its last key is the tip), else the chain part of the tree it was born from (`main`'s
+ * `chain/tip`, image.zig's format), else none.
+ */
+export declare function skeinTip(store: Store): Promise<{
+    height: number;
+    hash: string;
+} | undefined>;

package/dist/host/image-chain.js

@@ -0,0 +1,440 @@
+// The default image's chain part (#132): the whole header chain, from the
+// network's genesis header to the last header the host received, as blocks
+// in the image tree — so a skein made at any moment is born with the chain up
+// to the current tip, and its chain app starts from it (skein-sdk
+// `chain.image`). Headers are pushed, never pulled by a skein: the host grows
+// the image, and from its creation on a skein gets each new tip as an event,
+// as before.
+//
+// The layout (skein-sdk chain/src/image.zig, the same bytes):
+//
+//   chain/headers/<first>   the raw 80-byte headers, concatenated in height order, 2016 per block,
+//                           <first> the first one's height in 8 digits (00000000, 00002016, …);
+//                           every block but the last is full; the last holds the rest
+//   chain/tip               {"height":<n>,"hash":"<display hex>"} and a newline
+//
+// The image tree is the static part — the repo's images/default, scanned —
+// with `chain` added at its root. **A new tree per header**: each header the
+// host takes rewrites the last block (at most 2016 × 80 bytes), the tip, the
+// two trees above them and the root; every full block stays as it is. The
+// chain part's objects live in host.db (`image_blocks`: only the current ones;
+// a replaced object is deleted with the write that replaces it), the current
+// root and `chain` tree in `host_settings` (`image`, `image_chain`).
+//
+// Where the headers come from: the host's headers feed (SKEIN_HEADERS_URL,
+// feeds.ts), each one appended as it arrives; and its history, from the same
+// chaintracks service (`/headers?height=&count=`, 80 bytes a header, next to
+// `/tip/stream`): at start the host fills the chain from genesis once, then
+// catches up from a little below its tip (a restart, a gap, a reorg deeper
+// than the last block). A header that links to none the host holds near its
+// tip is taken through the history; with no history service it is dropped,
+// logged. The host checks what it writes as the chain app will: each header
+// links to the one before, its target is usable and its hash meets it. It does
+// not judge the network: the chain app refuses an image whose first header is
+// not its network's genesis.
+import { createHash } from "node:crypto";
+import { CID as Cid } from "multiformats/cid";
+import * as dagCbor from "@ipld/dag-cbor";
+import { headTree } from "../runtime/heads.js";
+import { hashBlob, hashTree, parseTree, readBlob, readTree } from "../runtime/tree.js";
+import { anyOf, DEFAULT_IMAGE, HOST_IMAGE, imageDir, MemBlocks, overlayImage, WASM_DIR, wasmDirObjects } from "./boot.js";
+/** Headers per block (skein-sdk `image.per_block`). */
+export const PER_BLOCK = 2016;
+const SIZE = 80;
+export const blockName = (first) => String(first).padStart(8, "0");
+const sha256d = (b) => createHash("sha256").update(createHash("sha256").update(b).digest()).digest();
+const display = (h) => Buffer.from(h).reverse().toString("hex");
+/** The target a compact `bits` encodes, or undefined when it is not usable (skein-sdk header.zig `target`). */
+function target(bits) {
+    const mantissa = BigInt(bits & 0x007fffff);
+    const negative = (bits & 0x00800000) !== 0;
+    const exponent = bits >>> 24;
+    let t;
+    if (exponent <= 3)
+        t = mantissa >> BigInt(8 * (3 - exponent));
+    else {
+        const shift = 8 * (exponent - 3);
+        if (shift >= 256)
+            return undefined;
+        t = mantissa << BigInt(shift);
+        if (t >> 256n !== 0n)
+            return undefined;
+    }
+    return t === 0n || negative ? undefined : t;
+}
+/** Why a header (80 bytes) is not one the chain app takes on its own: an unusable target, or a hash that misses it. */
+export function headerProblem(raw) {
+    if (raw.length !== SIZE)
+        return "not 80 bytes";
+    const t = target(Buffer.from(raw).readUInt32LE(72));
+    if (t === undefined)
+        return "an unusable target";
+    return BigInt(`0x${display(sha256d(raw))}`) <= t ? undefined : "its hash misses its target";
+}
+const prevOf = (raw) => Buffer.from(raw.subarray(4, 36));
+/** The history endpoint beside a chaintracks tip stream (`…/tip/stream` → `…/headers`), if the URL is one. */
+export function historyOf(feed) {
+    if (!feed)
+        return undefined;
+    const u = new URL(feed);
+    if (!/\/tip\/stream\/?$/.test(u.pathname))
+        return undefined;
+    u.pathname = u.pathname.replace(/\/tip\/stream\/?$/, "/headers");
+    u.search = "";
+    return u.toString();
+}
+/** The image names (#152): `default`, and `host` (images/host merged over it, #142). */
+export const IMAGE_NAMES = ["default", "host"];
+export class ImageChain {
+    o;
+    /** chain/headers' blocks, in height order. */
+    blocks = [];
+    /** The last block's headers (raw). */
+    last = Buffer.alloc(0);
+    queue = Promise.resolve();
+    stat;
+    /** #142, #152: the overlay images' static parts (images/host, a directory with no `bin/`), each merged over the default image once. */
+    merged = new Map();
+    /** Settles once the first sync (start) is done: what a creation waits for. */
+    ready = Promise.resolve();
+    constructor(o) {
+        this.o = o;
+        const chain = o.db.setting("image_chain");
+        if (chain) {
+            const ch = parseTree(this.object(Cid.parse(chain)));
+            const hd = ch.find((e) => e.name === "headers");
+            if (hd) {
+                this.blocks = parseTree(this.object(hd.cid)).map((e) => e.cid);
+                if (this.blocks.length)
+                    this.last = this.blob(this.blocks.at(-1));
+            }
+        }
+    }
+    say(line) { this.o.log?.(line); }
+    object(cid) {
+        const b = this.o.db.imageBlock(cid.toString());
+        if (!b)
+            throw new Error(`the image's ${cid} is not in host.db`);
+        return Buffer.from(b);
+    }
+    /** A block's headers (the one read last kept: a search below the tip reads one block many times). */
+    blob(cid) {
+        if (this.read?.cid.equals(cid))
+            return this.read.bytes;
+        const o = this.object(cid);
+        this.read = { cid, bytes: o.subarray(o.indexOf(0) + 1) };
+        return this.read.bytes;
+    }
+    read;
+    /** The tip's height (-1: no chain part). */
+    height() { return this.blocks.length ? (this.blocks.length - 1) * PER_BLOCK + this.last.length / SIZE - 1 : -1; }
+    tip() {
+        const h = this.height();
+        return h < 0 ? undefined : { height: h, hash: display(sha256d(this.last.subarray(this.last.length - SIZE))) };
+    }
+    /** The header at a height (raw), from its block. */
+    at(height) {
+        const b = Math.floor(height / PER_BLOCK);
+        const bytes = b === this.blocks.length - 1 ? this.last : this.blob(this.blocks[b]);
+        const o = (height - b * PER_BLOCK) * SIZE;
+        return bytes.subarray(o, o + SIZE);
+    }
+    /** One at a time: every change to the chain part goes through here. */
+    serial(f) {
+        const p = this.queue.then(f, f);
+        this.queue = p.catch(() => { });
+        return p;
+    }
+    /**
+     * Put `raws` at `height` (at most the tip + 1): the headers held from there
+     * that differ are replaced (a reorg), the ones that match are kept, the
+     * rest appended; a new tree. Whether anything changed. Refused: a gap, a
+     * header that does not link to the one before it, one the chain app would
+     * refuse on its own.
+     */
+    put(height, raws) { return this.serial(() => this.write(height, raws)); }
+    async write(height, raws) {
+        const tipH = this.height();
+        if (height > tipH + 1)
+            throw new Error(`a gap: header ${height} after the tip ${tipH}`);
+        let prev = height === 0 ? Buffer.alloc(32) : sha256d(this.at(height - 1));
+        for (const [i, raw] of raws.entries()) {
+            const why = headerProblem(raw);
+            if (why)
+                throw new Error(`header ${height + i}: ${why}`);
+            if (!prevOf(raw).equals(prev))
+                throw new Error(`header ${height + i} does not link to header ${height + i - 1}`);
+            prev = sha256d(raw);
+        }
+        // Skip what is held already.
+        let i = 0;
+        while (i < raws.length && height + i <= tipH && this.at(height + i).equals(raws[i]))
+            i++;
+        if (i === raws.length)
+            return false;
+        const h0 = height + i;
+        const b0 = Math.floor(h0 / PER_BLOCK);
+        const base = b0 < this.blocks.length ? (b0 === this.blocks.length - 1 ? this.last : this.blob(this.blocks[b0])) : Buffer.alloc(0);
+        const rest = Buffer.concat([base.subarray(0, (h0 - b0 * PER_BLOCK) * SIZE), ...raws.slice(i)]);
+        const puts = new Map();
+        const drops = new Set(this.blocks.slice(b0).map(String));
+        const blocks = this.blocks.slice(0, b0);
+        for (let o = 0; o < rest.length; o += PER_BLOCK * SIZE) {
+            const { cid, object } = hashBlob(rest.subarray(o, o + PER_BLOCK * SIZE));
+            blocks.push(cid);
+            puts.set(cid.toString(), object);
+        }
+        const last = rest.subarray(Math.floor((rest.length - 1) / (PER_BLOCK * SIZE)) * PER_BLOCK * SIZE);
+        const tipHeight = blocks.length ? (blocks.length - 1) * PER_BLOCK + last.length / SIZE - 1 : -1;
+        const tipText = `{"height":${tipHeight},"hash":"${display(sha256d(last.subarray(last.length - SIZE)))}"}\n`;
+        const headers = hashTree(blocks.map((cid, k) => ({ mode: "100644", name: blockName(k * PER_BLOCK), cid })));
+        const tip = hashBlob(Buffer.from(tipText));
+        const chain = hashTree([{ mode: "40000", name: "headers", cid: headers.cid }, { mode: "100644", name: "tip", cid: tip.cid }]);
+        const root = await this.rootWith(chain.cid, await this.static());
+        for (const x of [headers, tip, chain, root])
+            puts.set(x.cid.toString(), x.object);
+        // The objects this tree no longer names.
+        const old = this.o.db.setting("image_chain");
+        if (old) {
+            const ch = parseTree(this.object(Cid.parse(old)));
+            drops.add(old);
+            for (const e of ch)
+                drops.add(e.cid.toString());
+        }
+        const oldRoot = this.o.db.setting("image");
+        if (oldRoot)
+            drops.add(oldRoot);
+        for (const k of puts.keys())
+            drops.delete(k);
+        this.o.db.writeImage(puts, drops, { image: root.cid.toString(), image_chain: chain.cid.toString() });
+        this.blocks = blocks;
+        this.last = Buffer.from(last);
+        return true;
+    }
+    /** The static part: the image directory, scanned once (boot.ts imageDir: the apps it names beside it too). */
+    static() {
+        this.stat ??= (async () => {
+            const d = await imageDir(this.o.dir ?? DEFAULT_IMAGE);
+            return { root: d.root, entries: parseTree(await d.objects.bytes(d.root)), objects: d.objects, apps: d.apps };
+        })();
+        return this.stat;
+    }
+    /**
+     * #142, #152: an overlay image's static part — its directory (images/host, or one with no `bin/`) merged
+     * over the default image (boot.ts overlayImage, mergeImages), once per directory.
+     */
+    overlayStatic(dir) {
+        let p = this.merged.get(dir);
+        if (!p) {
+            p = (async () => {
+                const m = await overlayImage(await this.static(), dir);
+                return { ...m, entries: parseTree((await m.objects.get(m.root))) };
+            })();
+            this.merged.set(dir, p);
+        }
+        return p;
+    }
+    /** The image's root: the static part's entries, `chain` among them. */
+    async rootWith(chain, s) {
+        return hashTree([...s.entries.filter((e) => e.name !== "chain"), { mode: "40000", name: "chain", cid: chain }]);
+    }
+    /**
+     * The current image as a boot source (#89, #132): the static part with the
+     * chain part at `chain/`; with no chain part, the static part alone (the
+     * repo's images/default, as before). `host` / `image: "host"`: the host
+     * image; `overlay` (#152): a directory with no `bin/`, merged over the
+     * default image as the host image is, with the same chain part. Its
+     * objects: host.db's, the scan's, the repo's pinned modules.
+     */
+    async source(o = {}) {
+        if (o.image !== undefined && !IMAGE_NAMES.includes(o.image))
+            throw new Error(`image ${JSON.stringify(o.image)}: this host has ${IMAGE_NAMES.join(", ")}`);
+        const over = o.overlay ?? (o.host || o.image === "host" ? this.o.hostDir ?? HOST_IMAGE : undefined);
+        const named = over !== undefined;
+        const s = named ? await this.overlayStatic(over) : await this.static();
+        const chainObjects = { get: async (cid) => this.o.db.imageBlock(cid.toString()) };
+        const chain = this.o.db.setting("image_chain");
+        if (named) {
+            // An overlay image (#142 the host image, #152 a directory with no bin/): its root is not kept in host.db; the chain part's objects are the same.
+            const root = chain ? await this.rootWith(Cid.parse(chain), s) : undefined;
+            const mem = new MemBlocks();
+            if (root)
+                await mem.putBlock(root.cid, root.object);
+            return { kind: "tree", root: root?.cid ?? s.root, objects: anyOf(mem, s.objects, wasmDirObjects(WASM_DIR), chainObjects), apps: s.apps };
+        }
+        const objects = anyOf(s.objects, wasmDirObjects(WASM_DIR), chainObjects);
+        if (!chain)
+            return { kind: "tree", root: s.root, objects, apps: s.apps };
+        const root = await this.rootWith(Cid.parse(chain), s);
+        // The static part changed since the last write (a new checkout): this root is the current one.
+        if (this.o.db.setting("image") !== root.cid.toString())
+            this.o.db.writeImage(new Map([[root.cid.toString(), root.object]]), new Set([this.o.db.setting("image") ?? ""]), { image: root.cid.toString() });
+        return { kind: "tree", root: root.cid, objects, apps: s.apps };
+    }
+    /**
+     * Headers from the stream (feeds.ts, in order): each appended at the tip
+     * when it links there; one that links to a header a little below the tip
+     * replaces from there (a reorg); otherwise the history fills in (a gap,
+     * a deeper reorg), or, with none, it is dropped.
+     */
+    headers(raws) {
+        return this.serial(async () => {
+            for (const raw of raws) {
+                try {
+                    const prev = prevOf(raw);
+                    const tipH = this.height();
+                    let at;
+                    if (tipH < 0)
+                        at = prev.equals(Buffer.alloc(32)) ? 0 : undefined;
+                    else
+                        for (let h = tipH; h >= Math.max(0, tipH - 2 * PER_BLOCK); h--)
+                            if (sha256d(this.at(h)).equals(prev)) {
+                                at = h + 1;
+                                break;
+                            }
+                    if (at !== undefined) {
+                        await this.write(at, [raw]);
+                        continue;
+                    }
+                    if (!this.o.history) {
+                        this.say(`header ${display(sha256d(raw))}: links to no header near the tip ${tipH}, and no history to fill in from: dropped`);
+                        continue;
+                    }
+                    await this.syncNow();
+                }
+                catch (e) {
+                    this.say(`header ${display(sha256d(raw))} not taken: ${e.message}`);
+                }
+            }
+        });
+    }
+    /** Fill in from the history (#132): from genesis once, then from a little below the tip. */
+    sync() { return this.serial(() => this.syncNow()); }
+    async syncNow() {
+        const url = this.o.history;
+        if (!url)
+            return;
+        const page = this.o.page ?? 50 * PER_BLOCK;
+        const t0 = Date.now();
+        const start = this.height();
+        let from = Math.max(0, start - 6);
+        for (let back = 0;;) {
+            const res = await (this.o.fetch ?? fetch)(`${url}?height=${from}&count=${page}`);
+            if (!res.ok)
+                throw new Error(`${url}: HTTP ${res.status}`);
+            const bytes = Buffer.from(await res.arrayBuffer());
+            if (bytes.length % SIZE)
+                throw new Error(`${url}: ${bytes.length} bytes, not whole headers`);
+            const raws = [];
+            for (let o = 0; o < bytes.length; o += SIZE)
+                raws.push(bytes.subarray(o, o + SIZE));
+            if (!raws.length)
+                break;
+            if (from > 0 && from <= this.height() + 1 && !prevOf(raws[0]).equals(sha256d(this.at(from - 1)))) {
+                // A reorg below where we asked from: further back.
+                if (++back > 8)
+                    throw new Error(`${url}: header ${from} links to none held, ${back} pages back`);
+                from = Math.max(0, from - PER_BLOCK * back);
+                continue;
+            }
+            await this.write(from, raws);
+            from += raws.length;
+        }
+        const tip = this.tip();
+        if (tip && tip.height !== start)
+            this.say(`the image's chain: ${start < 0 ? "built from genesis" : `from ${start}`} to ${tip.height} (${tip.hash}) in ${Date.now() - t0} ms`);
+    }
+    /**
+     * #141: the headers a skein whose tip is `tip` lacks, from the image's chain, in order — what the
+     * host pushes it on (re)subscribing, before the live stream. From the header after its tip when
+     * the image holds that tip; a tip the image does not hold at its height (a fork) from a little
+     * below it; none when the skein is at or past the image's tip, or has no tip (no chain part).
+     * Run in turn with the chain part's writes: every header the feed brought before this call is in.
+     */
+    after(tip) {
+        return this.serial(() => {
+            const top = this.height();
+            if (!tip || tip.height >= top)
+                return [];
+            const from = display(sha256d(this.at(tip.height))) === tip.hash ? tip.height + 1 : Math.max(0, tip.height - 6);
+            const out = [];
+            for (let h = from; h <= top; h++)
+                out.push(new Uint8Array(this.at(h)));
+            return out;
+        });
+    }
+    /** Start: the first sync, which creations wait for (`ready`). */
+    start() {
+        this.ready = this.sync().catch((e) => this.say(`the image's chain not synced: ${e.message}`));
+        return this.ready;
+    }
+}
+/**
+ * shruggr/skein#150: the chain app's best-chain header at `height` (the head `chain/state`, map
+ * `headers`: the MST height (u32 big-endian) → header): its hash (display hex) and merkle root
+ * (display hex); undefined when the chain state holds none there.
+ */
+export async function chainHeader(store, height) {
+    const state = await headTree(store, "chain/state");
+    if (!state)
+        return undefined;
+    const v = await store.get(state).catch(() => undefined);
+    const key = Buffer.alloc(4);
+    key.writeUInt32BE(height);
+    let node = v?.kind === "chain-state" ? v.maps?.headers ?? undefined : undefined;
+    while (node) {
+        const [left, es] = dagCbor.decode(await store.bytes(node));
+        let next = left;
+        let found;
+        for (const [k, val, right] of es) {
+            const c = Buffer.compare(Buffer.from(k), key);
+            if (c === 0) {
+                found = val;
+                break;
+            }
+            if (c > 0)
+                break;
+            next = right;
+        }
+        if (found) {
+            const raw = await store.bytes(found);
+            return { hash: display(sha256d(raw)), root: Buffer.from(raw.subarray(36, 68)).reverse().toString("hex") };
+        }
+        node = next ?? undefined;
+    }
+    return undefined;
+}
+/**
+ * #141: a skein's chain tip as its store holds it: the chain app's state (the head `chain/state`,
+ * {kind: "chain-state", maps: {headers}} — the MST height (u32 big-endian) → header, skein-sdk
+ * chain.zig; its last key is the tip), else the chain part of the tree it was born from (`main`'s
+ * `chain/tip`, image.zig's format), else none.
+ */
+export async function skeinTip(store) {
+    const state = await headTree(store, "chain/state");
+    if (state) {
+        const v = await store.get(state).catch(() => undefined);
+        let node = v?.kind === "chain-state" ? v.maps?.headers ?? undefined : undefined;
+        let last;
+        while (node) {
+            const [, es] = dagCbor.decode(await store.bytes(node));
+            if (!es.length)
+                break;
+            last = es[es.length - 1];
+            node = last[2] ?? undefined;
+        }
+        if (last) {
+            const raw = await store.bytes(last[1]);
+            return { height: Buffer.from(last[0]).readUInt32BE(0), hash: display(sha256d(raw)) };
+        }
+    }
+    const main = await headTree(store, "main");
+    if (!main)
+        return undefined;
+    const chain = (await readTree(store, main).catch(() => [])).find((e) => e.name === "chain" && e.mode === "40000");
+    const tip = chain && (await readTree(store, chain.cid)).find((e) => e.name === "tip");
+    if (!tip)
+        return undefined;
+    const t = JSON.parse(Buffer.from(await readBlob(store, tip.cid)).toString("utf8"));
+    return typeof t.height === "number" && typeof t.hash === "string" ? { height: t.height, hash: t.hash } : undefined;
+}

package/dist/host/install.d.ts

@@ -0,0 +1,22 @@
+import type { CID } from "multiformats/cid";
+import type { Store } from "../runtime/store.ts";
+import { type AppRecord, type AppTree, type InstanceView } from "./plan.ts";
+export * from "./plan.ts";
+/** What a tree carries that is not the app: build output, dependencies, VCS. */
+export declare function appIgnore(rel: string): boolean;
+/** Read and check the app in `dir`. */
+export declare function readApp(dir: string): Promise<AppTree>;
+/**
+ * Where the app is: a directory, or a git repository URL (`<url>` or
+ * `<url>#<rev>`) cloned into a temporary directory.
+ */
+export declare function fetchApp(spec: string): string;
+/** The view of an instance's store file (the CLI's, the tests'). */
+export declare function instanceView(store: Store): Promise<InstanceView>;
+/** The root holders (hex) as the head `grants` names them (#143; none: an unclaimed image). */
+export declare function rootOf(store: Store): Promise<string[]>;
+/** The app record a head's root is, if it is one. */
+export declare function appRecordOf(store: Store, name: string): Promise<{
+    cid: CID;
+    record: AppRecord;
+} | undefined>;