@starlove/orbit 1.4.1 → 2.0.0

package/lib/core/boards.js

@@ -0,0 +1,288 @@
+/**
+ * Boards: making one with its lanes, its settings, its journal, its context
+ * for agents, and deleting it.
+ */
+import { isAgent } from "./context.js";
+import { OrbitError, isOrbitError } from "./errors.js";
+import { record } from "./history.js";
+import { normalizeEntryType, requiredString, slugify, asText } from "./text.js";
+import { Lanes, ticketView } from "./views.js";
+const LANES_WITH_AI = [
+    ["Backlog", null],
+    ["Todo", null],
+    ["AI Ready", "ai_ready"],
+    ["In Progress", "in_progress"],
+    ["Review", "review"],
+    ["Done", "done"],
+    ["Cancelled", null]
+];
+function startingLanes(input, aiEnabled) {
+    if (Array.isArray(input.states)) {
+        return input.states.filter(Array.isArray).map((pair) => [String(pair[0]), (pair[1] ?? null)]);
+    }
+    return aiEnabled ? LANES_WITH_AI : LANES_WITH_AI.filter(([, role]) => role !== "ai_ready");
+}
+/** Makes a board with its lanes, and lists it. Answers the board's own record. */
+export async function createBoard(c, input) {
+    const name = requiredString(input.name, "name");
+    const slug = slugify(input.slug || name);
+    if (await c.store.boards.bySlug(slug))
+        throw new OrbitError("board_slug_taken");
+    const at = c.clock.now();
+    const aiEnabled = input.ai_enabled === undefined ? true : Boolean(input.ai_enabled);
+    const board = {
+        id: c.ids.next(),
+        slug,
+        name,
+        repo_url: typeof input.repo_url === "string" ? input.repo_url : "",
+        default_branch: typeof input.default_branch === "string" && input.default_branch ? input.default_branch : "main",
+        project_notes: "",
+        agent_instructions: "",
+        ai_enabled: aiEnabled ? 1 : 0,
+        created_at: at,
+        updated_at: at
+    };
+    await c.store.boards.create(board, async (w) => {
+        let position = 0;
+        for (const [laneName, role] of startingLanes(input, aiEnabled)) {
+            await w.states.insert({ id: c.ids.next(), board_id: board.id, name: laneName, position: position++, is_default: laneName === "Todo" ? 1 : 0, role, created_at: at });
+        }
+        if (aiEnabled)
+            await ensureAgentLanes(w, c, board.id);
+        await record(w, c, "board_created", null, { board_id: board.id, slug });
+    });
+    c.changed(board.id);
+    return board;
+}
+const AGENT_LANES = [
+    { name: "AI Ready", role: "ai_ready" },
+    { name: "In Progress", role: "in_progress" },
+    { name: "Review", role: "review" }
+];
+function desiredPosition(states, role) {
+    if (role === "ai_ready") {
+        const todo = states.find((state) => state.name === "Todo");
+        if (todo)
+            return todo.position + 1;
+        const inProgress = states.find((state) => state.role === "in_progress");
+        if (inProgress)
+            return inProgress.position;
+    }
+    return states.reduce((max, state) => Math.max(max, state.position), -1) + 1;
+}
+/** In position order, ties by when each was written (the list's own order), with positions 0 to n-1. */
+function compact(states) {
+    const order = states.map((state, index) => ({ state, index })).sort((a, b) => a.state.position - b.state.position || a.index - b.index);
+    order.forEach(({ state }, position) => {
+        state.position = position;
+    });
+}
+/**
+ * Makes sure the lanes the agent flow needs exist: AI Ready right after Todo
+ * (so taking work has a predictable lane), In Progress and Review. Changes
+ * only what isn't so.
+ */
+export async function ensureAgentLanes(w, c, boardId) {
+    const before = await w.states.list();
+    const states = before.map((state) => ({ ...state }));
+    const added = [];
+    for (const lane of AGENT_LANES) {
+        const existing = states.find((state) => state.role === lane.role);
+        if (existing) {
+            if (lane.role !== "ai_ready" || existing.position === desiredPosition(states, lane.role))
+                continue;
+            existing.position = -1;
+            compact(states);
+            const position = desiredPosition(states, lane.role);
+            for (const state of states)
+                if (state !== existing && state.position >= position)
+                    state.position += 1;
+            existing.position = position;
+            continue;
+        }
+        const position = desiredPosition(states, lane.role);
+        for (const state of states)
+            if (state.position >= position)
+                state.position += 1;
+        const state = { id: c.ids.next(), board_id: boardId, name: lane.name, position, is_default: 0, role: lane.role, created_at: c.clock.now() };
+        states.push(state);
+        added.push(state);
+    }
+    for (const state of states) {
+        const old = before.find((b) => b.id === state.id);
+        if (old && old.position !== state.position)
+            await w.states.update(state.id, { position: state.position });
+    }
+    for (const state of added)
+        await w.states.insert(state);
+}
+const BOARD_FIELDS = ["name", "repo_url", "default_branch", "project_notes", "agent_instructions"];
+/** Changes a board's settings; turning AI on adds the agent lanes. */
+export async function updateBoard(c, input) {
+    const patch = {};
+    const applied = [];
+    for (const field of BOARD_FIELDS) {
+        const value = input[field];
+        if (value === undefined)
+            continue;
+        patch[field] = field === "name" ? requiredString(value, "name") : asText(value ?? "");
+        applied.push(field);
+    }
+    const aiTurningOn = input.ai_enabled !== undefined && Boolean(input.ai_enabled);
+    if (input.ai_enabled !== undefined) {
+        patch.ai_enabled = input.ai_enabled ? 1 : 0;
+        applied.push("ai_enabled");
+    }
+    if (!applied.length)
+        return c.data.read((r) => r.board.get());
+    const after = await c.data.write(async (w) => {
+        const board = await w.board.update({ ...patch, updated_at: c.clock.now() });
+        if (aiTurningOn)
+            await ensureAgentLanes(w, c, c.board.id);
+        await record(w, c, "board_updated", null, { board_id: c.board.id, fields: applied });
+        return board;
+    });
+    c.changed(c.board.id);
+    return after;
+}
+/** The board as agents may read it: no notes meant for people only. */
+function agentBoard(board) {
+    return {
+        id: board.id,
+        slug: board.slug,
+        name: board.name,
+        repo_url: board.repo_url,
+        default_branch: board.default_branch,
+        agent_instructions: board.agent_instructions,
+        ai_enabled: board.ai_enabled,
+        created_at: board.created_at,
+        updated_at: board.updated_at
+    };
+}
+/** The board's rules for agents and its journal (newest first; struck entries only when asked). */
+export async function boardManual(c, options = {}) {
+    const [board, entries] = await c.data.read(async (r) => [await r.board.get(), await r.entries.list()]);
+    return manualOf(c, board, entries, options);
+}
+export function manualOf(c, board, entries, options = {}) {
+    const newestFirst = [...entries].reverse();
+    const manual = {
+        board: agentBoard(board),
+        entries: options.includeStruck ? newestFirst : newestFirst.filter((entry) => !entry.struck_at)
+    };
+    if (!isAgent(c.actor)) {
+        const { app_root, data_dir, data_dir_default, mcp_server_path } = c.deployment;
+        manual.deployment = { app_root, data_dir, data_dir_default, mcp_server_path, db_path: c.board.db_path };
+    }
+    return manual;
+}
+/** A decision or a lesson in the board's journal, optionally about a card. */
+export async function createEntry(c, input) {
+    const type = normalizeEntryType(input.type);
+    const title = requiredString(input.title, "title");
+    const ticketId = typeof input.ticket_id === "string" && input.ticket_id ? input.ticket_id : null;
+    const entry = await c.data.write(async (w) => {
+        const at = c.clock.now();
+        const made = {
+            id: c.ids.next(),
+            board_id: c.board.id,
+            type,
+            title,
+            body: typeof input.body === "string" ? input.body : "",
+            ticket_id: ticketId,
+            created_by: c.actor.name,
+            created_at: at,
+            updated_at: at,
+            struck_at: null
+        };
+        await w.entries.insert(made);
+        await record(w, c, "board_entry_created", ticketId, { board_id: c.board.id, entry_id: made.id, type });
+        return made;
+    });
+    c.changed(c.board.id);
+    return entry;
+}
+/** Strikes a journal entry, or brings it back. */
+export async function strikeEntry(c, entryId, input) {
+    const strike = Boolean(input.struck);
+    const entry = await c.data.write(async (w) => {
+        const before = await w.entries.get(entryId);
+        if (!before)
+            throw new OrbitError("board_entry_not_found");
+        const at = c.clock.now();
+        const after = await w.entries.update(entryId, { struck_at: strike ? (before.struck_at ?? at) : null, updated_at: at });
+        await record(w, c, strike ? "board_entry_struck" : "board_entry_restored", before.ticket_id, { board_id: c.board.id, entry_id: before.id, type: before.type });
+        return after;
+    });
+    c.changed(c.board.id);
+    return entry;
+}
+/**
+ * Deletes a struck journal entry for good. Only a person may: an agent strikes
+ * an entry, which takes it out of agents' context and leaves the person to
+ * decide. An entry still live is refused, so nothing goes in one step.
+ */
+export async function deleteEntry(c, entryId) {
+    if (isAgent(c.actor))
+        throw new OrbitError("forbidden", { message: "Deleting a journal entry is the person's call, not an agent's: strike it instead." });
+    await c.data.write(async (w) => {
+        const before = await w.entries.get(entryId);
+        if (!before)
+            throw new OrbitError("board_entry_not_found");
+        if (!before.struck_at)
+            throw new OrbitError("entry_not_struck", { message: "Strike the entry before you delete it." });
+        await w.entries.remove(entryId);
+        await record(w, c, "board_entry_deleted", before.ticket_id, { board_id: c.board.id, entry_id: before.id, type: before.type });
+    });
+    c.changed(c.board.id);
+    return { ok: true, deleted_id: entryId };
+}
+/** A board's archived cards, most recently archived first. */
+export async function archivedTickets(c) {
+    return c.data.read(async (r) => {
+        const [lanes, tickets] = await Promise.all([Lanes.of(r), r.tickets.list({ archived: true })]);
+        return tickets
+            .sort((a, b) => (b.archived_at ?? "").localeCompare(a.archived_at ?? ""))
+            .map((ticket) => ticketView(ticket, lanes, c.board));
+    });
+}
+/** Every board, by name: a small list without opening any board. */
+export async function listBoards(c) {
+    const agent = isAgent(c.actor);
+    return {
+        boards: (await c.store.boards.list()).map((row) => ({
+            id: row.id,
+            slug: row.slug,
+            name: row.name,
+            repo_url: row.repo_url,
+            default_branch: row.default_branch,
+            ...(agent ? {} : { db_path: row.db_path }),
+            last_active_at: row.last_active_at
+        }))
+    };
+}
+/**
+ * Deletes a board once its slug is typed back. A copy is kept first where the
+ * storage can make one. With `delete_files: false` the board leaves the list
+ * and its data stays. Never an agent's, as with a replace: refused before
+ * anything is read, whatever the transport (the JSON API, or a host's
+ * in-process client).
+ */
+export async function deleteBoard(c, board, input) {
+    if (isAgent(c.actor))
+        throw new OrbitError("forbidden", { message: "Deleting a board is the person's call, not an agent's: ask them to delete it in Orbit." });
+    if (asText(input.confirm_slug ?? "").trim() !== board.slug)
+        throw new OrbitError("board_slug_confirmation_required");
+    const deleteFiles = input.delete_files !== false;
+    // A board whose file is gone has nothing to copy, and deleting it is the way out.
+    if (deleteFiles)
+        await c.store.backups?.board(board.id, "pre-board-delete").catch((error) => {
+            if (!(isOrbitError(error) && error.code === "board_file_missing"))
+                throw error;
+        });
+    await c.store.backups?.directory("pre-board-delete");
+    const { removed } = await c.store.boards.remove(board.id, { keepData: !deleteFiles });
+    if (deleteFiles)
+        await c.blobs.removeBoard(board.id);
+    return { ok: true, deleted_board_id: board.id, deleted_board_slug: board.slug, deleted_files: deleteFiles, artifacts: removed.map((path) => ({ path, removed: true })) };
+}

package/lib/core/bootstrap.d.ts

@@ -0,0 +1,47 @@
+/**
+ * What the app loads first: the list of boards, and one board whole (its
+ * lanes, open cards with their labels and counts, labels and journal). The
+ * board is the one asked for, else the one used last.
+ */
+import type { CrossCard } from "./cross-board.ts";
+import type { Ctx } from "./context.ts";
+import type { Actor, Board, BoardEntry, Id, Label, State } from "./model.ts";
+import type { CompactTicket, TicketView } from "./views.ts";
+export type PublicActor = Pick<Actor, "id" | "name" | "type" | "role" | "permissions">;
+export declare function publicActor(actor: Actor): PublicActor;
+export interface BootstrapTicket extends TicketView {
+    labels: {
+        ticket_id: Id;
+        id: Id;
+        name: string;
+        color: string;
+    }[];
+    comment_count: number;
+    child_count: number;
+    parent_ticket: CompactTicket | null;
+    /** Cards on other boards this card waits on; present only when there are some. */
+    waiting_on?: CrossCard[];
+}
+export interface Bootstrap {
+    actor: PublicActor;
+    active_board_id?: Id;
+    /**
+     * Where the board's data is, for the person's own app; empty for an agent.
+     * `older_data` is there, true, only while no board exists and an older
+     * Orbit's boards wait for `orbit migrate` (the welcome says so).
+     */
+    meta: {
+        db_path?: string | null;
+        export_dir?: string;
+        older_data?: true;
+    };
+    boards: Board[];
+    board_entries: BoardEntry[];
+    states: State[];
+    labels: Label[];
+    tickets: BootstrapTicket[];
+}
+export declare function bootstrap(c: Ctx, request?: {
+    board_id?: string | null;
+    board?: string | null;
+}): Promise<Bootstrap>;

package/lib/core/bootstrap.js

@@ -0,0 +1,100 @@
+/**
+ * What the app loads first: the list of boards, and one board whole (its
+ * lanes, open cards with their labels and counts, labels and journal). The
+ * board is the one asked for, else the one used last.
+ */
+import { isAgent } from "./context.js";
+import { crossBlockers } from "./cross-board.js";
+import { Lanes, byCodePoint, compactTicket, ticketView } from "./views.js";
+export function publicActor(actor) {
+    return { id: actor.id, name: actor.name, type: actor.type, role: actor.role, permissions: actor.permissions };
+}
+/** A listed board as the boards list shows one that isn't loaded: its settings left blank. */
+function summary(row) {
+    return {
+        id: row.id,
+        slug: row.slug,
+        name: row.name,
+        repo_url: row.repo_url,
+        default_branch: row.default_branch,
+        project_notes: "",
+        agent_instructions: "",
+        ai_enabled: 0,
+        created_at: row.created_at,
+        updated_at: row.updated_at
+    };
+}
+export async function bootstrap(c, request = {}) {
+    const agent = isAgent(c.actor);
+    const rows = await c.store.boards.list();
+    const meta = (dbPath) => (agent ? {} : { db_path: dbPath, export_dir: c.deployment.export_dir });
+    if (!rows.length) {
+        const older = !agent && c.deployment.older_data ? { older_data: true } : {};
+        return { actor: publicActor(c.actor), meta: { ...meta(null), ...older }, boards: [], board_entries: [], states: [], labels: [], tickets: [] };
+    }
+    const chosen = (request.board_id ? rows.find((row) => row.id === request.board_id) : undefined) ??
+        (request.board ? rows.find((row) => row.slug === request.board) : undefined) ??
+        (await c.store.boards.latest()) ??
+        rows[0];
+    if (!chosen)
+        throw new Error("A board list with boards has a first board.");
+    await c.store.boards.touch(chosen.id, c.clock.now());
+    const data = await c.store.board(chosen.id);
+    const loaded = await data.read(async (r) => {
+        const [board, states, tickets, labels, links, comments, entries, crossLinks] = await Promise.all([
+            r.board.get(),
+            r.states.list(),
+            r.tickets.list({ archived: false }),
+            r.labels.list(),
+            r.ticketLabels.list(),
+            r.comments.countByTicket(),
+            r.entries.list(),
+            r.crossBoardRelations.list()
+        ]);
+        const open = new Map(tickets.map((ticket) => [ticket.id, ticket]));
+        const missing = [...new Set(tickets.map((ticket) => ticket.parent_ticket_id).filter((id) => id !== null && !open.has(id)))];
+        const archivedParents = missing.length ? await r.tickets.list({ ids: missing }) : [];
+        return { board, states, tickets, labels, links, comments, entries, crossLinks, parents: new Map([...open, ...archivedParents.map((t) => [t.id, t])]) };
+    });
+    // Cards waiting on other boards' cards: one read per other board, after this board's own.
+    const waiting = await crossBlockers(c, loaded.crossLinks);
+    const lanes = new Lanes(loaded.states);
+    const labelById = new Map(loaded.labels.map((label) => [label.id, label]));
+    const labelsOf = new Map();
+    for (const link of loaded.links) {
+        const label = labelById.get(link.label_id);
+        if (!label)
+            continue;
+        const list = labelsOf.get(link.ticket_id) ?? [];
+        list.push({ ticket_id: link.ticket_id, id: label.id, name: label.name, color: label.color });
+        labelsOf.set(link.ticket_id, list);
+    }
+    const commentCount = new Map(loaded.comments.map((row) => [row.ticket_id, row.count]));
+    const childCount = new Map();
+    for (const ticket of loaded.tickets)
+        if (ticket.parent_ticket_id)
+            childCount.set(ticket.parent_ticket_id, (childCount.get(ticket.parent_ticket_id) ?? 0) + 1);
+    const tickets = [...loaded.tickets]
+        .sort((a, b) => byCodePoint(b.updated_at, a.updated_at) || byCodePoint(a.id, b.id))
+        .map((ticket) => {
+        const parent = ticket.parent_ticket_id ? loaded.parents.get(ticket.parent_ticket_id) : undefined;
+        return {
+            ...ticketView(ticket, lanes, loaded.board),
+            labels: labelsOf.get(ticket.id) ?? [],
+            comment_count: commentCount.get(ticket.id) ?? 0,
+            child_count: childCount.get(ticket.id) ?? 0,
+            parent_ticket: parent ? compactTicket(ticketView(parent, lanes, loaded.board)) : null,
+            ...(waiting.has(ticket.id) ? { waiting_on: waiting.get(ticket.id) } : {})
+        };
+    });
+    return {
+        actor: publicActor(c.actor),
+        active_board_id: chosen.id,
+        meta: meta(chosen.db_path),
+        boards: rows.map((row) => (row.id === loaded.board.id ? loaded.board : summary(row))),
+        board_entries: [...loaded.entries].reverse(),
+        states: loaded.states,
+        labels: loaded.labels,
+        tickets
+    };
+}

package/lib/core/bytes.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Bytes without Node: base64 and SHA-256 over the Web platform's own
+ * `crypto`, so the core runs the same on a server and in a browser tab.
+ */
+export declare function toBase64(bytes: Uint8Array): string;
+/** Decodes base64, skipping anything outside its alphabet (line breaks, a data: prefix's tail). */
+export declare function fromBase64(text: string): Uint8Array;
+export declare function sha256Hex(bytes: Uint8Array): Promise<string>;
+export declare function utf8(text: string): Uint8Array;
+export declare function fromUtf8(bytes: Uint8Array): string;

package/lib/core/bytes.js

@@ -0,0 +1,52 @@
+/**
+ * Bytes without Node: base64 and SHA-256 over the Web platform's own
+ * `crypto`, so the core runs the same on a server and in a browser tab.
+ */
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const LOOKUP = new Map(Array.from(ALPHABET, (ch, i) => [ch, i]));
+export function toBase64(bytes) {
+    let out = "";
+    let i = 0;
+    for (; i + 2 < bytes.length; i += 3) {
+        const n = ((bytes[i] ?? 0) << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);
+        out += ALPHABET.charAt(n >> 18) + ALPHABET.charAt((n >> 12) & 63) + ALPHABET.charAt((n >> 6) & 63) + ALPHABET.charAt(n & 63);
+    }
+    const rest = bytes.length - i;
+    if (rest === 1) {
+        const n = (bytes[i] ?? 0) << 16;
+        out += `${ALPHABET.charAt(n >> 18)}${ALPHABET.charAt((n >> 12) & 63)}==`;
+    }
+    else if (rest === 2) {
+        const n = ((bytes[i] ?? 0) << 16) | ((bytes[i + 1] ?? 0) << 8);
+        out += `${ALPHABET.charAt(n >> 18)}${ALPHABET.charAt((n >> 12) & 63)}${ALPHABET.charAt((n >> 6) & 63)}=`;
+    }
+    return out;
+}
+/** Decodes base64, skipping anything outside its alphabet (line breaks, a data: prefix's tail). */
+export function fromBase64(text) {
+    const clean = text.replace(/[^A-Za-z0-9+/]/g, "");
+    const out = new Uint8Array(Math.floor((clean.length * 3) / 4));
+    let length = 0;
+    let buffer = 0;
+    let bits = 0;
+    for (const ch of clean) {
+        buffer = (buffer << 6) | (LOOKUP.get(ch) ?? 0);
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[length++] = (buffer >> bits) & 0xff;
+        }
+    }
+    return out.subarray(0, length);
+}
+export async function sha256Hex(bytes) {
+    // A copy on its own ArrayBuffer, which the DOM's typings of digest() require.
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new Uint8Array(bytes)));
+    return [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export function utf8(text) {
+    return new TextEncoder().encode(text);
+}
+export function fromUtf8(bytes) {
+    return new TextDecoder().decode(bytes);
+}

package/lib/core/card-paths.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A card's two links to markdown, its plan (`plan_artifact_path`) and its
+ * work summary (`implementation_artifact_path`), as they are stored. A link is
+ * relative to the board's artifacts (`tickets/<card id>/plan.md`), which is
+ * how Orbit reads it back on any machine, and how no answer an agent reads
+ * ever carries the folders of the machine Orbit runs on.
+ */
+import type { Ctx } from "./context.ts";
+import type { Id } from "./model.ts";
+/** Where a board's markdown lives in its blob store. */
+export declare const ARTIFACTS = "artifacts/";
+/**
+ * A link as a person or an agent gives it. A full path into the board's
+ * artifacts becomes relative to them; a full path anywhere else in Orbit's
+ * data folder names none of the card's files, so it is refused. Any other
+ * text is kept as given.
+ */
+export declare function cardLinkFromInput(c: Ctx, boardId: Id, value: unknown): string;
+/**
+ * A link from an export or an older Orbit's data, which was made on another
+ * machine or in another folder: a full path into a board's artifacts keeps
+ * its part inside them; any other full path names a file this Orbit can't
+ * reach, so it is left out (null, for the caller to count).
+ */
+export declare function cardLinkFromElsewhere(value: unknown): string | null;

package/lib/core/card-paths.js

@@ -0,0 +1,44 @@
+/**
+ * A card's two links to markdown, its plan (`plan_artifact_path`) and its
+ * work summary (`implementation_artifact_path`), as they are stored. A link is
+ * relative to the board's artifacts (`tickets/<card id>/plan.md`), which is
+ * how Orbit reads it back on any machine, and how no answer an agent reads
+ * ever carries the folders of the machine Orbit runs on.
+ */
+import { OrbitError } from "./errors.js";
+import { textOr } from "./text.js";
+/** Where a board's markdown lives in its blob store. */
+export const ARTIFACTS = "artifacts/";
+const FULL_PATH = /^([a-z]:)?[\\/]/i;
+/**
+ * A link as a person or an agent gives it. A full path into the board's
+ * artifacts becomes relative to them; a full path anywhere else in Orbit's
+ * data folder names none of the card's files, so it is refused. Any other
+ * text is kept as given.
+ */
+export function cardLinkFromInput(c, boardId, value) {
+    const text = textOr(value);
+    if (!FULL_PATH.test(text))
+        return text;
+    const path = text.replace(/\\/g, "/");
+    const root = c.blobs.location?.(boardId, ARTIFACTS.slice(0, -1));
+    if (root && path.startsWith(`${root}/`))
+        return path.slice(root.length + 1);
+    const data = c.deployment.data_dir;
+    if (data && (path === data || path.startsWith(`${data}/`)))
+        throw new OrbitError("artifact_path_outside_allowed_roots");
+    return text;
+}
+/**
+ * A link from an export or an older Orbit's data, which was made on another
+ * machine or in another folder: a full path into a board's artifacts keeps
+ * its part inside them; any other full path names a file this Orbit can't
+ * reach, so it is left out (null, for the caller to count).
+ */
+export function cardLinkFromElsewhere(value) {
+    const text = textOr(value);
+    if (!FULL_PATH.test(text))
+        return text;
+    const inside = /\/artifacts\/(.+)$/.exec(text.replace(/\\/g, "/"));
+    return inside?.[1] && !inside[1].split("/").some((segment) => segment === ".." || segment === "." || segment === "") ? inside[1] : null;
+}

package/lib/core/context.d.ts

@@ -0,0 +1,60 @@
+/**
+ * What every use case runs with: the ports (storage, bytes, a clock and ids),
+ * who is acting, and, for a use case on one board, that board. The core never
+ * reaches for anything else, so the same code runs on a server, in a CLI and
+ * in a browser tab.
+ */
+import type { Actor, Id, RegisteredBoard, Timestamp } from "./model.ts";
+import type { BlobStore, BoardStore, OrbitStore } from "../store/types.ts";
+export interface Clock {
+    now(): Timestamp;
+}
+export interface Ids {
+    next(): Id;
+}
+/**
+ * Where this Orbit runs, for the person's own app (the Settings screen builds
+ * its agent-connection command from it). Never shown to an agent. A host that
+ * runs no files (the browser edition) leaves the paths empty.
+ */
+export interface Deployment {
+    app_root: string;
+    data_dir: string;
+    /** True when Orbit uses its default data folder, which an agent's `orbit mcp` finds without being told. */
+    data_dir_default: boolean;
+    mcp_server_path: string;
+    export_dir: string;
+    /**
+     * True when an older Orbit's boards wait in its default folder for `orbit
+     * migrate`, so an empty Orbit can say how to bring them. Its path is never
+     * shown to an agent.
+     */
+    older_data: boolean;
+}
+export interface Runtime {
+    readonly store: OrbitStore;
+    readonly blobs: BlobStore;
+    readonly clock: Clock;
+    readonly ids: Ids;
+    readonly deployment: Deployment;
+    /** Called after each change that went through, with its board (automatic backups). */
+    readonly changed: (boardId: Id) => void;
+}
+export interface Ctx extends Runtime {
+    readonly actor: Actor;
+}
+/** A use case on one board: the board as the directory lists it, and its data. */
+export interface BoardCtx extends Ctx {
+    readonly board: RegisteredBoard;
+    readonly data: BoardStore;
+}
+/** True when an agent is asking: its answers carry no server paths. */
+export declare function isAgent(actor: Actor): boolean;
+/** The context for one board, as the directory lists it. */
+export declare function onBoard(c: Ctx, board: RegisteredBoard): Promise<BoardCtx>;
+/** A board by its id or slug, or null. */
+export declare function findBoard(c: Ctx, ident: string): Promise<RegisteredBoard | null>;
+/** A board named by id first, then slug; null when neither is given; `board_not_found` when one is given and unknown. */
+export declare function boardFromHints(c: Ctx, id: string | null | undefined, slug: string | null | undefined): Promise<RegisteredBoard | null>;
+/** The board holding a record, looked for on `hint` first; `notFound` when no board has it. */
+export declare function boardHolding(c: Ctx, kind: "state" | "ticket" | "entry" | "relation", id: string, hint: RegisteredBoard | null, notFound: "state_not_found" | "ticket_not_found" | "board_entry_not_found" | "relation_not_found"): Promise<BoardCtx>;

package/lib/core/context.js

@@ -0,0 +1,42 @@
+/**
+ * What every use case runs with: the ports (storage, bytes, a clock and ids),
+ * who is acting, and, for a use case on one board, that board. The core never
+ * reaches for anything else, so the same code runs on a server, in a CLI and
+ * in a browser tab.
+ */
+import { OrbitError } from "./errors.js";
+/** True when an agent is asking: its answers carry no server paths. */
+export function isAgent(actor) {
+    return actor.type === "agent";
+}
+/** The context for one board, as the directory lists it. */
+export async function onBoard(c, board) {
+    return { ...c, board, data: await c.store.board(board.id) };
+}
+/** A board by its id or slug, or null. */
+export async function findBoard(c, ident) {
+    return (await c.store.boards.get(ident)) ?? (await c.store.boards.bySlug(ident));
+}
+/** A board named by id first, then slug; null when neither is given; `board_not_found` when one is given and unknown. */
+export async function boardFromHints(c, id, slug) {
+    if (id) {
+        const row = await c.store.boards.get(id);
+        if (!row)
+            throw new OrbitError("board_not_found");
+        return row;
+    }
+    if (slug) {
+        const row = await c.store.boards.bySlug(slug);
+        if (!row)
+            throw new OrbitError("board_not_found");
+        return row;
+    }
+    return null;
+}
+/** The board holding a record, looked for on `hint` first; `notFound` when no board has it. */
+export async function boardHolding(c, kind, id, hint, notFound) {
+    const row = await c.store.locate(kind, id, hint?.id);
+    if (!row)
+        throw new OrbitError(notFound);
+    return onBoard(c, row);
+}