@starlove/orbit 1.4.1 → 2.0.0

package/lib/node/repo-board.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A repo names its board in a committed orbit.json: { "board": "<slug>" }.
+ * Orbit reads it only when a command names no board, and records no folder:
+ * the `orbit` CLI and `orbit mcp` read the file where they run (or where
+ * `--cwd` says) and hand the board on, to their own session or, in remote
+ * mode, to POST /api/cmd as `repo_board`.
+ *
+ * Which file counts: the nearest orbit.json up from where the agent runs,
+ * stopping at the repo's top (the folder holding .git, a folder or a
+ * worktree's file). Outside a repo, only the current folder's. Nothing above
+ * the repo's top or above $HOME ever applies.
+ *
+ * A cloned repo's file is untrusted. It only names a board and grants nothing:
+ * only a regular file of at most 16 KB is read, a board must be a slug, and
+ * writing never follows a symlink (a temporary file is renamed into place).
+ */
+import type { RepoChoice, RepoSource } from "../commands/index.ts";
+export declare const REPO_FILE = "orbit.json";
+export declare const REPO_FILE_MAX_BYTES: number;
+/** The repo's top: the nearest folder at or above `start` holding .git, never above $HOME. Null outside a repo. */
+export declare function repoTop(start: string): string | null;
+/** The orbit.json that applies at `start`: where it is (or where link would make it), whether it exists, and whether it's in a repo. */
+export declare function findRepoFile(start: string): {
+    path: string;
+    exists: boolean;
+    inRepo: boolean;
+};
+/** The board the repo at `start` names, or why its file can't be used. */
+export declare function readRepoBoard(start: string): RepoChoice;
+/** What a remote client sends for a repo's board: the fields of POST /api/cmd. */
+export declare function repoBoardFields(repo: RepoChoice): {
+    repo_board?: string;
+    repo_board_problem?: string;
+};
+export interface LinkResult {
+    ok: boolean;
+    text: string;
+    data: unknown;
+}
+/** Makes the repo at `start` name board `slug`, keeping every other field. */
+export declare function linkRepoBoard(start: string, slug: string): LinkResult;
+/** Takes `board` out of the repo's orbit.json, and the file with it when nothing else is left. */
+export declare function unlinkRepoBoard(start: string): LinkResult;
+/** `boards link <board>` or `boards unlink`, from a shell's words: which, or null. */
+export declare function repoLinkWords(argv: readonly string[]): "link" | "unlink" | null;
+/** The repo source for a command run where `dir` is: reads the file there, and (for a shell) writes it. */
+export declare function repoSourceAt(dir: string, options?: {
+    writes?: boolean;
+}): RepoSource;

package/lib/node/repo-board.js

@@ -0,0 +1,245 @@
+/**
+ * A repo names its board in a committed orbit.json: { "board": "<slug>" }.
+ * Orbit reads it only when a command names no board, and records no folder:
+ * the `orbit` CLI and `orbit mcp` read the file where they run (or where
+ * `--cwd` says) and hand the board on, to their own session or, in remote
+ * mode, to POST /api/cmd as `repo_board`.
+ *
+ * Which file counts: the nearest orbit.json up from where the agent runs,
+ * stopping at the repo's top (the folder holding .git, a folder or a
+ * worktree's file). Outside a repo, only the current folder's. Nothing above
+ * the repo's top or above $HOME ever applies.
+ *
+ * A cloned repo's file is untrusted. It only names a board and grants nothing:
+ * only a regular file of at most 16 KB is read, a board must be a slug, and
+ * writing never follows a symlink (a temporary file is renamed into place).
+ */
+import { randomBytes } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { oneLine } from "../commands/present.js";
+import { isSlug } from "../core/text.js";
+export const REPO_FILE = "orbit.json";
+export const REPO_FILE_MAX_BYTES = 16 * 1024;
+class RepoFileProblem extends Error {
+    problem;
+    constructor(problem) {
+        super(problem);
+        this.problem = problem;
+    }
+}
+function lstatOrNull(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+const homeDir = () => resolve(process.env.HOME ?? homedir());
+/** The repo's top: the nearest folder at or above `start` holding .git, never above $HOME. Null outside a repo. */
+export function repoTop(start) {
+    const home = homeDir();
+    let dir = resolve(start);
+    for (;;) {
+        const git = lstatOrNull(join(dir, ".git"));
+        if (git && (git.isDirectory() || git.isFile()))
+            return dir;
+        const parent = dirname(dir);
+        if (dir === home || parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** The orbit.json that applies at `start`: where it is (or where link would make it), whether it exists, and whether it's in a repo. */
+export function findRepoFile(start) {
+    const from = resolve(start);
+    const top = repoTop(from);
+    if (!top) {
+        const path = join(from, REPO_FILE);
+        return { path, exists: Boolean(lstatOrNull(path)), inRepo: false };
+    }
+    for (let dir = from;; dir = dirname(dir)) {
+        const path = join(dir, REPO_FILE);
+        if (lstatOrNull(path))
+            return { path, exists: true, inRepo: true };
+        if (dir === top || dirname(dir) === dir)
+            break;
+    }
+    return { path: join(top, REPO_FILE), exists: false, inRepo: true };
+}
+/** The file's JSON object, read safely: a regular file, at most 16 KB, never through a symlink. */
+function readObject(path) {
+    const stat = lstatOrNull(path);
+    if (!stat)
+        return null;
+    if (stat.isSymbolicLink())
+        throw new RepoFileProblem("symlink");
+    if (!stat.isFile())
+        throw new RepoFileProblem("not_file");
+    if (stat.size > REPO_FILE_MAX_BYTES)
+        throw new RepoFileProblem("too_big");
+    // O_NOFOLLOW: a file swapped for a link after the lstat isn't followed.
+    // O_NONBLOCK: a file swapped for a pipe doesn't hang the command.
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    let text;
+    let mode;
+    try {
+        const opened = fstatSync(fd);
+        if (!opened.isFile())
+            throw new RepoFileProblem("not_file");
+        if (opened.size > REPO_FILE_MAX_BYTES)
+            throw new RepoFileProblem("too_big");
+        mode = opened.mode & 0o777;
+        const buffer = Buffer.alloc(REPO_FILE_MAX_BYTES + 1);
+        let length = 0;
+        for (let n = 1; length < buffer.length && n > 0; length += n)
+            n = readSync(fd, buffer, length, buffer.length - length, null);
+        if (length > REPO_FILE_MAX_BYTES)
+            throw new RepoFileProblem("too_big");
+        text = buffer.subarray(0, length).toString("utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new RepoFileProblem("not_json");
+    }
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        throw new RepoFileProblem("not_json");
+    return { data: data, mode };
+}
+/** The board the repo at `start` names, or why its file can't be used. */
+export function readRepoBoard(start) {
+    try {
+        const found = findRepoFile(start);
+        const read = found.exists ? readObject(found.path) : null;
+        const value = read?.data.board;
+        if (value === undefined || value === null)
+            return { board: null };
+        if (!isSlug(value))
+            return { board: null, problem: "not_slug", value };
+        return { board: value };
+    }
+    catch (error) {
+        if (error instanceof RepoFileProblem)
+            return { board: null, problem: error.problem === "symlink" ? "not_file" : error.problem };
+        return { board: null, problem: "not_file" };
+    }
+}
+/** What a remote client sends for a repo's board: the fields of POST /api/cmd. */
+export function repoBoardFields(repo) {
+    const fields = {};
+    if (repo.board)
+        fields.repo_board = repo.board;
+    if (repo.problem)
+        fields.repo_board_problem = repo.problem;
+    if (repo.problem === "not_slug" && typeof repo.value === "string")
+        fields.repo_board = repo.value;
+    return fields;
+}
+/** A refusal for a file Orbit won't write. */
+function writeProblemText(problem) {
+    switch (problem) {
+        case "symlink":
+            return "This repo's orbit.json is a symlink, so Orbit won't write through it. Replace it with a plain file, then link again.";
+        case "too_big":
+            return "This repo's orbit.json is over 16 KB, so Orbit won't overwrite it. Fix or remove it, then link again.";
+        case "not_json":
+            return "This repo's orbit.json isn't a JSON object, so Orbit won't overwrite it. Fix or remove it, then link again.";
+        case "not_file":
+            return "This repo's orbit.json isn't a plain file, so Orbit won't write it. Remove it, then link again.";
+    }
+}
+/** The file's text: one line when it holds only the board, else two-space JSON. */
+function fileText(data) {
+    const keys = Object.keys(data);
+    if (keys.length === 1 && keys[0] === "board")
+        return `{ "board": ${JSON.stringify(data.board)} }\n`;
+    return `${JSON.stringify(data, null, 2)}\n`;
+}
+/** Writes through a new file renamed into place, so no link or shared inode is ever written through. */
+function writeReplacing(path, text, mode = 0o644) {
+    const temporary = join(dirname(path), `.${REPO_FILE}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    try {
+        writeFileSync(temporary, text, { flag: "wx", mode });
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            // Never made.
+        }
+        throw error;
+    }
+}
+function readForWrite(start) {
+    const found = findRepoFile(start);
+    try {
+        const read = found.exists ? readObject(found.path) : null;
+        return { found, data: read?.data ?? {}, mode: read?.mode };
+    }
+    catch (error) {
+        if (error instanceof RepoFileProblem)
+            return { found, refused: writeProblemText(error.problem) };
+        throw error;
+    }
+}
+/** Makes the repo at `start` name board `slug`, keeping every other field. */
+export function linkRepoBoard(start, slug) {
+    const read = readForWrite(start);
+    if (read.refused !== undefined)
+        return { ok: false, text: read.refused, data: null };
+    const { found, data, mode } = read;
+    const previous = typeof data.board === "string" ? data.board : null;
+    const whose = found.inRepo ? "This repo's" : "This folder's";
+    // What happens, not an order: take's rule (a branch, local commits, never push or merge) still holds.
+    const commit = found.inRepo ? "Other branches and clones see it once it is committed and reaches the main branch." : "It isn't in a git repo, so it counts in this folder only.";
+    const result = { board: slug, linked: true, previous };
+    if (previous === slug)
+        return { ok: true, text: `${whose} orbit.json already names board ${slug}. ${commit}`, data: result };
+    writeReplacing(found.path, fileText({ ...data, board: slug }), mode);
+    const was = previous ? ` (it named ${oneLine(previous, 60)})` : "";
+    return { ok: true, text: `${whose} orbit.json names board ${slug} now${was}, so commands here use it when they name none. ${commit}`, data: result };
+}
+/** Takes `board` out of the repo's orbit.json, and the file with it when nothing else is left. */
+export function unlinkRepoBoard(start) {
+    const read = readForWrite(start);
+    if (read.refused !== undefined)
+        return { ok: false, text: read.refused, data: null };
+    const { found, data, mode } = read;
+    const whose = found.inRepo ? "This repo's" : "This folder's";
+    const commit = found.inRepo ? " Commit the change." : "";
+    if (!found.exists || data.board === undefined)
+        return { ok: true, text: `${whose} orbit.json names no board, so there's nothing to unlink.`, data: { board: null, linked: false } };
+    const { board, ...rest } = data;
+    const named = typeof board === "string" ? oneLine(board, 60) : "";
+    if (!Object.keys(rest).length) {
+        unlinkSync(found.path);
+        return { ok: true, text: `${whose} orbit.json named board ${named}; Orbit removed the file, since nothing else was in it.${commit}`, data: { board: null, linked: false, previous: board, removed: true } };
+    }
+    writeReplacing(found.path, fileText(rest), mode);
+    return { ok: true, text: `${whose} orbit.json names no board now (it named ${named}); its other fields stay.${commit}`, data: { board: null, linked: false, previous: board, removed: false } };
+}
+/** `boards link <board>` or `boards unlink`, from a shell's words: which, or null. */
+export function repoLinkWords(argv) {
+    const words = argv.filter((word) => !word.startsWith("-"));
+    if (words[0] !== "boards")
+        return null;
+    return words[1] === "link" || words[1] === "unlink" ? words[1] : null;
+}
+/** The repo source for a command run where `dir` is: reads the file there, and (for a shell) writes it. */
+export function repoSourceAt(dir, options = {}) {
+    // "this repo" in a git repo, else "this folder", for "let ... name it".
+    const source = { read: () => readRepoBoard(dir), place: repoTop(dir) ? "this repo" : "this folder" };
+    if (options.writes)
+        source.link = (sub, slug) => (sub === "link" ? linkRepoBoard(dir, slug ?? "") : unlinkRepoBoard(dir));
+    return source;
+}

package/lib/node/serve.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `orbit run`: the app and the API on this computer, over @hono/node-server.
+ * It listens on 127.0.0.1 unless HOST says otherwise (the API has no
+ * accounts, so it is never exposed by accident), starts at 13701 and moves
+ * up past busy ports unless PORT names one, then says what to do next.
+ */
+import type { OrbitEnv } from "./env.ts";
+export declare function runServer(env: OrbitEnv): Promise<void>;

package/lib/node/serve.js

@@ -0,0 +1,106 @@
+/**
+ * `orbit run`: the app and the API on this computer, over @hono/node-server.
+ * It listens on 127.0.0.1 unless HOST says otherwise (the API has no
+ * accounts, so it is never exposed by accident), starts at 13701 and moves
+ * up past busy ports unless PORT names one, then says what to do next.
+ */
+import { networkInterfaces } from "node:os";
+import { createAdaptorServer } from "@hono/node-server";
+import { createOrbitApp } from "../http/app.js";
+import { folderAssets } from "./assets.js";
+import { nextSteps } from "./data-folder.js";
+import { hostCheck, misdirected } from "./host-check.js";
+import { hostServices } from "./host-services.js";
+import { openLocalOrbit, packageVersion, publicDir } from "./local.js";
+const DEFAULT_PORT = 13701;
+function displayHost(host) {
+    return !host || host === "::" || host === "0.0.0.0" ? "localhost" : host;
+}
+function networkUrls(port) {
+    return Object.values(networkInterfaces())
+        .flat()
+        .filter((item) => item && item.family === "IPv4" && !item.internal)
+        .map((item) => `http://${item?.address ?? ""}:${port}`);
+}
+/**
+ * What `orbit run` adds around the app: a request naming a host Orbit doesn't
+ * answer to is refused (DNS rebinding; host-check.ts), and every response
+ * says not to sniff its type and to send the page's address only to Orbit
+ * itself.
+ */
+function guarded(fetch, check) {
+    return async (request) => {
+        const refused = check.refused(request.headers);
+        if (refused !== null) {
+            console.error(`Orbit: 421 for the host name ${refused.replace(/[^A-Za-z0-9.:[\]_-]/g, "").slice(0, 120)} on ${request.method} ${new URL(request.url).pathname} (see ORBIT_ALLOWED_HOSTS)`);
+            return misdirected(refused);
+        }
+        const response = await fetch(request);
+        const headers = new Headers(response.headers);
+        headers.set("X-Content-Type-Options", "nosniff");
+        if (!headers.has("Referrer-Policy"))
+            headers.set("Referrer-Policy", "same-origin");
+        return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+    };
+}
+export async function runServer(env) {
+    const local = await openLocalOrbit(env, { host: hostServices(env, env.dataDir) });
+    const { orbit } = local;
+    const app = createOrbitApp(orbit, {
+        assets: folderAssets(publicDir()),
+        version: packageVersion(),
+        log: (line) => { console.error(line); }
+    });
+    const server = createAdaptorServer({ fetch: guarded(app.fetch, hostCheck({ bind: env.host, allowed: env.allowedHosts })) });
+    const first = env.port ?? DEFAULT_PORT;
+    let port = first;
+    const listen = () => {
+        server.listen(port, env.host);
+    };
+    server.on("error", (error) => {
+        if (env.port === null && error.code === "EADDRINUSE" && port < first + 99) {
+            port += 1;
+            console.warn(`[orbit] Port ${port - 1} is in use; trying ${port}.`);
+            listen();
+            return;
+        }
+        console.error(error);
+        void local.close().finally(() => process.exit(1));
+    });
+    server.on("listening", () => {
+        void (async () => {
+            const address = server.address();
+            const boundPort = address?.port ?? port;
+            const url = `http://${displayHost(address?.address ?? env.host)}:${boundPort}`;
+            const boards = (await orbit.context({ id: "local", name: "local", type: "human", role: "owner", permissions: [], boards: ["*"] }).store.boards.list()).length;
+            console.log(`Starscape Orbit listening on ${url}`);
+            // An upgrader's first sight of v2: an empty folder, and their old boards one command away, first.
+            const older = !boards && orbit.deployment.older_data;
+            const others = ["0.0.0.0", "::"].includes(env.host) ? networkUrls(boundPort).filter((other) => other !== url) : [];
+            if (others.length)
+                console.log(`Network: ${others.join(", ")}`);
+            // What a newcomer does next: open the app, then tell their agents.
+            console.log("");
+            console.log("Next:");
+            nextSteps(url, boards ? "to see your boards" : older ? "to see them" : "and make a board", older).forEach((line) => { console.log(line); });
+            console.log("");
+            console.log(`Boards: ${boards || "none yet"}, in ${env.dataDir}`);
+            console.log("Stop it with Ctrl+C.");
+        })();
+    });
+    let stopping = false;
+    const shutdown = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        server.close(() => {
+            void local.close().finally(() => process.exit(0));
+        });
+        setTimeout(() => {
+            void local.close().finally(() => process.exit(0));
+        }, 1500).unref();
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+    listen();
+}

package/lib/orbit.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Orbit as a library: `createOrbit({ store, blobs })` gives every use case,
+ * acting as an actor, through one client (./client/types.ts), and every
+ * board's committed changes. It touches nothing but the ports it is given,
+ * so the same code runs on a server, in a CLI and in a browser tab.
+ */
+import type { Clock, Ctx, Deployment, Ids } from "./core/context.ts";
+import type { Actor, BoardChange, Id } from "./core/model.ts";
+import type { RepoSource, Transport } from "./commands/index.ts";
+import type { HostServices, OrbitClient } from "./client/types.ts";
+import type { BlobStore, OrbitStore } from "./store/types.ts";
+export interface OrbitOptions {
+    store: OrbitStore;
+    blobs: BlobStore;
+    /** Default: the system clock. */
+    clock?: Clock;
+    /** Default: crypto.randomUUID(). */
+    ids?: Ids;
+    /** Where this Orbit runs, for the person's own app; empty for a host without files. */
+    deployment?: Partial<Deployment>;
+    /** Called after each change that went through, with its board (a host's automatic backups). */
+    changed?: (boardId: Id) => void;
+    /** What the computer Orbit runs on can do: the version check, self-update, a folder picker. None by default. */
+    host?: HostServices;
+}
+export interface ClientSession {
+    transport?: Transport;
+    shared?: boolean;
+    board?: string | null;
+    repo?: RepoSource | null;
+}
+export interface Orbit {
+    /** Every use case, acting as `actor`, in this process: the in-process OrbitClient. */
+    client(actor: Actor, session?: ClientSession): OrbitClient;
+    /** The use cases' context for `actor`, for hosts that call the core directly. */
+    context(actor: Actor): Ctx;
+    /** One board's committed changes, from any process. Returns the function that stops. */
+    watch(boardId: Id, listener: (change: BoardChange) => void): () => void;
+    readonly deployment: Deployment;
+    readonly host: HostServices;
+    close(): Promise<void>;
+}
+export declare function createOrbit(options: OrbitOptions): Orbit;
+export type { ChangesOptions, HostServices, ImageUrl, OrbitClient, StreamState, VersionInfo } from "./client/types.ts";
+export type * from "./core/model.ts";
+export { OrbitError, isOrbitError } from "./core/errors.ts";
+export { localAgentActor, localOwnerActor, namedAgentActor } from "./core/actors.ts";

package/lib/orbit.js

@@ -0,0 +1,44 @@
+/**
+ * Orbit as a library: `createOrbit({ store, blobs })` gives every use case,
+ * acting as an actor, through one client (./client/types.ts), and every
+ * board's committed changes. It touches nothing but the ports it is given,
+ * so the same code runs on a server, in a CLI and in a browser tab.
+ */
+import { createLocalClient } from "./client/local.js";
+const systemClock = { now: () => new Date().toISOString() };
+const randomIds = { next: () => crypto.randomUUID() };
+export function createOrbit(options) {
+    const deployment = { app_root: "", data_dir: "", data_dir_default: false, mcp_server_path: "", export_dir: "", older_data: false, ...options.deployment };
+    const runtime = {
+        store: options.store,
+        blobs: options.blobs,
+        clock: options.clock ?? systemClock,
+        ids: options.ids ?? randomIds,
+        deployment,
+        changed: options.changed ?? (() => undefined)
+    };
+    const context = (actor) => ({ ...runtime, actor });
+    const host = options.host ?? {};
+    function watch(boardId, listener) {
+        let stop = null;
+        let stopped = false;
+        void options.store.board(boardId).then((data) => {
+            if (!stopped)
+                stop = data.watch(listener);
+        }, () => undefined);
+        return () => {
+            stopped = true;
+            stop?.();
+        };
+    }
+    return {
+        client: (actor, session = {}) => createLocalClient(context(actor), { ...session, watch, host }),
+        context,
+        watch,
+        deployment,
+        host,
+        close: () => options.store.close()
+    };
+}
+export { OrbitError, isOrbitError } from "./core/errors.js";
+export { localAgentActor, localOwnerActor, namedAgentActor } from "./core/actors.js";

package/lib/quiet-sqlite-warning.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/quiet-sqlite-warning.js

@@ -0,0 +1,18 @@
+// Node 22 warns "SQLite is an experimental feature and might change
+// at any time" when node:sqlite loads, so every orbit command printed it (and
+// Node's --trace-warnings hint) to stderr. Orbit's entry points import this
+// file first, before anything loads node:sqlite. It drops exactly that one
+// warning; every other warning, ExperimentalWarning or not, still prints.
+//
+// Node emits a warning's event on the next tick, after the module graph that
+// loaded node:sqlite has run, so the filter sits on the event: it works
+// whether node:sqlite is imported statically or later.
+const SQLITE_WARNING = /^SQLite is an experimental feature/;
+const emit = process.emit.bind(process);
+process.emit = function orbitEmit(name, ...args) {
+    const warning = args[0];
+    if (name === "warning" && warning instanceof Error && warning.name === "ExperimentalWarning" && SQLITE_WARNING.test(warning.message))
+        return false;
+    return emit(name, ...args);
+};
+export {};

package/lib/store/blob-path.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The rule every BlobStore applies to paths: relative, POSIX-style, and
+ * inside the board. Shared so every adapter refuses the same paths.
+ */
+/** Refuses an empty or absolute path, a backslash or NUL, and any empty, `.` or `..` segment, with `invalid_blob_path`. */
+export declare function checkBlobPath(path: string): void;

package/lib/store/blob-path.js

@@ -0,0 +1,12 @@
+/**
+ * The rule every BlobStore applies to paths: relative, POSIX-style, and
+ * inside the board. Shared so every adapter refuses the same paths.
+ */
+import { OrbitError } from "../core/errors.js";
+/** Refuses an empty or absolute path, a backslash or NUL, and any empty, `.` or `..` segment, with `invalid_blob_path`. */
+export function checkBlobPath(path) {
+    const segments = path.split("/");
+    const bad = path === "" || path.includes("\\") || path.includes("\0") || segments.some((segment) => segment === "" || segment === "." || segment === "..");
+    if (bad)
+        throw new OrbitError("invalid_blob_path");
+}

package/lib/store/conformance.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The behaviour every OrbitStore and BlobStore must show, written once and
+ * run against each adapter: memory and SQLite in vitest, IndexedDB in real
+ * browsers too. It imports no test framework, so a stranger's adapter proves
+ * itself the same way:
+ *
+ *   registerStoreConformance({ describe, it }, "my adapter", () => ({ open: () => openMyStore(dir) }));
+ *
+ * Each case gets a fresh harness. `open()` gives a store over the harness's
+ * data; calling it again gives a second store over the same data, as a second
+ * process (or tab) would have, which is how the cases prove that writes are
+ * serialised and heard everywhere.
+ */
+import type { BlobStore, OrbitStore } from "./types.ts";
+export interface StoreHarness {
+    /** A store over this harness's data; each call opens another over the same data. */
+    open(): Promise<OrbitStore>;
+    /** Closes what `open()` opened and deletes the data. */
+    dispose?(): Promise<void>;
+}
+export type StoreHarnessFactory = () => StoreHarness | Promise<StoreHarness>;
+export interface ConformanceCase {
+    name: string;
+    run(harness: StoreHarness): Promise<void>;
+}
+export interface BlobConformanceCase {
+    name: string;
+    run(blobs: BlobStore): Promise<void>;
+}
+export interface ConformanceResult {
+    name: string;
+    ok: boolean;
+    error?: string;
+}
+/** The part of vitest, jest or mocha the suite registers itself with. */
+export interface TestApi {
+    describe(name: string, body: () => void): void;
+    it(name: string, body: () => Promise<void>): void;
+}
+export declare const storeConformanceCases: ConformanceCase[];
+export declare const blobConformanceCases: BlobConformanceCase[];
+/** Registers every store case, under one describe block, with a test framework. */
+export declare function registerStoreConformance(api: TestApi, label: string, factory: StoreHarnessFactory, options?: {
+    skip?: string[];
+}): void;
+/** Registers every blob case, each on a fresh BlobStore. */
+export declare function registerBlobConformance(api: TestApi, label: string, factory: () => BlobStore | Promise<BlobStore>): void;
+/** Runs every store case in order, each on a fresh harness, and reports instead of throwing. */
+export declare function runStoreConformance(factory: StoreHarnessFactory, options?: {
+    skip?: string[];
+    only?: string[];
+}): Promise<ConformanceResult[]>;