@starlove/orbit 1.4.0 → 2.0.0

package/lib/core/sessions.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Agents' sessions on every board, for the quick menu (`GET /api/sessions`).
+ * Not part of the command language, so agents
+ * pay nothing for them.
+ *
+ * A session is one agent's run of writes on one board with no gap over 30
+ * minutes; its id is `board id:agent:first event id`, so dismissing it hides
+ * that run and not the agent. Its state comes from its last write:
+ * - waiting: an ask, or a finish into a review lane, while the card still sits
+ *   in the lane it moved to;
+ * - working: any other write in the last 5 minutes;
+ * - finished: anything else. A session shows until 2 hours after its last write.
+ * A person's writes (actor `local`) are never sessions; an agent that never
+ * said its name writes as `agent`. Events are read from each board, so writes
+ * from MCP and the CLI in other processes count.
+ */
+import type { Ctx } from "./context.ts";
+import type { AgentSession, OrbitEvent, RegisteredBoard, State } from "./model.ts";
+export declare const GAP_MS: number;
+export declare const WORKING_MS: number;
+export declare const SHOW_MS: number;
+/** "30m" or "2h" (at most 24h) in milliseconds; the default is 2 hours. */
+export declare function parseWindow(value: unknown): number;
+/** An event with its card's number, title and current lane, and an ask's question. */
+export interface SessionEvent extends OrbitEvent {
+    number: number | null;
+    title: string | null;
+    card_lane: string | null;
+    question: string | null;
+}
+/** The sessions on one board from its events, oldest first; runs whose last write is before `sinceMs` are left out. */
+export declare function sessionsFromEvents(events: readonly SessionEvent[], options: {
+    board: Pick<RegisteredBoard, "id" | "slug" | "name">;
+    lanes?: Pick<State, "name" | "role">[];
+    nowMs: number;
+    sinceMs: number;
+}): AgentSession[];
+/** Every board's sessions whose last write is within `since` (default 2h), with the window's start. */
+export declare function listSessions(c: Ctx, options?: {
+    since?: unknown;
+}): Promise<{
+    since: string;
+    sessions: AgentSession[];
+}>;

package/lib/core/sessions.js

@@ -0,0 +1,158 @@
+/**
+ * Agents' sessions on every board, for the quick menu (`GET /api/sessions`).
+ * Not part of the command language, so agents
+ * pay nothing for them.
+ *
+ * A session is one agent's run of writes on one board with no gap over 30
+ * minutes; its id is `board id:agent:first event id`, so dismissing it hides
+ * that run and not the agent. Its state comes from its last write:
+ * - waiting: an ask, or a finish into a review lane, while the card still sits
+ *   in the lane it moved to;
+ * - working: any other write in the last 5 minutes;
+ * - finished: anything else. A session shows until 2 hours after its last write.
+ * A person's writes (actor `local`) are never sessions; an agent that never
+ * said its name writes as `agent`. Events are read from each board, so writes
+ * from MCP and the CLI in other processes count.
+ */
+import { describeEvent } from "./describe.js";
+import { OrbitError } from "./errors.js";
+import { asText } from "./text.js";
+const MINUTE = 60_000;
+export const GAP_MS = 30 * MINUTE;
+export const WORKING_MS = 5 * MINUTE;
+export const SHOW_MS = 120 * MINUTE;
+/** How far before the window a run is read back, so a long run keeps its first id. */
+const LOOKBACK_MS = 24 * 60 * MINUTE;
+const MAX_WINDOW_MS = 24 * 60 * MINUTE;
+const PERSON = "local";
+const UNNAMED = "agent";
+const ORDER = { waiting: 0, working: 1, finished: 2 };
+/** "30m" or "2h" (at most 24h) in milliseconds; the default is 2 hours. */
+export function parseWindow(value) {
+    if (value === undefined || value === null || value === "")
+        return SHOW_MS;
+    const match = /^(\d{1,4})(m|h)$/.exec(asText(value).trim());
+    const ms = match ? Number(match[1]) * (match[2] === "h" ? 60 * MINUTE : MINUTE) : NaN;
+    if (!(ms > 0 && ms <= MAX_WINDOW_MS))
+        throw new OrbitError("invalid_since", { message: "since takes a time like 30m or 2h, up to 24h." });
+    return ms;
+}
+function bodyOf(json) {
+    try {
+        const body = JSON.parse(json || "{}");
+        return body && typeof body === "object" ? body : {};
+    }
+    catch {
+        return {};
+    }
+}
+function stateOf(last, roles, nowMs) {
+    const body = bodyOf(last.body_json);
+    const to = typeof body.to === "string" ? body.to : "";
+    const stillThere = Boolean(to) && last.card_lane === to;
+    if (last.type === "checkpoint_requested")
+        return stillThere ? ["waiting", "ask"] : ["finished", null];
+    if (last.type === "agent_completed")
+        return stillThere && roles.get(to) === "review" ? ["waiting", "review"] : ["finished", null];
+    return nowMs - Date.parse(last.created_at) <= WORKING_MS ? ["working", null] : ["finished", null];
+}
+/** The sessions on one board from its events, oldest first; runs whose last write is before `sinceMs` are left out. */
+export function sessionsFromEvents(events, options) {
+    const { board, nowMs, sinceMs } = options;
+    const roles = new Map((options.lanes ?? []).map((lane) => [lane.name, lane.role]));
+    const open = new Map();
+    const runs = [];
+    for (const event of events) {
+        if (!event.actor || event.actor === PERSON)
+            continue;
+        const time = Date.parse(event.created_at);
+        const run = open.get(event.actor);
+        if (run && time - run.lastMs <= GAP_MS) {
+            run.events.push(event);
+            run.lastMs = time;
+        }
+        else {
+            if (run)
+                runs.push(run);
+            open.set(event.actor, { actor: event.actor, events: [event], lastMs: time });
+        }
+    }
+    runs.push(...open.values());
+    const sessions = [];
+    for (const { actor, events: list, lastMs } of runs) {
+        const first = list[0];
+        const last = list[list.length - 1];
+        if (!first || !last || lastMs < sinceMs)
+            continue;
+        const [state, reason] = stateOf(last, roles, nowMs);
+        const withCard = [...list].reverse().find((event) => event.number !== null);
+        const card = withCard?.ticket_id && withCard.number !== null ? { id: withCard.ticket_id, number: withCard.number, title: withCard.title ?? "" } : null;
+        sessions.push({
+            id: `${board.id}:${actor}:${first.id}`,
+            board: { id: board.id, slug: board.slug, name: board.name },
+            agent: actor,
+            unnamed: actor === UNNAMED,
+            state,
+            reason,
+            what: describeEvent(last),
+            detail: reason === "ask" ? (last.question ?? "") : (card?.title ?? ""),
+            card,
+            started_at: first.created_at,
+            at: last.created_at,
+            writes: list.length
+        });
+    }
+    return sortSessions(sessions);
+}
+function sortSessions(sessions) {
+    return sessions.sort((a, b) => ORDER[a.state] - ORDER[b.state] || Date.parse(b.at) - Date.parse(a.at));
+}
+/** Every board's sessions whose last write is within `since` (default 2h), with the window's start. */
+export async function listSessions(c, options = {}) {
+    const windowMs = parseWindow(options.since);
+    const nowMs = Date.parse(c.clock.now());
+    const sinceMs = nowMs - windowMs;
+    const from = new Date(sinceMs - LOOKBACK_MS).toISOString();
+    const all = [];
+    for (const row of await c.store.boards.list()) {
+        try {
+            const data = await c.store.board(row.id);
+            const { events, lanes } = await data.read(async (r) => {
+                const raw = (await r.events.list({ since: from })).filter((event) => event.actor !== PERSON);
+                if (!raw.length)
+                    return { events: [], lanes: [] };
+                const ids = [...new Set(raw.map((event) => event.ticket_id).filter((id) => id !== null))];
+                const [states, tickets] = await Promise.all([r.states.list(), ids.length ? r.tickets.list({ ids }) : Promise.resolve([])]);
+                const byId = new Map(tickets.map((ticket) => [ticket.id, ticket]));
+                const laneName = new Map(states.map((state) => [state.id, state.name]));
+                const questions = new Map();
+                for (const event of raw) {
+                    if (event.type !== "checkpoint_requested" || !event.ticket_id)
+                        continue;
+                    const key = `${event.ticket_id}\n${event.actor}`;
+                    if (questions.has(key))
+                        continue;
+                    const asked = (await r.comments.list(event.ticket_id)).filter((comment) => comment.author === event.actor && comment.kind === "checkpoint");
+                    questions.set(key, asked[asked.length - 1]?.body ?? "");
+                }
+                const events = raw.map((event) => {
+                    const ticket = event.ticket_id ? byId.get(event.ticket_id) : undefined;
+                    return {
+                        ...event,
+                        number: ticket?.number ?? null,
+                        title: ticket?.title ?? null,
+                        card_lane: ticket ? (laneName.get(ticket.state_id) ?? null) : null,
+                        question: event.type === "checkpoint_requested" && event.ticket_id ? (questions.get(`${event.ticket_id}\n${event.actor}`) ?? null) : null
+                    };
+                });
+                return { events, lanes: states };
+            });
+            if (events.length)
+                all.push(...sessionsFromEvents(events, { board: row, lanes, nowMs, sinceMs }));
+        }
+        catch {
+            // One unreadable board never hides the others' sessions.
+        }
+    }
+    return { since: new Date(sinceMs).toISOString(), sessions: sortSessions(all) };
+}

package/lib/core/snapshot-schema.d.ts

@@ -0,0 +1,295 @@
+/**
+ * What an import may carry, checked with zod. Its own module so zod loads
+ * only when an import runs: the commands people run most never pay for it.
+ */
+import { z } from "zod";
+export declare const BoardIn: z.ZodObject<{
+    slug: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+    name: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+    repo_url: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+    default_branch: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+    project_notes: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+    agent_instructions: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+    ai_enabled: z.ZodOptional<z.ZodUnknown>;
+    created_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    updated_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+}, z.core.$loose>;
+export declare const SnapshotIn: z.ZodObject<{
+    format: z.ZodLiteral<"orbit-board-export">;
+    source_format: z.ZodOptional<z.ZodString>;
+    imported_counts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    board: z.ZodUnknown;
+    states: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodUnknown>;
+        position: z.ZodNumber;
+        is_default: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean]>>>, z.ZodTransform<0 | 1, number | boolean | null | undefined>>;
+        role: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        created_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    }, z.core.$loose>>>>, z.ZodTransform<{
+        [x: string]: unknown;
+        id: string;
+        position: number;
+        is_default: 0 | 1;
+        role: string | null;
+        created_at: string | null;
+        name?: unknown;
+    }[], {
+        [x: string]: unknown;
+        id: string;
+        position: number;
+        is_default: 0 | 1;
+        role: string | null;
+        created_at: string | null;
+        name?: unknown;
+    }[] | null | undefined>>;
+    labels: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        color: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        created_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    }, z.core.$loose>>>>, z.ZodTransform<{
+        [x: string]: unknown;
+        id: string;
+        name: string;
+        color: string | null;
+        created_at: string | null;
+    }[], {
+        [x: string]: unknown;
+        id: string;
+        name: string;
+        color: string | null;
+        created_at: string | null;
+    }[] | null | undefined>>;
+    tickets: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        number: z.ZodNumber;
+        title: z.ZodString;
+        description: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+        type: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        parent_ticket_id: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        ai_plan: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+        plan_artifact_path: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+        implementation_summary: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+        implementation_artifact_path: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+        implementation_updates: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+        nebula_url: z.ZodOptional<z.ZodUnknown>;
+        state_id: z.ZodString;
+        priority: z.ZodOptional<z.ZodUnknown>;
+        created_by: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        created_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        updated_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        archived_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        labels: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$loose>>>>;
+    }, z.core.$loose>>>>, z.ZodTransform<{
+        [x: string]: unknown;
+        id: string;
+        number: number;
+        title: string;
+        description: string;
+        type: string | null;
+        parent_ticket_id: string | null;
+        ai_plan: string;
+        plan_artifact_path: string;
+        implementation_summary: string;
+        implementation_artifact_path: string;
+        implementation_updates: string;
+        state_id: string;
+        created_by: string | null;
+        created_at: string | null;
+        updated_at: string | null;
+        archived_at: string | null;
+        nebula_url?: unknown;
+        priority?: unknown;
+        labels?: {
+            [x: string]: unknown;
+            id: string;
+        }[] | null | undefined;
+    }[], {
+        [x: string]: unknown;
+        id: string;
+        number: number;
+        title: string;
+        description: string;
+        type: string | null;
+        parent_ticket_id: string | null;
+        ai_plan: string;
+        plan_artifact_path: string;
+        implementation_summary: string;
+        implementation_artifact_path: string;
+        implementation_updates: string;
+        state_id: string;
+        created_by: string | null;
+        created_at: string | null;
+        updated_at: string | null;
+        archived_at: string | null;
+        nebula_url?: unknown;
+        priority?: unknown;
+        labels?: {
+            [x: string]: unknown;
+            id: string;
+        }[] | null | undefined;
+    }[] | null | undefined>>;
+    comments: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        ticket_id: z.ZodString;
+        author: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        kind: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        body: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+        omitted_for_ai: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean]>>>, z.ZodTransform<0 | 1, number | boolean | null | undefined>>;
+        created_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    }, z.core.$loose>>>>, z.ZodTransform<{
+        [x: string]: unknown;
+        id: string;
+        ticket_id: string;
+        author: string | null;
+        kind: string | null;
+        body: string;
+        omitted_for_ai: 0 | 1;
+        created_at: string | null;
+    }[], {
+        [x: string]: unknown;
+        id: string;
+        ticket_id: string;
+        author: string | null;
+        kind: string | null;
+        body: string;
+        omitted_for_ai: 0 | 1;
+        created_at: string | null;
+    }[] | null | undefined>>;
+    review_verdicts: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        ticket_id: z.ZodString;
+        verdict: z.ZodEnum<{
+            PASS: "PASS";
+            BLOCK: "BLOCK";
+            QUESTION: "QUESTION";
+        }>;
+        blocking_findings_json: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        optional_findings_json: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        evidence_commands_json: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        reviewer_profile: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+        reviewer_session_id: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+        reviewed_commit_sha: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+        dispatch_run_id: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+        supersedes_prior_review_id: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        created_by: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        created_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    }, z.core.$loose>>>>, z.ZodTransform<{
+        [x: string]: unknown;
+        id: string;
+        ticket_id: string;
+        verdict: "PASS" | "BLOCK" | "QUESTION";
+        blocking_findings_json: string | null;
+        optional_findings_json: string | null;
+        evidence_commands_json: string | null;
+        reviewer_profile: string;
+        reviewer_session_id: string;
+        reviewed_commit_sha: string;
+        dispatch_run_id: string;
+        supersedes_prior_review_id: string | null;
+        created_by: string | null;
+        created_at: string | null;
+    }[], {
+        [x: string]: unknown;
+        id: string;
+        ticket_id: string;
+        verdict: "PASS" | "BLOCK" | "QUESTION";
+        blocking_findings_json: string | null;
+        optional_findings_json: string | null;
+        evidence_commands_json: string | null;
+        reviewer_profile: string;
+        reviewer_session_id: string;
+        reviewed_commit_sha: string;
+        dispatch_run_id: string;
+        supersedes_prior_review_id: string | null;
+        created_by: string | null;
+        created_at: string | null;
+    }[] | null | undefined>>;
+    relations: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        source_ticket_id: z.ZodString;
+        target_ticket_id: z.ZodString;
+        type: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        created_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    }, z.core.$loose>>>>, z.ZodTransform<{
+        [x: string]: unknown;
+        id: string;
+        source_ticket_id: string;
+        target_ticket_id: string;
+        type: string | null;
+        created_at: string | null;
+    }[], {
+        [x: string]: unknown;
+        id: string;
+        source_ticket_id: string;
+        target_ticket_id: string;
+        type: string | null;
+        created_at: string | null;
+    }[] | null | undefined>>;
+    cross_board_relations: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>, z.ZodTransform<Record<string, unknown>[], Record<string, unknown>[] | null | undefined>>;
+    comments_hidden_from_ai_left_out: z.ZodOptional<z.ZodUnknown>;
+    attachments: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>, z.ZodTransform<Record<string, unknown>[], Record<string, unknown>[] | null | undefined>>;
+    board_entries: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodOptional<z.ZodUnknown>;
+        title: z.ZodOptional<z.ZodUnknown>;
+        body: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string, string | null | undefined>>;
+        ticket_id: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        created_by: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        created_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        updated_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        struck_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    }, z.core.$loose>>>>, z.ZodTransform<{
+        [x: string]: unknown;
+        id: string;
+        body: string;
+        ticket_id: string | null;
+        created_by: string | null;
+        created_at: string | null;
+        updated_at: string | null;
+        struck_at: string | null;
+        type?: unknown;
+        title?: unknown;
+    }[], {
+        [x: string]: unknown;
+        id: string;
+        body: string;
+        ticket_id: string | null;
+        created_by: string | null;
+        created_at: string | null;
+        updated_at: string | null;
+        struck_at: string | null;
+        type?: unknown;
+        title?: unknown;
+    }[] | null | undefined>>;
+    events: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        ticket_id: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        actor: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        type: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        body_json: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+        created_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    }, z.core.$loose>>>>, z.ZodTransform<{
+        [x: string]: unknown;
+        id: string;
+        ticket_id: string | null;
+        actor: string | null;
+        type: string | null;
+        body_json: string | null;
+        created_at: string | null;
+    }[], {
+        [x: string]: unknown;
+        id: string;
+        ticket_id: string | null;
+        actor: string | null;
+        type: string | null;
+        body_json: string | null;
+        created_at: string | null;
+    }[] | null | undefined>>;
+}, z.core.$loose>;
+export type Snapshot = z.infer<typeof SnapshotIn> & {
+    board: z.infer<typeof BoardIn>;
+};

package/lib/core/snapshot-schema.js

@@ -0,0 +1,82 @@
+/**
+ * What an import may carry, checked with zod. Its own module so zod loads
+ * only when an import runs: the commands people run most never pay for it.
+ */
+import { z } from "zod";
+import { EXPORT_FORMAT } from "./snapshots.js";
+// No compiled parsers: zod's probe for them runs `new Function`, which the
+// app page's script policy refuses (and reports) in the browser edition.
+// Imports are rare, so the interpreted parse costs nothing anyone sees.
+z.config({ jitless: true });
+// What an import may carry. Records are loose (an older export has more
+// fields, a hand-made one fewer); what Orbit needs to keep a record is checked.
+// zod 4 treats a bare z.unknown() key as required, so every key Orbit fills
+// in by itself when it's missing is marked optional.
+const text = z.string().nullish().transform((value) => value ?? "");
+const maybeText = z.string().nullish().transform((value) => value || null);
+const flag = z.union([z.number(), z.boolean()]).nullish().transform((value) => (value ? 1 : 0));
+const id = z.string().min(1);
+export const BoardIn = z.looseObject({ slug: text, name: text, repo_url: text, default_branch: text, project_notes: text, agent_instructions: text, ai_enabled: z.unknown().optional(), created_at: maybeText, updated_at: maybeText });
+const StateIn = z.looseObject({ id, name: z.unknown().optional(), position: z.number(), is_default: flag, role: maybeText, created_at: maybeText });
+const LabelIn = z.looseObject({ id, name: z.string(), color: maybeText, created_at: maybeText });
+const TicketIn = z.looseObject({
+    id,
+    number: z.number().int(),
+    title: z.string(),
+    description: text,
+    type: maybeText,
+    parent_ticket_id: maybeText,
+    ai_plan: text,
+    plan_artifact_path: text,
+    implementation_summary: text,
+    implementation_artifact_path: text,
+    implementation_updates: text,
+    nebula_url: z.unknown().optional(),
+    state_id: id,
+    priority: z.unknown().optional(),
+    created_by: maybeText,
+    created_at: maybeText,
+    updated_at: maybeText,
+    archived_at: maybeText,
+    labels: z.array(z.looseObject({ id })).nullish()
+});
+const CommentIn = z.looseObject({ id, ticket_id: id, author: maybeText, kind: maybeText, body: text, omitted_for_ai: flag, created_at: maybeText });
+const VerdictIn = z.looseObject({
+    id,
+    ticket_id: id,
+    verdict: z.enum(["PASS", "BLOCK", "QUESTION"]),
+    blocking_findings_json: maybeText,
+    optional_findings_json: maybeText,
+    evidence_commands_json: maybeText,
+    reviewer_profile: text,
+    reviewer_session_id: text,
+    reviewed_commit_sha: text,
+    dispatch_run_id: text,
+    supersedes_prior_review_id: maybeText,
+    created_by: maybeText,
+    created_at: maybeText
+});
+const RelationIn = z.looseObject({ id, source_ticket_id: id, target_ticket_id: id, type: maybeText, created_at: maybeText });
+const EntryIn = z.looseObject({ id, type: z.unknown().optional(), title: z.unknown().optional(), body: text, ticket_id: maybeText, created_by: maybeText, created_at: maybeText, updated_at: maybeText, struck_at: maybeText });
+const EventIn = z.looseObject({ id, ticket_id: maybeText, actor: maybeText, type: maybeText, body_json: maybeText, created_at: maybeText });
+const list = (item) => z.array(item).nullish().transform((value) => value ?? []);
+export const SnapshotIn = z.looseObject({
+    format: z.literal(EXPORT_FORMAT),
+    source_format: z.string().optional(),
+    imported_counts: z.record(z.string(), z.number()).optional(),
+    board: z.unknown(),
+    states: list(StateIn),
+    labels: list(LabelIn),
+    tickets: list(TicketIn),
+    comments: list(CommentIn),
+    review_verdicts: list(VerdictIn),
+    relations: list(RelationIn),
+    // Checked one by one where they're kept (snapshots.ts), so one odd link never stops a board.
+    cross_board_relations: list(z.record(z.string(), z.unknown())),
+    // An agent's export says how many comments hidden from AI it left out. Read as sent, never coerced:
+    // a replace from a file that has the key goes ahead only when it is exactly 0 (importReplacing).
+    comments_hidden_from_ai_left_out: z.unknown().optional(),
+    attachments: list(z.record(z.string(), z.unknown())),
+    board_entries: list(EntryIn),
+    events: list(EventIn)
+});

package/lib/core/snapshots.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 type { Snapshot } from "./snapshot-schema.ts";
+import type { BoardCtx, Ctx } from "./context.ts";
+import type { Id, RegisteredBoard } from "./model.ts";
+export declare const EXPORT_FORMAT = "orbit-board-export";
+/** 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 declare function keptLabelColor(value: unknown): string;
+export declare const EXPORT_VERSION = 9;
+/** Exports a board whole: every record, events included; images' bytes when asked. */
+export declare function exportBoard(c: BoardCtx, options?: {
+    includeAttachments?: boolean;
+}): Promise<Record<string, unknown>>;
+export interface ImportInput {
+    snapshot?: unknown;
+    replace_existing?: unknown;
+    create_new?: unknown;
+    slug?: unknown;
+    [field: string]: unknown;
+}
+export interface ImportResult {
+    ok: true;
+    imported_board_id: Id;
+    imported_board_slug: string;
+    replace_existing: boolean;
+    source_format: string;
+    imported_counts: Record<string, number>;
+    /** Images kept as files to download only: an SVG, or bytes that aren't an image type Orbit shows. */
+    images_kept_as_downloads: number;
+    /** Cross-board links the export carried that didn't come (see `plannedCrossLinks`). */
+    cross_board_links_dropped: number;
+    created_new_board?: true;
+}
+/**
+ * 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 declare function refuseAgentReplace(c: Ctx, input: ImportInput): void;
+/**
+ * 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 declare function importReplacing(c: BoardCtx, input: ImportInput): Promise<ImportResult>;
+/**
+ * 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 declare function importKeepingBoard(c: Ctx, raw: unknown, board: {
+    id: Id;
+    slug: string;
+}): Promise<{
+    board: RegisteredBoard;
+    snapshot: Snapshot;
+    downloads: number;
+    crossDropped: number;
+}>;
+/** What the browser preview of 1.x and 2.0 exported (and kept in its database): `starscape-orbit-preview`. */
+export declare 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 declare function fromOldPreview(raw: Record<string, unknown>): Record<string, unknown>;
+/** Imports an export as a new board, under its own slug or the next free one. */
+export declare function importAsNewBoard(c: Ctx, input: ImportInput): Promise<ImportResult>;