@starlove/orbit 1.4.1 → 2.0.0

package/lib/core/trello.js

@@ -0,0 +1,269 @@
+/**
+ * Trello's board export, read as an Orbit export: lists become lanes (roles
+ * guessed from their names), cards become cards with their checklists,
+ * links and due dates in the description, labels and comments come along.
+ * Pure: it only reshapes the data it is given.
+ */
+import { slugify } from "./text.js";
+const isRaw = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const rawList = (value) => (Array.isArray(value) ? value.filter(isRaw) : []);
+const text = (value) => (typeof value === "string" || typeof value === "number" ? String(value) : "").replace(/\r\n/g, "\n").trim();
+export function looksLikeTrello(value) {
+    return isRaw(value) && Array.isArray(value.cards) && Array.isArray(value.lists) && (typeof value.id === "string" || typeof value.name === "string");
+}
+const LABEL_COLORS = {
+    green: "#61bd4f",
+    yellow: "#f2d600",
+    orange: "#ff9f1a",
+    red: "#eb5a46",
+    purple: "#c377e0",
+    blue: "#0079bf",
+    sky: "#00c2e0",
+    lime: "#51e898",
+    pink: "#ff78cb",
+    black: "#344563"
+};
+function byPosition(a, b) {
+    const pa = Number(a.pos ?? Number.MAX_SAFE_INTEGER);
+    const pb = Number(b.pos ?? Number.MAX_SAFE_INTEGER);
+    if (pa !== pb)
+        return pa - pb;
+    return text(a.id).localeCompare(text(b.id));
+}
+function dateFromObjectId(value) {
+    const id = text(value);
+    if (!/^[0-9a-fA-F]{8}/.test(id))
+        return null;
+    const seconds = Number.parseInt(id.slice(0, 8), 16);
+    return Number.isFinite(seconds) ? new Date(seconds * 1000).toISOString() : null;
+}
+function scopedId(ids, prefix, value) {
+    return `trello-${prefix}-${(text(value) || ids.next()).replace(/[^a-zA-Z0-9_-]/g, "-")}`;
+}
+function inferRole(name) {
+    const normalized = text(name).toLowerCase();
+    if (!normalized)
+        return null;
+    if (/^ai ready$|ai[- ]ready/.test(normalized))
+        return "ai_ready";
+    if (/review|qa|verify|validation/.test(normalized))
+        return "review";
+    if (/doing|in progress|active|working|wip/.test(normalized))
+        return "in_progress";
+    if (/done|complete|completed|shipped|closed/.test(normalized))
+        return "done";
+    return null;
+}
+function labelName(label, names) {
+    const explicit = text(label.name);
+    if (explicit)
+        return explicit;
+    const color = text(label.color);
+    const named = color && isRaw(names) ? text(names[color]) : "";
+    if (named)
+        return named;
+    return color ? `Trello ${color}` : "";
+}
+function priorityOf(card) {
+    const names = rawList(card.labels).map((label) => text(label.name || label.color).toLowerCase()).join(" ");
+    if (/urgent|critical|blocker|high|red/.test(names))
+        return 4;
+    if (/low|someday|backlog/.test(names))
+        return 1;
+    return 2;
+}
+function checklistsText(checklists) {
+    return checklists
+        .map((checklist) => {
+        const items = rawList(checklist.checkItems).sort(byPosition);
+        if (!items.length)
+            return "";
+        return [`Checklist: ${text(checklist.name) || "Untitled"}`, ...items.map((item) => `- [${item.state === "complete" ? "x" : " "}] ${text(item.name) || "Untitled item"}`)].join("\n");
+    })
+        .filter(Boolean)
+        .join("\n\n");
+}
+function attachmentsText(attachments) {
+    const lines = attachments.map((attachment) => {
+        const name = text(attachment.name) || text(attachment.fileName) || "Attachment";
+        const url = text(attachment.url);
+        return url ? `- ${name}: ${url}` : `- ${name}`;
+    });
+    return lines.length ? ["Trello attachments:", ...lines].join("\n") : "";
+}
+function description(card, listName, checklists) {
+    const parts = [];
+    const desc = text(card.desc);
+    if (desc)
+        parts.push(desc);
+    const meta = [];
+    if (card.idShort)
+        meta.push(`Trello card #${text(card.idShort)}`);
+    if (listName)
+        meta.push(`List: ${listName}`);
+    if (card.shortUrl || card.url)
+        meta.push(`URL: ${text(card.shortUrl || card.url)}`);
+    if (card.due)
+        meta.push(`Due: ${text(card.due)}${card.dueComplete ? " (complete)" : ""}`);
+    if (card.closed)
+        meta.push("Archived in Trello: yes");
+    if (meta.length)
+        parts.push(["Imported from Trello:", ...meta.map((line) => `- ${line}`)].join("\n"));
+    const checks = checklistsText(checklists);
+    if (checks)
+        parts.push(checks);
+    const files = attachmentsText(rawList(card.attachments));
+    if (files)
+        parts.push(files);
+    return parts.join("\n\n");
+}
+/** A Trello export as an Orbit export, for the board `target` names (or one named from Trello's). */
+export function trelloToSnapshot(trello, target, clock, ids) {
+    const time = clock.now();
+    const boardName = text(trello.name) || "Imported Trello Board";
+    const boardSlug = target.slug || slugify(boardName) || `trello-${ids.next().slice(0, 8)}`;
+    const labels = new Map();
+    const addLabel = (raw) => {
+        const key = text(raw.id) || `${text(raw.color) || "label"}-${text(raw.name)}`;
+        const name = labelName(raw, trello.labelNames);
+        if (!name || labels.has(key))
+            return;
+        labels.set(key, { id: scopedId(ids, "label", key), name, color: LABEL_COLORS[text(raw.color).toLowerCase()] ?? "#64748b", created_at: dateFromObjectId(raw.id) ?? time });
+    };
+    for (const label of rawList(trello.labels))
+        addLabel(label);
+    for (const card of rawList(trello.cards))
+        for (const label of rawList(card.labels))
+            addLabel(label);
+    const checklists = new Map();
+    const addChecklist = (cardId, checklist) => {
+        if (!cardId)
+            return;
+        checklists.set(cardId, [...(checklists.get(cardId) ?? []), checklist]);
+    };
+    for (const checklist of rawList(trello.checklists))
+        addChecklist(text(checklist.idCard), checklist);
+    for (const card of rawList(trello.cards))
+        for (const checklist of rawList(card.checklists))
+            addChecklist(text(card.id), checklist);
+    const commentsByCard = new Map();
+    for (const action of rawList(trello.actions)) {
+        if (action.type !== "commentCard")
+            continue;
+        const data = isRaw(action.data) ? action.data : {};
+        const cardId = isRaw(data.card) ? text(data.card.id) : "";
+        if (!cardId)
+            continue;
+        commentsByCard.set(cardId, [...(commentsByCard.get(cardId) ?? []), action]);
+    }
+    for (const actions of commentsByCard.values())
+        actions.sort((a, b) => text(a.date).localeCompare(text(b.date)));
+    const lists = rawList(trello.lists).sort(byPosition);
+    const rolesSeen = new Set();
+    const firstOpen = lists.findIndex((list) => !list.closed);
+    const defaultIndex = firstOpen >= 0 ? firstOpen : 0;
+    const states = lists.map((list, index) => {
+        let role = inferRole(list.name);
+        if (role && rolesSeen.has(role))
+            role = null;
+        if (role)
+            rolesSeen.add(role);
+        return {
+            id: scopedId(ids, "list", list.id || `${index + 1}`),
+            name: text(list.name) || `Trello List ${index + 1}`,
+            position: index,
+            is_default: index === defaultIndex ? 1 : 0,
+            role,
+            created_at: dateFromObjectId(list.id) ?? time
+        };
+    });
+    const fallbackState = states[0]?.id;
+    const stateOfList = new Map(lists.map((list, index) => [text(list.id), states[index]?.id ?? fallbackState]));
+    const tickets = [];
+    const comments = [];
+    rawList(trello.cards)
+        .sort(byPosition)
+        .forEach((card, index) => {
+        const cardId = text(card.id);
+        const ticketId = scopedId(ids, "card", cardId || `${index + 1}`);
+        const stateId = stateOfList.get(text(card.idList)) ?? fallbackState;
+        if (!stateId)
+            return;
+        const updatedAt = text(card.dateLastActivity) || time;
+        const cardLabels = [];
+        const seen = new Set();
+        const addById = (rawId) => {
+            const label = labels.get(rawId);
+            if (label && !seen.has(label.id)) {
+                seen.add(label.id);
+                cardLabels.push(label);
+            }
+        };
+        for (const label of rawList(card.labels))
+            addById(text(label.id) || `${text(label.color) || "label"}-${text(label.name)}`);
+        for (const labelId of Array.isArray(card.idLabels) ? card.idLabels : [])
+            addById(text(labelId));
+        const listName = text(lists.find((list) => text(list.id) === text(card.idList))?.name);
+        tickets.push({
+            id: ticketId,
+            number: index + 1,
+            title: text(card.name) || `Untitled Trello card ${index + 1}`,
+            description: description(card, listName, checklists.get(cardId) ?? []),
+            type: "task",
+            parent_ticket_id: null,
+            ai_plan: "",
+            implementation_summary: "",
+            implementation_updates: "",
+            nebula_url: "",
+            state_id: stateId,
+            priority: priorityOf(card),
+            created_by: "trello-import",
+            created_at: dateFromObjectId(card.id) ?? updatedAt,
+            updated_at: updatedAt,
+            archived_at: card.closed ? updatedAt : null,
+            labels: cardLabels
+        });
+        (commentsByCard.get(cardId) ?? []).forEach((action, i) => {
+            const member = isRaw(action.memberCreator) ? action.memberCreator : {};
+            const data = isRaw(action.data) ? action.data : {};
+            comments.push({
+                id: scopedId(ids, "comment", action.id || `${cardId}-${i + 1}`),
+                ticket_id: ticketId,
+                author: text(member.fullName) || text(member.username) || "Trello",
+                kind: "human_comment",
+                body: text(data.text),
+                omitted_for_ai: 0,
+                created_at: text(action.date) || updatedAt
+            });
+        });
+    });
+    return {
+        format: "orbit-board-export",
+        source_format: "trello-board-export",
+        version: 9,
+        exported_at: time,
+        include_attachments: false,
+        imported_counts: { states: states.length, tickets: tickets.length, comments: comments.length, labels: labels.size },
+        board: {
+            id: target.id ?? scopedId(ids, "board", trello.id || ids.next()),
+            slug: boardSlug,
+            name: boardName,
+            repo_url: target.repo_url ?? "",
+            default_branch: target.default_branch ?? "main",
+            project_notes: text(trello.desc) ? `Imported from Trello.\n\n${text(trello.desc)}` : "Imported from Trello.",
+            agent_instructions: "",
+            ai_enabled: 1,
+            created_at: text(trello.dateLastActivity) || time,
+            updated_at: time
+        },
+        states,
+        labels: [...labels.values()],
+        tickets,
+        comments: comments.filter((comment) => comment.body),
+        review_verdicts: [],
+        relations: [],
+        attachments: [],
+        board_entries: [],
+        events: []
+    };
+}

package/lib/core/verdicts.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Review verdicts: a reviewer's PASS, BLOCK or QUESTION on a card, with its
+ * findings and the commands it ran as structured lists, so tools read them
+ * instead of parsing comments.
+ */
+import type { BoardCtx } from "./context.ts";
+import type { Id, ReviewVerdict } from "./model.ts";
+declare const LISTS: readonly ["blocking_findings", "optional_findings", "evidence_commands"];
+/** A verdict as answers show it: its lists parsed, under their names without `_json`. */
+export type VerdictView = Omit<ReviewVerdict, "blocking_findings_json" | "optional_findings_json" | "evidence_commands_json"> & Record<(typeof LISTS)[number], unknown[]>;
+export interface NewVerdictInput {
+    verdict?: unknown;
+    blocking_findings?: unknown;
+    optional_findings?: unknown;
+    evidence_commands?: unknown;
+    reviewer_profile?: unknown;
+    reviewer_session_id?: unknown;
+    reviewed_commit_sha?: unknown;
+    dispatch_run_id?: unknown;
+    supersedes_prior_review_id?: unknown;
+}
+export declare function createVerdict(c: BoardCtx, ticketId: Id, input: NewVerdictInput): Promise<VerdictView>;
+export declare function getVerdict(c: BoardCtx, reviewId: Id): Promise<VerdictView>;
+/** A card's verdicts, newest first; 50 unless `limit` says (at most 200). */
+export declare function listVerdicts(c: BoardCtx, ticketId: Id, options?: {
+    limit?: unknown;
+}): Promise<VerdictView[]>;
+export {};

package/lib/core/verdicts.js

@@ -0,0 +1,92 @@
+/**
+ * Review verdicts: a reviewer's PASS, BLOCK or QUESTION on a card, with its
+ * findings and the commands it ran as structured lists, so tools read them
+ * instead of parsing comments.
+ */
+import { OrbitError } from "./errors.js";
+import { record, touchTicket } from "./history.js";
+import { optionalString, requiredString } from "./text.js";
+import { ticketOn } from "./tickets.js";
+const VERDICTS = ["PASS", "BLOCK", "QUESTION"];
+const LISTS = ["blocking_findings", "optional_findings", "evidence_commands"];
+function viewOf(row) {
+    const { blocking_findings_json, optional_findings_json, evidence_commands_json, ...rest } = row;
+    const parse = (json) => JSON.parse(json || "[]");
+    return {
+        ...rest,
+        blocking_findings: parse(blocking_findings_json),
+        optional_findings: parse(optional_findings_json),
+        evidence_commands: parse(evidence_commands_json),
+        supersedes_prior_review_id: rest.supersedes_prior_review_id || null
+    };
+}
+function list(value, field) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new OrbitError(`invalid_${field}`);
+    return value;
+}
+export async function createVerdict(c, ticketId, input) {
+    const made = await c.data.write(async (w) => {
+        const ticket = await ticketOn(w, ticketId);
+        const verdict = requiredString(input.verdict, "verdict").toUpperCase();
+        if (!VERDICTS.includes(verdict))
+            throw new OrbitError("invalid_review_verdict");
+        const [blocking, optional, evidence] = LISTS.map((field) => list(input[field], field));
+        const supersedes = optionalString(input.supersedes_prior_review_id) || null;
+        if (supersedes) {
+            const prior = await w.verdicts.get(supersedes);
+            if (!prior)
+                throw new OrbitError("invalid_supersedes_prior_review_id");
+            if (prior.ticket_id !== ticket.id)
+                throw new OrbitError("superseded_review_ticket_mismatch");
+        }
+        const at = c.clock.now();
+        const row = {
+            id: c.ids.next(),
+            ticket_id: ticket.id,
+            verdict: verdict,
+            blocking_findings_json: JSON.stringify(blocking),
+            optional_findings_json: JSON.stringify(optional),
+            evidence_commands_json: JSON.stringify(evidence),
+            reviewer_profile: optionalString(input.reviewer_profile),
+            reviewer_session_id: optionalString(input.reviewer_session_id),
+            reviewed_commit_sha: optionalString(input.reviewed_commit_sha),
+            dispatch_run_id: optionalString(input.dispatch_run_id),
+            supersedes_prior_review_id: supersedes,
+            created_by: c.actor.name,
+            created_at: at
+        };
+        await w.verdicts.insert(row);
+        await w.tickets.update(ticket.id, { updated_at: at });
+        await record(w, c, "review_verdict_created", ticket.id, {
+            review_id: row.id,
+            verdict,
+            supersedes_prior_review_id: supersedes,
+            reviewed_commit_sha: row.reviewed_commit_sha,
+            dispatch_run_id: row.dispatch_run_id,
+            actor_type: c.actor.type,
+            actor_id: c.actor.id
+        });
+        await touchTicket(w, ticket.parent_ticket_id, at);
+        return row;
+    });
+    c.changed(c.board.id);
+    return viewOf(made);
+}
+export async function getVerdict(c, reviewId) {
+    const row = await c.data.read((r) => r.verdicts.get(reviewId));
+    if (!row)
+        throw new OrbitError("review_verdict_not_found");
+    return viewOf(row);
+}
+/** A card's verdicts, newest first; 50 unless `limit` says (at most 200). */
+export async function listVerdicts(c, ticketId, options = {}) {
+    const n = Number(options.limit ?? 50);
+    const limit = !Number.isInteger(n) || n <= 0 ? 50 : Math.min(n, 200);
+    return c.data.read(async (r) => {
+        await ticketOn(r, ticketId);
+        return (await r.verdicts.list(ticketId)).reverse().slice(0, limit).map(viewOf);
+    });
+}

package/lib/core/views.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The shapes answers carry, built from records: a card with its lane's name
+ * and its board (`TicketView`), a short card, a card's blockers and who holds
+ * it. Each helper reads what it needs as sets, never one query per card.
+ */
+import type { Board, Id, Label, LaneRole, OrbitEvent, RegisteredBoard, Relation, State, Ticket } from "./model.ts";
+import type { BoardReader } from "../store/types.ts";
+/** A card as answers show it: its record, its lane's name and role, and its board. */
+export interface TicketView extends Ticket {
+    state_name: string;
+    state_role: LaneRole | null;
+    board_slug: string;
+    board_name: string;
+}
+/** A card with its lane, as blockers list them. */
+export interface LanedTicket extends Ticket {
+    state_name: string;
+    state_role: LaneRole | null;
+    /** Set when the card blocks because it is an open sub-card of a blocking epic. */
+    via_epic_id?: Id;
+}
+/** A card in a few words, for lists inside answers. */
+export interface CompactTicket {
+    id: Id;
+    board_id: Id;
+    board_slug: string | undefined;
+    number: number;
+    title: string;
+    type: Ticket["type"];
+    state_name: string;
+    state_role: LaneRole | null;
+    priority: Ticket["priority"];
+}
+/** The board as answers name it: its slug and name. */
+export type BoardName = Pick<RegisteredBoard | Board, "slug" | "name">;
+/** A board's lanes, by id. */
+export declare class Lanes {
+    readonly list: State[];
+    private readonly byId;
+    constructor(list: State[]);
+    static of(r: BoardReader): Promise<Lanes>;
+    get(id: Id): State | undefined;
+    /** The first lane, by position, with this role. */
+    byRole(role: LaneRole): State | undefined;
+    byName(name: string): State | undefined;
+    /** The lane holding a role, or by its usual name on a board that never set one. */
+    forRole(role: LaneRole, name: string): State | undefined;
+    nameOf(ticket: Ticket): string;
+    roleOf(ticket: Ticket): LaneRole | null;
+}
+export declare function ticketView(ticket: Ticket, lanes: Lanes, board: BoardName): TicketView;
+export declare function laned(ticket: Ticket, lanes: Lanes): LanedTicket;
+export declare function compactTicket(ticket: LanedTicket & {
+    board_slug?: string;
+}): CompactTicket;
+/** Each card's labels, by name, for these cards (all when absent). */
+export declare function labelsByTicket(r: BoardReader, ticketIds?: readonly Id[]): Promise<Map<Id, Label[]>>;
+export declare function byCodePoint(a: string, b: string): number;
+/** The ids of the cards blocking `ticketId` directly: "this blocked_by X" on the card, or "X blocks this" on the blocker. */
+export declare function blockerIds(relations: readonly Relation[], ticketId: Id): Id[];
+/**
+ * What blocks a card: its open blockers by number, where an epic stands for
+ * its open sub-cards not in a done lane (each with `via_epic_id`). The
+ * relation is the record: finishing a blocker deletes it.
+ */
+export declare function unresolvedBlockers(r: BoardReader, ticketId: Id, lanes: Lanes): Promise<LanedTicket[]>;
+/**
+ * Blockers for many cards at once, from the board's relations and open
+ * cards already read: what `view` shows for every open card.
+ */
+export declare function blockersFromSets(ticketId: Id, relations: readonly Relation[], open: ReadonlyMap<Id, Ticket>, childrenOf: ReadonlyMap<Id, Ticket[]>, lanes: Lanes): Ticket[];
+/** The events that start or end an agent's hold on a card. */
+export declare const WORK_EVENTS: readonly ["agent_claimed", "state_changed", "agent_completed", "checkpoint_requested"];
+export interface Holder {
+    name: string;
+    id: string | null;
+    since: string;
+}
+/** Who holds a card: the agent whose claim is the card's latest work event, from that event. */
+export declare function holderFrom(event: OrbitEvent | undefined): Holder | null;
+export declare function currentHolder(r: BoardReader, ticketId: Id): Promise<Holder | null>;
+/** Whether a holder is this actor: by id when the claim recorded one, else by name. */
+export declare function isHolder(holder: Holder | null, actor: {
+    id: string;
+    name: string;
+}): boolean;
+/** A lane that closes work: a done lane, or one named Cancelled or Won't. */
+export declare function isClosedLane(state: Pick<State, "name" | "role">): boolean;
+/** The cards on either side of a card's relations, both open, oldest relation first. */
+export declare function relationRows(r: BoardReader, ticketId: Id, lanes: Lanes, board: BoardName): Promise<{
+    id: Id;
+    type: string;
+    direction: "outgoing" | "incoming";
+    other_ticket: TicketView;
+}[]>;

package/lib/core/views.js

@@ -0,0 +1,186 @@
+/**
+ * The shapes answers carry, built from records: a card with its lane's name
+ * and its board (`TicketView`), a short card, a card's blockers and who holds
+ * it. Each helper reads what it needs as sets, never one query per card.
+ */
+/** A board's lanes, by id. */
+export class Lanes {
+    list;
+    byId;
+    constructor(list) {
+        this.list = list;
+        this.byId = new Map(list.map((state) => [state.id, state]));
+    }
+    static async of(r) {
+        return new Lanes(await r.states.list());
+    }
+    get(id) {
+        return this.byId.get(id);
+    }
+    /** The first lane, by position, with this role. */
+    byRole(role) {
+        return this.list.find((state) => state.role === role);
+    }
+    byName(name) {
+        return this.list.find((state) => state.name === name);
+    }
+    /** The lane holding a role, or by its usual name on a board that never set one. */
+    forRole(role, name) {
+        return this.byRole(role) ?? this.byName(name);
+    }
+    nameOf(ticket) {
+        return this.byId.get(ticket.state_id)?.name ?? "";
+    }
+    roleOf(ticket) {
+        return this.byId.get(ticket.state_id)?.role ?? null;
+    }
+}
+export function ticketView(ticket, lanes, board) {
+    return { ...ticket, state_name: lanes.nameOf(ticket), state_role: lanes.roleOf(ticket), board_slug: board.slug, board_name: board.name };
+}
+export function laned(ticket, lanes) {
+    return { ...ticket, state_name: lanes.nameOf(ticket), state_role: lanes.roleOf(ticket) };
+}
+export function compactTicket(ticket) {
+    return {
+        id: ticket.id,
+        board_id: ticket.board_id,
+        board_slug: ticket.board_slug,
+        number: ticket.number,
+        title: ticket.title,
+        type: ticket.type,
+        state_name: ticket.state_name,
+        state_role: ticket.state_role,
+        priority: ticket.priority
+    };
+}
+/** Each card's labels, by name, for these cards (all when absent). */
+export async function labelsByTicket(r, ticketIds) {
+    const [labels, links] = await Promise.all([r.labels.list(), r.ticketLabels.list(ticketIds)]);
+    const byId = new Map(labels.map((label) => [label.id, label]));
+    const out = new Map();
+    for (const link of links) {
+        const label = byId.get(link.label_id);
+        if (!label)
+            continue;
+        const list = out.get(link.ticket_id) ?? [];
+        list.push(label);
+        out.set(link.ticket_id, list);
+    }
+    for (const list of out.values())
+        list.sort((a, b) => byCodePoint(a.name, b.name));
+    return out;
+}
+export function byCodePoint(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** The ids of the cards blocking `ticketId` directly: "this blocked_by X" on the card, or "X blocks this" on the blocker. */
+export function blockerIds(relations, ticketId) {
+    const ids = [];
+    for (const relation of relations) {
+        if (relation.source_ticket_id === ticketId && relation.type === "blocked_by")
+            ids.push(relation.target_ticket_id);
+        else if (relation.target_ticket_id === ticketId && relation.type === "blocks")
+            ids.push(relation.source_ticket_id);
+    }
+    return ids;
+}
+/**
+ * What blocks a card: its open blockers by number, where an epic stands for
+ * its open sub-cards not in a done lane (each with `via_epic_id`). The
+ * relation is the record: finishing a blocker deletes it.
+ */
+export async function unresolvedBlockers(r, ticketId, lanes) {
+    const ids = blockerIds(await r.relations.list(ticketId), ticketId);
+    if (!ids.length)
+        return [];
+    const direct = (await r.tickets.list({ ids, archived: false })).sort((a, b) => a.number - b.number);
+    const seen = new Set();
+    const out = [];
+    for (const blocker of direct) {
+        if (blocker.type === "epic") {
+            for (const child of await r.tickets.list({ parent: blocker.id, archived: false })) {
+                if (lanes.roleOf(child) === "done" || seen.has(child.id))
+                    continue;
+                seen.add(child.id);
+                out.push({ ...laned(child, lanes), via_epic_id: blocker.id });
+            }
+            continue;
+        }
+        if (seen.has(blocker.id))
+            continue;
+        seen.add(blocker.id);
+        out.push(laned(blocker, lanes));
+    }
+    return out;
+}
+/**
+ * Blockers for many cards at once, from the board's relations and open
+ * cards already read: what `view` shows for every open card.
+ */
+export function blockersFromSets(ticketId, relations, open, childrenOf, lanes) {
+    const direct = blockerIds(relations, ticketId)
+        .map((id) => open.get(id))
+        .filter((ticket) => ticket !== undefined)
+        .sort((a, b) => a.number - b.number);
+    const seen = new Set();
+    const out = [];
+    for (const blocker of direct) {
+        const list = blocker.type === "epic" ? (childrenOf.get(blocker.id) ?? []).filter((child) => lanes.roleOf(child) !== "done") : [blocker];
+        for (const ticket of list) {
+            if (seen.has(ticket.id))
+                continue;
+            seen.add(ticket.id);
+            out.push(ticket);
+        }
+    }
+    return out;
+}
+/** The events that start or end an agent's hold on a card. */
+export const WORK_EVENTS = ["agent_claimed", "state_changed", "agent_completed", "checkpoint_requested"];
+/** Who holds a card: the agent whose claim is the card's latest work event, from that event. */
+export function holderFrom(event) {
+    if (event?.type !== "agent_claimed")
+        return null;
+    let id = null;
+    try {
+        const body = JSON.parse(event.body_json || "{}");
+        id = typeof body.agent_id === "string" && body.agent_id ? body.agent_id : null;
+    }
+    catch {
+        id = null;
+    }
+    return { name: event.actor, id, since: event.created_at };
+}
+export async function currentHolder(r, ticketId) {
+    const [event] = await r.events.latest([ticketId], WORK_EVENTS);
+    return holderFrom(event);
+}
+/** Whether a holder is this actor: by id when the claim recorded one, else by name. */
+export function isHolder(holder, actor) {
+    if (!holder)
+        return false;
+    return holder.id ? holder.id === actor.id : holder.name === actor.name;
+}
+/** A lane that closes work: a done lane, or one named Cancelled or Won't. */
+export function isClosedLane(state) {
+    return state.role === "done" || /^(cancel|won['\u2019]?t)/i.test(state.name);
+}
+/** The cards on either side of a card's relations, both open, oldest relation first. */
+export async function relationRows(r, ticketId, lanes, board) {
+    const relations = await r.relations.list(ticketId);
+    if (!relations.length)
+        return [];
+    const ids = [...new Set(relations.flatMap((relation) => [relation.source_ticket_id, relation.target_ticket_id]))];
+    const open = new Map((await r.tickets.list({ ids, archived: false })).map((ticket) => [ticket.id, ticket]));
+    const out = [];
+    for (const relation of relations) {
+        const source = open.get(relation.source_ticket_id);
+        const target = open.get(relation.target_ticket_id);
+        if (!source || !target)
+            continue;
+        const outgoing = relation.source_ticket_id === ticketId;
+        out.push({ id: relation.id, type: relation.type, direction: outgoing ? "outgoing" : "incoming", other_ticket: ticketView(outgoing ? target : source, lanes, board) });
+    }
+    return out;
+}