@dcasegr/skein 0.0.0-stage → 0.1.1

package/dist/testapps.d.ts

@@ -0,0 +1,101 @@
+import { type WalletInterface } from "@bsv/sdk";
+import type { CID } from "multiformats/cid";
+import { type AdminPlan } from "./client/admin.ts";
+import { type InstanceView } from "./host/install.ts";
+import type { Store } from "./runtime/store.ts";
+export interface PinnedApp {
+    name: string;
+    repo: string;
+    rev: string;
+    dir?: string;
+}
+/** shruggr/skein-shell: `run` and the shell (brush, coreutils, the toolset); 0.2.0 (#143): route `run` → run.run, roles {root: [run]}. */
+export declare const SHELL_APP: PinnedApp;
+/** shruggr/skein-chat: the chat loop (`chat`); 0.2.0 (#143): one open route `chat` → loop.chat. */
+export declare const CHAT_APP: PinnedApp;
+/** shruggr/skein-onboard (#90, #113): the onboarding app, installed in the host skein: onboard.create, registration, BRC-169; #127: onboard.create takes the caller's signed claim (0.3.0); #126: the manager and the certifier by peerAt (0.3.2, skein-sdk 0.7.1); #135: /register takes a session, the registrant its identity (0.3.3); resolve, search, the manifest and the paymail PKI are reads, reads[] (0.3.4); #143: routes, filters and roles ({user: [call, register, profile]}), reads are filter answers, root from the grants head (0.4.0). */
+export declare const ONBOARD_APP: PinnedApp;
+/** shruggr/skein-git (#91): the git app — `git.clone {url, hash}` into the store, the app record answered; #126: its fetch is the `fetch` intention (0.1.1, skein-sdk 0.7.1); 0.1.2: the manifest checked by every rule of src/host/manifest.ts (an overlay may list no topics, #120; boxes relative to the app, #128); 0.1.3: reads[] in the record, /lookup a read (#135); 0.2.0: routes, filters and roles, the record checked by every rule of #143's checkManifest. */
+export declare const GIT_APP: PinnedApp;
+/** shruggr/skein-site (#125): the management site as an app — its page at /site/, served from its own tree's www (0.6.2: bundles on a skein with no address-book roles, #126; 0.6.3: the catalog pins the current releases, git 0.1.2 among them; 0.7.3: the page in the skein brand — header and wallet chip, skein cards, the handle/Register card, the logged-out landing page; 0.7.6: Register over the wallet's session, #135; 0.7.7: the page a read, reads[], #135; 0.9.0: routes, filters and roles — the read route `get`, the Routes view, the roles/grants editor, no owner rows, #143). */
+export declare const SITE_APP: PinnedApp;
+/** shruggr/skein-chain (#78): the chain app, `chain/1`; v0.7.0 (#156: its state points at the host chain), the version the equivs pin. */
+export declare const CHAIN_APP: PinnedApp;
+/**
+ * #152: chain, git and site — what an image installed at birth before images carried apps — in that
+ * order, for installApps after the claim (each at its pin, or $SKEIN_CHAIN_DIR / $SKEIN_GIT_DIR /
+ * $SKEIN_SITE_DIR).
+ */
+export declare const CHAIN_GIT_SITE: PinnedApp[];
+/** A checkout of the app: its env directory, else the pinned commit, fetched once. */
+export declare function appCheckout(app: PinnedApp): string;
+/** What installing needs of a host: its SKEIN_HOME (host.db), the router's port, the owner's wallet, a wait for the router to settle. */
+export interface InstallHost {
+    home: string;
+    port: number;
+    owner: WalletInterface;
+    settled(): Promise<void>;
+}
+/** The instance `handle` as the plan reads it: its store file (host.db's row), read only, while the router runs it. */
+export declare function viewOf(h: Pick<InstallHost, "home">, handle: string): Promise<InstanceView & {
+    close(): void;
+}>;
+/**
+ * Deliver a plan as the operator's client does (#142): each message on the wallet's BRC-104 session with the
+ * instance's front door (dag-cbor bodies, src/client/raw.ts), in order; throws at the first refusal.
+ */
+export declare function sendPlan(h: Pick<InstallHost, "port" | "owner" | "settled">, handle: string, p: AdminPlan, wallet?: WalletInterface): Promise<number>;
+/**
+ * Install the app in `dir` into `handle` as its owner: planned from the instance's store (as `skein install
+ * --store` plans), `config` merged over the manifest's, then sent (sendPlan). The prompt.
+ */
+export declare function installApp(h: InstallHost, handle: string, dir: string, o?: {
+    config?: Record<string, unknown>;
+    wallet?: WalletInterface;
+}): Promise<string[]>;
+/** Uninstall `app` from `handle` as its owner (planned as `skein uninstall` plans, then sent). The prompt. */
+export declare function uninstallApp(h: InstallHost, handle: string, app: string, o?: {
+    wallet?: WalletInterface;
+}): Promise<string[]>;
+/**
+ * What the equivs ran as `skein-host install|uninstall` before #124, now the owner's path: `install <dir>
+ * --instance <h> [--config json] [--dry-run]` or `uninstall <app> --instance <h>` — planned from the
+ * instance's store and, unless a dry run, sent by `wallet` (default the owner) on its session (sendPlan). `out`: the prompt, then `<h>: <app> <version> installed|upgraded: <n>
+ * messages sent` (or `<h>: <app> uninstalled: …`); `err` and code 1 when planning or a send fails.
+ */
+export declare function ownerCli(h: InstallHost, args: string[], wallet?: WalletInterface): Promise<{
+    code: number;
+    out: string[];
+    err: string[];
+}>;
+/**
+ * #152: root's own route `/` to the site's page (`skein routes add --transport http --prefix --filters
+ * site.get --settings '{"root":"www"}' /`), sent as the owner; the site installed first.
+ */
+export declare function siteAtRoot(h: InstallHost, handle: string, o?: {
+    wallet?: WalletInterface;
+}): Promise<void>;
+/** Install apps into an instance as its owner (installApp each; the instance's store must exist: hydrate it first). */
+export declare function installApps(h: InstallHost, handle: string, apps?: PinnedApp[], o?: {
+    config?: Record<string, unknown>;
+    wallet?: WalletInterface;
+}): Promise<void>;
+/**
+ * The shell app's shell program put straight into a store with no instance
+ * (the shell cases and git in the VM run `skein-kernel shell <store>
+ * <program>`, no log): the record and the blocks the install would send for
+ * it, built by the install's own code (readApp, shellProgram). Its CID.
+ */
+export declare function putShellProgram(store: Pick<Store, "put" | "putBlock" | "has">, app?: PinnedApp): Promise<CID>;
+/**
+ * #135: a BRC-22 submission as a signed request — POST <base>/submit is a message route. The stock AuthFetch
+ * carries only content-type, authorization and x-bsv-* headers, so X-Topics rides beside the signed ones (added
+ * on the wire by the transport, not covered by the signature). One session per origin. An answer that is not
+ * signed (a 503 at the router's bound) comes back as its status. A fetch for the SDK's
+ * HTTPSOverlayBroadcastFacilitator too.
+ */
+export declare function signedSubmitter(wallet: WalletInterface): (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+}) => Promise<Response>;

package/dist/testapps.js

@@ -0,0 +1,275 @@
+// The shell app and the chat app for tests and equivs (#83), the
+// onboarding app (#90), the git app (#91) and the management site (#125). A genesis has no shell, no
+// `run`, no `chat`: a test that runs them installs the apps first, through
+// the real install path (the owner's messages src/client/admin.ts builds, sent
+// on the owner's BRC-104 session as the client sends them, #142), from a
+// checkout at the commit pinned here — $SKEIN_SHELL_DIR / $SKEIN_CHAT_DIR /
+// $SKEIN_ONBOARD_DIR / $SKEIN_GIT_DIR name a checkout instead,
+// $SKEIN_SHELL_REV / $SKEIN_CHAT_REV / $SKEIN_ONBOARD_REV / $SKEIN_GIT_REV
+// another commit. A pinned commit is fetched once into
+// <tmpdir>/skein-apps/<name>-<rev> and reused. Not part of anything that runs.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AuthFetch } from "@bsv/sdk";
+import { join as joinPath } from "node:path";
+import { planInstallApp, planRoute, planUninstallApp } from "./client/admin.js";
+import { RawBox } from "./client/raw.js";
+import { WASM_DIR, wasmDirObjects } from "./host/boot.js";
+import { HostDb } from "./host/instances.js";
+import { fetchApp, instanceView, readApp, shellProgram } from "./host/install.js";
+import { storeSpec } from "./runtime/index-store.js";
+import { openStoreFile, storeExists } from "./host/stores.js";
+/** shruggr/skein-shell: `run` and the shell (brush, coreutils, the toolset); 0.2.0 (#143): route `run` → run.run, roles {root: [run]}. */
+export const SHELL_APP = {
+    name: "shell", repo: "https://github.com/shruggr/skein-shell",
+    rev: process.env.SKEIN_SHELL_REV ?? "86c834368dd81893069c0e131dd33f432d69e44f", dir: process.env.SKEIN_SHELL_DIR,
+};
+/** shruggr/skein-chat: the chat loop (`chat`); 0.2.0 (#143): one open route `chat` → loop.chat. */
+export const CHAT_APP = {
+    name: "chat", repo: "https://github.com/shruggr/skein-chat",
+    rev: process.env.SKEIN_CHAT_REV ?? "e01eb737b234f4abdfb2704bb3cc0d6747b8a01f", dir: process.env.SKEIN_CHAT_DIR,
+};
+/** shruggr/skein-onboard (#90, #113): the onboarding app, installed in the host skein: onboard.create, registration, BRC-169; #127: onboard.create takes the caller's signed claim (0.3.0); #126: the manager and the certifier by peerAt (0.3.2, skein-sdk 0.7.1); #135: /register takes a session, the registrant its identity (0.3.3); resolve, search, the manifest and the paymail PKI are reads, reads[] (0.3.4); #143: routes, filters and roles ({user: [call, register, profile]}), reads are filter answers, root from the grants head (0.4.0). */
+export const ONBOARD_APP = {
+    name: "onboard", repo: "https://github.com/shruggr/skein-onboard",
+    rev: process.env.SKEIN_ONBOARD_REV ?? "189b7c2df3041c4914dcf189ade4c8ca241a9b5f", dir: process.env.SKEIN_ONBOARD_DIR,
+};
+/** shruggr/skein-git (#91): the git app — `git.clone {url, hash}` into the store, the app record answered; #126: its fetch is the `fetch` intention (0.1.1, skein-sdk 0.7.1); 0.1.2: the manifest checked by every rule of src/host/manifest.ts (an overlay may list no topics, #120; boxes relative to the app, #128); 0.1.3: reads[] in the record, /lookup a read (#135); 0.2.0: routes, filters and roles, the record checked by every rule of #143's checkManifest. */
+export const GIT_APP = {
+    name: "git", repo: "https://github.com/shruggr/skein-git",
+    rev: process.env.SKEIN_GIT_REV ?? "01e804adcd86bfbad0139667ac362949c067d4e3", dir: process.env.SKEIN_GIT_DIR,
+};
+/** shruggr/skein-site (#125): the management site as an app — its page at /site/, served from its own tree's www (0.6.2: bundles on a skein with no address-book roles, #126; 0.6.3: the catalog pins the current releases, git 0.1.2 among them; 0.7.3: the page in the skein brand — header and wallet chip, skein cards, the handle/Register card, the logged-out landing page; 0.7.6: Register over the wallet's session, #135; 0.7.7: the page a read, reads[], #135; 0.9.0: routes, filters and roles — the read route `get`, the Routes view, the roles/grants editor, no owner rows, #143). */
+export const SITE_APP = {
+    name: "site", repo: "https://github.com/shruggr/skein-site",
+    rev: process.env.SKEIN_SITE_REV ?? "3913f1927e401a43861150583ffa5342b1cc28f3", dir: process.env.SKEIN_SITE_DIR,
+};
+/** shruggr/skein-chain (#78): the chain app, `chain/1`; v0.7.0 (#156: its state points at the host chain), the version the equivs pin. */
+export const CHAIN_APP = {
+    name: "chain", repo: "https://github.com/shruggr/skein-chain",
+    rev: process.env.SKEIN_CHAIN_REV ?? "4d3f595c0f073db63223907fcd0909d53e770b91", dir: process.env.SKEIN_CHAIN_DIR,
+};
+/**
+ * #152: chain, git and site — what an image installed at birth before images carried apps — in that
+ * order, for installApps after the claim (each at its pin, or $SKEIN_CHAIN_DIR / $SKEIN_GIT_DIR /
+ * $SKEIN_SITE_DIR).
+ */
+export const CHAIN_GIT_SITE = [CHAIN_APP, GIT_APP, SITE_APP];
+/** A checkout of the app: its env directory, else the pinned commit, fetched once. */
+export function appCheckout(app) {
+    if (app.dir)
+        return app.dir;
+    const cache = join(tmpdir(), "skein-apps");
+    const dir = join(cache, `${app.name}-${app.rev}`);
+    if (existsSync(join(dir, "etc/app.json")))
+        return dir;
+    mkdirSync(cache, { recursive: true });
+    // Fetched beside, then renamed into place: two test files may want it at once.
+    const tmp = mkdtempSync(join(cache, `${app.name}-`));
+    const run = (...args) => {
+        const r = spawnSync("git", args, { cwd: tmp, encoding: "utf8" });
+        if (r.status !== 0)
+            throw new Error(`git ${args.join(" ")}: ${r.stderr.trim() || `exit ${r.status}`}`);
+    };
+    run("init", "-q");
+    run("fetch", "-q", "--depth", "1", app.repo, app.rev);
+    run("checkout", "-q", "FETCH_HEAD");
+    try {
+        renameSync(tmp, dir);
+    }
+    catch {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+    return dir;
+}
+/** The instance `handle` as the plan reads it: its store file (host.db's row), read only, while the router runs it. */
+export async function viewOf(h, handle) {
+    const db = new HostDb(joinPath(h.home, "host.db"));
+    const row = db.get(handle);
+    db.close();
+    if (!row)
+        throw new Error(`no instance ${handle}`);
+    if (!storeExists(storeSpec(row)))
+        throw new Error(`${handle}: no store at ${storeSpec(row)} yet (hydrate it first)`);
+    const s = openStoreFile(storeSpec(row), { readOnly: true });
+    try {
+        return { ...(await instanceView(s)), close: () => s.close() };
+    }
+    catch (e) {
+        s.close();
+        throw e;
+    }
+}
+/**
+ * Deliver a plan as the operator's client does (#142): each message on the wallet's BRC-104 session with the
+ * instance's front door (dag-cbor bodies, src/client/raw.ts), in order; throws at the first refusal.
+ */
+export async function sendPlan(h, handle, p, wallet = h.owner) {
+    const box = new RawBox(wallet, `http://127.0.0.1:${h.port}/@${handle}`);
+    for (const m of p.messages)
+        await box.send(p.recipient, m.box, m.body);
+    await h.settled();
+    return p.messages.length;
+}
+/**
+ * Install the app in `dir` into `handle` as its owner: planned from the instance's store (as `skein install
+ * --store` plans), `config` merged over the manifest's, then sent (sendPlan). The prompt.
+ */
+export async function installApp(h, handle, dir, o = {}) {
+    await h.settled();
+    const view = await viewOf(h, handle);
+    let p;
+    try {
+        p = await planInstallApp(await readApp(dir), view, { config: o.config, modules: wasmDirObjects(WASM_DIR) });
+    }
+    finally {
+        view.close();
+    }
+    await sendPlan(h, handle, p, o.wallet);
+    return p.prompt;
+}
+/** Uninstall `app` from `handle` as its owner (planned as `skein uninstall` plans, then sent). The prompt. */
+export async function uninstallApp(h, handle, app, o = {}) {
+    await h.settled();
+    const view = await viewOf(h, handle);
+    let p;
+    try {
+        p = await planUninstallApp(app, view);
+    }
+    finally {
+        view.close();
+    }
+    await sendPlan(h, handle, p, o.wallet);
+    return p.prompt;
+}
+/**
+ * What the equivs ran as `skein-host install|uninstall` before #124, now the owner's path: `install <dir>
+ * --instance <h> [--config json] [--dry-run]` or `uninstall <app> --instance <h>` — planned from the
+ * instance's store and, unless a dry run, sent by `wallet` (default the owner) on its session (sendPlan). `out`: the prompt, then `<h>: <app> <version> installed|upgraded: <n>
+ * messages sent` (or `<h>: <app> uninstalled: …`); `err` and code 1 when planning or a send fails.
+ */
+export async function ownerCli(h, args, wallet = h.owner) {
+    const out = [], err = [];
+    const [cmd, what] = args;
+    const opt = (name) => { const i = args.indexOf(name); return i > 0 ? args[i + 1] : undefined; };
+    const handle = opt("--instance");
+    if ((cmd !== "install" && cmd !== "uninstall") || !what || !handle)
+        return { code: 2, out, err: [`ownerCli: ${args.join(" ")}`] };
+    try {
+        await h.settled();
+        const view = await viewOf(h, handle);
+        let p;
+        try {
+            if (cmd === "install") {
+                const c = opt("--config");
+                const r = await planInstallApp(await readApp(fetchApp(what)), view, { config: c ? JSON.parse(c) : undefined, modules: wasmDirObjects(WASM_DIR) });
+                p = { ...r, upgrade: r.prompt[0].startsWith("upgrade") };
+            }
+            else
+                p = { ...(await planUninstallApp(what, view)), app: what };
+        }
+        finally {
+            view.close();
+        }
+        out.push(...p.prompt);
+        if (args.includes("--dry-run"))
+            return { code: 0, out, err };
+        const n = await sendPlan(h, handle, p, wallet);
+        out.push(cmd === "install" ? `${handle}: ${p.app} ${p.version} ${p.upgrade ? "upgraded" : "installed"}: ${n} messages sent` : `${handle}: ${what} uninstalled: ${n} messages sent`);
+        return { code: 0, out, err };
+    }
+    catch (e) {
+        err.push(`${cmd}: ${e.message}`);
+        return { code: 1, out, err };
+    }
+}
+/**
+ * #152: root's own route `/` to the site's page (`skein routes add --transport http --prefix --filters
+ * site.get --settings '{"root":"www"}' /`), sent as the owner; the site installed first.
+ */
+export async function siteAtRoot(h, handle, o = {}) {
+    await h.settled();
+    const view = await viewOf(h, handle);
+    let p;
+    try {
+        p = await planRoute(view, { op: "add", transport: "http", address: "/", prefix: true, filters: ["site.get"], settings: { root: "www" } });
+    }
+    finally {
+        view.close();
+    }
+    await sendPlan(h, handle, p, o.wallet);
+}
+/** Install apps into an instance as its owner (installApp each; the instance's store must exist: hydrate it first). */
+export async function installApps(h, handle, apps = [SHELL_APP, CHAT_APP], o = {}) {
+    for (const app of apps) {
+        try {
+            await installApp(h, handle, appCheckout(app), o);
+        }
+        catch (e) {
+            throw new Error(`install ${app.name} into ${handle}: ${e.message}`);
+        }
+    }
+}
+/**
+ * The shell app's shell program put straight into a store with no instance
+ * (the shell cases and git in the VM run `skein-kernel shell <store>
+ * <program>`, no log): the record and the blocks the install would send for
+ * it, built by the install's own code (readApp, shellProgram). Its CID.
+ */
+export async function putShellProgram(store, app = SHELL_APP) {
+    const dir = appCheckout(app);
+    const t = await readApp(dir);
+    const src = t.checked.sources.shell;
+    if (src?.kind !== "shell")
+        throw new Error(`${dir}: etc/app.json has no shell program`);
+    const { record, blocks } = shellProgram(t.read, "shell", src, t.checked.manifest.name);
+    for (const b of blocks)
+        if (!(await store.has(b.cid)))
+            await store.putBlock(b.cid, b.bytes);
+    return await store.put(record);
+}
+/**
+ * #135: a BRC-22 submission as a signed request — POST <base>/submit is a message route. The stock AuthFetch
+ * carries only content-type, authorization and x-bsv-* headers, so X-Topics rides beside the signed ones (added
+ * on the wire by the transport, not covered by the signature). One session per origin. An answer that is not
+ * signed (a 503 at the router's bound) comes back as its status. A fetch for the SDK's
+ * HTTPSOverlayBroadcastFacilitator too.
+ */
+export function signedSubmitter(wallet) {
+    const sessions = new Map();
+    return async (url, init = {}) => {
+        const u = new URL(url);
+        // The dev form /@<handle>/…: the session is that instance's, its handshake under the prefix (as RawBox's).
+        const prefix = /^\/@[^/]+/.exec(u.pathname)?.[0] ?? "";
+        let s = sessions.get(u.origin + prefix);
+        if (!s) {
+            const slot = {};
+            const wire = ((input, i) => {
+                const w = new URL(input instanceof Request ? input.url : String(input));
+                if (prefix && w.pathname === "/.well-known/auth")
+                    w.pathname = `${prefix}/.well-known/auth`;
+                const h = new Headers(i?.headers);
+                if (slot.topics !== undefined && w.pathname.endsWith("/submit"))
+                    h.set("x-topics", slot.topics);
+                return fetch(w, { ...i, headers: h });
+            });
+            slot.af = new AuthFetch(wallet, undefined, undefined, undefined, {}, wire);
+            s = slot;
+            sessions.set(u.origin + prefix, s);
+        }
+        const hs = Object.fromEntries(Object.entries(init.headers ?? {}).map(([k, v]) => [k.toLowerCase(), v]));
+        s.topics = hs["x-topics"];
+        const body = init.body instanceof Uint8Array ? init.body : Uint8Array.from(init.body);
+        try {
+            return await s.af.fetch(url, { method: init.method ?? "POST", headers: { "content-type": hs["content-type"] ?? "application/octet-stream" }, body: Buffer.from(body) });
+        }
+        catch (e) {
+            const m = /Received HTTP (\d+)/.exec(e.message);
+            if (m)
+                return new Response(JSON.stringify({ status: "error" }), { status: Number(m[1]), headers: { "content-type": "application/json" } });
+            throw e;
+        }
+    };
+}

package/dist/testkit.d.ts

@@ -0,0 +1,25 @@
+import type { CID } from "multiformats/cid";
+import type { Listed, MessageBox } from "./peers/infer.ts";
+import type { Stamp } from "./runtime/syscalls.ts";
+export declare function collect<T>(it: AsyncIterable<T>): Promise<T[]>;
+/** An in-process BRC-33 messagebox: sendMessage / listMessages / acknowledgeMessage, per identity. */
+export declare function messageBoxHub(): {
+    as(identity: string): MessageBox;
+    /** Put a message in a box as if `sender` had authenticated (tests of forged senders). */
+    inject: (recipient: string, box: string, m: Omit<Listed, "messageId" | "created_at">) => void;
+    pending: (recipient: string, box: string) => Listed[];
+};
+export type Hub = ReturnType<typeof messageBoxHub>;
+export declare const T0: Stamp;
+export declare const iso: (s: Stamp) => string;
+/** A settable clock for admission stamps. */
+export declare function scriptClock(start?: Stamp): {
+    now: () => Stamp;
+    set(s: Stamp): void;
+};
+/** A directory as the client sends it: {root, bundles of ≤ 1 MiB, the last naming the root}. */
+export declare function bundlesOf(dir: string, limit?: number): Promise<{
+    root: CID;
+    bundles: Uint8Array[];
+    records: number;
+}>;

package/dist/testkit.js

@@ -0,0 +1,48 @@
+// Test helpers shared across directories (and kernel-zig/equiv). Not part of
+// anything that runs.
+import { dirBundles } from "./client/client.js";
+export async function collect(it) {
+    const out = [];
+    for await (const x of it)
+        out.push(x);
+    return out;
+}
+/** An in-process BRC-33 messagebox: sendMessage / listMessages / acknowledgeMessage, per identity. */
+export function messageBoxHub() {
+    const boxes = new Map();
+    let n = 0;
+    const key = (recipient, box) => `${recipient} ${box}`;
+    const deliver = (recipient, box, m) => {
+        const q = boxes.get(key(recipient, box)) ?? [];
+        n++;
+        q.push({ ...m, messageId: `m${n}`, created_at: String(n).padStart(8, "0") });
+        boxes.set(key(recipient, box), q);
+    };
+    return {
+        as(identity) {
+            return {
+                list: async (box) => [...(boxes.get(key(identity, box)) ?? [])],
+                ack: async (ids) => {
+                    for (const [k, q] of boxes)
+                        if (k.startsWith(`${identity} `))
+                            boxes.set(k, q.filter((m) => !ids.includes(m.messageId)));
+                },
+                send: async ({ recipient, box, body }) => deliver(recipient, box, { sender: identity, body: JSON.stringify(body) }),
+            };
+        },
+        /** Put a message in a box as if `sender` had authenticated (tests of forged senders). */
+        inject: deliver,
+        pending: (recipient, box) => [...(boxes.get(key(recipient, box)) ?? [])],
+    };
+}
+export const T0 = [1_790_000_000, 250_000_000];
+export const iso = (s) => new Date(s[0] * 1000 + Math.floor(s[1] / 1e6)).toISOString();
+/** A settable clock for admission stamps. */
+export function scriptClock(start = T0) {
+    let now = start;
+    return { now: () => now, set(s) { now = s; } };
+}
+/** A directory as the client sends it: {root, bundles of ≤ 1 MiB, the last naming the root}. */
+export async function bundlesOf(dir, limit) {
+    return dirBundles(dir, { limit });
+}

package/dist/wallet.d.ts

@@ -0,0 +1,35 @@
+import { PrivateKey, ProtoWallet, type WalletInterface } from "@bsv/sdk";
+export type { WalletInterface };
+export * from "./runtime/identity.ts";
+export type WalletConfig = 
+/** An in-process @1sat/wallet-node wallet. The key comes from the host's config/env, never from skein's files. */
+{
+    kind: "node";
+    chain?: "main" | "test";
+    privateKey?: string;
+    storage: string;
+    storageIdentityKey?: string;
+}
+/** A running BRC-100 JSON endpoint, e.g. `1sat serve wallet-api` (default http://127.0.0.1:3321). */
+ | {
+    kind: "remote";
+    url?: string;
+    originator?: string;
+}
+/** Tests only: a random key that lives as long as the process. */
+ | {
+    kind: "ephemeral";
+};
+export declare function connectWallet(config: WalletConfig): Promise<WalletInterface>;
+/**
+ * Tests only. Never persisted, so nothing it signs is attributable after the
+ * process exits. A ProtoWallet has keys but no actions; those reject.
+ */
+export declare function ephemeralWallet(key?: PrivateKey): WalletInterface;
+/**
+ * A wallet over one private key (#142: the operator's, from its key file): it signs, derives and opens
+ * BRC-103/104 sessions (a ProtoWallet); it has no actions (no coins), and those reject. `base`: the
+ * ProtoWallet over that key it wraps (#160: the one-key host's, signer.ts OneKeyWallet), by default a plain one.
+ */
+export declare function keyWallet(key: PrivateKey, base?: ProtoWallet): WalletInterface;
+export declare function remoteWallet(url?: string, originator?: string): WalletInterface;

package/dist/wallet.js

@@ -0,0 +1,87 @@
+// Connecting to a BRC-100 wallet: the runtime's second edge (docs/ARCH.md).
+// This file is outside src/runtime because a remote wallet is reached over
+// HTTP; identities under it are derived with src/runtime/identity.ts. The
+// host, the client, the peers and skein-dev use it.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { HTTPWalletJSON, PrivateKey, ProtoWallet } from "@bsv/sdk";
+export * from "./runtime/identity.js";
+export async function connectWallet(config) {
+    switch (config.kind) {
+        case "remote": return remoteWallet(config.url, config.originator);
+        case "node": return nodeWallet(config);
+        case "ephemeral": return ephemeralWallet();
+    }
+}
+/**
+ * Tests only. Never persisted, so nothing it signs is attributable after the
+ * process exits. A ProtoWallet has keys but no actions; those reject.
+ */
+export function ephemeralWallet(key = PrivateKey.fromRandom()) {
+    return keyWallet(key);
+}
+/**
+ * A wallet over one private key (#142: the operator's, from its key file): it signs, derives and opens
+ * BRC-103/104 sessions (a ProtoWallet); it has no actions (no coins), and those reject. `base`: the
+ * ProtoWallet over that key it wraps (#160: the one-key host's, signer.ts OneKeyWallet), by default a plain one.
+ */
+export function keyWallet(key, base = new ProtoWallet(key)) {
+    return new Proxy(base, {
+        get(t, p) {
+            // `then` must stay undefined or awaiting the wallet would call it.
+            if (typeof p !== "string" || p === "then" || p in t)
+                return Reflect.get(t, p);
+            return () => Promise.reject(new Error(`ephemeral wallet: ${p} is not supported`));
+        },
+    });
+}
+export function remoteWallet(url = "http://127.0.0.1:3321", originator = "skein") {
+    return new HTTPWalletJSON(originator, url, relayErrors);
+}
+// wallet-api answers a refusal with 400 {"error": "..."}; HTTPWalletJSON only
+// understands {isError, ...} and would reduce the message to a status code,
+// losing the `1sat permissions grant …` command the refusal names.
+async function relayErrors(input, init) {
+    const res = await fetch(input, init);
+    if (res.ok)
+        return res;
+    let body;
+    try {
+        body = await res.clone().json();
+    }
+    catch {
+        return res;
+    }
+    const b = body;
+    if (b && typeof b.error === "string" && !b.isError)
+        throw new Error(`wallet: ${b.error}`);
+    return res;
+}
+async function nodeWallet(c) {
+    const privateKey = c.privateKey ?? process.env.PRIVATE_KEY_WIF;
+    if (!privateKey)
+        throw new Error("node wallet: no privateKey in config and $PRIVATE_KEY_WIF unset");
+    // Optional dependency: loaded by name so skein installs and typechecks without it.
+    const spec = "@1sat/wallet-node";
+    let mod;
+    try {
+        mod = await import(__rewriteRelativeImportExtension(spec));
+    }
+    catch (e) {
+        throw new Error(`node wallet: ${spec} is not installed (${e.message}); use {kind:"remote"} against \`1sat serve wallet-api\``);
+    }
+    const { wallet } = await mod.createNodeWallet({
+        privateKey,
+        chain: c.chain ?? "main",
+        storageIdentityKey: c.storageIdentityKey ?? "skein",
+        storage: { provider: "bun-sqlite", filename: c.storage }, // picks node:sqlite under Node
+        skipInitialMonitor: true,
+    });
+    return wallet;
+}

package/images/README.md

@@ -0,0 +1,68 @@
+# Images
+
+An image is a system tree a skein is born from (docs/BOOTSTRAP.md, "The
+system tree"), with no root in its genesis and a claim route. It is the
+boundary programs and, optionally, a list of apps to install at birth.
+
+- `default/`: the default image — the front door, the messagebox, the
+  wallet and the claim route; no apps. `skein-host add <h> --image default`,
+  and every skein the instance manager creates.
+- `host/`: the host image's own part, merged over `default/` (src/host/boot.ts
+  `mergeImages`): the host skein's image, with skein-onboard. `skein-host
+  add <h> --image host` boots an unclaimed skein from it.
+
+`skein-host add <h> --image <dir>` boots from an image directory. One
+with `bin/` is a complete image. One without `bin/` is merged over
+`default/` first, exactly as `host/` is (#152), so an app repository's
+`image/` needs only `etc/apps.json`.
+
+## An image's form
+
+```
+bin/<name>.wasm | bin/<name>.cid   a program's module, or its CID (the kernel's pinned modules: wasm/)
+bin/<name>.json                    the program record's inputs, services and description
+etc/dispatch.json                  the routes; an image's carry the claim route
+etc/config.json                    optional: defaults, peers, names, collect, feeds, roles
+etc/apps.json                      optional: the apps installed at birth, and root's own routes
+```
+
+`etc/apps.json`:
+
+```json
+{
+  "install": [
+    "apps/one",
+    "..",
+    { "url": "https://github.com/shruggr/skein-onboard/archive/refs/tags/v0.4.0.tar.gz",
+      "hash": "ba29f99adb0d2d1849aa7f0cf72ceeefde88c5ae" }
+  ],
+  "routes": [{ "transport": "http", "address": "/", "prefix": true, "filters": ["site.get"], "root": "www" }]
+}
+```
+
+Each `install` entry is one app, installed in order:
+
+- **a directory**, relative to the image: a directory of the image's tree
+  (`apps/one`), or one beside it (`..`, `../<dir>`), read from disk when the
+  image is booted from its directory, as `skein install <dir>` reads it
+  (`zig-out`, `.zig-cache`, `zig-pkg`, `.git` and `node_modules` left
+  out). An app repository can carry its image as `image/`, listing `..`;
+- **a release tarball** `{url, hash}`: `hash` is the git id of the app's
+  tree (`git rev-parse <tag>^{tree}`). The host fetches it (gzip or plain
+  tar; a tarball holding one directory, as a tag's archive does, is that
+  directory), scans it as a directory, and refuses it unless its tree is
+  `hash`. A source that already holds the tree is not fetched.
+
+Each is installed as a directory install by message would install it — the
+app's objects, its record under `<app>/app`, its routes — and the genesis
+carries the result, so root upgrades it later by installing a newer version
+the same way, keeping its state. An app with a `start` message is refused
+at birth (a genesis carries no message): install it after the claim.
+`routes` are root's own routes, added after the apps (a handler may be
+`<app>.<role>` of an app above).
+
+Two images merge (`mergeImages`): their `install` lists are joined (an app
+in both is refused), and a route of the second at the same transport,
+address and prefix as one of the first replaces it. Any other path in both
+(`etc/dispatch.json`, `etc/config.json`, `bin/<name>.json`) is refused
+unless it is the same file: a merge adds paths, it does not replace one.