@starlove/orbit 1.4.0 → 2.0.0

package/lib/core/snapshots.js

@@ -0,0 +1,409 @@
+/**
+ * A board's export (`orbit-board-export`), and importing one: into a new
+ * board, or over a board it replaces (keeping that board's id and slug). An
+ * import is checked where it enters, with zod; a Trello export is read as
+ * one first. One field Orbit wouldn't keep (a link with a password in it)
+ * is dropped, not refused, so one bad field never stops a whole board.
+ */
+import { cardLinkFromElsewhere } from "./card-paths.js";
+import { exportedAttachment, importedAttachment, isShownImage } from "./files.js";
+import { isAgent, onBoard } from "./context.js";
+import { OrbitError, isOrbitError } from "./errors.js";
+import { record, searchDocument } from "./history.js";
+import { CROSS_BOARD_TYPES } from "./cross-board.js";
+import { parseNebulaUrl } from "./nebula-link.js";
+import { cleanName, normalizeEntryType, normalizePriority, normalizeTicketType, requiredString, slugify, asText } from "./text.js";
+import { looksLikeTrello, trelloToSnapshot } from "./trello.js";
+import { labelsByTicket } from "./views.js";
+export const EXPORT_FORMAT = "orbit-board-export";
+const HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+/** A label colour as an import keeps it. It is CSS the app paints with, so only `#rgb` or `#rrggbb` is kept; anything else (a `url(...)`) gets the default. */
+export function keptLabelColor(value) {
+    return typeof value === "string" && HEX_COLOR.test(value) ? value : "#64748b";
+}
+export const EXPORT_VERSION = 9;
+/** Exports a board whole: every record, events included; images' bytes when asked. */
+export async function exportBoard(c, options = {}) {
+    const include = Boolean(options.includeAttachments);
+    const agent = isAgent(c.actor);
+    const data = await c.data.read(async (r) => {
+        const [board, states, tickets, labels, comments, verdicts, relations, crossOut, attachments, entries, events] = await Promise.all([
+            r.board.get(),
+            r.states.list(),
+            r.tickets.list(),
+            r.labels.list(),
+            r.comments.list(),
+            r.verdicts.list(),
+            r.relations.list(),
+            r.crossBoardRelations.list(),
+            r.attachments.list(),
+            r.entries.list(),
+            r.events.list()
+        ]);
+        return { board, states, tickets, labels, comments, verdicts, relations, crossOut, attachments, entries, events, labelsOf: await labelsByTicket(r) };
+    });
+    // An agent's export leaves out what agents never read, comments hidden from AI, and says how many,
+    // so a replace from it can refuse rather than delete them (importReplacing).
+    const comments = agent ? data.comments.filter((comment) => !comment.omitted_for_ai) : data.comments;
+    return {
+        format: EXPORT_FORMAT,
+        version: EXPORT_VERSION,
+        exported_at: c.clock.now(),
+        include_attachments: include,
+        ...(agent ? { comments_hidden_from_ai_left_out: data.comments.length - comments.length } : {}),
+        board: { ...data.board },
+        states: data.states,
+        labels: data.labels,
+        tickets: data.tickets.map((ticket) => ({ ...ticket, labels: data.labelsOf.get(ticket.id) ?? [] })),
+        comments,
+        review_verdicts: data.verdicts,
+        relations: data.relations,
+        // The board's links to cards on other boards of this Orbit. They name those boards by id, so they mean something only here.
+        // Other boards' links to its cards live on those boards, and a replace of this board leaves them be.
+        cross_board_relations: data.crossOut,
+        attachments: await Promise.all(data.attachments.map((attachment) => exportedAttachment(c, attachment, include))),
+        board_entries: data.entries,
+        events: data.events
+    };
+}
+/** The export in `raw`, read and checked: a Trello export becomes one first. */
+async function readSnapshot(c, raw, target) {
+    const { BoardIn, SnapshotIn } = await import("./snapshot-schema.js");
+    const source = looksLikeTrello(raw) ? trelloToSnapshot(raw, target, c.clock, c.ids) : raw;
+    const parsed = SnapshotIn.safeParse(source);
+    if (!parsed.success)
+        throw new OrbitError("invalid_import_snapshot");
+    if (parsed.data.board === undefined || parsed.data.board === null)
+        throw new OrbitError("snapshot_missing_board");
+    const board = BoardIn.safeParse(parsed.data.board);
+    if (!board.success)
+        throw new OrbitError("invalid_import_snapshot");
+    return { ...parsed.data, board: board.data };
+}
+const rawOf = (input) => input.snapshot ?? input;
+function boardRecord(c, snapshot, boardId, slug, name) {
+    const now = c.clock.now();
+    const b = snapshot.board;
+    return {
+        id: boardId,
+        slug,
+        name,
+        repo_url: b.repo_url,
+        default_branch: b.default_branch || "main",
+        project_notes: b.project_notes,
+        agent_instructions: b.agent_instructions,
+        ai_enabled: b.ai_enabled === 0 ? 0 : 1,
+        created_at: b.created_at ?? now,
+        updated_at: b.updated_at ?? now
+    };
+}
+/** Writes every record of the snapshot onto the board `w` writes, its search documents too; not its images. */
+async function writeRecords(w, c, snapshot, boardId) {
+    const now = () => c.clock.now();
+    for (const s of snapshot.states) {
+        const state = { id: s.id, board_id: boardId, name: cleanName(s.name) || "Lane", position: s.position, is_default: s.is_default, role: s.role, created_at: s.created_at ?? now() };
+        await w.states.insert(state);
+    }
+    for (const l of snapshot.labels) {
+        const label = { id: l.id, board_id: boardId, name: l.name, color: keptLabelColor(l.color), created_at: l.created_at ?? now() };
+        await w.labels.insert(label);
+    }
+    const tickets = new Set();
+    for (const t of snapshot.tickets) {
+        const ticket = {
+            id: t.id,
+            board_id: boardId,
+            number: t.number,
+            title: t.title,
+            description: t.description,
+            type: normalizeTicketType(t.type ?? "task"),
+            parent_ticket_id: t.parent_ticket_id,
+            ai_plan: t.ai_plan,
+            plan_artifact_path: cardLinkFromElsewhere(t.plan_artifact_path) ?? "",
+            implementation_summary: t.implementation_summary,
+            implementation_artifact_path: cardLinkFromElsewhere(t.implementation_artifact_path) ?? "",
+            implementation_updates: t.implementation_updates,
+            nebula_url: parseNebulaUrl(t.nebula_url) ?? "",
+            state_id: t.state_id,
+            priority: normalizePriority(t.priority),
+            created_by: t.created_by ?? "import",
+            created_at: t.created_at ?? now(),
+            updated_at: t.updated_at ?? now(),
+            archived_at: t.archived_at
+        };
+        await w.tickets.insert(ticket);
+        tickets.add(ticket.id);
+        for (const label of t.labels ?? [])
+            await w.ticketLabels.add(ticket.id, label.id);
+    }
+    const comments = new Map();
+    for (const k of snapshot.comments) {
+        if (!tickets.has(k.ticket_id))
+            continue;
+        const comment = { id: k.id, ticket_id: k.ticket_id, author: k.author ?? "import", kind: k.kind ?? "comment", body: k.body, omitted_for_ai: k.omitted_for_ai, created_at: k.created_at ?? now() };
+        await w.comments.insert(comment);
+        comments.set(comment.ticket_id, [...(comments.get(comment.ticket_id) ?? []), comment]);
+    }
+    const verdicts = new Set();
+    for (const v of snapshot.review_verdicts) {
+        if (!tickets.has(v.ticket_id))
+            continue;
+        const verdict = {
+            id: v.id,
+            ticket_id: v.ticket_id,
+            verdict: v.verdict,
+            blocking_findings_json: v.blocking_findings_json ?? "[]",
+            optional_findings_json: v.optional_findings_json ?? "[]",
+            evidence_commands_json: v.evidence_commands_json ?? "[]",
+            reviewer_profile: v.reviewer_profile,
+            reviewer_session_id: v.reviewer_session_id,
+            reviewed_commit_sha: v.reviewed_commit_sha,
+            dispatch_run_id: v.dispatch_run_id,
+            supersedes_prior_review_id: v.supersedes_prior_review_id && verdicts.has(v.supersedes_prior_review_id) ? v.supersedes_prior_review_id : null,
+            created_by: v.created_by ?? "import",
+            created_at: v.created_at ?? now()
+        };
+        await w.verdicts.insert(verdict);
+        verdicts.add(verdict.id);
+    }
+    const relations = new Set();
+    for (const x of snapshot.relations) {
+        const type = x.type ?? "relates_to";
+        const key = `${x.source_ticket_id}\n${x.target_ticket_id}\n${type}`;
+        if (!tickets.has(x.source_ticket_id) || !tickets.has(x.target_ticket_id) || relations.has(key))
+            continue;
+        relations.add(key);
+        const relation = { id: x.id, source_ticket_id: x.source_ticket_id, target_ticket_id: x.target_ticket_id, type, created_at: x.created_at ?? now() };
+        await w.relations.insert(relation);
+    }
+    for (const e of snapshot.board_entries) {
+        const entry = {
+            id: e.id,
+            board_id: boardId,
+            type: normalizeEntryType(e.type),
+            title: requiredString(e.title, "entry_title"),
+            body: e.body,
+            ticket_id: e.ticket_id && tickets.has(e.ticket_id) ? e.ticket_id : null,
+            created_by: e.created_by ?? "import",
+            created_at: e.created_at ?? now(),
+            updated_at: e.updated_at ?? now(),
+            struck_at: e.struck_at
+        };
+        await w.entries.insert(entry);
+    }
+    for (const v of snapshot.events) {
+        const event = { id: v.id, ticket_id: v.ticket_id && tickets.has(v.ticket_id) ? v.ticket_id : null, actor: v.actor ?? "import", type: v.type ?? "imported_event", body_json: v.body_json ?? "{}", created_at: v.created_at ?? now() };
+        await w.events.append(event);
+    }
+    for (const t of snapshot.tickets) {
+        const ticket = await w.tickets.get(t.id);
+        if (ticket)
+            await w.search.index(ticket.id, searchDocument(ticket, comments.get(ticket.id) ?? []));
+    }
+}
+/** Stores the snapshot's images whose cards came in, bytes first, then their records; says how many are kept as downloads only. */
+async function writeImages(c, snapshot) {
+    const tickets = new Set(snapshot.tickets.map((ticket) => ticket.id));
+    const images = [];
+    for (const row of snapshot.attachments) {
+        const ticketId = typeof row.ticket_id === "string" ? row.ticket_id : "";
+        if (!tickets.has(ticketId))
+            continue;
+        images.push(await importedAttachment(c, row, ticketId));
+    }
+    if (!images.length)
+        return 0;
+    return c.data.write(async (w) => {
+        const seen = new Set();
+        for (const image of images) {
+            if (seen.has(image.id))
+                continue;
+            seen.add(image.id);
+            await w.attachments.insert(image);
+        }
+        return images.filter((image, i) => images.findIndex((other) => other.id === image.id) === i && !isShownImage(image.mime_type)).length;
+    });
+}
+/** A cross-board link from an export, or null when it isn't one Orbit could keep. */
+function crossRow(row, now) {
+    const field = (key) => {
+        const value = row[key];
+        return typeof value === "string" ? value : "";
+    };
+    const type = field("type");
+    if (!field("id") || !field("source_ticket_id") || !field("target_board_id") || !field("target_ticket_id"))
+        return null;
+    if (!CROSS_BOARD_TYPES.includes(type))
+        return null;
+    return { id: field("id"), source_ticket_id: field("source_ticket_id"), target_board_id: field("target_board_id"), target_ticket_id: field("target_ticket_id"), type: type, created_at: field("created_at") || now };
+}
+/** Of `wanted` (card ids by board), the ones each board of this Orbit has; a board gone or unreadable has none. */
+async function cardsThere(c, wanted) {
+    const found = new Map();
+    for (const [boardId, ids] of wanted) {
+        if (!(await c.store.boards.get(boardId)))
+            continue;
+        try {
+            const data = await c.store.board(boardId);
+            const tickets = await data.read((r) => r.tickets.list({ ids: [...ids] }));
+            found.set(boardId, new Set(tickets.map((ticket) => ticket.id)));
+        }
+        catch (error) {
+            if (!isOrbitError(error))
+                throw error;
+        }
+    }
+    return found;
+}
+const want = (wanted, boardId, ticketId) => {
+    wanted.set(boardId, (wanted.get(boardId) ?? new Set()).add(ticketId));
+};
+/**
+ * The cross-board links an import keeps onto board `boardId`: only the
+ * board's own, since a link lives on the board it starts from. Replacing a
+ * board from its own export (`own`) brings back each link whose card comes
+ * back, as it was. Anywhere else a link is kept only when the other card
+ * exists in this Orbit, under a new id: a copy's link is its own, never the
+ * original's, so removing one can't remove the other. Other boards are never written: their links to this board
+ * live on them, and a replace leaves them be. `dropped` counts what didn't
+ * come.
+ */
+async function plannedCrossLinks(c, snapshot, boardId, own) {
+    const tickets = new Set(snapshot.tickets.map((ticket) => ticket.id));
+    const now = c.clock.now();
+    const rows = snapshot.cross_board_relations.map((row) => crossRow(row, now));
+    const wanted = new Map();
+    if (!own)
+        for (const row of rows)
+            if (row)
+                want(wanted, row.target_board_id, row.target_ticket_id);
+    const there = await cardsThere(c, wanted);
+    const has = (board, card) => there.get(board)?.has(card) ?? false;
+    const outgoing = [];
+    const keys = new Set();
+    for (const row of rows) {
+        if (!row || !tickets.has(row.source_ticket_id) || row.target_board_id === boardId || !(own || has(row.target_board_id, row.target_ticket_id)))
+            continue;
+        const key = `${row.source_ticket_id}\n${row.target_board_id}\n${row.target_ticket_id}\n${row.type}`;
+        if (keys.has(key))
+            continue;
+        keys.add(key);
+        outgoing.push({ id: own ? row.id : c.ids.next(), source_ticket_id: row.source_ticket_id, target_board_id: row.target_board_id, target_ticket_id: row.target_ticket_id, type: row.type, created_at: row.created_at });
+    }
+    return { outgoing, dropped: rows.length - outgoing.length };
+}
+function counts(snapshot) {
+    return snapshot.imported_counts ?? { states: snapshot.states.length, tickets: snapshot.tickets.length, comments: snapshot.comments.length, labels: snapshot.labels.length };
+}
+/**
+ * Replacing a board deletes what it holds, so it is the person's call,
+ * never an agent's, as with a self-update. Refused before anything is read,
+ * whatever the transport: the JSON API, or a host's in-process client.
+ */
+export function refuseAgentReplace(c, input) {
+    if (input.replace_existing && isAgent(c.actor))
+        throw new OrbitError("forbidden", { message: "Replacing a board is the person's call, not an agent's: import it as a new board instead." });
+}
+/**
+ * Replaces a board with an export. The board keeps its own id and slug, so
+ * links to it still work; a copy of it is kept first where storage can.
+ * Never an agent's (`refuseAgentReplace`).
+ */
+export async function importReplacing(c, input) {
+    refuseAgentReplace(c, input);
+    const snapshot = await readSnapshot(c, rawOf(input), { id: c.board.id, slug: c.board.slug });
+    const replace = Boolean(input.replace_existing);
+    if (!replace)
+        throw new OrbitError("import_requires_empty_board_or_replace_existing");
+    // Fails closed: a file that has the marker goes ahead only when it is exactly the number 0. A file
+    // whose marker was removed by hand reads as one made in the app; nothing can tell them apart.
+    const hidden = snapshot.comments_hidden_from_ai_left_out;
+    if (hidden !== undefined && hidden !== 0) {
+        const count = typeof hidden === "number" && Number.isInteger(hidden) && hidden > 0 ? hidden : null;
+        const message = count === null
+            ? "Replacing the board from this export could delete comments hidden from AI: it carries an agent's count of them left out (comments_hidden_from_ai_left_out) that isn't a whole number. Use an export made in the app."
+            : `Replacing the board from this export would delete ${String(count)} comment${count === 1 ? "" : "s"} hidden from AI: an agent made it, and an agent's export leaves them out. Use an export made in the app.`;
+        throw new OrbitError("import_would_delete_hidden_comments", { message });
+    }
+    await c.store.backups?.board(c.board.id, "pre-import-replace");
+    const board = boardRecord(c, snapshot, c.board.id, c.board.slug, snapshot.board.name || c.board.name);
+    const own = snapshot.board.id === c.board.id;
+    const cross = await plannedCrossLinks(c, snapshot, board.id, own);
+    await c.data.write(async (w) => {
+        await w.clear();
+        await w.board.set(board);
+        await writeRecords(w, c, snapshot, board.id);
+        for (const relation of cross.outgoing)
+            await w.crossBoardRelations.insert(relation);
+        await record(w, c, "board_imported", null, { board_id: board.id, replace_existing: true });
+    });
+    const downloads = await writeImages(c, snapshot);
+    c.changed(board.id);
+    return { ok: true, imported_board_id: board.id, imported_board_slug: board.slug, replace_existing: true, source_format: snapshot.source_format ?? EXPORT_FORMAT, imported_counts: counts(snapshot), images_kept_as_downloads: downloads, cross_board_links_dropped: cross.dropped };
+}
+async function freeSlug(c, value) {
+    const base = slugify(value) || `imported-board-${c.ids.next().slice(0, 8)}`;
+    if (!(await c.store.boards.bySlug(base)))
+        return base;
+    for (let i = 2; i < 1000; i += 1) {
+        const candidate = `${base}-${i}`;
+        if (!(await c.store.boards.bySlug(candidate)))
+            return candidate;
+    }
+    return `${base}-${c.ids.next().slice(0, 8)}`;
+}
+/**
+ * Brings a board from an older Orbit (its folder read as an export, or its
+ * export): a new board with the board's own id and slug, every record with
+ * its own id, and no event of its own, so the board reads as it did there.
+ * Refused when this Orbit already has a board with that id or slug.
+ */
+export async function importKeepingBoard(c, raw, board) {
+    const snapshot = await readSnapshot(c, raw, board);
+    if ((await c.store.boards.get(board.id)) || (await c.store.boards.bySlug(board.slug)))
+        throw new OrbitError("board_slug_taken", { message: `This Orbit already has the board ${board.slug}.` });
+    const record = boardRecord(c, snapshot, board.id, board.slug, snapshot.board.name.trim() || board.slug);
+    const cross = await plannedCrossLinks(c, snapshot, board.id, false);
+    const row = await c.store.boards.create(record, async (w) => {
+        await writeRecords(w, c, snapshot, board.id);
+        for (const relation of cross.outgoing)
+            await w.crossBoardRelations.insert(relation);
+    });
+    const downloads = await writeImages(await onBoard(c, row), snapshot);
+    return { board: row, snapshot, downloads, crossDropped: cross.dropped };
+}
+/** What the browser preview of 1.x and 2.0 exported (and kept in its database): `starscape-orbit-preview`. */
+export const OLD_PREVIEW_FORMAT = "orbit.board.snapshot/v1";
+/**
+ * The old browser preview's board as an export: it kept the cards' labels
+ * beside them and a relation's type as `kind`. `raw` is its export, or its
+ * database's stores read whole.
+ */
+export function fromOldPreview(raw) {
+    const rows = (value) => (Array.isArray(value) ? value : []);
+    const byId = new Map(rows(raw.labels).map((label) => [label.id, label]));
+    const links = rows(raw.ticket_labels);
+    const tickets = rows(raw.tickets).map((ticket) => ({ ...ticket, labels: links.filter((link) => link.ticket_id === ticket.id).flatMap((link) => byId.get(link.label_id) ?? []) }));
+    const relations = rows(raw.relations).map((relation) => ({ ...relation, type: relation.type ?? relation.kind }));
+    return { ...raw, format: EXPORT_FORMAT, source_format: OLD_PREVIEW_FORMAT, tickets, relations };
+}
+/** Imports an export as a new board, under its own slug or the next free one. */
+export async function importAsNewBoard(c, input) {
+    const raw = rawOf(input);
+    const boardId = c.ids.next();
+    const snapshot = await readSnapshot(c, raw, { id: boardId, slug: "" });
+    const rawName = raw && typeof raw === "object" && "name" in raw ? raw.name : undefined;
+    const name = snapshot.board.name.trim() || asText(rawName ?? "").trim() || "Imported Board";
+    const slug = await freeSlug(c, input.slug || snapshot.board.slug || rawName || name);
+    const board = boardRecord(c, snapshot, boardId, slug, name);
+    const cross = await plannedCrossLinks(c, snapshot, boardId, false);
+    const row = await c.store.boards.create(board, async (w) => {
+        await writeRecords(w, c, snapshot, boardId);
+        for (const relation of cross.outgoing)
+            await w.crossBoardRelations.insert(relation);
+        await record(w, c, "board_imported", null, { board_id: boardId, replace_existing: false });
+    });
+    const downloads = await writeImages(await onBoard(c, row), snapshot);
+    c.changed(boardId);
+    return { ok: true, imported_board_id: boardId, imported_board_slug: slug, replace_existing: false, source_format: snapshot.source_format ?? EXPORT_FORMAT, imported_counts: counts(snapshot), images_kept_as_downloads: downloads, cross_board_links_dropped: cross.dropped, created_new_board: true };
+}

package/lib/core/states.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Lanes: making, renaming, reordering and deleting them. A lane's role ties it
+ * to the agent flow; the AI Ready lane keeps its name, since agents take work
+ * from it by name.
+ */
+import type { BoardCtx } from "./context.ts";
+import type { Id, State } from "./model.ts";
+export declare function createState(c: BoardCtx, input: {
+    name?: unknown;
+    role?: unknown;
+}): Promise<State>;
+export declare function updateState(c: BoardCtx, stateId: Id, input: {
+    name?: unknown;
+    is_default?: unknown;
+    role?: unknown;
+}): Promise<State>;
+/** Puts the lanes in this order; every lane of the board, each once. */
+export declare function reorderStates(c: BoardCtx, input: {
+    state_ids?: unknown;
+}): Promise<State[]>;
+/** Deletes an empty lane; the board keeps at least one, and a default. */
+export declare function deleteState(c: BoardCtx, stateId: Id): Promise<{
+    ok: true;
+    deleted_state_id: Id;
+}>;

package/lib/core/states.js

@@ -0,0 +1,126 @@
+/**
+ * Lanes: making, renaming, reordering and deleting them. A lane's role ties it
+ * to the agent flow; the AI Ready lane keeps its name, since agents take work
+ * from it by name.
+ */
+import { OrbitError } from "./errors.js";
+import { record } from "./history.js";
+import { laneNameOf, normalizeStateRole } from "./text.js";
+const AI_READY = "AI Ready";
+/** Takes a role from whichever other lane holds it: at most one lane per board plays each role. */
+async function freeRole(w, role, except) {
+    if (!role)
+        return;
+    for (const state of await w.states.list()) {
+        if (state.role === role && state.id !== except)
+            await w.states.update(state.id, { role: null });
+    }
+}
+export async function createState(c, input) {
+    const role = input.role !== undefined ? normalizeStateRole(input.role) : null;
+    let name;
+    if (role === "ai_ready") {
+        if (input.name && input.name !== AI_READY)
+            throw new OrbitError("ai_ready_lane_must_be_named_ai_ready");
+        name = AI_READY;
+    }
+    else {
+        name = laneNameOf(input.name);
+    }
+    const state = await c.data.write(async (w) => {
+        await freeRole(w, role, null);
+        const states = await w.states.list();
+        const top = states.reduce((max, s) => Math.max(max, s.position), 0);
+        const made = { id: c.ids.next(), board_id: c.board.id, name, position: top + 1, is_default: 0, role, created_at: c.clock.now() };
+        await w.states.insert(made);
+        await record(w, c, "state_created", null, { board_id: c.board.id, state_id: made.id, name, role });
+        return made;
+    });
+    c.changed(c.board.id);
+    return state;
+}
+export async function updateState(c, stateId, input) {
+    const state = await c.data.write(async (w) => {
+        const before = await w.states.get(stateId);
+        if (!before)
+            throw new OrbitError("state_not_found");
+        const patch = {};
+        if (input.name !== undefined) {
+            const name = laneNameOf(input.name);
+            if (before.role === "ai_ready" && name !== AI_READY)
+                throw new OrbitError("cannot_rename_ai_ready_lane");
+            patch.name = name;
+        }
+        if (input.is_default !== undefined) {
+            const isDefault = input.is_default ? 1 : 0;
+            if (isDefault) {
+                for (const other of await w.states.list()) {
+                    if (other.is_default)
+                        await w.states.update(other.id, { is_default: 0 });
+                }
+            }
+            patch.is_default = isDefault;
+        }
+        if (input.role !== undefined) {
+            const role = normalizeStateRole(input.role);
+            await freeRole(w, role, stateId);
+            if (role === "ai_ready") {
+                const finalName = input.name !== undefined ? laneNameOf(input.name) : before.name;
+                if (finalName !== AI_READY) {
+                    if (input.name !== undefined)
+                        throw new OrbitError("ai_ready_lane_must_be_named_ai_ready");
+                    patch.name = AI_READY;
+                }
+            }
+            patch.role = role;
+        }
+        if (!Object.keys(patch).length)
+            return before;
+        const after = await w.states.update(stateId, patch);
+        await record(w, c, "state_updated", null, { board_id: c.board.id, state_id: stateId, fields: Object.keys(input) });
+        return after;
+    });
+    c.changed(c.board.id);
+    return state;
+}
+/** Puts the lanes in this order; every lane of the board, each once. */
+export async function reorderStates(c, input) {
+    const ids = Array.isArray(input.state_ids) ? input.state_ids.map(String) : [];
+    const states = await c.data.write(async (w) => {
+        const existing = (await w.states.list()).map((state) => state.id);
+        if (ids.length !== existing.length || !existing.every((id) => ids.includes(id)))
+            throw new OrbitError("invalid_state_order");
+        for (const [position, id] of ids.entries())
+            await w.states.update(id, { position });
+        await record(w, c, "states_reordered", null, { board_id: c.board.id, state_ids: ids });
+        return w.states.list();
+    });
+    c.changed(c.board.id);
+    return states;
+}
+/** Deletes an empty lane; the board keeps at least one, and a default. */
+export async function deleteState(c, stateId) {
+    const answer = await c.data.write(async (w) => {
+        const states = await w.states.list();
+        const state = states.find((s) => s.id === stateId);
+        if (!state)
+            throw new OrbitError("state_not_found");
+        if ((await w.tickets.list({ state: stateId })).length)
+            throw new OrbitError("state_has_tickets");
+        if (states.length <= 1)
+            throw new OrbitError("cannot_delete_last_state");
+        await w.states.remove(stateId);
+        const rest = states.filter((s) => s.id !== stateId);
+        for (const [position, s] of rest.entries()) {
+            if (s.position !== position)
+                await w.states.update(s.id, { position });
+        }
+        const first = rest[0];
+        if (state.is_default && first)
+            await w.states.update(first.id, { is_default: 1 });
+        await record(w, c, "state_deleted", null, { board_id: c.board.id, state_id: stateId, name: state.name });
+        return { ok: true, deleted_state_id: stateId };
+    });
+    c.changed(c.board.id);
+    return answer;
+}

package/lib/core/text.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The small rules every use case shares for what people and agents send:
+ * names on one line, slugs, priorities and types read the way the API has
+ * always read them, each refusal with its error code.
+ */
+import type { EntryType, LaneRole, Priority, TicketType } from "./model.ts";
+/**
+ * What a field holds as text: a string as it is, a number or boolean written
+ * out, anything else (an object, null, nothing) as "". Input is never
+ * stringified as "[object Object]".
+ */
+export declare function asText(value: unknown): string;
+/** A board slug: lowercase letters, digits and single dashes, at most 80 characters. */
+export declare function slugify(value: unknown): string;
+/** True for a slug slugify leaves as it is. */
+export declare function isSlug(value: unknown): value is string;
+/** A name as one clean line: line breaks and control characters become spaces. */
+export declare function cleanName(value: unknown): string;
+/** A string with something in it, trimmed; otherwise `missing_<field>`. */
+export declare function requiredString(value: unknown, field: string): string;
+/** A lane's name: required, and one clean line. */
+export declare function laneNameOf(value: unknown): string;
+/** 0 to 4, rounded; anything unreadable is med (2). */
+export declare function normalizePriority(value: unknown): Priority;
+export declare function normalizeTicketType(value: unknown): TicketType;
+export declare function normalizeEntryType(value: unknown): EntryType;
+/** A lane's role in the agent flow, or null for none. */
+export declare function normalizeStateRole(value: unknown): LaneRole | null;
+/** `existing`, then a blank line, then `note`; just `existing` when the note is empty. */
+export declare function appendNote(existing: string, note: unknown): string;
+/** At most `max` characters; `max` 0 means no cap. */
+export declare function cap(value: unknown, max: number): string;
+/** A whole number above zero, else `fallback`. */
+export declare function positiveInt(value: unknown, fallback: number): number;
+/** A whole number from zero, else `fallback`. */
+export declare function nonNegativeInt(value: unknown, fallback: number): number;
+/** An optional string field, trimmed; "" when absent. */
+export declare function optionalString(value: unknown): string;
+/** A field that is a string when given, else "" (the API's `body.x || ""`). */
+export declare function textOr(value: unknown, fallback?: string): string;