@anchrd/intel-api 0.27.0 → 0.28.0

package/migrations/0023_a_board_and_its_tasks.sql

@@ -0,0 +1,116 @@
+-- Two more node kinds, `board` and `task`, and the two side tables that carry what a node row must
+-- not (D66, anchrd/intel#376).
+--
+-- ⚠️ BOTH words in ONE rebuild. Adding them in two migrations would be the same risky operation
+-- twice, and this one has gone wrong before: `0005` committed with every row of `node_links` gone.
+--
+-- The split this migration encodes: IDENTITY through `kind`, FIELDS through a side table.
+--   * `kind` because the tree has to hide `task` on EVERY level query. As a kind that is a condition
+--     on a column the query already carries; as a `document` plus a side-table row it would be a
+--     join on the hottest path in the interface.
+--   * the side table because `status`, `assignee` and the dates are FILTER columns. In the `nodes`
+--     row they would stand empty for every other kind.
+--
+-- The recipe below is the one in `packages/api/CLAUDE.md`, *Rebuilding `nodes` is a recipe*. All
+-- four points, and each is one a previous migration got wrong first:
+--   1. the new table is created under its FINAL name — never `ALTER TABLE … RENAME`, which rewrites
+--      every `REFERENCES` clause and drags the children onto the table about to be dropped;
+--   2. `node_links` is carried out and back with `INSERT OR IGNORE`, because it is the one child
+--      declared `ON DELETE CASCADE` and `DROP TABLE nodes` fires an implicit `DELETE FROM`;
+--   3. `PRAGMA defer_foreign_keys`, never `foreign_keys = OFF` — D1 ignores the latter over its HTTP
+--      API while miniflare honours it, so a green test here would prove nothing about production;
+--   4. the columns are named on BOTH sides of `INSERT … SELECT`, so a future reordering cannot turn
+--      every title into an owner id and still commit.
+PRAGMA defer_foreign_keys = TRUE;
+
+CREATE TABLE nodes_carry AS SELECT * FROM nodes;
+CREATE TABLE node_links_carry AS SELECT * FROM node_links;
+
+DROP TABLE nodes;
+
+CREATE TABLE nodes (
+  id TEXT PRIMARY KEY NOT NULL,
+  parent_id TEXT REFERENCES nodes(id),
+  kind TEXT NOT NULL CHECK (kind IN ('folder', 'document', 'attachment', 'table', 'board', 'task')),
+  title TEXT NOT NULL CHECK (length(title) BETWEEN 1 AND 240),
+  description TEXT CHECK (description IS NULL OR length(description) <= 2000),
+  owner_id TEXT NOT NULL,
+  current_version_id TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  archived_at TEXT
+);
+
+INSERT INTO nodes (
+  id, parent_id, kind, title, description, owner_id,
+  current_version_id, created_at, updated_at, archived_at
+)
+SELECT
+  id, parent_id, kind, title, description, owner_id,
+  current_version_id, created_at, updated_at, archived_at
+FROM nodes_carry;
+
+INSERT OR IGNORE INTO node_links SELECT * FROM node_links_carry;
+
+DROP TABLE nodes_carry;
+DROP TABLE node_links_carry;
+
+CREATE INDEX nodes_parent_idx ON nodes(parent_id, archived_at, title);
+CREATE INDEX nodes_owner_idx ON nodes(owner_id, archived_at);
+
+-- The board's own configuration: which columns it has and in what order. It is one row per board
+-- node, and it exists because a list of statuses is not a node property — every other kind would
+-- carry it empty.
+--
+-- ⚠️ `ON DELETE CASCADE` here and on `board_tasks` below, and that is deliberate in a repository
+-- whose rule is *refuse rather than cascade*. The rule protects a CONTAINER from taking its contents
+-- down with it; these two rows are not contents but the node's own fields, split off only because
+-- SQLite has no per-kind columns. A board whose row here outlived it would be a configuration for a
+-- board that does not exist.
+CREATE TABLE boards (
+  node_id TEXT PRIMARY KEY NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+  statuses_json TEXT NOT NULL DEFAULT '[]',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+-- What a task carries beyond a node. Every column here is one somebody filters or sorts by — that
+-- is the whole reason they are not in the body.
+--
+-- ⚠️ `position` is REAL, not INTEGER. Dragging a card between two neighbours then needs no rewrite
+-- of the whole column: the new value is the midpoint of the two. With integers every drop would
+-- renumber the rows below it, and two people dropping at once would fight over rows neither touched.
+CREATE TABLE board_tasks (
+  node_id TEXT PRIMARY KEY NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+  board_id TEXT NOT NULL REFERENCES nodes(id),
+  status TEXT NOT NULL,
+  assignee_id TEXT,
+  labels_json TEXT NOT NULL DEFAULT '[]',
+  start_date TEXT,
+  due_date TEXT,
+  -- "waits for", as a COLUMN and not as a sentence in the body. The DoD of #376 says it in one
+  -- line: relations are columns the text points at, never the other way round. A dependency living
+  -- in prose cannot be asked "what is blocked right now", and `node_links` cannot answer it either
+  -- — that table says two nodes are related, not that one waits for the other.
+  --
+  -- ⚠️ It points at `nodes`, not at `board_tasks`. A task may wait for something that is not a
+  -- task: a document that has to be approved first, a board that has to be finished. Narrowing it
+  -- to the side table would decide today that only tasks can block, and nothing asked for that.
+  depends_on TEXT REFERENCES nodes(id),
+  position REAL NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+-- The board view reads one column at a time, ordered. Both columns of the sort are in the index, so
+-- the read needs no sorting pass — the same reason `audit_events_feed_idx` carries its tie-break
+-- (anchrd/intel#620).
+CREATE INDEX board_tasks_column_idx ON board_tasks(board_id, status, position);
+
+-- "What is assigned to me, soonest first" — across every board, which is why `assignee_id` leads
+-- and `board_id` does not appear.
+CREATE INDEX board_tasks_assignee_idx ON board_tasks(assignee_id, due_date);
+
+-- "What is blocked by this node" — the direction the interface asks in. Without it the question is
+-- a scan of every task on every board.
+CREATE INDEX board_tasks_depends_idx ON board_tasks(depends_on) WHERE depends_on IS NOT NULL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@anchrd/gate-sdk": "^0.21.0",
-    "@anchrd/intel-contract": "^0.22.0",
+    "@anchrd/intel-contract": "^0.23.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",