@starlove/orbit 1.0.1

package/src/core/seed.js

@@ -0,0 +1,226 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { addComment } from "./queries.js";
+import { recordEvent } from "./events.js";
+import { id, now, normalizeTicketType, slugify, titleize } from "./util.js";
+
+/**
+ * Seed a fresh per-board DB with the universal first-run profile. Caller
+ * supplies the connection and the repo path the board lives in. Returns the
+ * new board row, or null if the DB already had a board.
+ */
+export function seedIfEmpty(db, repoPath, options = {}) {
+  const existing = db.prepare("SELECT COUNT(*) AS count FROM boards").get().count;
+  if (existing > 0) return null;
+
+  const time = now();
+  const boardId = id();
+  const seed = buildBoardFromRepo(repoPath);
+
+  db.exec("BEGIN;");
+  try {
+    db.prepare(
+      `INSERT INTO boards
+       (id, slug, name, repo_url, system_path, default_branch,
+        project_notes, agent_instructions, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(
+      boardId,
+      seed.boardSlug,
+      seed.boardName,
+      seed.repoUrl,
+      seed.systemPath,
+      seed.defaultBranch,
+      seed.projectNotes,
+      seed.agentInstructions,
+      time,
+      time
+    );
+
+    const states = [
+      ["Backlog", null],
+      ["Todo", null],
+      ["In Progress", "in_progress"],
+      ["Review", "review"],
+      ["Done", "done"],
+      ["Cancelled", null]
+    ];
+    const stateIds = new Map();
+    states.forEach(([name, role], position) => {
+      const stateId = id();
+      stateIds.set(name, stateId);
+      db.prepare(
+        `INSERT INTO states
+         (id, board_id, name, position, is_default, role, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`
+      ).run(stateId, boardId, name, position, name === "Todo" ? 1 : 0, role, time);
+    });
+
+    // User-defined labels only at seed time.
+    const labelIds = new Map();
+    [
+      ["human-only", "#7c2d12"],
+      ["needs-human-input", "#dc2626"],
+      ["needs-decomposition", "#9333ea"],
+      ["needs-followup", "#b45309"],
+      ["tech-debt", "#64748b"],
+      ["security", "#991b1b"],
+      ["onboarding", "#0f766e"]
+    ].forEach(([name, color]) => {
+      const labelId = id();
+      labelIds.set(name, labelId);
+      db.prepare(
+        "INSERT INTO labels (id, board_id, name, color, created_at) VALUES (?, ?, ?, ?, ?)"
+      ).run(labelId, boardId, name, color, time);
+    });
+
+    if (options.includeExamples) {
+      const epicTicket = insertSeedTicket(db, boardId, 1, {
+        title: `Onboard ${seed.boardName} into this board`,
+        description:
+          "First-run onboarding epic. Use this to turn the generic seed into a useful repo-specific project context and work queue.",
+        type: "epic",
+        aiPlan:
+          "1. Fill Settings → AI (Agent Instructions) and Settings → Notes (Notes For You).\n2. Capture initial decisions and lessons in the Journal.\n3. Create the first real epic or AI-ready implementation ticket.",
+        stateId: stateIds.get("Todo"),
+        priority: 4,
+        labels: [labelIds.get("human-only"), labelIds.get("needs-decomposition"), labelIds.get("onboarding")]
+      });
+
+      const firstTicket = insertSeedTicket(db, boardId, 2, {
+        title: "Fill agent context & personal notes",
+        description:
+          "Open Settings → AI (Agent Instructions) and Settings → Notes, and replace the seed text with real project context plus your own reminders.",
+        type: "feature",
+        parentTicketId: epicTicket,
+        stateId: stateIds.get("Todo"),
+        priority: 3,
+        labels: [labelIds.get("human-only"), labelIds.get("onboarding")]
+      });
+
+      insertSeedTicket(db, boardId, 3, {
+        title: "Create the first real implementation ticket",
+        description:
+          "Create a focused feature, task, or bug card with acceptance criteria, labels, and enough context for an agent or human to execute.",
+        type: "feature",
+        parentTicketId: epicTicket,
+        stateId: stateIds.get("Backlog"),
+        priority: 1,
+        labels: [labelIds.get("human-only"), labelIds.get("onboarding")]
+      });
+
+      // #12 is a stable “try the agent on this card” handle for docs and `orbit init` next steps (MCP + claim-next).
+      insertSeedTicket(db, boardId, 12, {
+        title: "Try Orbit MCP on this ticket",
+        description:
+          "After `orbit init` and registering MCP, ask your agent from this repo to use the Orbit MCP tools on ticket 12 (claim context, update fields, move lanes). Read SKILL-ORBIT.md first.",
+        type: "task",
+        stateId: stateIds.get("Backlog"),
+        priority: 2,
+        labels: [labelIds.get("onboarding")]
+      });
+
+      addComment(db, epicTicket, "system", "note", "Universal first-run seed. Delete or complete these onboarding cards once this board reflects the repo.");
+      addComment(db, firstTicket, "system", "note", "Settings → AI: agent_instructions (ticket context). Settings → Notes: project_notes (you only).");
+    }
+    recordEvent(db, boardId, "seed", null, "system", { board: seed.boardSlug });
+    db.exec("COMMIT;");
+  } catch (error) {
+    db.exec("ROLLBACK;");
+    throw error;
+  }
+
+  return db.prepare("SELECT * FROM boards WHERE id = ?").get(boardId);
+}
+
+function insertSeedTicket(db, boardId, number, ticket) {
+  const ticketId = id();
+  const time = now();
+  db.prepare(
+    `INSERT INTO tickets
+     (id, board_id, number, title, description, type, parent_ticket_id, ai_plan,
+      implementation_summary, implementation_updates, state_id, priority, created_by, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  ).run(
+    ticketId,
+    boardId,
+    number,
+    ticket.title,
+    ticket.description,
+    normalizeTicketType(ticket.type || (ticket.parentTicketId ? "feature" : "task")),
+    ticket.parentTicketId || null,
+    ticket.aiPlan || "",
+    ticket.implementationSummary || "",
+    ticket.implementationUpdates || "",
+    ticket.stateId,
+    ticket.priority,
+    "system",
+    time,
+    time
+  );
+
+  for (const labelId of ticket.labels || []) {
+    db.prepare("INSERT OR IGNORE INTO ticket_labels (ticket_id, label_id) VALUES (?, ?)").run(ticketId, labelId);
+  }
+  return ticketId;
+}
+
+/** Sniff repo metadata for a new board (package.json, git, env). */
+export function buildBoardFromRepo(projectRoot) {
+  const packageInfo = readPackageInfo(projectRoot);
+  const directoryName = basename(projectRoot);
+  const boardName =
+    readSeedValue("board_name") || titleize(packageInfo.name || directoryName || "My Board");
+  const boardSlug = slugify(
+    readSeedValue("board_slug") || packageInfo.name || boardName || "my-board"
+  );
+  const repoUrl = readSeedValue("repo_url") || gitValue(["config", "--get", "remote.origin.url"], projectRoot) || "";
+  const systemPath = readSeedValue("system_path") || projectRoot;
+  const defaultBranch =
+    readSeedValue("default_branch") ||
+    gitValue(["branch", "--show-current"], projectRoot) ||
+    gitValue(["symbolic-ref", "--short", "HEAD"], projectRoot) ||
+    "main";
+  const defaultProjectNotes =
+    "Personal reminders (Settings → Notes: Notes For You). Point yourself at SKILL-ORBIT.md, runbooks, or nudges for your tools.";
+  const defaultAgentInstructions = `Describe why ${boardName} exists, who it serves, and what success looks like. Add features, stack, constraints, and anything agents should know — this project-level context is provided to agents when they work on tickets.`;
+  return {
+    boardName,
+    boardSlug,
+    repoUrl,
+    systemPath,
+    defaultBranch,
+    projectNotes: readSeedValue("project_notes") || defaultProjectNotes,
+    agentInstructions: readSeedValue("agent_instructions") || defaultAgentInstructions
+  };
+}
+
+function readPackageInfo(root) {
+  const path = join(root, "package.json");
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function readSeedValue(key) {
+  const envValue = process.env[key.toUpperCase()];
+  if (typeof envValue === "string" && envValue.trim()) return envValue.trim();
+  return "";
+}
+
+function gitValue(args, cwd) {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2000
+    }).trim();
+  } catch {
+    return "";
+  }
+}

package/src/core/snapshots.js

@@ -0,0 +1,255 @@
+import { resetBoard, tx } from "./db.js";
+import { backupBoardDatabase } from "./backups.js";
+import { boardById, labelsForTicket } from "./queries.js";
+import { requireBoardAccess } from "./auth.js";
+import { recordEvent } from "./events.js";
+import { syncRegistryFromBoardDb } from "./registry.js";
+import {
+  httpError,
+  normalizePriority,
+  normalizeProjectEntryType,
+  normalizeTicketType,
+  now,
+  requiredString
+} from "./util.js";
+import { reindexAllTickets } from "./tickets.js";
+
+export function exportBoard(boardId, ctx) {
+  const { db, board, actor } = ctx;
+  if (boardId !== board.id) throw httpError(404, "board_not_found");
+  const innerBoard = boardById(db, boardId);
+  if (!innerBoard) throw httpError(404, "board_not_found");
+  requireBoardAccess(actor, innerBoard);
+
+  const states = db.prepare("SELECT * FROM states WHERE board_id = ? ORDER BY position").all(boardId);
+  const tickets = db
+    .prepare("SELECT * FROM tickets WHERE board_id = ? ORDER BY number ASC")
+    .all(boardId)
+    .map((ticket) => ({ ...ticket, labels: labelsForTicket(db, ticket.id) }));
+  const ticketIds = tickets.map((ticket) => ticket.id);
+  const comments = ticketIds.length
+    ? db
+        .prepare("SELECT * FROM comments WHERE ticket_id IN (SELECT id FROM tickets WHERE board_id = ?) ORDER BY created_at ASC")
+        .all(boardId)
+    : [];
+  const relations = ticketIds.length
+    ? db
+        .prepare(
+          `SELECT *
+           FROM relations
+           WHERE source_ticket_id IN (SELECT id FROM tickets WHERE board_id = ?)
+              OR target_ticket_id IN (SELECT id FROM tickets WHERE board_id = ?)
+           ORDER BY created_at ASC`
+        )
+        .all(boardId, boardId)
+    : [];
+  const entries = db
+    .prepare("SELECT * FROM board_entries WHERE board_id = ? ORDER BY created_at ASC")
+    .all(boardId);
+  const labels = db.prepare("SELECT * FROM labels WHERE board_id = ? ORDER BY name ASC").all(boardId);
+  const events = db
+    .prepare(
+      `SELECT *
+       FROM events
+       WHERE ticket_id IS NULL
+          OR ticket_id IN (SELECT id FROM tickets WHERE board_id = ?)
+       ORDER BY created_at ASC`
+    )
+    .all(boardId);
+
+  return {
+    format: "orbit-board-export",
+    version: 5,
+    exported_at: now(),
+    board: { ...innerBoard },
+    states,
+    labels,
+    tickets,
+    comments,
+    relations,
+    board_entries: entries,
+    events
+  };
+}
+
+export function importBoardSnapshot(body, ctx) {
+  const { db, actor, board } = ctx;
+  const snapshot = body?.snapshot || body;
+  const format = snapshot?.format;
+  if (!snapshot || format !== "orbit-board-export") throw httpError(400, "invalid_import_snapshot");
+  if (!snapshot.board) throw httpError(400, "snapshot_missing_board");
+
+  const replaceExisting = Boolean(body?.replace_existing);
+  const existingCount = db.prepare("SELECT COUNT(*) AS count FROM boards").get().count;
+  if (existingCount > 0 && !replaceExisting) {
+    throw httpError(409, "import_requires_empty_board_or_replace_existing");
+  }
+
+  // Snapshot the existing DB file before a destructive replace, outside the
+  // transaction (it copies the file on disk, not rows).
+  if (existingCount > 0 && replaceExisting) {
+    backupBoardDatabase(ctx.board, db, "pre-import-replace");
+  }
+
+  const targetBoardId = board.id;
+  const importedBoard = {
+    ...snapshot.board,
+    id: targetBoardId
+  };
+
+  const result = tx(db, () => {
+    if (existingCount > 0 && replaceExisting) resetBoard(db);
+
+    db.prepare(
+      `INSERT INTO boards
+       (id, slug, name, repo_url, system_path, default_branch,
+        project_notes, agent_instructions, ai_enabled, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(
+      importedBoard.id,
+      importedBoard.slug,
+      importedBoard.name,
+      importedBoard.repo_url || "",
+      importedBoard.system_path || "",
+      importedBoard.default_branch || "main",
+      importedBoard.project_notes || "",
+      importedBoard.agent_instructions || "",
+      importedBoard.ai_enabled === 0 ? 0 : 1,
+      importedBoard.created_at || now(),
+      importedBoard.updated_at || now()
+    );
+
+    for (const state of snapshot.states || []) {
+      db.prepare(
+        `INSERT INTO states
+         (id, board_id, name, position, is_default, role, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`
+      ).run(
+        state.id,
+        targetBoardId,
+        state.name,
+        state.position,
+        state.is_default || 0,
+        state.role || null,
+        state.created_at || now()
+      );
+    }
+
+    for (const label of snapshot.labels || []) {
+      db.prepare("INSERT INTO labels (id, board_id, name, color, created_at) VALUES (?, ?, ?, ?, ?)").run(
+        label.id,
+        targetBoardId,
+        label.name,
+        label.color || "#64748b",
+        label.created_at || now()
+      );
+    }
+
+    for (const ticket of snapshot.tickets || []) {
+      db.prepare(
+        `INSERT INTO tickets
+         (id, board_id, number, title, description, type, parent_ticket_id, ai_plan,
+          implementation_summary, implementation_updates, state_id, priority,
+          created_by, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+      ).run(
+        ticket.id,
+        targetBoardId,
+        ticket.number,
+        ticket.title,
+        ticket.description || "",
+        normalizeTicketType(ticket.type || "task"),
+        ticket.parent_ticket_id || null,
+        ticket.ai_plan || "",
+        ticket.implementation_summary || "",
+        ticket.implementation_updates || "",
+        ticket.state_id,
+        normalizePriority(ticket.priority),
+        ticket.created_by || "import",
+        ticket.created_at || now(),
+        ticket.updated_at || now()
+      );
+
+      for (const label of ticket.labels || []) {
+        db.prepare("INSERT OR IGNORE INTO ticket_labels (ticket_id, label_id) VALUES (?, ?)").run(ticket.id, label.id);
+      }
+    }
+
+    for (const comment of snapshot.comments || []) {
+      db.prepare(
+        "INSERT INTO comments (id, ticket_id, author, kind, body, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+      ).run(
+        comment.id,
+        comment.ticket_id,
+        comment.author || "import",
+        comment.kind || "comment",
+        comment.body || "",
+        comment.created_at || now()
+      );
+    }
+
+    for (const relation of snapshot.relations || []) {
+      db.prepare(
+        "INSERT OR IGNORE INTO relations (id, source_ticket_id, target_ticket_id, type, created_at) VALUES (?, ?, ?, ?, ?)"
+      ).run(
+        relation.id,
+        relation.source_ticket_id,
+        relation.target_ticket_id,
+        relation.type || "relates_to",
+        relation.created_at || now()
+      );
+    }
+
+    for (const entry of snapshot.board_entries || []) {
+      db.prepare(
+        `INSERT INTO board_entries
+         (id, board_id, type, title, body, ticket_id, created_by, created_at, updated_at, struck_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+      ).run(
+        entry.id,
+        targetBoardId,
+        normalizeProjectEntryType(entry.type),
+        requiredString(entry.title, "entry_title"),
+        entry.body || "",
+        entry.ticket_id || null,
+        entry.created_by || "import",
+        entry.created_at || now(),
+        entry.updated_at || now(),
+        entry.struck_at || null
+      );
+    }
+
+    for (const event of snapshot.events || []) {
+      db.prepare(
+        "INSERT INTO events (id, ticket_id, actor, type, body_json, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+      ).run(
+        event.id,
+        event.ticket_id || null,
+        event.actor || "import",
+        event.type || "imported_event",
+        event.body_json || "{}",
+        event.created_at || now()
+      );
+    }
+
+    // Reindex inside the transaction: a committed import must never leave the
+    // FTS table empty/stale (previously this ran after COMMIT and a throw here
+    // left search broken on otherwise-imported data).
+    reindexAllTickets(db);
+    recordEvent(db, targetBoardId, "board_imported", null, actor.name, {
+      board_id: targetBoardId,
+      replace_existing: replaceExisting
+    });
+    return {
+      ok: true,
+      imported_board_id: targetBoardId,
+      imported_board_slug: importedBoard.slug,
+      replace_existing: replaceExisting
+    };
+  });
+
+  // Registry sync writes the separate registry DB (a different connection), so
+  // it runs after the board-DB transaction commits, not inside it.
+  syncRegistryFromBoardDb(board, db);
+  return result;
+}

package/src/core/states.js

@@ -0,0 +1,167 @@
+import { boardById, compactStatePositions, stateById } from "./queries.js";
+import { tx } from "./db.js";
+import { requireBoardAccess, requirePermission } from "./auth.js";
+import { recordEvent } from "./events.js";
+import {
+  httpError,
+  id,
+  normalizeStateRole,
+  now,
+  requiredString
+} from "./util.js";
+
+export function createState(boardId, body, ctx) {
+  const { db, actor } = ctx;
+  const board = boardById(db, boardId);
+  if (!board) throw httpError(404, "board_not_found");
+  requireBoardAccess(actor, board);
+  requirePermission(actor, "write");
+
+  const role = body.role !== undefined ? normalizeStateRole(body.role) : null;
+  // role='ai_ready' implies canonical name; reject mismatches so the AI tab
+  // checkbox always lands a lane named exactly "AI Ready".
+  const name =
+    role === "ai_ready"
+      ? body.name && body.name !== "AI Ready"
+        ? (() => { throw httpError(409, "ai_ready_lane_must_be_named_ai_ready"); })()
+        : "AI Ready"
+      : requiredString(body.name, "name");
+  const stateId = id();
+  return tx(db, () => {
+    if (role) {
+      db.prepare("UPDATE states SET role = NULL WHERE board_id = ? AND role = ?").run(boardId, role);
+    }
+    const maxPosition = db.prepare("SELECT MAX(position) AS value FROM states WHERE board_id = ?").get(boardId).value;
+    db.prepare(
+      `INSERT INTO states
+       (id, board_id, name, position, is_default, role, created_at)
+       VALUES (?, ?, ?, ?, 0, ?, ?)`
+    ).run(stateId, boardId, name, Number(maxPosition || 0) + 1, role, now());
+    recordEvent(db, boardId, "state_created", null, actor.name, {
+      board_id: boardId,
+      state_id: stateId,
+      name,
+      role
+    });
+    return stateById(db, stateId);
+  });
+}
+
+export function updateState(stateId, body, ctx) {
+  const { db, actor } = ctx;
+  const before = stateById(db, stateId);
+  if (!before) throw httpError(404, "state_not_found");
+  const board = boardById(db, before.board_id);
+  requireBoardAccess(actor, board);
+  requirePermission(actor, "write");
+
+  return tx(db, () => {
+  const sets = [];
+  const values = [];
+  if (body.name !== undefined) {
+    const nextName = requiredString(body.name, "name");
+    // The AI Ready lane is the canonical anchor for agent claim-next. Locking
+    // its name removes a whole class of silent breakage; users who want a
+    // different label can disable the AI Ready column from Settings → AI.
+    if (before.role === "ai_ready" && nextName !== "AI Ready") {
+      throw httpError(409, "cannot_rename_ai_ready_lane");
+    }
+    sets.push("name = ?");
+    values.push(nextName);
+  }
+  if (body.is_default !== undefined) {
+    const nextDefault = body.is_default ? 1 : 0;
+    if (nextDefault) db.prepare("UPDATE states SET is_default = 0 WHERE board_id = ?").run(before.board_id);
+    sets.push("is_default = ?");
+    values.push(nextDefault);
+  }
+  if (body.role !== undefined) {
+    const nextRole = normalizeStateRole(body.role);
+    // Roles are unique per board: at most one lane plays each role. If another
+    // lane already holds it, clear that one first so the new assignment wins.
+    if (nextRole) {
+      db.prepare("UPDATE states SET role = NULL WHERE board_id = ? AND role = ? AND id != ?")
+        .run(before.board_id, nextRole, stateId);
+    }
+    // Assigning role='ai_ready' implies the lane name must be "AI Ready" (the
+    // canonical name agents key off). If the caller is also renaming via
+    // body.name above, that took precedence; otherwise force it here.
+    if (nextRole === "ai_ready") {
+      const finalName = body.name !== undefined ? requiredString(body.name, "name") : before.name;
+      if (finalName !== "AI Ready") {
+        if (body.name === undefined) {
+          // Caller didn't ask to rename — silently set the canonical name.
+          sets.push("name = ?");
+          values.push("AI Ready");
+        } else {
+          throw httpError(409, "ai_ready_lane_must_be_named_ai_ready");
+        }
+      }
+    }
+    sets.push("role = ?");
+    values.push(nextRole);
+  }
+  if (sets.length === 0) return before;
+
+  values.push(stateId);
+  db.prepare(`UPDATE states SET ${sets.join(", ")} WHERE id = ?`).run(...values);
+  recordEvent(db, before.board_id, "state_updated", null, actor.name, {
+    board_id: before.board_id,
+    state_id: stateId,
+    fields: Object.keys(body)
+  });
+  return stateById(db, stateId);
+  });
+}
+
+export function reorderStates(boardId, body, ctx) {
+  const { db, actor } = ctx;
+  const board = boardById(db, boardId);
+  if (!board) throw httpError(404, "board_not_found");
+  requireBoardAccess(actor, board);
+  requirePermission(actor, "write");
+
+  const ids = Array.isArray(body.state_ids) ? body.state_ids : [];
+  const existing = db.prepare("SELECT id FROM states WHERE board_id = ?").all(boardId).map((row) => row.id);
+  if (ids.length !== existing.length || !existing.every((stateId) => ids.includes(stateId))) {
+    throw httpError(400, "invalid_state_order");
+  }
+
+  return tx(db, () => {
+    ids.forEach((stateId, position) => {
+      db.prepare("UPDATE states SET position = ? WHERE id = ? AND board_id = ?").run(position, stateId, boardId);
+    });
+    recordEvent(db, boardId, "states_reordered", null, actor.name, { board_id: boardId, state_ids: ids });
+    return db.prepare("SELECT * FROM states WHERE board_id = ? ORDER BY position").all(boardId);
+  });
+}
+
+export function deleteState(stateId, ctx) {
+  const { db, actor } = ctx;
+  const state = stateById(db, stateId);
+  if (!state) throw httpError(404, "state_not_found");
+  const board = boardById(db, state.board_id);
+  requireBoardAccess(actor, board);
+  requirePermission(actor, "write");
+
+  const ticketCount = db.prepare("SELECT COUNT(*) AS count FROM tickets WHERE state_id = ?").get(stateId).count;
+  if (ticketCount > 0) throw httpError(409, "state_has_tickets");
+
+  const stateCount = db.prepare("SELECT COUNT(*) AS count FROM states WHERE board_id = ?").get(state.board_id).count;
+  if (stateCount <= 1) throw httpError(409, "cannot_delete_last_state");
+
+  return tx(db, () => {
+    db.prepare("DELETE FROM states WHERE id = ?").run(stateId);
+    compactStatePositions(db, state.board_id);
+    if (state.is_default) {
+      const first = db.prepare("SELECT id FROM states WHERE board_id = ? ORDER BY position LIMIT 1").get(state.board_id);
+      if (first) db.prepare("UPDATE states SET is_default = 1 WHERE id = ?").run(first.id);
+    }
+    recordEvent(db, state.board_id, "state_deleted", null, actor.name, {
+      board_id: state.board_id,
+      state_id: stateId,
+      name: state.name
+    });
+    return { ok: true, deleted_state_id: stateId };
+  });
+}