@starlove/orbit 1.4.1 → 2.0.0

package/lib/core/cross-board.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Cards linked to cards on other boards of the same Orbit: a card blocked by
+ * another board's card (a game waiting on an identity board's payments), or
+ * related to one. Each board is its own store, which nothing can change at
+ * once with another, so a link lives on its source card's board
+ * (`CrossBoardRelation`) and nothing on the other board changes. Whether a
+ * link still blocks is read from the other card when asked: it blocks until
+ * that card is in a closed lane (done, cancelled), archived or gone, and an
+ * epic blocks through its open sub-cards, as on one board. So nothing has to
+ * clean a link up when the other card is done.
+ */
+import type { BoardCtx, Ctx } from "./context.ts";
+import type { CrossBoardRelation, Id, LaneRole, RegisteredBoard, Ticket } from "./model.ts";
+import type { BoardReader } from "../store/types.ts";
+/** The link types that cross boards: a blocker, or a relation. */
+export declare const CROSS_BOARD_TYPES: readonly ["blocked_by", "relates_to"];
+/** A card on another board, as a link names it. */
+export interface CrossCard {
+    board_id: Id;
+    board_slug: string;
+    id: Id;
+    number: number;
+    title: string;
+    type: Ticket["type"];
+    priority: Ticket["priority"];
+    state_name: string;
+    state_role: LaneRole | null;
+    /** Set when it blocks because it is an open sub-card of the epic the link names. */
+    via_epic_id: Id | null;
+}
+/** One cross-board link as a card's relations list it. */
+export interface CrossLink {
+    id: Id;
+    type: CrossBoardRelation["type"];
+    /** outgoing: this card's link to the other card; incoming: the other card's link to this one. */
+    direction: "outgoing" | "incoming";
+    /** Whether the other card still blocks this one (outgoing blocked_by), or this card blocks it (incoming). */
+    blocking: boolean;
+    /** The other card; null when it is gone, or its board is. */
+    other_ticket: Omit<CrossCard, "via_epic_id"> | null;
+    other_board_id: Id;
+}
+/**
+ * What blocks each card from other boards, from the board's cross-board
+ * links already read: one read per other board, never one per card.
+ */
+export declare function crossBlockers(c: Ctx, relations: readonly CrossBoardRelation[]): Promise<Map<Id, CrossCard[]>>;
+/** What blocks one card from other boards (`r` is its own board's reader, inside a read or a write). */
+export declare function crossBlockersFor(c: Ctx, r: BoardReader, ticketId: Id): Promise<CrossCard[]>;
+/** A card's links across boards: its own (outgoing), and other boards' links to it (incoming). */
+export declare function crossLinks(c: BoardCtx, ticketId: Id): Promise<CrossLink[]>;
+/**
+ * A card's links across boards from what was read on its own board (its
+ * links, and whether it is still open), reading only the other boards: safe
+ * inside a read of the card's board.
+ */
+export declare function crossLinksFrom(c: Ctx, outgoing: readonly CrossBoardRelation[], incoming: readonly {
+    board_id: Id;
+    relation: CrossBoardRelation;
+}[], open: boolean): Promise<CrossLink[]>;
+/**
+ * Links a card to a card on another board. `blocks` is said from the other
+ * side: the link is made on the blocked card's board, as `blocked_by`.
+ */
+/** A cross-board link as it was made, with the board it lives on. */
+export type CrossBoardRelationAnswer = CrossBoardRelation & {
+    board_id: Id;
+};
+export declare function linkAcrossBoards(c: Ctx, from: BoardCtx, fromId: Id, to: BoardCtx, toId: Id, type: unknown): Promise<CrossBoardRelationAnswer>;
+/**
+ * The board holding a cross-board link with this id, or null. The `hint`
+ * board is asked first: a caller that knows where the link lives (the card
+ * drawer names it for a link into its card) removes it there.
+ */
+export declare function boardHoldingCrossLink(c: Ctx, id: Id, hint: RegisteredBoard | null): Promise<RegisteredBoard | null>;
+/** Removes a cross-board link from the board it lives on. */
+export declare function unlinkAcrossBoards(c: BoardCtx, relationId: Id): Promise<{
+    ok: true;
+}>;
+/** Another board's card as the command language names it: `garden#3`. */
+export declare function crossRef(card: Pick<CrossCard, "board_slug" | "number">): string;

package/lib/core/cross-board.js

@@ -0,0 +1,228 @@
+/**
+ * Cards linked to cards on other boards of the same Orbit: a card blocked by
+ * another board's card (a game waiting on an identity board's payments), or
+ * related to one. Each board is its own store, which nothing can change at
+ * once with another, so a link lives on its source card's board
+ * (`CrossBoardRelation`) and nothing on the other board changes. Whether a
+ * link still blocks is read from the other card when asked: it blocks until
+ * that card is in a closed lane (done, cancelled), archived or gone, and an
+ * epic blocks through its open sub-cards, as on one board. So nothing has to
+ * clean a link up when the other card is done.
+ */
+import { OrbitError, isOrbitError } from "./errors.js";
+import { record } from "./history.js";
+import { ticketOn } from "./tickets.js";
+import { Lanes, isClosedLane } from "./views.js";
+/** The link types that cross boards: a blocker, or a relation. */
+export const CROSS_BOARD_TYPES = ["blocked_by", "relates_to"];
+/**
+ * Reads the named cards on each board once (an epic's open sub-cards with
+ * them). A board that is gone, or can't be read, reads as having none of them.
+ */
+async function readBoards(c, wanted) {
+    const out = new Map();
+    for (const [boardId, ids] of wanted) {
+        const board = await c.store.boards.get(boardId);
+        if (!board)
+            continue;
+        try {
+            const data = await c.store.board(boardId);
+            const read = await data.read(async (r) => {
+                const lanes = await Lanes.of(r);
+                const tickets = await r.tickets.list({ ids: [...ids] });
+                const children = new Map();
+                for (const epic of tickets.filter((t) => t.type === "epic" && !t.archived_at))
+                    children.set(epic.id, await r.tickets.list({ parent: epic.id, archived: false }));
+                return { lanes, tickets: new Map(tickets.map((t) => [t.id, t])), children };
+            });
+            out.set(boardId, { board, ...read });
+        }
+        catch (error) {
+            // A board whose file is gone, or that went meanwhile, blocks nothing.
+            if (!isOrbitError(error))
+                throw error;
+        }
+    }
+    return out;
+}
+const closed = (read, ticket) => {
+    const state = read.lanes.get(ticket.state_id);
+    return Boolean(ticket.archived_at) || (state ? isClosedLane(state) : false);
+};
+function linkedCard(read, ticket) {
+    return {
+        board_id: read.board.id,
+        board_slug: read.board.slug,
+        id: ticket.id,
+        number: ticket.number,
+        title: ticket.title,
+        type: ticket.type,
+        priority: ticket.priority,
+        state_name: read.lanes.nameOf(ticket),
+        state_role: read.lanes.roleOf(ticket)
+    };
+}
+function crossCard(read, ticket, viaEpic) {
+    return { ...linkedCard(read, ticket), via_epic_id: viaEpic };
+}
+/** What still blocks the card each link starts from: the other card, or an epic's open sub-cards. */
+function blockersOf(read, relation) {
+    const target = read?.tickets.get(relation.target_ticket_id);
+    if (!read || !target || closed(read, target))
+        return [];
+    if (target.type !== "epic")
+        return [crossCard(read, target, null)];
+    return (read.children.get(target.id) ?? []).filter((child) => !closed(read, child)).map((child) => crossCard(read, child, target.id));
+}
+function wantedBy(relations) {
+    const wanted = new Map();
+    for (const relation of relations) {
+        const ids = wanted.get(relation.target_board_id) ?? new Set();
+        ids.add(relation.target_ticket_id);
+        wanted.set(relation.target_board_id, ids);
+    }
+    return wanted;
+}
+/**
+ * What blocks each card from other boards, from the board's cross-board
+ * links already read: one read per other board, never one per card.
+ */
+export async function crossBlockers(c, relations) {
+    const blocking = relations.filter((relation) => relation.type === "blocked_by");
+    const out = new Map();
+    if (!blocking.length)
+        return out;
+    const boards = await readBoards(c, wantedBy(blocking));
+    for (const relation of blocking) {
+        const found = blockersOf(boards.get(relation.target_board_id), relation);
+        if (!found.length)
+            continue;
+        const list = out.get(relation.source_ticket_id) ?? [];
+        for (const card of found)
+            if (!list.some((other) => other.id === card.id && other.board_id === card.board_id))
+                list.push(card);
+        out.set(relation.source_ticket_id, list);
+    }
+    for (const list of out.values())
+        list.sort((a, b) => (a.board_slug < b.board_slug ? -1 : a.board_slug > b.board_slug ? 1 : a.number - b.number));
+    return out;
+}
+/** What blocks one card from other boards (`r` is its own board's reader, inside a read or a write). */
+export async function crossBlockersFor(c, r, ticketId) {
+    return (await crossBlockers(c, await r.crossBoardRelations.list(ticketId))).get(ticketId) ?? [];
+}
+/** A card's links across boards: its own (outgoing), and other boards' links to it (incoming). */
+export async function crossLinks(c, ticketId) {
+    const here = await c.data.read(async (r) => {
+        const [outgoing, lanes, ticket] = await Promise.all([r.crossBoardRelations.list(ticketId), Lanes.of(r), r.tickets.get(ticketId)]);
+        const state = ticket ? lanes.get(ticket.state_id) : undefined;
+        return { outgoing, open: Boolean(ticket && !ticket.archived_at && !(state && isClosedLane(state))) };
+    });
+    const incoming = (await c.store.relationsInto(c.board.id)).filter((row) => row.relation.target_ticket_id === ticketId);
+    return crossLinksFrom(c, here.outgoing, incoming, here.open);
+}
+/**
+ * A card's links across boards from what was read on its own board (its
+ * links, and whether it is still open), reading only the other boards: safe
+ * inside a read of the card's board.
+ */
+export async function crossLinksFrom(c, outgoing, incoming, open) {
+    const wanted = wantedBy(outgoing);
+    for (const row of incoming) {
+        const ids = wanted.get(row.board_id) ?? new Set();
+        ids.add(row.relation.source_ticket_id);
+        wanted.set(row.board_id, ids);
+    }
+    const boards = await readBoards(c, wanted);
+    const other = (boardId, cardId) => {
+        const read = boards.get(boardId);
+        const ticket = read?.tickets.get(cardId);
+        if (!read || !ticket || ticket.archived_at)
+            return null;
+        return linkedCard(read, ticket);
+    };
+    const links = outgoing.map((relation) => ({
+        id: relation.id,
+        type: relation.type,
+        direction: "outgoing",
+        blocking: relation.type === "blocked_by" && blockersOf(boards.get(relation.target_board_id), relation).length > 0,
+        other_ticket: other(relation.target_board_id, relation.target_ticket_id),
+        other_board_id: relation.target_board_id
+    }));
+    for (const { board_id, relation } of incoming) {
+        links.push({ id: relation.id, type: relation.type, direction: "incoming", blocking: relation.type === "blocked_by" && open, other_ticket: other(board_id, relation.source_ticket_id), other_board_id: board_id });
+    }
+    return links;
+}
+export async function linkAcrossBoards(c, from, fromId, to, toId, type) {
+    if (from.board.id === to.board.id)
+        throw new OrbitError("invalid_relation_type", { message: "Both cards are on one board: link them as one board's cards." });
+    const kind = typeof type === "string" && type ? type : "relates_to";
+    if (kind === "child_of" || kind === "parent_of")
+        throw new OrbitError("hierarchy_uses_parent_ticket_id");
+    if (kind !== "blocks" && !CROSS_BOARD_TYPES.includes(kind))
+        throw new OrbitError("invalid_relation_type");
+    // The link lives on the card that waits (or, for a relation, the card it starts from).
+    const [source, sourceId, target, targetId] = kind === "blocks" ? [to, toId, from, fromId] : [from, fromId, to, toId];
+    const linkType = kind === "relates_to" ? "relates_to" : "blocked_by";
+    const other = await target.data.read(async (r) => {
+        const ticket = await ticketOn(r, targetId);
+        const lanes = await Lanes.of(r);
+        const state = lanes.get(ticket.state_id);
+        return { ticket, done: Boolean(ticket.archived_at) || (state ? isClosedLane(state) : false) };
+    });
+    if (other.ticket.archived_at)
+        throw new OrbitError("ticket_not_found");
+    // A blocker already done would block nothing.
+    if (linkType === "blocked_by" && other.done)
+        throw new OrbitError("blocker_target_already_done");
+    const relation = await source.data.write(async (w) => {
+        const card = await ticketOn(w, sourceId);
+        const existing = await w.crossBoardRelations.list(card.id);
+        if (existing.some((x) => x.target_board_id === target.board.id && x.target_ticket_id === targetId && x.type === linkType))
+            throw new OrbitError("relation_exists");
+        const made = { id: c.ids.next(), source_ticket_id: card.id, target_board_id: target.board.id, target_ticket_id: targetId, type: linkType, created_at: c.clock.now() };
+        await w.crossBoardRelations.insert(made);
+        await record(w, c, "relation_created", card.id, { target_board_id: target.board.id, target_board: target.board.slug, target_ticket_id: targetId, target_number: other.ticket.number, type: linkType });
+        return made;
+    });
+    source.changed(source.board.id);
+    return { ...relation, board_id: source.board.id };
+}
+/**
+ * The board holding a cross-board link with this id, or null. The `hint`
+ * board is asked first: a caller that knows where the link lives (the card
+ * drawer names it for a link into its card) removes it there.
+ */
+export async function boardHoldingCrossLink(c, id, hint) {
+    const rows = await c.store.boards.list();
+    const ordered = hint ? [hint, ...rows.filter((row) => row.id !== hint.id)] : rows;
+    for (const row of ordered) {
+        try {
+            const data = await c.store.board(row.id);
+            if ((await data.read((r) => r.crossBoardRelations.list())).some((relation) => relation.id === id))
+                return row;
+        }
+        catch (error) {
+            if (!isOrbitError(error))
+                throw error;
+        }
+    }
+    return null;
+}
+/** Removes a cross-board link from the board it lives on. */
+export async function unlinkAcrossBoards(c, relationId) {
+    await c.data.write(async (w) => {
+        const relation = (await w.crossBoardRelations.list()).find((x) => x.id === relationId);
+        if (!relation)
+            throw new OrbitError("relation_not_found");
+        await w.crossBoardRelations.remove(relationId);
+        await record(w, c, "relation_deleted", relation.source_ticket_id, { target_board_id: relation.target_board_id, target_ticket_id: relation.target_ticket_id, type: relation.type });
+    });
+    c.changed(c.board.id);
+    return { ok: true };
+}
+/** Another board's card as the command language names it: `garden#3`. */
+export function crossRef(card) {
+    return `${card.board_slug}#${card.number}`;
+}

package/lib/core/describe.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Orbit's own words for what people wrote and what happened: text folded to
+ * one safe line, and an event said as a short phrase ("took #14"). Shared by
+ * the command language's answers and the quick menu's sessions.
+ */
+/**
+ * Text as one safe line: control characters and line breaks become spaces,
+ * so a title can never forge a lane header or another card's line.
+ */
+export declare function oneLine(value: unknown, max?: number): string;
+/** A lane's name as shown: one line (a board made before lane names were cleaned may hold anything). */
+export declare function laneText(name: unknown): string;
+/** An event with its card's number and title, as `changes` and the sessions read it. */
+export interface EventLine {
+    type: string;
+    body_json: string;
+    number?: number | null;
+    title?: string | null;
+}
+/** One event in words: "took #14", "asked about #8 (In Progress -> Review)". */
+export declare function describeEvent(event: EventLine): string;

package/lib/core/describe.js

@@ -0,0 +1,81 @@
+/**
+ * Orbit's own words for what people wrote and what happened: text folded to
+ * one safe line, and an event said as a short phrase ("took #14"). Shared by
+ * the command language's answers and the quick menu's sessions.
+ */
+import { asText } from "./text.js";
+/**
+ * Text as one safe line: control characters and line breaks become spaces,
+ * so a title can never forge a lane header or another card's line.
+ */
+export function oneLine(value, max = 160) {
+    const clean = asText(value ?? "")
+        .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return clean.length > max ? `${clean.slice(0, max - 1).trimEnd()}…` : clean;
+}
+/** A lane's name as shown: one line (a board made before lane names were cleaned may hold anything). */
+export function laneText(name) {
+    return oneLine(name, 60);
+}
+const FIELD_WORDS = {
+    parent_ticket_id: "parent",
+    ai_plan: "plan",
+    implementation_summary: "summary",
+    implementation_updates: "revisions",
+    state_id: "lane",
+    plan_artifact_path: "plan link",
+    implementation_artifact_path: "summary link",
+    nebula_url: "Nebula link"
+};
+/** One event in words: "took #14", "asked about #8 (In Progress -> Review)". */
+export function describeEvent(event) {
+    const n = event.number ? `#${event.number}` : "a card";
+    let body = {};
+    try {
+        const parsed = JSON.parse(event.body_json || "{}");
+        if (parsed && typeof parsed === "object")
+            body = parsed;
+    }
+    catch {
+        body = {};
+    }
+    const from = body.from;
+    const to = body.to;
+    const path = from && to ? ` (${laneText(from)} -> ${laneText(to)})` : to ? ` (-> ${laneText(to)})` : "";
+    switch (event.type) {
+        case "ticket_created":
+            return `created ${n} ${oneLine(body.title || event.title || "", 80)}`.trimEnd();
+        case "agent_claimed":
+            if (body.took_over_from)
+                return `took over ${n} from @${oneLine(body.took_over_from, 40)}`;
+            return from && from === to ? `took ${n}` : `took ${n}${path}`;
+        case "state_changed":
+            return `moved ${n}${path}`;
+        case "agent_completed":
+            return `finished ${n}${path}`;
+        case "checkpoint_requested":
+            return `asked about ${n}${path}`;
+        case "comment_created":
+            return `noted on ${n}`;
+        case "ticket_updated":
+            return `edited ${n} (${Object.keys(body).map((key) => FIELD_WORDS[key] ?? key).join(", ") || "fields"})`;
+        case "ticket_archived":
+            return `archived ${n}`;
+        case "ticket_restored":
+            return `restored ${n}`;
+        case "ticket_deleted":
+            return `deleted ${oneLine(body.title || "a card", 80)}`;
+        case "relation_created":
+            if (typeof body.target_board === "string" && typeof body.target_number === "number")
+                return `linked ${n} to ${body.target_board}#${body.target_number} (${asText(body.type ?? "").replace(/_/g, " ")})`;
+            return `linked ${n} (${asText(body.type ?? "").replace(/_/g, " ")})`;
+        case "relation_deleted":
+            return `unlinked ${n}`;
+        case "board_entry_created":
+            return `wrote a ${typeof body.type === "string" && body.type ? body.type : "journal entry"} in the journal`;
+        default:
+            return `${event.type.replace(/_/g, " ")}${event.number ? ` ${n}` : ""}`;
+    }
+}

package/lib/core/errors.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Orbit's errors. Each carries a code, the same codes Orbit's answers have
+ * always used (`invalid_state`, `board_not_found`...), and a kind that says
+ * what went wrong in words any transport understands. The core and the storage
+ * adapters throw them; each transport maps the kind to its own form: an HTTP
+ * status (`HTTP_STATUS` below), an MCP tool error, a CLI exit code.
+ *
+ * `message` is what people and agents read. It is the code itself unless a
+ * clearer sentence was given, which is what Orbit's answers and the command
+ * language ("Orbit refused: invalid state.") already show.
+ */
+export type ErrorKind = 
+/** The request is malformed or names something that can't be used. */
+"invalid"
+/** No one is signed in where an account is needed (hosts with accounts). */
+ | "unauthorized"
+/** The actor may not do this. */
+ | "forbidden" | "not_found"
+/** The address exists, but not for this method (HTTP only). */
+ | "method_not_allowed"
+/** The request collides with what is there now. */
+ | "conflict" | "too_large" | "unsupported_type"
+/** This Orbit can't do it here (a feature of another host). */
+ | "not_supported"
+/** Storage is busy or out of room; the same request may work later. */
+ | "unavailable"
+/** A fault in Orbit or its storage. The message never carries a database's words. */
+ | "internal";
+/** Every code Orbit raises, with its kind. */
+export declare const ERROR_CODES: {
+    readonly board_not_found: "not_found";
+    readonly board_id_required: "invalid";
+    readonly board_id_mismatch: "invalid";
+    readonly board_slug_taken: "conflict";
+    readonly board_slug_confirmation_required: "invalid";
+    readonly board_has_no_states: "invalid";
+    readonly board_files_busy: "conflict";
+    readonly board_file_missing: "conflict";
+    readonly unsafe_board_db_path: "conflict";
+    readonly missing_name: "invalid";
+    readonly state_not_found: "not_found";
+    readonly invalid_state: "invalid";
+    readonly invalid_state_order: "invalid";
+    readonly invalid_state_role: "invalid";
+    readonly state_has_tickets: "conflict";
+    readonly cannot_delete_last_state: "conflict";
+    readonly cannot_rename_ai_ready_lane: "conflict";
+    readonly ai_ready_lane_must_be_named_ai_ready: "conflict";
+    readonly missing_in_progress_state: "invalid";
+    readonly missing_review_state: "invalid";
+    readonly missing_next_state: "invalid";
+    readonly ticket_not_found: "not_found";
+    readonly missing_title: "invalid";
+    readonly invalid_ticket_type: "invalid";
+    readonly invalid_number: "invalid";
+    readonly invalid_nebula_url: "invalid";
+    readonly ticket_id_or_number_or_title_required: "invalid";
+    readonly missing_ticket_id: "invalid";
+    readonly ticket_not_archived: "conflict";
+    readonly invalid_parent_ticket: "invalid";
+    readonly epic_cannot_have_parent: "invalid";
+    readonly ticket_cannot_parent_itself: "invalid";
+    readonly ticket_parent_cycle: "invalid";
+    readonly missing_label: "invalid";
+    readonly comment_not_found: "not_found";
+    readonly missing_body: "invalid";
+    readonly omitted_for_ai_required: "invalid";
+    readonly relation_not_found: "not_found";
+    readonly relation_exists: "conflict";
+    readonly relation_self: "invalid";
+    readonly relation_redundant_with_parent: "invalid";
+    readonly hierarchy_uses_parent_ticket_id: "invalid";
+    readonly blocker_target_already_done: "invalid";
+    readonly blocker_source_already_done: "invalid";
+    readonly invalid_relation_type: "invalid";
+    readonly missing_source_ticket_id: "invalid";
+    readonly missing_target_ticket_id: "invalid";
+    readonly board_entry_not_found: "not_found";
+    readonly invalid_project_entry_type: "invalid";
+    readonly missing_entry_title: "invalid";
+    readonly entry_not_struck: "conflict";
+    readonly forbidden: "forbidden";
+    readonly missing_message: "invalid";
+    readonly missing_summary: "invalid";
+    readonly invalid_since: "invalid";
+    readonly review_verdict_not_found: "not_found";
+    readonly missing_verdict: "invalid";
+    readonly invalid_review_verdict: "invalid";
+    readonly invalid_blocking_findings: "invalid";
+    readonly invalid_optional_findings: "invalid";
+    readonly invalid_evidence_commands: "invalid";
+    readonly invalid_supersedes_prior_review_id: "invalid";
+    readonly superseded_review_ticket_mismatch: "invalid";
+    readonly attachment_not_found: "not_found";
+    readonly attachment_file_missing: "not_found";
+    readonly empty_attachment: "invalid";
+    readonly invalid_attachment_path: "invalid";
+    readonly attachment_too_large: "too_large";
+    readonly unsupported_attachment_type: "unsupported_type";
+    readonly attachment_type_mismatch: "unsupported_type";
+    readonly artifact_not_found: "not_found";
+    readonly artifact_path_required: "invalid";
+    readonly artifact_path_outside_allowed_roots: "invalid";
+    readonly artifact_root_unavailable: "invalid";
+    readonly artifact_not_file: "invalid";
+    readonly artifact_too_large: "too_large";
+    readonly unsupported_artifact_type: "unsupported_type";
+    readonly invalid_import_snapshot: "invalid";
+    readonly snapshot_missing_board: "invalid";
+    readonly import_requires_empty_board_or_replace_existing: "conflict";
+    readonly import_would_delete_hidden_comments: "conflict";
+    readonly not_found: "not_found";
+    readonly method_not_allowed: "method_not_allowed";
+    readonly invalid_json: "invalid";
+    readonly invalid_body: "invalid";
+    readonly payload_too_large: "too_large";
+    readonly cross_site_request: "forbidden";
+    readonly folder_picker_unavailable: "not_supported";
+    readonly duplicate_id: "conflict";
+    readonly ticket_number_taken: "conflict";
+    readonly state_name_taken: "conflict";
+    readonly label_name_taken: "conflict";
+    readonly invalid_reference: "invalid";
+    readonly invalid_blob_path: "invalid";
+    readonly blob_exists: "conflict";
+    readonly write_closed: "internal";
+    readonly storage_busy: "unavailable";
+    readonly storage_full: "unavailable";
+    readonly storage_failed: "internal";
+    readonly data_needs_migration: "unavailable";
+    readonly data_from_newer_orbit: "unavailable";
+    readonly migration_source_unreadable: "invalid";
+    readonly migration_target_in_use: "conflict";
+};
+export type ErrorCode = keyof typeof ERROR_CODES;
+/** The HTTP status each kind answers with: the statuses Orbit's API has always used for these codes. */
+export declare const HTTP_STATUS: {
+    readonly invalid: 400;
+    readonly unauthorized: 401;
+    readonly forbidden: 403;
+    readonly not_found: 404;
+    readonly method_not_allowed: 405;
+    readonly conflict: 409;
+    readonly too_large: 413;
+    readonly unsupported_type: 415;
+    readonly not_supported: 501;
+    readonly unavailable: 503;
+    readonly internal: 500;
+};
+export declare class OrbitError extends Error {
+    readonly code: ErrorCode;
+    readonly kind: ErrorKind;
+    constructor(code: ErrorCode, options?: {
+        message?: string;
+        cause?: unknown;
+    });
+}
+/** True for an OrbitError, from this copy of Orbit or another (a host may bundle its own). */
+export declare function isOrbitError(value: unknown): value is OrbitError;