@starlove/orbit 1.4.1 → 2.0.0

package/lib/adapters/sqlite/schema.js

@@ -0,0 +1,276 @@
+/**
+ * The SQLite adapter's schema: every table Orbit 2.0 keeps on a computer or
+ * server, top to bottom. A data folder holds two kinds of database:
+ *
+ *   registry.db               the list of boards and this Orbit's settings
+ *   boards/<folder>/board.db  one board's records, one file per board
+ *
+ * with each board's images and markdown beside its board.db (the blob store,
+ * ./blobs.ts) and copies under backups/ (./backups.ts).
+ *
+ * Every file carries two numbers in its header: `application_id`, which says
+ * the file is Orbit's, and `user_version`, the version of the schema below.
+ * A file without them was written by Orbit 1.x or the first 2.0 (same tables,
+ * no version), and the adapter refuses to open it rather than change it: the
+ * migration brings such folders over.
+ *
+ * Conventions:
+ *
+ * - Field names are the records' own (src/core/model.ts), so a row and its
+ *   record read the same.
+ * - A board's database holds one board, so its rows carry no `board_id`: the
+ *   adapter adds the board's id when it hands a record out, and refuses a
+ *   record naming another board.
+ * - `seq INTEGER PRIMARY KEY` keeps the order records were written, which the
+ *   port's lists fall back on ("then by when it was written"). It is an
+ *   explicit column because VACUUM (and so every backup) may renumber an
+ *   implicit rowid. The record's own id is `UNIQUE` beside it.
+ * - Foreign keys hold the board together (`PRAGMA foreign_keys` is on for
+ *   every connection): a comment's card exists, deleting a card deletes what
+ *   belongs to it, a lane with cards can't be deleted. Two names are left
+ *   unchecked on purpose, as the port says: a card's epic and a cross-board
+ *   relation's target.
+ * - Flags are 0 or 1, times are ISO 8601 text in UTC, JSON stays text.
+ */
+/** Says "this file is Orbit's": 'ORBT' as a big-endian 32-bit integer. */
+export const APPLICATION_ID = 0x4f524254;
+/** The version of the schema below, in every file's `user_version`. */
+export const SCHEMA_VERSION = 1;
+/**
+ * The version of the search index's shape (its columns and tokenizer). When
+ * it changes, a board's index is rebuilt from the documents it holds, once,
+ * the first time the board is opened; never at every start.
+ */
+export const SEARCH_INDEX_VERSION = 1;
+/**
+ * The search index's table, apart from the rest so a change of its shape
+ * rebuilds it alone (./board.ts). Its columns are the core's document
+ * (SearchDocument in src/store/types.ts).
+ */
+export const SEARCH_TABLE = `CREATE VIRTUAL TABLE search USING fts5 (
+  title, description, type, details, comments,
+  tokenize = "unicode61 remove_diacritics 2 tokenchars '_'"
+);`;
+/** registry.db */
+export const REGISTRY_SCHEMA = `
+-- The boards this Orbit has. A board's records live in its own board.db, in
+-- boards/<folder>/; the folder is named once, by the slug the board was made
+-- with, and stays put when the slug changes. The name, slug and the rest are
+-- copies of the board's own record, kept in step after each write, so the
+-- list of boards is one read.
+CREATE TABLE boards (
+  seq            INTEGER PRIMARY KEY,
+  id             TEXT NOT NULL UNIQUE,
+  slug           TEXT NOT NULL UNIQUE,
+  name           TEXT NOT NULL,
+  folder         TEXT NOT NULL UNIQUE,
+  repo_url       TEXT NOT NULL,
+  default_branch TEXT NOT NULL,
+  last_active_at TEXT,
+  created_at     TEXT NOT NULL,
+  updated_at     TEXT NOT NULL
+);
+CREATE INDEX boards_by_name ON boards (name, seq);
+
+-- Small values this Orbit keeps for itself (the computer's default board).
+CREATE TABLE settings (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`;
+/** board.db */
+export const BOARD_SCHEMA = `
+-- The board's own record: one row.
+CREATE TABLE board (
+  id                 TEXT PRIMARY KEY,
+  slug               TEXT NOT NULL,
+  name               TEXT NOT NULL,
+  repo_url           TEXT NOT NULL,
+  default_branch     TEXT NOT NULL,
+  project_notes      TEXT NOT NULL,
+  agent_instructions TEXT NOT NULL,
+  ai_enabled         INTEGER NOT NULL CHECK (ai_enabled IN (0, 1)),
+  created_at         TEXT NOT NULL,
+  updated_at         TEXT NOT NULL
+);
+
+-- Lanes (the code says states). Names are unique on the board; a role says
+-- what the lane does in the agent flow.
+CREATE TABLE states (
+  seq        INTEGER PRIMARY KEY,
+  id         TEXT NOT NULL UNIQUE,
+  name       TEXT NOT NULL UNIQUE,
+  position   INTEGER NOT NULL,
+  is_default INTEGER NOT NULL CHECK (is_default IN (0, 1)),
+  role       TEXT CHECK (role IN ('ai_ready', 'in_progress', 'review', 'done')),
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE labels (
+  seq        INTEGER PRIMARY KEY,
+  id         TEXT NOT NULL UNIQUE,
+  name       TEXT NOT NULL UNIQUE,
+  color      TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+-- Cards (the code says tickets). Numbers are unique on the board and given
+-- by the adapter, one past the highest, inside the write that makes the card.
+-- A card's epic (parent_ticket_id) is not a foreign key: a sub-card keeps it
+-- when its epic is deleted.
+CREATE TABLE tickets (
+  id                           TEXT PRIMARY KEY,
+  number                       INTEGER NOT NULL UNIQUE CHECK (number > 0),
+  title                        TEXT NOT NULL,
+  description                  TEXT NOT NULL,
+  type                         TEXT NOT NULL CHECK (type IN ('epic', 'feature', 'task', 'bug')),
+  parent_ticket_id             TEXT,
+  ai_plan                      TEXT NOT NULL,
+  plan_artifact_path           TEXT NOT NULL,
+  implementation_summary       TEXT NOT NULL,
+  implementation_artifact_path TEXT NOT NULL,
+  implementation_updates       TEXT NOT NULL,
+  nebula_url                   TEXT NOT NULL,
+  state_id                     TEXT NOT NULL REFERENCES states (id),
+  priority                     INTEGER NOT NULL CHECK (priority BETWEEN 0 AND 4),
+  created_by                   TEXT NOT NULL,
+  created_at                   TEXT NOT NULL,
+  updated_at                   TEXT NOT NULL,
+  archived_at                  TEXT
+);
+CREATE INDEX tickets_by_state ON tickets (state_id);
+CREATE INDEX tickets_by_parent ON tickets (parent_ticket_id);
+CREATE INDEX tickets_by_title ON tickets (lower(title));
+
+CREATE TABLE ticket_labels (
+  seq       INTEGER PRIMARY KEY,
+  ticket_id TEXT NOT NULL REFERENCES tickets (id) ON DELETE CASCADE,
+  label_id  TEXT NOT NULL REFERENCES labels (id) ON DELETE CASCADE,
+  UNIQUE (ticket_id, label_id)
+);
+CREATE INDEX ticket_labels_by_label ON ticket_labels (label_id);
+
+-- kind is free text: Orbit writes human_comment, agent_note, checkpoint and
+-- completion. omitted_for_ai = 1 hides a comment from agents, search included.
+CREATE TABLE comments (
+  seq            INTEGER PRIMARY KEY,
+  id             TEXT NOT NULL UNIQUE,
+  ticket_id      TEXT NOT NULL REFERENCES tickets (id) ON DELETE CASCADE,
+  author         TEXT NOT NULL,
+  kind           TEXT NOT NULL,
+  body           TEXT NOT NULL,
+  omitted_for_ai INTEGER NOT NULL CHECK (omitted_for_ai IN (0, 1)),
+  created_at     TEXT NOT NULL
+);
+CREATE INDEX comments_by_ticket ON comments (ticket_id, created_at, seq);
+
+-- Links between two cards of this board.
+CREATE TABLE relations (
+  seq              INTEGER PRIMARY KEY,
+  id               TEXT NOT NULL UNIQUE,
+  source_ticket_id TEXT NOT NULL REFERENCES tickets (id) ON DELETE CASCADE,
+  target_ticket_id TEXT NOT NULL REFERENCES tickets (id) ON DELETE CASCADE,
+  type             TEXT NOT NULL,
+  created_at       TEXT NOT NULL,
+  UNIQUE (source_ticket_id, target_ticket_id, type)
+);
+CREATE INDEX relations_by_target ON relations (target_ticket_id);
+
+-- Links from a card of this board to a card on another board of the same
+-- Orbit. They live here, on the source's board; the target is named, never
+-- checked, and whether it still blocks is read from it when asked.
+CREATE TABLE cross_board_relations (
+  seq              INTEGER PRIMARY KEY,
+  id               TEXT NOT NULL UNIQUE,
+  source_ticket_id TEXT NOT NULL REFERENCES tickets (id) ON DELETE CASCADE,
+  target_board_id  TEXT NOT NULL,
+  target_ticket_id TEXT NOT NULL,
+  type             TEXT NOT NULL CHECK (type IN ('blocked_by', 'relates_to')),
+  created_at       TEXT NOT NULL,
+  UNIQUE (source_ticket_id, target_board_id, target_ticket_id, type)
+);
+CREATE INDEX cross_board_relations_by_target ON cross_board_relations (target_board_id);
+
+-- The journal: decisions and lessons, optionally about a card. Struck
+-- entries stay; deleting their card keeps them, unlinked.
+CREATE TABLE board_entries (
+  seq        INTEGER PRIMARY KEY,
+  id         TEXT NOT NULL UNIQUE,
+  type       TEXT NOT NULL CHECK (type IN ('decision', 'lesson')),
+  title      TEXT NOT NULL,
+  body       TEXT NOT NULL,
+  ticket_id  TEXT REFERENCES tickets (id) ON DELETE SET NULL,
+  created_by TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  struck_at  TEXT
+);
+
+CREATE TABLE review_verdicts (
+  seq                        INTEGER PRIMARY KEY,
+  id                         TEXT NOT NULL UNIQUE,
+  ticket_id                  TEXT NOT NULL REFERENCES tickets (id) ON DELETE CASCADE,
+  verdict                    TEXT NOT NULL CHECK (verdict IN ('PASS', 'BLOCK', 'QUESTION')),
+  blocking_findings_json     TEXT NOT NULL,
+  optional_findings_json     TEXT NOT NULL,
+  evidence_commands_json     TEXT NOT NULL,
+  reviewer_profile           TEXT NOT NULL,
+  reviewer_session_id        TEXT NOT NULL,
+  reviewed_commit_sha        TEXT NOT NULL,
+  dispatch_run_id            TEXT NOT NULL,
+  supersedes_prior_review_id TEXT REFERENCES review_verdicts (id) ON DELETE SET NULL,
+  created_by                 TEXT NOT NULL,
+  created_at                 TEXT NOT NULL
+);
+CREATE INDEX review_verdicts_by_ticket ON review_verdicts (ticket_id, created_at, seq);
+CREATE INDEX review_verdicts_by_supersedes ON review_verdicts (supersedes_prior_review_id);
+
+-- Images on cards. The bytes are files beside this database, at
+-- attachments/<stored_path>.
+CREATE TABLE attachments (
+  seq           INTEGER PRIMARY KEY,
+  id            TEXT NOT NULL UNIQUE,
+  ticket_id     TEXT NOT NULL REFERENCES tickets (id) ON DELETE CASCADE,
+  original_name TEXT NOT NULL,
+  stored_path   TEXT NOT NULL,
+  mime_type     TEXT NOT NULL,
+  size_bytes    INTEGER NOT NULL,
+  sha256        TEXT NOT NULL,
+  created_by    TEXT NOT NULL,
+  created_at    TEXT NOT NULL
+);
+CREATE INDEX attachments_by_ticket ON attachments (ticket_id, created_at, seq);
+
+-- The board's history, in the order it was appended. seq is AUTOINCREMENT so
+-- it never goes back, even after a board is cleared: a watcher that has seen
+-- event n reads what came after it by seq > n (ARCHITECTURE.md, watch()).
+CREATE TABLE events (
+  seq        INTEGER PRIMARY KEY AUTOINCREMENT,
+  id         TEXT NOT NULL UNIQUE,
+  ticket_id  TEXT REFERENCES tickets (id) ON DELETE SET NULL,
+  actor      TEXT NOT NULL,
+  type       TEXT NOT NULL,
+  body_json  TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+CREATE INDEX events_by_ticket ON events (ticket_id, created_at, seq);
+CREATE INDEX events_by_time ON events (created_at, seq);
+
+-- The search index: one document per card, built by the core (a comment
+-- hidden from agents is never in it). Its rowid is the card's number, which
+-- never changes. Words are runs of letters, digits and _, folded to lower
+-- case without accents.
+${SEARCH_TABLE}
+
+-- Deleting a card deletes its document.
+CREATE TRIGGER tickets_drop_document AFTER DELETE ON tickets BEGIN
+  DELETE FROM search WHERE rowid = old.number;
+END;
+
+-- What this file knows about itself: the search index's version.
+CREATE TABLE meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+INSERT INTO meta (key, value) VALUES ('search_index_version', '${String(SEARCH_INDEX_VERSION)}');
+`;

package/lib/adapters/sqlite/store.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The SQLite adapter: Orbit's storage port on `node:sqlite`, over a data
+ * folder.
+ *
+ *   registry.db                        the list of boards and the settings
+ *   boards/<folder>/board.db           one board's records
+ *   boards/<folder>/attachments/...    its images (the blob store)
+ *   boards/<folder>/artifacts/...      its markdown
+ *   backups/                           copies (VACUUM INTO), with each board's files linked beside them
+ *
+ * The schema is ./schema.ts. A folder whose files lack v2's version (Orbit
+ * 1.x, or 2.0 before its rebuild) is refused untouched, with
+ * `data_needs_migration`. Several stores, in one process or several, can open
+ * one folder at once: SQLite's locks keep their writes one at a time, and
+ * each hears the others' changes.
+ */
+import type { Backups, BlobStore, OrbitStore } from "../../store/types.ts";
+export interface SqliteStoreOptions {
+    /** The data folder. Made when missing. */
+    dataDir: string;
+    /** How long a write waits for a lock another process holds, in ms, before refusing with `storage_busy`. Default 5000. */
+    busyTimeoutMs?: number;
+    /** Copies kept per board and for the registry. Default 30. */
+    backupRetention?: number;
+    /** The clock backups are named by and counted against (once per day, UTC). Records never read it. */
+    now?: () => Date;
+}
+/** An OrbitStore over a data folder, with the blob store for the same folder. */
+export interface SqliteStore extends OrbitStore {
+    readonly backups: Backups;
+    /** The bytes beside each board's database. */
+    readonly blobs: BlobStore;
+}
+/**
+ * Opens a store over `dataDir`, making the folder and its registry when
+ * they're missing. Rejects with `data_needs_migration` for a folder of older
+ * data, which it leaves as it was.
+ */
+export declare function openSqliteStore(options: SqliteStoreOptions): Promise<SqliteStore>;