@anchrd/intel-api 0.27.0 → 0.29.0

package/dist/nodes/nodes.js

@@ -62,6 +62,119 @@ function decodeBase64(value) {
         throw new IntelError(400, "attachment_invalid", "Attachment content is not valid base64");
     }
 }
+/**
+ * Where a kind may be filed, and it is one rule read by two callers — `create` and the move inside
+ * `update` (#377).
+ *
+ * ⚠️ **Three cases, and the first version had only one of them.** It handled "wrong parent that
+ * exists" and left two doors open, both of which produced exactly the state the rule exists against:
+ *
+ *   * **No parent at all.** `parentId: null` is the ROOT, and the root is not a board. The first
+ *     version skipped the check entirely for `null`, so `node_create({ kind: "task", parentId:
+ *     null })` made a task with no board — and `attachToBoard` did not run either, for the same
+ *     reason. A task on no board, created through the front door.
+ *   * **Right kind, wrong board.** Every `kind === "board"` was accepted as a destination, so a
+ *     task could be moved to ANOTHER board while its `board_tasks.board_id` stayed behind. That
+ *     divergence was reachable only by writing D1 by hand before this rule existed (the join in
+ *     `db-boards.ts` guards against it); the first version of this rule opened a real code path to
+ *     it. **A change that widens what is allowed has to be read for what it now permits, not only
+ *     for what it now refuses.**
+ *
+ * ⚠️ The refusal names the KIND in the sentence rather than a bare "not a folder". Somebody
+ * dragging a card into a folder has to learn what went wrong, not that something did.
+ */
+/**
+ * ⚠️ **Nothing may be filed under an ARCHIVED node**, and this is not tidiness — it is what keeps
+ * the purge honest.
+ *
+ * A parent may be archived while it is empty; `task_has_subtasks` only refuses one that still has
+ * live children. Without this rule it could then GAIN a live child afterwards, and `purge` — which
+ * asks only whether the node itself is archived — walks the whole subtree and takes that child
+ * with it. It would disappear for good without ever being named in the confirmation.
+ *
+ * Found in review of #669, against my own sentence claiming purge needed no rule of its own. That
+ * sentence was true only as long as an archived node could never gain a live child, and nothing
+ * made it true.
+ */
+/**
+ * The board a node would be filed on: the board itself, or the board of the task it hangs under
+ * (#669).
+ *
+ * ⚠️ **One function, because there are three callers and they must not drift.** The create path,
+ * the move and the idempotent replay all ask the same question, and the replay was written when a
+ * task's parent was always its board — it passed `parentId` straight through as the board id. With
+ * nesting that files a subtask on a "board" that is another card, and `board_tasks.board_id` has no
+ * foreign key saying otherwise. Found in review of #669: the main path had been corrected and this
+ * one had not, which is the shape of `anchrd/intel#457` — two places answering one question, only
+ * one of them told about the change.
+ */
+async function boardFor(deps, actor, parent) {
+    if (parent === null)
+        return null;
+    if (parent.kind === "board")
+        return parent.id;
+    // ⚠️ Only a TASK can have a board, and asking for anything else costs a D1 round trip on every
+    // write in the whole tree — a document filed in a folder would pay for a board feature. The
+    // question is not "do we know the board" but "can this parent have one at all".
+    if (parent.kind !== "task")
+        return null;
+    return (await deps.boardOfTask?.(actor, parent.id)) ?? null;
+}
+function refuseArchivedParent(childKind, parent) {
+    // ⚠️ Tasks only, and the narrowness is deliberate. The same hole exists for a folder — archive an
+    // empty one, file a document in it, purge — but it is OLDER than this ticket and fixing it here
+    // would change the behaviour of the whole tree out of a board ticket, with no test outside
+    // `boards.int.ts` covering it. It is #679, which also asks what such data already exists.
+    //
+    // ⚠️ A reference without its number is not a reference: the review of #677 searched for this
+    // ticket and could not find it, because this comment did not name it.
+    if (childKind !== "task")
+        return;
+    if (parent === null || parent.archivedAt === null)
+        return;
+    throw new IntelError(409, "parent_archived", `This ${parent.kind} is archived, so nothing new can be filed under it. Restore it first.`);
+}
+function refuseWrongParent(childKind, parent, boards) {
+    if (childKind === "task") {
+        if (parent === null) {
+            throw new IntelError(409, "task_belongs_to_a_board", "A task lives on a board. The top level is not one, so there is nowhere for it to sit there.");
+        }
+        // ⚠️ Since #669 a task may sit under a task — the hierarchy is the node tree. Everything else
+        // is still refused by name.
+        if (parent.kind !== "board" && parent.kind !== "task") {
+            throw new IntelError(409, "task_belongs_to_a_board", `A task lives on a board and cannot be filed under a ${parent.kind}. Move the board instead, or make a new task on the board you want it on.`);
+        }
+        /**
+         * ⚠️ **The same BOARD, not the same parent node — and that difference is what #669 changed.**
+         * Until then the two were interchangeable, because a task's parent always WAS its board; the
+         * check compared parent ids and was right by accident. With nesting, moving a card under a
+         * sibling changes its parent legitimately while the board stays the same, and comparing ids
+         * would refuse a move that is allowed.
+         *
+         * The rule it protects is unchanged: `board_tasks.board_id` does not travel with a move through
+         * the node path, so a card handed to another board would answer from one board's query while
+         * its row names the other — and the card would show up on neither, or on both.
+         */
+        if (boards?.destination === null || boards?.destination === undefined) {
+            throw new IntelError(409, "task_belongs_to_a_board", "This destination has no board, so a card cannot be filed under it.");
+        }
+        if (boards.current !== undefined &&
+            boards.current !== null &&
+            boards.destination !== boards.current) {
+            throw new IntelError(409, "task_cannot_change_board", "A card cannot be handed to another board this way. Make it on the board you want it on; its position, status and dependencies belong to the board it was filed on.");
+        }
+        return;
+    }
+    // The root takes everything else — that is what a top-level folder or document is.
+    if (parent === null)
+        return;
+    if (parent.kind === "board") {
+        throw new IntelError(409, "board_holds_only_tasks", `A board holds tasks and nothing else; a ${childKind} cannot be filed on one.`);
+    }
+    if (parent.kind !== "folder") {
+        throw new IntelError(409, "parent_not_folder", "A node's parent must be a folder");
+    }
+}
 export function createNodes(deps) {
     function mergeSearchResults(lexical, semantic, semanticScores, limit) {
         const merged = new Map();
@@ -446,13 +559,47 @@ export function createNodes(deps) {
         },
         async create(actor, input) {
             const existingId = await deps.repository.findIdempotentNode(actor.id, "node.create", input.idempotencyKey);
-            if (existingId)
-                return await requireVisible(actor, existingId);
+            if (existingId) {
+                const existing = await requireVisible(actor, existingId);
+                /**
+                 * ⚠️ **The filing runs on the REPLAY path too, and that is what makes a retry a repair.**
+                 *
+                 * `insertNode` commits the node, its idempotency key and its audit row in one batch;
+                 * `attachToBoard` is a separate statement after it. If that one fails — a transient D1
+                 * error is enough — the node exists and its board row does not, and `create` throws. The
+                 * obvious response is the same call again with the same key, and until this line that call
+                 * returned here **without filing anything**: a task that is a task by kind, sits under a
+                 * board, and appears on no board, permanently, with nothing reporting it.
+                 *
+                 * `attach` is `ON CONFLICT DO NOTHING`, so running it on a node that is already filed costs
+                 * one statement and changes nothing. That asymmetry is why the repair belongs here rather
+                 * than in a sweeper somebody has to remember to write.
+                 */
+                if (existing.kind === "task" && existing.parentId !== null) {
+                    // ⚠️ The BOARD, resolved the same way the create path resolves it. Passing `parentId`
+                    // straight through was right only while a task's parent was always its board.
+                    const board = await boardFor(deps, actor, await requireVisible(actor, existing.parentId));
+                    if (board !== null) {
+                        await deps.attachToBoard?.(actor, existing.id, board, deps.now().toISOString());
+                    }
+                }
+                return existing;
+            }
             if (input.parentId !== null && !(await deps.repository.can(actor, input.parentId, "write"))) {
                 throw new IntelError(403, "node_forbidden", "Parent folder cannot be edited");
             }
+            // ⚠️ The same rule on the way IN, and it runs for the ROOT as well. Guarding only a named
+            // parent leaves `parentId: null` open, and that is not a smaller hole: the task is created,
+            // `attachToBoard` skips it for the same reason, and the card belongs to no board at all.
+            const destinationParent = input.parentId === null ? null : await requireVisible(actor, input.parentId);
+            const destinationBoard = await boardFor(deps, actor, destinationParent);
+            // ⚠️ Kind first, archive second. A task under an archived FOLDER is refused for the deeper
+            // reason — a task lives on a board — and saying "restore the folder first" would send the
+            // reader to do something that changes nothing: restored, the folder still cannot hold a task.
+            refuseWrongParent(input.kind, destinationParent, { destination: destinationBoard });
+            refuseArchivedParent(input.kind, destinationParent);
             const timestamp = deps.now().toISOString();
-            return await deps.repository.insertNode({
+            const created = await deps.repository.insertNode({
                 node: {
                     id: deps.id(),
                     parentId: input.parentId,
@@ -469,6 +616,27 @@ export function createNodes(deps) {
                 idempotencyKey: input.idempotencyKey,
                 auditId: deps.id(),
             });
+            /**
+             * ⚠️ **A task created through the plain node path still gets its board row** (#648). Without
+             * this an agent calling `node_create` under a board makes a node that is a task by kind, has
+             * no row in `board_tasks`, and therefore appears on NO board — with nothing reporting an
+             * error. It is exactly the shape of failure this repository keeps writing rules about: not a
+             * refusal, an absence.
+             *
+             * ⚠️ It runs AFTER the node exists and is its own statement rather than part of the batch.
+             * The node is the truth; the board row is derived from it. A pass that dies in between leaves
+             * a task nobody filed — visible through `node_get`, repairable by filing it — while the other
+             * order would leave a board row pointing at a node that was never written.
+             *
+             * The port is optional because the node service must not require a board to exist: the CLI
+             * and the bundle importer build one without that half of the world.
+             */
+            // ⚠️ `destinationBoard`, not `input.parentId`. Since #669 the parent may be another task, and
+            // filing the card under its parent's ID would put a subtask on a "board" that is a card.
+            if (created.kind === "task" && destinationBoard !== null) {
+                await deps.attachToBoard?.(actor, created.id, destinationBoard, timestamp);
+            }
+            return created;
         },
         async save(actor, input) {
             const existingId = await deps.repository.findIdempotentNode(actor.id, "node.save", input.idempotencyKey);
@@ -779,17 +947,43 @@ export function createNodes(deps) {
             const replayedId = await deps.repository.findIdempotentNode(actor.id, "node.update", input.idempotencyKey);
             if (replayedId)
                 return await requireVisible(actor, replayedId);
-            if (input.parentId !== undefined && input.parentId !== null) {
+            // ⚠️ `undefined` means "do not move" and is the only value that skips this. An explicit
+            // `null` IS a move — to the root — and has to be checked like any other destination; the
+            // first version of this treated the two the same and let a card be dragged to the top level.
+            if (input.parentId !== undefined) {
                 if (input.parentId === current.id) {
                     throw new IntelError(409, "move_cycle", "A node cannot contain itself");
                 }
-                const parent = await requireVisible(actor, input.parentId);
-                if (parent.kind !== "folder") {
-                    throw new IntelError(409, "parent_not_folder", "A node's parent must be a folder");
-                }
-                if (!(await deps.repository.can(actor, parent.id, "write"))) {
+                const parent = input.parentId === null ? null : await requireVisible(actor, input.parentId);
+                /**
+                 * ⚠️ **The write check on the destination comes FIRST, before the board is resolved.**
+                 * `boardOfTask` asks with the verb `write`, so for a destination this actor may only read
+                 * it answers `null` — and the refusal below would then say "this destination has no board"
+                 * about a card that has one perfectly well. The honest answer is 403, and it is the order
+                 * `packages/api/CLAUDE.md` prescribes anyway: capability, then resource, then action.
+                 */
+                if (parent !== null && !(await deps.repository.can(actor, parent.id, "write"))) {
                     throw new IntelError(403, "node_forbidden", "Destination folder cannot be edited");
                 }
+                const destinationBoard = await boardFor(deps, actor, parent);
+                /**
+                 * ⚠️ **A board that cannot be resolved is refused, not skipped.** Without this line an
+                 * installation whose board port is absent — or one where the actor may not write the
+                 * board — would answer `undefined`, the comparison below would read that as "not a move
+                 * between boards", and a card could be handed to any board at all. The integration test
+                 * `refuses the three ways a card could leave its board` caught exactly that: the test
+                 * harness did not wire the port, and door 3 stood open again.
+                 */
+                const currentBoard = current.kind === "task" ? ((await deps.boardOfTask?.(actor, current.id)) ?? null) : null;
+                if (current.kind === "task" && currentBoard === null) {
+                    throw new IntelError(409, "task_cannot_change_board", "This card's board cannot be resolved, so it cannot be moved. A card belongs to the board it was filed on.");
+                }
+                // Kind first, archive second — see the same pair in `create`.
+                refuseWrongParent(current.kind, parent, {
+                    destination: destinationBoard,
+                    current: currentBoard,
+                });
+                refuseArchivedParent(current.kind, parent);
             }
             const updatedAt = deps.now().toISOString();
             const updated = await deps.repository.updateNode({
@@ -837,6 +1031,27 @@ export function createNodes(deps) {
             // A replay does nothing a second time and answers with what the first run made.
             if (replayedId)
                 return await requireVisible(actor, replayedId);
+            /**
+             * ⚠️ **A task with live subtasks is refused, not archived with them** (#669).
+             * `destructive.md`: *verweigern schlägt kaskadieren* — a cascade turns one confirmed click
+             * into an unknown number of disappearances, and the question that was asked ("archive this
+             * card") cannot then name what actually vanishes.
+             *
+             * ⚠️ It is refused only ON THE WAY IN. Restoring a parent must stay possible, or a card
+             * archived together with its children by an older path could never come back.
+             *
+             * The other half — `purge` — needs no rule of its own, but ONLY together with
+             * `refuseArchivedParent` below: only an archived node may be purged, a parent cannot reach
+             * that state while a child is live, and nothing new may be filed under it afterwards. Take
+             * any one of the three away and a live card can be deleted for good without being named —
+             * which is what the review of #669 found in the first version of this sentence.
+             */
+            if (input.archived && current.kind === "task") {
+                const children = await deps.repository.countLiveChildren(current.id);
+                if (children > 0) {
+                    throw new IntelError(409, "task_has_subtasks", `This card still has ${children} subtask(s). Archive them first, or move them somewhere else — archiving a card does not archive what hangs under it.`);
+                }
+            }
             const updatedAt = deps.now().toISOString();
             const updated = await deps.repository.archiveNode({
                 nodeId: current.id,

package/dist/nodes/nodes.types.d.ts

@@ -55,6 +55,23 @@ export interface NodeRepository {
         limit: number;
     }): Promise<BoundedChildren>;
     getVisible(actor: Actor, nodeId: string): Promise<Node | null>;
+    /**
+     * How many live children this node has — **every kind, tasks included** (#669).
+     *
+     * ⚠️ **`listVisibleBounded` cannot answer this**, and the difference is invisible at the call
+     * site: that query runs through `visibleChildren`, which cuts `kind = 'task'` out of every level
+     * so a board shows no cards in the tree (D66). Asked about a task, it therefore answers `0` for
+     * every task that ever existed — a guard built on it would never fire once, and nothing would
+     * report that. Two queries with similar names are two different questions
+     * (`destructive.md`, `anchrd/intel#457`).
+     *
+     * ⚠️ **It takes no actor, and that is the second half of the same lesson.** A grant can sit on a
+     * single node (ADR-0004 §2), so a child may be invisible to whoever archives its parent. Counted
+     * through the visibility predicate, such a child reads as `0`, the refusal does not fire, the
+     * parent becomes purgeable — and the child is deleted for good without ever being named. The
+     * question here is "is anything still hanging under this node", not "what may this actor see".
+     */
+    countLiveChildren(nodeId: string): Promise<number>;
     listVisibleSubtree(actor: Actor, rootId: string | null): Promise<SubtreeNode[]>;
     can(actor: Actor, nodeId: string, verb: ResourceVerb): Promise<boolean>;
     findIdempotentNode(actorId: string, operation: "node.create" | "node.save" | "node.append" | "node.update" | "node.archive" | "node.share" | "node.revoke" | SnapshotOperation, idempotencyKey: string): Promise<string | null>;
@@ -213,6 +230,28 @@ export interface NodeAttachmentBody {
 }
 export interface NodesDeps {
     repository: NodeRepository;
+    /**
+     * Files a freshly created `task` node on the board it was created under (#648).
+     *
+     * ⚠️ Optional on purpose, and the optionality is the decision rather than a convenience: the node
+     * service is the one path every node takes, including in the CLI and the bundle importer, and
+     * neither of those has a board half of the world. A required port would make "create a node" fail
+     * where boards are not wired — and the answer to a missing board is that a task keeps its node
+     * and gets filed later, never that the node is refused.
+     */
+    attachToBoard?(actor: Actor, taskId: string, boardId: string, occurredAt: string): Promise<void>;
+    /**
+     * Which board a task belongs to (#669).
+     *
+     * ⚠️ Needed since a task may sit under another task: the destination of a move is then not the
+     * board itself, and "does this card change boards" cannot be answered from the node row alone.
+     *
+     * Optional for the same reason as `attachToBoard` — the CLI and the bundle importer have no
+     * board half. ⚠️ **Where it is absent, filing a task UNDER a task is refused** rather than
+     * allowed unchecked: the rule it would skip is the one that keeps a card from silently changing
+     * boards.
+     */
+    boardOfTask?(actor: Actor, taskId: string): Promise<string | null>;
     content: ContentStore;
     id(): string;
     now(): Date;

package/migrations/0022_a_cursor_over_the_journal.sql

@@ -0,0 +1,14 @@
+-- A change feed reads the journal in the order it happened, not by resource. The two indexes from
+-- 0000 both lead with a resource or an actor, so neither can serve "everything since position X":
+-- SQLite would have to scan and sort the whole table on every poll.
+--
+-- ⚠️ Both columns, in the order the cursor compares them. `occurred_at` alone is not enough and the
+-- shortfall is invisible: two events written in the same millisecond — the normal case inside one
+-- batch, not the exception — are indistinguishable, and a reader continuing past the timestamp
+-- skips the second one with no error and no log. The tie-break on `id` is what makes the position
+-- stable, and the index has to carry it or the sort falls back to a scan (anchrd/intel#620).
+--
+-- `resource_type` leads because every query names exactly one kind: today only node events can be
+-- listed at all, and flow events need a different visibility check before they could be.
+CREATE INDEX audit_events_feed_idx
+  ON audit_events(resource_type, occurred_at, id);

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/migrations/0024_the_archive_is_a_column.sql

@@ -0,0 +1,33 @@
+-- The archive as a column every board has (D68, #674).
+--
+-- ⚠️ Only the VISIBILITY is stored. Which cards are in the archive is `nodes.archived_at` and
+-- nothing else — a second column holding "is archived" would be the two truths D68 exists against.
+-- A card is in the archive column BECAUSE it is archived; dropping it there archives it, and
+-- pulling it out restores it into the working column `board_tasks.status` still names.
+--
+-- ⚠️ Default 1: the column is there on every board unless somebody hides it. A board that predates
+-- this migration therefore shows it too, which is the decided behaviour rather than an accident —
+-- an archive nobody can see is an archive nobody empties.
+ALTER TABLE boards ADD COLUMN archive_visible INTEGER NOT NULL DEFAULT 1;
+
+-- ⚠️ **Existing data.** Until this migration `BoardColumn.id` was a free string: a board could
+-- configure a column called `archived` itself. From here the name is reserved, and without this
+-- step such a board would show TWO columns with one id — the stored one and the derived one — and
+-- the cards of both would be indistinguishable.
+--
+-- ⚠️ **Every row with that status, not only the ones whose board still configures it.** Columns are
+-- REPLACED rather than merged, so a board may have used the column and dropped it again; those
+-- cards still carry `status = 'archived'` while `statuses_json` has long forgotten it. Left alone
+-- they would surface in the archive column with `archived_at` still `null` — a card that looks
+-- archived, is not, and cannot be restored, because there is nothing to restore.
+--
+-- The new name is deliberately ugly, because it is meant to be seen: whoever reads it knows
+-- something was renamed here and can put it right in the settings.
+UPDATE board_tasks SET status = 'archived_column_renamed' WHERE status = 'archived';
+
+UPDATE boards
+SET statuses_json = replace(statuses_json, '"id":"archived"', '"id":"archived_column_renamed"')
+WHERE node_id IN (
+  SELECT b.node_id FROM boards b, json_each(b.statuses_json)
+  WHERE json_extract(json_each.value, '$.id') = 'archived'
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.27.0",
+  "version": "0.29.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.24.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",