@starlove/orbit 1.4.0 → 2.0.0

package/lib/core/model.d.ts

@@ -0,0 +1,263 @@
+/**
+ * The records Orbit keeps, typed with the names the JSON API, the export
+ * format (`.orbit.json`) and the database already use: one name per field
+ * everywhere, snake_case, so nothing maps between layers.
+ *
+ * Each record is what storage holds, field for field, in the order answers list
+ * them. Flags are 0 or 1 and JSON columns stay strings, because answers and
+ * exports carry them that way. What the core derives for an answer (a card's
+ * lane name, its comment count) is built from these and is not stored.
+ *
+ * This file has no logic but the one helper every adapter needs to turn a
+ * stored event into the change it announces.
+ */
+/** A record's id: a UUID for anything Orbit made, any string an import brought. */
+export type Id = string;
+/** An instant as `Date.prototype.toISOString()` writes it (UTC, milliseconds). */
+export type Timestamp = string;
+/** A yes or no as storage and answers carry it. */
+export type Flag = 0 | 1;
+/** 0 to 4. People and agents read them as words: maybe, low, med, high, urgent. */
+export type Priority = 0 | 1 | 2 | 3 | 4;
+export type TicketType = "epic" | "feature" | "task" | "bug";
+/** What a lane does in the agent flow. At most one lane per board holds each role. */
+export type LaneRole = "ai_ready" | "in_progress" | "review" | "done";
+/** A journal entry's kind. */
+export type EntryType = "decision" | "lesson";
+export type Verdict = "PASS" | "BLOCK" | "QUESTION";
+/** A board's own record: what its settings hold. */
+export interface Board {
+    id: Id;
+    slug: string;
+    name: string;
+    repo_url: string;
+    default_branch: string;
+    project_notes: string;
+    agent_instructions: string;
+    ai_enabled: Flag;
+    created_at: Timestamp;
+    updated_at: Timestamp;
+}
+/**
+ * A board as the list of boards shows it. `db_path` says where the adapter
+ * keeps the board's data, for people to read (a file for SQLite); adapters
+ * without files leave it empty. Nothing parses it.
+ */
+export interface RegisteredBoard {
+    id: Id;
+    slug: string;
+    name: string;
+    db_path: string;
+    repo_url: string;
+    default_branch: string;
+    last_active_at: Timestamp | null;
+    created_at: Timestamp;
+    updated_at: Timestamp;
+}
+/** A lane. The code calls lanes states, as the API does. */
+export interface State {
+    id: Id;
+    board_id: Id;
+    name: string;
+    position: number;
+    is_default: Flag;
+    role: LaneRole | null;
+    created_at: Timestamp;
+}
+/** A card. The code calls cards tickets, as the API does. */
+export interface Ticket {
+    id: Id;
+    board_id: Id;
+    /** Unique on its board, assigned by storage when the card is made. */
+    number: number;
+    title: string;
+    description: string;
+    type: TicketType;
+    /** An epic on the same board. */
+    parent_ticket_id: Id | null;
+    ai_plan: string;
+    plan_artifact_path: string;
+    implementation_summary: string;
+    implementation_artifact_path: string;
+    implementation_updates: string;
+    /** A link to a Nebula file or folder, or ''. */
+    nebula_url: string;
+    state_id: Id;
+    priority: Priority;
+    /** The actor's name. */
+    created_by: string;
+    created_at: Timestamp;
+    /** Every change to the card moves it, a sub-card's change moves its epic's too. */
+    updated_at: Timestamp;
+    archived_at: Timestamp | null;
+}
+export interface Label {
+    id: Id;
+    board_id: Id;
+    /** Unique on its board. */
+    name: string;
+    color: string;
+    created_at: Timestamp;
+}
+export interface TicketLabel {
+    ticket_id: Id;
+    label_id: Id;
+}
+/**
+ * A comment on a card. `kind` is free text: Orbit writes human_comment,
+ * agent_note, checkpoint and completion, and an import may bring others.
+ */
+export interface Comment {
+    id: Id;
+    ticket_id: Id;
+    author: string;
+    kind: string;
+    body: string;
+    /** 1: hidden from agents. Kept out of everything an agent can read or search. */
+    omitted_for_ai: Flag;
+    created_at: Timestamp;
+}
+/**
+ * A link between two cards on one board. Orbit writes blocks, blocked_by and
+ * relates_to; the JSON API stores any type it is sent.
+ */
+export interface Relation {
+    id: Id;
+    source_ticket_id: Id;
+    target_ticket_id: Id;
+    type: string;
+    created_at: Timestamp;
+}
+/**
+ * A link from a card on this board to a card on another board of the same
+ * Orbit. It lives on the source card's board and names the target by board
+ * and id; nothing on the target's board changes. Whether a cross-board blocker
+ * still blocks is read from the target card when asked, so nothing has to
+ * clean it up when that card is done.
+ */
+export interface CrossBoardRelation {
+    id: Id;
+    source_ticket_id: Id;
+    target_board_id: Id;
+    target_ticket_id: Id;
+    type: "blocked_by" | "relates_to";
+    created_at: Timestamp;
+}
+/** A journal entry: a decision or a lesson, optionally about a card. A struck entry stays, out of agents' context, until a person deletes it. */
+export interface BoardEntry {
+    id: Id;
+    board_id: Id;
+    type: EntryType;
+    title: string;
+    body: string;
+    ticket_id: Id | null;
+    created_by: string;
+    created_at: Timestamp;
+    updated_at: Timestamp;
+    struck_at: Timestamp | null;
+}
+/** A reviewer's verdict on a card. The `_json` fields hold JSON arrays as text. */
+export interface ReviewVerdict {
+    id: Id;
+    ticket_id: Id;
+    verdict: Verdict;
+    blocking_findings_json: string;
+    optional_findings_json: string;
+    evidence_commands_json: string;
+    reviewer_profile: string;
+    reviewer_session_id: string;
+    reviewed_commit_sha: string;
+    dispatch_run_id: string;
+    supersedes_prior_review_id: Id | null;
+    created_by: string;
+    created_at: Timestamp;
+}
+/** An image on a card. Its bytes are in the BlobStore at `attachments/<stored_path>`. */
+export interface Attachment {
+    id: Id;
+    ticket_id: Id;
+    board_id: Id;
+    original_name: string;
+    /** Relative to the board's attachments, POSIX-style: tickets/<ticket id>/<attachment id>.png */
+    stored_path: string;
+    mime_type: string;
+    size_bytes: number;
+    sha256: string;
+    created_by: string;
+    created_at: Timestamp;
+}
+/** What Orbit records as it changes a board. Imports may bring other types. */
+export type EventType = "board_created" | "board_updated" | "board_imported" | "board_entry_created" | "board_entry_struck" | "board_entry_restored" | "board_entry_deleted" | "state_created" | "state_updated" | "states_reordered" | "state_deleted" | "ticket_created" | "ticket_updated" | "state_changed" | "ticket_archived" | "ticket_restored" | "ticket_deleted" | "comment_created" | "comment_ai_omission_changed" | "relation_created" | "relation_deleted" | "attachment_created" | "attachment_deleted" | "review_verdict_created" | "agent_claimed" | "checkpoint_requested" | "agent_completed";
+/**
+ * One entry in a board's history. `body_json` is the event's data as JSON
+ * text. Every write that changes a board appends at least one, and the live
+ * stream, an agent's `changes` and the quick menu's sessions are read from
+ * them.
+ */
+export interface OrbitEvent {
+    id: Id;
+    ticket_id: Id | null;
+    /** The actor's name. */
+    actor: string;
+    type: EventType | (string & {});
+    body_json: string;
+    created_at: Timestamp;
+}
+/**
+ * A committed change, as `BoardStore.watch()` and the live event stream
+ * (`GET /api/events/stream`) announce it: the event, with its board and its
+ * data parsed.
+ */
+export interface BoardChange {
+    id: Id;
+    type: OrbitEvent["type"];
+    ticket_id: Id | null;
+    board_id: Id;
+    actor: string;
+    data: Record<string, unknown>;
+    timestamp: Timestamp;
+}
+/** The change a stored event announces. Unreadable data announces as `{}`. */
+export declare function changeOf(boardId: Id, event: OrbitEvent): BoardChange;
+/**
+ * Who is acting. Orbit has no accounts: a person at the computer is `local`,
+ * and an agent is named by `ORBIT_AGENT_NAME` or the `x-orbit-agent-name`
+ * header. Hosts that add accounts resolve their own actor here.
+ */
+export interface Actor {
+    id: string;
+    name: string;
+    type: "human" | "agent";
+    role: string;
+    permissions: string[];
+    /** Board slugs the actor may open; ["*"] for all. */
+    boards: string[];
+}
+/**
+ * An agent's run of writes on one board, for the quick menu (`GET
+ * /api/sessions`). Derived from events; never stored.
+ */
+export interface AgentSession {
+    /** `<board id>:<agent>:<first event id>` */
+    id: string;
+    board: {
+        id: Id;
+        slug: string;
+        name: string;
+    };
+    agent: string;
+    /** True when the agent never said its name. */
+    unnamed: boolean;
+    state: "waiting" | "working" | "finished";
+    reason: "ask" | "review" | null;
+    what: string;
+    detail: string;
+    card: {
+        id: Id;
+        number: number;
+        title: string;
+    } | null;
+    started_at: Timestamp;
+    at: Timestamp;
+    writes: number;
+}

package/lib/core/model.js

@@ -0,0 +1,34 @@
+/**
+ * The records Orbit keeps, typed with the names the JSON API, the export
+ * format (`.orbit.json`) and the database already use: one name per field
+ * everywhere, snake_case, so nothing maps between layers.
+ *
+ * Each record is what storage holds, field for field, in the order answers list
+ * them. Flags are 0 or 1 and JSON columns stay strings, because answers and
+ * exports carry them that way. What the core derives for an answer (a card's
+ * lane name, its comment count) is built from these and is not stored.
+ *
+ * This file has no logic but the one helper every adapter needs to turn a
+ * stored event into the change it announces.
+ */
+/** The change a stored event announces. Unreadable data announces as `{}`. */
+export function changeOf(boardId, event) {
+    return {
+        id: event.id,
+        type: event.type,
+        ticket_id: event.ticket_id,
+        board_id: boardId,
+        actor: event.actor,
+        data: parseData(event.body_json),
+        timestamp: event.created_at
+    };
+}
+function parseData(json) {
+    try {
+        const value = JSON.parse(json || "{}");
+        return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+    }
+    catch {
+        return {};
+    }
+}

package/lib/core/nebula-link.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A card's optional link to a Nebula file or folder. Orbit keeps the address
+ * people paste when it is a plain web link: http or https, no user name or
+ * password, no spaces or control characters, at most 2,048 characters. Any
+ * host is allowed, since a Nebula can live on your own server or tailnet as
+ * well as at nebula.starscape.app. An empty value clears the link.
+ *
+ * The web app imports it from here (web/src/card/).
+ */
+export declare const NEBULA_URL_MAX = 2048;
+/** The normalized link, "" for none, or null when Orbit wouldn't keep it. */
+export declare function parseNebulaUrl(value: unknown): string | null;
+/** The link to store ("" clears it), or `invalid_nebula_url`. */
+export declare function normalizeNebulaUrl(value: unknown): string;

package/lib/core/nebula-link.js

@@ -0,0 +1,39 @@
+/**
+ * A card's optional link to a Nebula file or folder. Orbit keeps the address
+ * people paste when it is a plain web link: http or https, no user name or
+ * password, no spaces or control characters, at most 2,048 characters. Any
+ * host is allowed, since a Nebula can live on your own server or tailnet as
+ * well as at nebula.starscape.app. An empty value clears the link.
+ *
+ * The web app imports it from here (web/src/card/).
+ */
+import { OrbitError } from "./errors.js";
+import { asText } from "./text.js";
+export const NEBULA_URL_MAX = 2048;
+/** The normalized link, "" for none, or null when Orbit wouldn't keep it. */
+export function parseNebulaUrl(value) {
+    const text = asText(value ?? "").trim();
+    if (!text)
+        return "";
+    if (text.length > NEBULA_URL_MAX || /[\s\u0000-\u001f\u007f]/.test(text))
+        return null;
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        return null;
+    if (url.username || url.password || !url.hostname)
+        return null;
+    return url.href.length > NEBULA_URL_MAX ? null : url.href;
+}
+/** The link to store ("" clears it), or `invalid_nebula_url`. */
+export function normalizeNebulaUrl(value) {
+    const kept = parseNebulaUrl(value);
+    if (kept === null)
+        throw new OrbitError("invalid_nebula_url");
+    return kept;
+}

package/lib/core/relations.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Links between cards on one board: blocks, blocked_by and relates_to. An
+ * epic and its sub-cards are linked by the sub-card's `parent_ticket_id`,
+ * which answers show as read-only `child_of` and `parent_of` entries.
+ */
+import type { BoardCtx } from "./context.ts";
+import type { CrossCard, CrossLink } from "./cross-board.ts";
+import type { Id, Relation } from "./model.ts";
+/** The relation types Orbit keeps. */
+export declare const RELATION_TYPES: readonly ["blocks", "blocked_by", "relates_to"];
+export declare function createRelation(c: BoardCtx, input: {
+    source_ticket_id?: unknown;
+    target_ticket_id?: unknown;
+    type?: unknown;
+}): Promise<Relation>;
+export declare function deleteRelation(c: BoardCtx, relationId: Id): Promise<{
+    ok: true;
+}>;
+/** The other card of a link, as a card's relations and blockers name it. */
+export interface LinkedCard {
+    id: Id;
+    number: number;
+    title: string;
+    type: string;
+    state_id: Id;
+    state_name: string;
+    state_role: string | null;
+    parent_ticket_id: Id | null;
+}
+/** One link as a card's relations list it. */
+export interface RelationLine {
+    id: Id | null;
+    type: string;
+    direction: string;
+    source: "relation" | "hierarchy";
+    other_ticket: LinkedCard;
+}
+/** Every link touching a card: its relations, then its epic (`child_of`) and its open sub-cards (`parent_of`). */
+export declare function ticketRelations(c: BoardCtx, ticketId: Id): Promise<TicketRelations>;
+/** A card's links: its relations, its epic and its open sub-cards, and its links to cards on other boards. */
+export interface TicketRelations {
+    ticket_id: Id;
+    relations: RelationLine[];
+    cross_board: CrossLink[];
+}
+/** A card still blocking another; `via_epic_id` when it blocks the card's epic rather than the card. */
+export type Blocker = Omit<LinkedCard, "parent_ticket_id"> & {
+    via_epic_id: Id | null;
+};
+/** What still blocks a card, on its board and on others, and whether it can start. */
+export interface TicketBlockers {
+    ticket_id: Id;
+    can_start: boolean;
+    blockers: Blocker[];
+    waiting_on: CrossCard[];
+}
+/** What still blocks a card, and whether it can start. */
+export declare function ticketBlockers(c: BoardCtx, ticketId: Id): Promise<TicketBlockers>;

package/lib/core/relations.js

@@ -0,0 +1,112 @@
+/**
+ * Links between cards on one board: blocks, blocked_by and relates_to. An
+ * epic and its sub-cards are linked by the sub-card's `parent_ticket_id`,
+ * which answers show as read-only `child_of` and `parent_of` entries.
+ */
+import { crossBlockersFor, crossLinks } from "./cross-board.js";
+import { OrbitError } from "./errors.js";
+import { record } from "./history.js";
+import { ticketOn } from "./tickets.js";
+import { requiredString } from "./text.js";
+import { Lanes, laned, relationRows, ticketView, unresolvedBlockers } from "./views.js";
+/** The relation types Orbit keeps. */
+export const RELATION_TYPES = ["blocks", "blocked_by", "relates_to"];
+export async function createRelation(c, input) {
+    const sourceId = requiredString(input.source_ticket_id, "source_ticket_id");
+    const relation = await c.data.write(async (w) => {
+        const source = await ticketOn(w, sourceId);
+        // A relation lives on one board; a card on another board is no card here.
+        const target = await ticketOn(w, requiredString(input.target_ticket_id, "target_ticket_id"));
+        if (source.id === target.id)
+            throw new OrbitError("relation_self");
+        if (source.parent_ticket_id === target.id || target.parent_ticket_id === source.id)
+            throw new OrbitError("relation_redundant_with_parent");
+        const type = typeof input.type === "string" && input.type ? input.type : "relates_to";
+        // Epics and sub-cards are linked by parent_ticket_id, not by relations.
+        if (type === "child_of" || type === "parent_of")
+            throw new OrbitError("hierarchy_uses_parent_ticket_id");
+        if (!RELATION_TYPES.includes(type))
+            throw new OrbitError("invalid_relation_type");
+        const lanes = await Lanes.of(w);
+        // A blocker already done would block nothing.
+        if (type === "blocked_by" && lanes.roleOf(target) === "done")
+            throw new OrbitError("blocker_target_already_done");
+        if (type === "blocks" && lanes.roleOf(source) === "done")
+            throw new OrbitError("blocker_source_already_done");
+        if ((await w.relations.list(source.id)).some((r) => r.source_ticket_id === source.id && r.target_ticket_id === target.id && r.type === type)) {
+            throw new OrbitError("relation_exists");
+        }
+        const made = { id: c.ids.next(), source_ticket_id: source.id, target_ticket_id: target.id, type, created_at: c.clock.now() };
+        await w.relations.insert(made);
+        await record(w, c, "relation_created", source.id, { target_ticket_id: target.id, type });
+        return made;
+    });
+    c.changed(c.board.id);
+    return relation;
+}
+export async function deleteRelation(c, relationId) {
+    await c.data.write(async (w) => {
+        const relation = await w.relations.get(relationId);
+        if (!relation)
+            throw new OrbitError("relation_not_found");
+        await w.relations.remove(relationId);
+        await record(w, c, "relation_deleted", relation.source_ticket_id, { target_ticket_id: relation.target_ticket_id, type: relation.type });
+    });
+    c.changed(c.board.id);
+    return { ok: true };
+}
+function linkedCard(other) {
+    return {
+        id: other.id,
+        number: other.number,
+        title: other.title,
+        type: other.type,
+        state_id: other.state_id,
+        state_name: other.state_name,
+        state_role: other.state_role,
+        parent_ticket_id: other.parent_ticket_id
+    };
+}
+/** Every link touching a card: its relations, then its epic (`child_of`) and its open sub-cards (`parent_of`). */
+export async function ticketRelations(c, ticketId) {
+    const found = await c.data.read(async (r) => {
+        const ticket = await ticketOn(r, ticketId);
+        const lanes = await Lanes.of(r);
+        const relations = (await relationRows(r, ticketId, lanes, c.board)).map((row) => ({
+            id: row.id,
+            type: row.type,
+            direction: row.direction,
+            source: "relation",
+            other_ticket: linkedCard(row.other_ticket)
+        }));
+        if (ticket.parent_ticket_id) {
+            const parent = await r.tickets.get(ticket.parent_ticket_id);
+            if (parent && !parent.archived_at)
+                relations.push({ id: null, type: "child_of", direction: "outgoing", source: "hierarchy", other_ticket: linkedCard(ticketView(parent, lanes, c.board)) });
+        }
+        for (const child of await r.tickets.list({ parent: ticketId, archived: false })) {
+            relations.push({ id: null, type: "parent_of", direction: "outgoing", source: "hierarchy", other_ticket: linkedCard(laned(child, lanes)) });
+        }
+        return { ticket_id: ticket.id, relations };
+    });
+    // Read after this board's own read: links across boards read the other boards.
+    return { ...found, cross_board: await crossLinks(c, ticketId) };
+}
+/** What still blocks a card, and whether it can start. */
+export async function ticketBlockers(c, ticketId) {
+    return c.data.read(async (r) => {
+        const ticket = await ticketOn(r, ticketId);
+        const blockers = (await unresolvedBlockers(r, ticketId, await Lanes.of(r))).map((row) => ({
+            id: row.id,
+            number: row.number,
+            title: row.title,
+            type: row.type,
+            state_id: row.state_id,
+            state_name: row.state_name,
+            state_role: row.state_role,
+            via_epic_id: row.via_epic_id ?? null
+        }));
+        const waiting = await crossBlockersFor(c, r, ticket.id);
+        return { ticket_id: ticket.id, can_start: blockers.length === 0 && waiting.length === 0, blockers, waiting_on: waiting };
+    });
+}

package/lib/core/search.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Search on one board: open cards whose text, plan, summary, revisions or
+ * agent-readable comments match, best first. A query that is a card number
+ * (`12`, `#12`) puts that card first.
+ */
+import type { BoardCtx } from "./context.ts";
+import type { Id, Label, Ticket } from "./model.ts";
+export interface SearchInput {
+    q?: unknown;
+    limit?: unknown;
+    mode?: unknown;
+    include_full?: unknown;
+    fields?: unknown;
+    max_chars_per_field?: unknown;
+}
+export type SearchMode = "ids" | "summary" | "full";
+/**
+ * One hit. Which fields it has depends on the mode: `ids` gives ticket_id,
+ * id, number and rank; `summary` (the default) adds title, state_name,
+ * state_role, type, priority, parent_ticket_id, a snippet and the labels'
+ * names; `full` gives the card's own fields, state_name, state_role,
+ * board_slug, rank and the labels as records. With `fields`, only those named.
+ */
+export type SearchHit = Partial<Ticket> & {
+    ticket_id?: Id;
+    rank?: number;
+    state_name?: string;
+    state_role?: string | null;
+    board_slug?: string;
+    snippet?: string;
+    labels?: string[] | Label[];
+};
+export interface SearchAnswer {
+    query: string;
+    mode: SearchMode;
+    results: SearchHit[];
+}
+export declare function searchTickets(c: BoardCtx, input: SearchInput): Promise<SearchAnswer>;

package/lib/core/search.js

@@ -0,0 +1,92 @@
+/**
+ * Search on one board: open cards whose text, plan, summary, revisions or
+ * agent-readable comments match, best first. A query that is a card number
+ * (`12`, `#12`) puts that card first.
+ */
+import { cap, positiveInt, asText } from "./text.js";
+import { Lanes, labelsByTicket } from "./views.js";
+function modeOf(input) {
+    if (input.include_full === true)
+        return "full";
+    const mode = asText(input.mode ?? "summary").trim().toLowerCase();
+    return mode === "ids" || mode === "full" ? mode : "summary";
+}
+function fieldsOf(fields) {
+    if (Array.isArray(fields))
+        return new Set(fields.map(String));
+    if (typeof fields === "string" && fields.trim())
+        return new Set(fields.split(",").map((field) => field.trim()).filter(Boolean));
+    return null;
+}
+function pick(row, fields) {
+    if (!fields)
+        return row;
+    const picked = {};
+    for (const field of fields)
+        if (Object.hasOwn(row, field))
+            Object.assign(picked, { [field]: row[field] });
+    return picked;
+}
+function numberQuery(q) {
+    const match = /^#?(\d+)$/.exec(q.trim());
+    if (!match)
+        return null;
+    const number = Number(match[1]);
+    return Number.isSafeInteger(number) ? number : null;
+}
+export async function searchTickets(c, input) {
+    const q = asText(input.q ?? "").trim();
+    const limit = Math.min(Number(input.limit || 20), 50);
+    const mode = modeOf(input);
+    const maxChars = positiveInt(input.max_chars_per_field, 0);
+    const fields = fieldsOf(input.fields);
+    if (!q)
+        return { query: q, mode, results: [] };
+    const { hits, labels } = await c.data.read(async (r) => {
+        const number = numberQuery(q);
+        const ranked = new Map();
+        if (number !== null) {
+            const ticket = await r.tickets.byNumber(number);
+            if (ticket && !ticket.archived_at)
+                ranked.set(ticket.id, -1);
+        }
+        for (const hit of await r.search.query(q, { limit }))
+            if (!ranked.has(hit.ticket_id))
+                ranked.set(hit.ticket_id, hit.rank);
+        const ids = [...ranked.keys()];
+        if (!ids.length)
+            return { hits: [], labels: new Map() };
+        const [lanes, tickets] = await Promise.all([Lanes.of(r), r.tickets.list({ ids, archived: false })]);
+        const found = tickets.map((ticket) => ({ ...ticket, state_name: lanes.nameOf(ticket), state_role: lanes.roleOf(ticket), board_slug: c.board.slug, rank: ranked.get(ticket.id) ?? 0 }));
+        found.sort((a, b) => a.rank - b.rank || b.updated_at.localeCompare(a.updated_at) || a.id.localeCompare(b.id));
+        const top = found.slice(0, limit);
+        return { hits: top, labels: await labelsByTicket(r, top.map((hit) => hit.id)) };
+    });
+    const results = hits.map((hit) => {
+        const cardLabels = labels.get(hit.id) ?? [];
+        if (mode === "ids")
+            return pick({ ticket_id: hit.id, id: hit.id, number: hit.number, rank: hit.rank }, fields);
+        if (mode === "full") {
+            const full = { ...hit, labels: cardLabels };
+            if (maxChars)
+                for (const key of ["description", "ai_plan", "implementation_summary", "implementation_updates"])
+                    full[key] = cap(full[key], maxChars);
+            return pick(full, fields);
+        }
+        return pick({
+            ticket_id: hit.id,
+            id: hit.id,
+            number: hit.number,
+            title: hit.title,
+            state_name: hit.state_name,
+            state_role: hit.state_role,
+            type: hit.type,
+            priority: hit.priority,
+            parent_ticket_id: hit.parent_ticket_id,
+            rank: hit.rank,
+            snippet: cap(hit.description || hit.ai_plan || hit.implementation_summary || "", maxChars || 240),
+            labels: cardLabels.map((label) => label.name)
+        }, fields);
+    });
+    return { query: q, mode, results };
+}