@anchrd/intel-api 0.28.0 → 0.29.0

package/dist/adapters/cloudflare/cloudflare.js

@@ -123,6 +123,10 @@ export default {
             // ⚠️ The REPOSITORY, not the board service — that is what keeps this from being a cycle. The
             // board service needs the node service to create a task; the node service needs only the two
             // reads below to file one.
+            // ⚠️ `"write"` for the same reason as below: this answers "may this actor file a card here",
+            // not "may they look at it". Reading it with `"read"` would let somebody nest a card under a
+            // task on a board they may only look at.
+            boardOfTask: async (who, taskId) => (await boardRepository.taskRow(who, taskId, "write"))?.boardId ?? null,
             attachToBoard: async (who, taskId, boardId, occurredAt) => {
                 // ⚠️ `"write"` — the actor is filing a task on this board, and the board's own creation
                 // path is a write too. `"read"` here would put back exactly the hole #649 found.

package/dist/adapters/db/db-boards.js

@@ -1,4 +1,4 @@
-import { BoardColumn } from "@anchrd/intel-contract/board";
+import { ARCHIVE_COLUMN_ID, BoardColumn } from "@anchrd/intel-contract/board";
 import { subtreeBindings, subtreeCte } from "./db-grants.js";
 function parseList(raw, of) {
     // The column is `NOT NULL DEFAULT '[]'`, but it is JSON written by this repository and read back
@@ -14,16 +14,28 @@ function parseList(raw, of) {
         return [];
     }
 }
-function mapTask(row) {
+function mapTask(row, boardId) {
     return {
         id: row.id,
         title: row.title,
-        status: row.status,
+        /**
+         * ⚠️ **An archived card reports the ARCHIVE column, not the one it came from** — that is what
+         * makes the column real instead of a label. `board_tasks.status` keeps naming the working
+         * column underneath, untouched, and that is what a card pulled back out returns to.
+         *
+         * A card archived over `node_archive`, without anybody dragging it, therefore appears here too.
+         * That is the test which tells this design apart from a second stored status (D68).
+         */
+        status: row.archived_at === null ? row.status : ARCHIVE_COLUMN_ID,
         assigneeId: row.assignee_id,
         labels: parseList(row.labels_json, "labels").filter((entry) => typeof entry === "string"),
         startDate: row.start_date,
         dueDate: row.due_date,
         dependsOn: row.depends_on,
+        // ⚠️ The board itself is not a parent TASK. A card filed directly on the board has
+        // `parent_id = boardId`, and handing that back as `parentTaskId` would make every top-level
+        // card claim to be a subtask of the board — a tree one level too deep, in every view.
+        parentTaskId: row.parent_id === boardId ? null : row.parent_id,
         position: row.position,
         archivedAt: row.archived_at,
     };
@@ -53,7 +65,8 @@ export function createBoardRepository(deps) {
         async read(actor, input) {
             const board = await deps.db
                 .prepare(`${subtreeCte}
-          SELECT n.id, n.title, COALESCE(b.statuses_json, '[]') AS statuses_json
+          SELECT n.id, n.title, COALESCE(b.statuses_json, '[]') AS statuses_json,
+                 COALESCE(b.archive_visible, 1) AS archive_visible
           FROM nodes n
           JOIN allowed ON allowed.id = n.id
           LEFT JOIN boards b ON b.node_id = n.id
@@ -64,7 +77,14 @@ export function createBoardRepository(deps) {
                 return null;
             const conditions = ["t.board_id = ?"];
             const bindings = [input.boardId];
-            if (input.status !== undefined) {
+            if (input.status === ARCHIVE_COLUMN_ID) {
+                // ⚠️ The archive column is not a stored status — `board_tasks.status` keeps naming the
+                // working column underneath (D68). Matched against `t.status` the filter would answer
+                // "nothing here" on a board full of visibly archived cards, and the column would look
+                // broken rather than empty.
+                conditions.push("n.archived_at IS NOT NULL");
+            }
+            else if (input.status !== undefined) {
                 conditions.push("t.status = ?");
                 bindings.push(input.status);
             }
@@ -83,11 +103,18 @@ export function createBoardRepository(deps) {
                 conditions.push("t.depends_on = ?");
                 bindings.push(input.dependsOn);
             }
-            if (!input.includeArchived)
+            /**
+             * ⚠️ **The archive column IS the archived cards** (D68, #674). While it is drawn they belong
+             * in the answer, or the column would always be empty and nobody could pull anything back out
+             * of it. `includeArchived` stays for the other direction: a caller — an agent, a report —
+             * that wants them even on a board where the column is hidden.
+             */
+            const archiveVisible = board.archive_visible !== 0;
+            if (!input.includeArchived && !archiveVisible)
                 conditions.push("n.archived_at IS NULL");
             const tasks = await deps.db
                 .prepare(`${subtreeCte}
-          SELECT n.id, n.title, t.status, t.assignee_id, t.labels_json,
+          SELECT n.id, n.title, n.parent_id, t.status, t.assignee_id, t.labels_json,
                  t.start_date, t.due_date, t.depends_on, t.position, n.archived_at
           FROM board_tasks t
           JOIN nodes n ON n.id = t.node_id
@@ -96,6 +123,10 @@ export function createBoardRepository(deps) {
           ORDER BY t.status, t.position, n.id`)
                 .bind(...walkBindings(actor, "read"), ...bindings)
                 .all();
+            // ⚠️ The CONFIGURED columns only. The archive column is appended by the service, after the
+            // fallback for an unconfigured board has been applied — appended here it would make every
+            // board look configured, and a board with no columns of its own would answer with the
+            // archive and nothing else.
             const columns = parseList(board.statuses_json, "columns")
                 .map((entry) => BoardColumn.safeParse(entry))
                 .filter((parsed) => parsed.success)
@@ -103,8 +134,9 @@ export function createBoardRepository(deps) {
             return {
                 boardId: board.id,
                 title: board.title,
+                archiveVisible,
                 columns,
-                tasks: (tasks.results ?? []).map(mapTask),
+                tasks: (tasks.results ?? []).map((row) => mapTask(row, board.id)),
             };
         },
         async columnsOf(actor, boardId, verb) {
@@ -124,13 +156,17 @@ export function createBoardRepository(deps) {
                 .filter((parsed) => parsed.success)
                 .map((parsed) => parsed.data.id);
         },
-        async setColumns(boardId, columnsJson, occurredAt) {
+        async setColumns(boardId, columnsJson, occurredAt, archiveVisible) {
+            // ⚠️ `COALESCE(?, archive_visible)` rather than a second statement: an absent flag means
+            // "leave it", and writing a default here would un-hide an archive somebody put away every
+            // time the columns are reordered.
             await deps.db
-                .prepare(`INSERT INTO boards (node_id, statuses_json, created_at, updated_at)
-          VALUES (?, ?, ?, ?)
+                .prepare(`INSERT INTO boards (node_id, statuses_json, archive_visible, created_at, updated_at)
+          VALUES (?, ?, COALESCE(?, 1), ?, ?)
           ON CONFLICT(node_id) DO UPDATE SET statuses_json = excluded.statuses_json,
+                                             archive_visible = COALESCE(?, boards.archive_visible),
                                              updated_at = excluded.updated_at`)
-                .bind(boardId, columnsJson, occurredAt, occurredAt)
+                .bind(boardId, columnsJson, archiveVisible === undefined ? null : Number(archiveVisible), occurredAt, occurredAt, archiveVisible === undefined ? null : Number(archiveVisible))
                 .run();
         },
         /**
@@ -154,7 +190,7 @@ export function createBoardRepository(deps) {
         async taskRow(actor, taskId, verb) {
             const row = await deps.db
                 .prepare(`${subtreeCte}
-          SELECT t.node_id, t.board_id, t.status, t.position
+          SELECT t.node_id, t.board_id, t.status, t.position, n.archived_at, n.updated_at
           FROM board_tasks t
           JOIN nodes n ON n.id = t.node_id
           JOIN allowed ON allowed.id = n.id
@@ -168,6 +204,8 @@ export function createBoardRepository(deps) {
                 boardId: row.board_id,
                 status: row.status,
                 position: row.position,
+                archivedAt: row.archived_at,
+                updatedAt: row.updated_at,
             };
         },
         /**

package/dist/adapters/db/db.js

@@ -176,6 +176,22 @@ export function createNodeRepository(deps) {
                 withChildren: rows.filter((row) => row.has_children === 1).map((row) => row.id),
             };
         },
+        /**
+         * ⚠️ Deliberately NOT `visibleChildren`: that builder cuts tasks out of every level, so it
+         * answers `0` for a task with any number of subtasks. This one asks the question the guard
+         * actually has — "is anything still hanging under this node".
+         */
+        async countLiveChildren(nodeId) {
+            // ⚠️ No `allowed` join, deliberately: a grant can sit on a single node, so a child may be
+            // invisible to whoever archives its parent. Filtered by visibility this answers `0`, the
+            // refusal does not fire, and the child is later purged without being named. A count leaks a
+            // number and nothing else; the alternative leaks the child itself, permanently.
+            const result = await deps.db
+                .prepare("SELECT COUNT(*) AS total FROM nodes WHERE parent_id = ? AND archived_at IS NULL")
+                .bind(nodeId)
+                .first();
+            return result?.total ?? 0;
+        },
         async listVisibleBounded(actor, input) {
             const result = await deps.db
                 .prepare(visibleChildren(true))

package/dist/boards/boards.d.ts

@@ -1,5 +1,19 @@
 import type { BoardDeps, BoardService } from "./boards.types.js";
+/**
+ * What a board with no configuration answers with. A board is usable the moment it is created, and
+ * nothing asks whoever made it to define columns before filing the first card.
+ *
+ * ⚠️ **This is the FALLBACK, not what a board made through the application gets.** Columns are
+ * shared data: two people on one board must read the same names, and the settings dialog edits one
+ * list. So the application writes them at creation, in the language of whoever created it (#675),
+ * and from then on they are data anybody can rename. This list only answers for a board nobody
+ * configured — one made over MCP, or one whose seeding did not land.
+ */
 export declare const DEFAULT_COLUMNS: readonly [{
+    readonly id: "backlog";
+    readonly title: "Backlog";
+    readonly terminal: false;
+}, {
     readonly id: "todo";
     readonly title: "Offen";
     readonly terminal: false;
@@ -12,5 +26,5 @@ export declare const DEFAULT_COLUMNS: readonly [{
     readonly title: "Fertig";
     readonly terminal: true;
 }];
-export declare const FIRST_DEFAULT_COLUMN: "todo";
+export declare const FIRST_DEFAULT_COLUMN: "backlog";
 export declare function createBoards(deps: BoardDeps): BoardService;

package/dist/boards/boards.js

@@ -1,7 +1,17 @@
+import { ARCHIVE_COLUMN_ID } from "@anchrd/intel-contract/board";
 import { IntelError } from "../shared/intel-error/intel-error.js";
-// What a board with no configuration answers with. A board is usable the moment it is created, and
-// nothing asks whoever made it to define columns before filing the first card.
+/**
+ * What a board with no configuration answers with. A board is usable the moment it is created, and
+ * nothing asks whoever made it to define columns before filing the first card.
+ *
+ * ⚠️ **This is the FALLBACK, not what a board made through the application gets.** Columns are
+ * shared data: two people on one board must read the same names, and the settings dialog edits one
+ * list. So the application writes them at creation, in the language of whoever created it (#675),
+ * and from then on they are data anybody can rename. This list only answers for a board nobody
+ * configured — one made over MCP, or one whose seeding did not land.
+ */
 export const DEFAULT_COLUMNS = [
+    { id: "backlog", title: "Backlog", terminal: false },
     { id: "todo", title: "Offen", terminal: false },
     { id: "doing", title: "Läuft", terminal: false },
     { id: "done", title: "Fertig", terminal: true },
@@ -35,7 +45,35 @@ export function createBoards(deps) {
         // A board that was never configured answers with the default columns rather than none. An empty
         // column list would render as a board with no columns at all — a screen with nowhere to put a
         // card, which looks broken rather than new.
-        return view.columns.length > 0 ? view : { ...view, columns: [...DEFAULT_COLUMNS] };
+        /**
+         * ⚠️ **A stored column may not claim the archive id, and the migration is not the only guard.**
+         * `0024` renames the ones that existed before the id was reserved, and `update` refuses new
+         * ones — but a row written straight into D1, or a migration that did not reach an installation,
+         * would still put two columns with one id in front of a reader. Dropping it here means the
+         * derived one always wins, which is the answer that cannot produce two.
+         */
+        const configured = (view.columns.length > 0 ? view.columns : [...DEFAULT_COLUMNS]).filter((column) => column.id !== ARCHIVE_COLUMN_ID);
+        /**
+         * ⚠️ **The archive column is appended here, after the fallback, and it is never stored.** A
+         * card is in it because `nodes.archived_at` is set; `board_tasks.status` keeps naming the
+         * working column underneath, which is what a card pulled back out returns to (D68).
+         *
+         * Always last, and not part of the list `board_update` writes: the archive is the same place on
+         * every board. A shelf that could be dragged between the working columns would be a shelf
+         * pretending to be a stage.
+         *
+         * ⚠️ **The title here is a fallback, not the label a reader sees.** Configured columns are
+         * shared data and are therefore written once in the creator's language (#675); this one is
+         * derived and identical on every board, so the browser says it in the reader's own words
+         * (`useBoard`). What travels is English, for everything without a catalog — MCP, an export, a
+         * report.
+         */
+        return {
+            ...view,
+            columns: view.archiveVisible
+                ? [...configured, { id: ARCHIVE_COLUMN_ID, title: "Archive", terminal: true }]
+                : configured,
+        };
     };
     const requireColumn = (columns, status) => {
         if (columns.includes(status))
@@ -56,7 +94,28 @@ export function createBoards(deps) {
             if (duplicate !== undefined) {
                 throw new IntelError(400, "duplicate_column", `The column id \`${duplicate}\` appears more than once.`);
             }
-            await deps.boards.setColumns(input.boardId, JSON.stringify(input.columns), deps.now().toISOString());
+            /**
+             * ⚠️ **The archive id cannot be claimed by a configured column.** It is derived — a card is in
+             * it because `archived_at` is set — so a stored column of the same id would give a board two
+             * columns with one id: every card in them lands in whichever the view draws first, and one of
+             * the two can never receive a card at all.
+             */
+            /**
+             * ⚠️ **Duplicate NAMES are refused here, not only in the dialog.** An id nobody sees may
+             * repeat without confusing anybody; a name is what a person reads, and two columns called the
+             * same thing cannot be told apart on the board, in the filter, or in the settings. Checked in
+             * the service because an agent calling `board_update` reaches no dialog — root `CLAUDE.md`:
+             * validation does not vary by surface.
+             */
+            const titles = input.columns.map((column) => column.title.trim());
+            const duplicateTitle = titles.find((title, index) => titles.indexOf(title) !== index);
+            if (duplicateTitle !== undefined) {
+                throw new IntelError(400, "duplicate_column_name", `Two columns are called \`${duplicateTitle}\`. A name is what tells them apart.`);
+            }
+            if (ids.includes(ARCHIVE_COLUMN_ID)) {
+                throw new IntelError(400, "reserved_column", `\`${ARCHIVE_COLUMN_ID}\` is the archive column, which every board has. Show or hide it instead of configuring it.`);
+            }
+            await deps.boards.setColumns(input.boardId, JSON.stringify(input.columns), deps.now().toISOString(), input.archiveVisible);
             return await viewOrRefuse(actor, { boardId: input.boardId, includeArchived: false });
         },
         async createTask(actor, input) {
@@ -67,11 +126,40 @@ export function createBoards(deps) {
             const status = input.status ?? columns[0] ?? DEFAULT_COLUMNS[0].id;
             if (input.status !== undefined)
                 requireColumn(columns, status);
+            /**
+             * ⚠️ **The parent's board must BE the board that was asked for**, checked here rather than
+             * left to the node path. `nodes.create` resolves the destination board from the parent, and
+             * on creation there is no previous board to compare it with — so a call naming board B with a
+             * parent on board A files the card on **A**, answers with the view of **B**, and the caller
+             * gets neither an error nor their card. The position would have been counted against B too.
+             */
+            if (input.parentTaskId !== null) {
+                // ⚠️ `"write"` for the same reason `attachToBoard` uses it — filing a card here is a write
+                // to that board. It is defence in depth rather than the only guard: `nodes.create` checks
+                // `write` on the parent node itself and answers 403 first, which is why a behaviour test
+                // cannot tell `"read"` from `"write"` here. Named so the next reader does not go looking
+                // for the test that proves it.
+                const parentRow = await deps.boards.taskRow(actor, input.parentTaskId, "write");
+                /**
+                 * ⚠️ **Only the wrong BOARD is refused here.** `taskRow` answers `null` for three different
+                 * things — the node does not exist, it is not a task, or this actor may not write it — and
+                 * each of those already has a precise answer further in: `404 node_not_found` from
+                 * `requireVisible`, `task_belongs_to_a_board` from `refuseWrongParent`, `403` from the
+                 * write check. Catching them here would answer "that parent card is not on this board" for
+                 * a card that does not exist, which claims it does.
+                 */
+                if (parentRow !== null && parentRow.boardId !== input.boardId) {
+                    throw new IntelError(409, "task_cannot_change_board", "That parent card is not on this board. A subtask belongs to the same board as the card it hangs under.");
+                }
+            }
             // ⚠️ Through the node service, not a second insert. The task gets the same authorization
             // check, the same audit row and the same version chain every other node gets — and that audit
             // row is what `anchrd/signals` reads (#620).
             const node = await deps.nodes.create(actor, {
-                parentId: input.boardId,
+                // ⚠️ A subtask's parent is the TASK, not the board — the hierarchy is the node tree (#669).
+                // The node service resolves which board that lands on and files the row there, so nothing
+                // here has to know: naming the board as parent would flatten every subtask on creation.
+                parentId: input.parentTaskId ?? input.boardId,
                 kind: "task",
                 title: input.title,
                 description: null,
@@ -117,7 +205,26 @@ export function createBoards(deps) {
             if (row === null) {
                 throw new IntelError(404, "task_not_found", "No task with this id is readable for you.");
             }
-            if (input.status !== undefined) {
+            /**
+             * ⚠️ **Dropping a card on the archive column archives it; pulling it out restores it** (D68).
+             * Neither writes `board_tasks.status`: the working column underneath is what a restored card
+             * returns to, and overwriting it with `archived` would be the second stored truth this
+             * design exists against.
+             *
+             * `nodes.archive` is the same door `node_archive` uses — one path, one audit row, one set of
+             * refusals (a card with live subtasks is still refused, #669).
+             */
+            const intoArchive = input.status === ARCHIVE_COLUMN_ID;
+            const outOfArchive = input.status !== undefined && !intoArchive && row.archivedAt !== null;
+            if (intoArchive || outOfArchive) {
+                await deps.nodes.archive(actor, {
+                    nodeId: input.taskId,
+                    baseUpdatedAt: row.updatedAt,
+                    archived: intoArchive,
+                    idempotencyKey: `${input.idempotencyKey}:archive`,
+                });
+            }
+            if (input.status !== undefined && !intoArchive) {
                 requireColumn(await columnsOrRefuse(actor, row.boardId, "write"), input.status);
             }
             // Only what arrived. An absent field means "leave it"; `null` where the column is nullable
@@ -129,9 +236,16 @@ export function createBoards(deps) {
                 // one would make two rows disagree about what a card is called.
                 throw new IntelError(400, "title_belongs_to_the_node", "Rename a task with `node_update`; the board row carries no title.");
             }
-            if (input.status !== undefined)
+            // ⚠️ Not for a drop into the archive: the working column stays as it is, so the card knows
+            // where to go back to.
+            if (input.status !== undefined && !intoArchive)
                 fields.status = input.status;
-            if (input.position !== undefined)
+            // ⚠️ Not for a drop into the archive either. The kanban sends a position with EVERY drop,
+            // computed from the neighbours inside the column it was dropped on — and inside the archive
+            // those are cards from all over the board. Taken, it would overwrite the card's place in the
+            // working column with a number that means nothing there. The status is guarded one line up;
+            // without this line the guard only covered half the write.
+            if (input.position !== undefined && !intoArchive)
                 fields.position = input.position;
             if (input.assigneeId !== undefined)
                 fields.assignee_id = input.assigneeId;
@@ -152,9 +266,17 @@ export function createBoards(deps) {
              * on every attempt while every call reported success. That is the idempotency the tool
              * promises with `idempotentHint: true`, kept by construction rather than by a key lookup.
              */
+            /**
+             * ⚠️ **Never for a drop into the archive**, and the reason is the same one that keeps
+             * `fields.status` unset there: `board_tasks.status` never holds `archived`, so
+             * `nextPosition(board, "archived")` counts zero rows and answers `1` — every time. The card
+             * keeps its working column but silently loses its place IN it, landing first among cards it
+             * used to sit behind. Nothing reports that, and the reader only sees it after restoring.
+             */
             if (input.status !== undefined &&
                 input.position === undefined &&
-                row.status !== input.status) {
+                row.status !== input.status &&
+                !intoArchive) {
                 fields.position = await deps.boards.nextPosition(row.boardId, input.status);
             }
             if (Object.keys(fields).length > 0) {

package/dist/boards/boards.types.d.ts

@@ -7,6 +7,15 @@ export interface BoardTaskRow {
     boardId: string;
     status: string;
     position: number;
+    /**
+     * From the NODE, not from `board_tasks` (D68, #674).
+     *
+     * ⚠️ Whether a card is archived is `nodes.archived_at` and nothing else. The row carries it so
+     * that a move can tell "into the archive" from "out of it" without a second read — and so that
+     * nobody is tempted to store the answer here, which would be the two truths D68 exists against.
+     */
+    archivedAt: string | null;
+    updatedAt: string;
 }
 export interface BoardTaskWrite {
     nodeId: string;
@@ -23,7 +32,12 @@ export interface BoardTaskWrite {
 export interface BoardRepository {
     read(actor: Actor, input: BoardGetInput): Promise<BoardView | null>;
     columnsOf(actor: Actor, boardId: string, verb: "read" | "write"): Promise<string[] | null>;
-    setColumns(boardId: string, columnsJson: string, occurredAt: string): Promise<void>;
+    /**
+     * ⚠️ `archiveVisible` is `undefined` for "leave it as it is" — the dialog that writes the columns
+     * and the switch that hides the archive are the same call, and a caller who only reorders columns
+     * must not silently un-hide an archive somebody put away.
+     */
+    setColumns(boardId: string, columnsJson: string, occurredAt: string, archiveVisible?: boolean): Promise<void>;
     attach(write: BoardTaskWrite): Promise<void>;
     taskRow(actor: Actor, taskId: string, verb: "read" | "write"): Promise<BoardTaskRow | null>;
     updateTask(taskId: string, fields: Record<string, string | number | null>, occurredAt: string): Promise<void>;
@@ -37,6 +51,17 @@ export interface BoardNodePort {
         description: null;
         idempotencyKey: string;
     }): Promise<Node>;
+    /**
+     * ⚠️ The same door `node_archive` uses. Dropping a card on the archive column must not become a
+     * second way to archive: one path means one audit row, one set of refusals — a card with live
+     * subtasks stays refused (#669) — and one answer to "what does archived mean".
+     */
+    archive(actor: Actor, input: {
+        nodeId: string;
+        baseUpdatedAt: string;
+        archived: boolean;
+        idempotencyKey: string;
+    }): Promise<Node>;
 }
 export interface BoardDeps {
     boards: BoardRepository;

package/dist/mcp/mcp.js

@@ -182,7 +182,7 @@ export async function handleMcp(request, deps) {
         }, async (input) => text(await deps.boards.get(actor, input)));
         server.registerTool("board_task_create", {
             title: "Add a card to a board",
-            description: "File a new card on a board. Omit the status to put it in the first column. The card is a node like any other — it has its own address, its own permissions and its own history.",
+            description: "File a new card on a board. Omit the status to put it in the first column. Name a parent task to make it a subtask — it lands on the same board, and moving an existing card under another one is `node_update` with a new parent. The card is a node like any other: its own address, its own permissions, its own history.",
             inputSchema: BoardTaskCreateInput,
             annotations: {
                 title: "Add a card to a board",
@@ -194,7 +194,7 @@ export async function handleMcp(request, deps) {
         }, async (input) => text(await deps.boards.createTask(actor, input)));
         server.registerTool("board_task_update", {
             title: "Change a card",
-            description: "Change a card's column, order, assignee, labels or dates. Moving a card is this call with a new status — send a position to place it, or leave it out to put it at the end of the column. An absent field is left alone; null clears one. Rename a card with node_update.",
+            description: "Change a card's column, order, assignee, labels or dates. Moving a card is this call with a new status — send a position to place it, or leave it out to put it at the end of the column. An absent field is left alone; null clears one. Rename a card with node_update. To move a card UNDER another card, use `node_update` with the other card as its parent — this tool changes what a card is, not where it hangs.",
             inputSchema: BoardTaskUpdateInput,
             annotations: {
                 title: "Change a card",

package/dist/nodes/nodes.js

@@ -83,20 +83,84 @@ function decodeBase64(value) {
  * ⚠️ 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.
  */
-function refuseWrongParent(childKind, parent, currentParentId) {
+/**
+ * ⚠️ **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.");
         }
-        if (parent.kind !== "board") {
+        // ⚠️ 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 merely a board. `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 (currentParentId !== undefined &&
-            currentParentId !== null &&
-            parent.id !== currentParentId) {
+        /**
+         * ⚠️ **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;
@@ -512,7 +576,12 @@ export function createNodes(deps) {
                  * than in a sweeper somebody has to remember to write.
                  */
                 if (existing.kind === "task" && existing.parentId !== null) {
-                    await deps.attachToBoard?.(actor, existing.id, existing.parentId, deps.now().toISOString());
+                    // ⚠️ 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;
             }
@@ -522,7 +591,13 @@ export function createNodes(deps) {
             // ⚠️ 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.
-            refuseWrongParent(input.kind, input.parentId === null ? null : await requireVisible(actor, input.parentId));
+            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();
             const created = await deps.repository.insertNode({
                 node: {
@@ -556,8 +631,10 @@ export function createNodes(deps) {
              * 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.
              */
-            if (created.kind === "task" && input.parentId !== null) {
-                await deps.attachToBoard?.(actor, created.id, input.parentId, timestamp);
+            // ⚠️ `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;
         },
@@ -878,10 +955,35 @@ export function createNodes(deps) {
                     throw new IntelError(409, "move_cycle", "A node cannot contain itself");
                 }
                 const parent = input.parentId === null ? null : await requireVisible(actor, input.parentId);
-                refuseWrongParent(current.kind, parent, current.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({
@@ -929,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>;
@@ -223,6 +240,18 @@ export interface NodesDeps {
      * 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/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.28.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.23.0",
+    "@anchrd/intel-contract": "^0.24.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",