@anchrd/intel-api 0.26.0 → 0.28.0

package/dist/boards/boards.js

@@ -0,0 +1,166 @@
+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.
+export const DEFAULT_COLUMNS = [
+    { id: "todo", title: "Offen", terminal: false },
+    { id: "doing", title: "Läuft", terminal: false },
+    { id: "done", title: "Fertig", terminal: true },
+];
+// The column a card lands in when nobody said and the board has none configured. One export rather
+// than the literal `"todo"` in three places: the fallback exists FOR the unconfigured board, so a
+// copy of it would drift exactly where it is the only thing deciding.
+export const FIRST_DEFAULT_COLUMN = DEFAULT_COLUMNS[0].id;
+export function createBoards(deps) {
+    /**
+     * ⚠️ The one place "which board, and may this actor DO THIS to it" is answered — and the verb is
+     * the whole question. It asked `read` for every caller once, including the three that were about
+     * to write: a board shared read-only could have its columns replaced and its cards moved. The
+     * refusal existed and asked the wrong thing, which is the harder failure to see.
+     *
+     * A `404` rather than a `403`, on purpose: "this board exists but you may not touch it" is itself
+     * information about somebody else's tree.
+     */
+    const columnsOrRefuse = async (actor, boardId, verb) => {
+        const columns = await deps.boards.columnsOf(actor, boardId, verb);
+        if (columns === null) {
+            throw new IntelError(404, "board_not_found", "No board with this id is readable for you.");
+        }
+        return columns.length > 0 ? columns : DEFAULT_COLUMNS.map((column) => column.id);
+    };
+    const viewOrRefuse = async (actor, input) => {
+        const view = await deps.boards.read(actor, input);
+        if (view === null) {
+            throw new IntelError(404, "board_not_found", "No board with this id is readable for you.");
+        }
+        // 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] };
+    };
+    const requireColumn = (columns, status) => {
+        if (columns.includes(status))
+            return;
+        throw new IntelError(400, "unknown_column", `This board has no column \`${status}\`. Its columns are: ${columns.join(", ")}.`);
+    };
+    return {
+        async get(actor, input) {
+            return await viewOrRefuse(actor, input);
+        },
+        async update(actor, input) {
+            await columnsOrRefuse(actor, input.boardId, "write");
+            // ⚠️ Duplicate ids are refused rather than deduplicated. Two columns with one id means every
+            // card in them lands in whichever the view draws first, and silently dropping one would
+            // discard a column somebody just wrote.
+            const ids = input.columns.map((column) => column.id);
+            const duplicate = ids.find((id, index) => ids.indexOf(id) !== index);
+            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());
+            return await viewOrRefuse(actor, { boardId: input.boardId, includeArchived: false });
+        },
+        async createTask(actor, input) {
+            const columns = await columnsOrRefuse(actor, input.boardId, "write");
+            // Absent means the first column — a caller who does not care where a task starts should not
+            // have to read the board first. A named one is checked, because a typo would otherwise create
+            // a card in a column no view draws.
+            const status = input.status ?? columns[0] ?? DEFAULT_COLUMNS[0].id;
+            if (input.status !== undefined)
+                requireColumn(columns, status);
+            // ⚠️ 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,
+                kind: "task",
+                title: input.title,
+                description: null,
+                idempotencyKey: input.idempotencyKey,
+            });
+            /**
+             * ⚠️ **`update`, not `attach` — the row already exists by the time this line runs**, and
+             * getting that wrong is silent. `nodes.create` files every new task through `attachToBoard`,
+             * with the board's first column and no fields; a second `INSERT` here is refused by the
+             * primary key, `ON CONFLICT DO NOTHING` swallows the refusal, and the caller's `status`,
+             * assignee and dates are **discarded without an error**. The card lands in the wrong column
+             * and nothing anywhere says why.
+             *
+             * It was written as an insert first, and three tests caught it: a card created in `doing`
+             * came back in `todo`. The lesson is the shape rather than the line — one row, one writer,
+             * and the writer is the node path.
+             */
+            /**
+             * ⚠️ **The position is computed only when the card is not already in that column**, and that
+             * is what makes a retry safe. `deps.nodes.create` honours the idempotency key and answers with
+             * the SAME node on a replay; recomputing here would push the card one place further on every
+             * attempt — a client retrying a timeout would watch its card walk down the column, with every
+             * call succeeding.
+             *
+             * The other fields are rewritten with the same values, which is idempotent by construction.
+             */
+            const filed = await deps.boards.taskRow(actor, node.id, "write");
+            await deps.boards.updateTask(node.id, {
+                status,
+                assignee_id: input.assigneeId,
+                labels_json: JSON.stringify(input.labels),
+                start_date: input.startDate,
+                due_date: input.dueDate,
+                depends_on: input.dependsOn,
+                ...(filed?.status === status
+                    ? {}
+                    : { position: await deps.boards.nextPosition(input.boardId, status) }),
+            }, deps.now().toISOString());
+            return await viewOrRefuse(actor, { boardId: input.boardId, includeArchived: false });
+        },
+        async updateTask(actor, input) {
+            const row = await deps.boards.taskRow(actor, input.taskId, "write");
+            if (row === null) {
+                throw new IntelError(404, "task_not_found", "No task with this id is readable for you.");
+            }
+            if (input.status !== undefined) {
+                requireColumn(await columnsOrRefuse(actor, row.boardId, "write"), input.status);
+            }
+            // Only what arrived. An absent field means "leave it"; `null` where the column is nullable
+            // means "clear it", which is why the check is against `undefined` and not against falsiness —
+            // `dueDate: null` and `position: 0` both have to get through.
+            const fields = {};
+            if (input.title !== undefined) {
+                // ⚠️ The title lives on the NODE, not here. `board_tasks` has no title column, and adding
+                // 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)
+                fields.status = input.status;
+            if (input.position !== undefined)
+                fields.position = input.position;
+            if (input.assigneeId !== undefined)
+                fields.assignee_id = input.assigneeId;
+            if (input.labels !== undefined)
+                fields.labels_json = JSON.stringify(input.labels);
+            if (input.startDate !== undefined)
+                fields.start_date = input.startDate;
+            if (input.dueDate !== undefined)
+                fields.due_date = input.dueDate;
+            if (input.dependsOn !== undefined)
+                fields.depends_on = input.dependsOn;
+            /**
+             * A move that names a new column but no position lands at the end of it — otherwise the card
+             * would keep the number it had in its old column and appear at an arbitrary place.
+             *
+             * ⚠️ **Only when the column actually CHANGES.** Asking again for the column a card is already
+             * in is what a retry looks like, and recomputing there would move the card one place further
+             * 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.
+             */
+            if (input.status !== undefined &&
+                input.position === undefined &&
+                row.status !== input.status) {
+                fields.position = await deps.boards.nextPosition(row.boardId, input.status);
+            }
+            if (Object.keys(fields).length > 0) {
+                await deps.boards.updateTask(input.taskId, fields, deps.now().toISOString());
+            }
+            return await viewOrRefuse(actor, { boardId: row.boardId, includeArchived: false });
+        },
+    };
+}

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

@@ -0,0 +1,51 @@
+import type { BoardGetInput, BoardTaskCreateInput, BoardTaskUpdateInput, BoardUpdateInput, BoardView } from "@anchrd/intel-contract/board";
+import type { Node } from "@anchrd/intel-contract/node";
+import type { Actor } from "../nodes/nodes.types.js";
+export type { BoardView };
+export interface BoardTaskRow {
+    nodeId: string;
+    boardId: string;
+    status: string;
+    position: number;
+}
+export interface BoardTaskWrite {
+    nodeId: string;
+    boardId: string;
+    status: string;
+    assigneeId: string | null;
+    labels: string[];
+    startDate: string | null;
+    dueDate: string | null;
+    dependsOn: string | null;
+    position: number;
+    occurredAt: string;
+}
+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>;
+    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>;
+    nextPosition(boardId: string, status: string): Promise<number>;
+}
+export interface BoardNodePort {
+    create(actor: Actor, input: {
+        parentId: string;
+        kind: "task";
+        title: string;
+        description: null;
+        idempotencyKey: string;
+    }): Promise<Node>;
+}
+export interface BoardDeps {
+    boards: BoardRepository;
+    nodes: BoardNodePort;
+    now(): Date;
+}
+export interface BoardService {
+    get(actor: Actor, input: BoardGetInput): Promise<BoardView>;
+    update(actor: Actor, input: BoardUpdateInput): Promise<BoardView>;
+    createTask(actor: Actor, input: BoardTaskCreateInput): Promise<BoardView>;
+    updateTask(actor: Actor, input: BoardTaskUpdateInput): Promise<BoardView>;
+}

package/dist/boards/boards.types.js

@@ -0,0 +1 @@
+export {};

package/dist/build/build.js

@@ -18,11 +18,20 @@ const defaultLogo = `export const customLogoUrl: string | null = null;\n`;
 //
 // Without it every asset answers with the platform default `public, max-age=0, must-revalidate`,
 // and `public` lets a browser store an ERROR answer too. A `403` that appears once during setup is
-// then replayed on every navigation WITHOUT a request leaving the browser — invisible in the worker
+// then replayed on BACK/FORWARD WITHOUT a request leaving the browser — invisible in the worker
 // log, in the Cloudflare Access log, in the firewall and in Cloudflare Analytics, while `curl`
 // against the same address keeps answering `200`. The second rule matters more here than in Gate:
 // the UI ships 1.9 MB of fingerprinted assets that are revalidated on every navigation today.
 //
+// ⚠️ The ERROR answer is NOT replayed on every navigation — that is the asset line right above, a
+// different statement about `/assets/*`, and it stays as it is. The narrower shape is what makes
+// this expensive to diagnose: `must-revalidate` DOES hold for a fresh navigation, so retyping the
+// address returns the REPAIRED page (`200 /` in the worker log), while a history navigation replays
+// the stored answer without any freshness check (`transferSize: 0`). Measured in Chromium with a
+// real cache, anchrd/gate#399. Whoever retypes the address rules the browser cache out and loses
+// the afternoon of anchrd/gate#329 a second time — going BACK is the only handle that shows the
+// frozen answer.
+//
 // ⚠️ `! Cache-Control` is not decoration, and the naive two-rule form from the ticket is WRONG.
 // A request matching several rules inherits ALL their headers, and a header named twice is joined
 // with a comma. Measured against `wrangler dev` 4.112.0 with both spellings side by side:

package/dist/http/http.js

@@ -1,3 +1,5 @@
+import { AuditListRequest } from "@anchrd/intel-contract/audit";
+import { BoardGetInput, BoardTaskCreateInput, BoardTaskUpdateInput, BoardUpdateInput, } from "@anchrd/intel-contract/board";
 import { ArchiveFlowInput, CreateFlowInput, GetFlowInput, GetFlowVersionInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, PurgeFlowInput, RelationGraphInput, SaveFlowVersionInput, UnpublishFlowInput, UpdateFlowInput, } from "@anchrd/intel-contract/flow";
 import { CancelFlowRunInput, CompleteFlowRunStepInput, GetFlowRunInput, ListFlowRunsInput, StartFlowRunInput, } from "@anchrd/intel-contract/flow-run";
 import { ArchiveNodeInput, CreateNodeInput, GetNodeInput, GetNodeVersionInput, ListNodesInput, NodeGraphInput, PurgeNodeInput, PurgeNodePreviewInput, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "@anchrd/intel-contract/node";
@@ -204,6 +206,71 @@ export function createHttp(deps) {
         const input = GetNodeInput.parse({ nodeId: context.req.param("nodeId") });
         return zipResponse(await deps.bundle.exportSubtree(asBundleActor(auth), input.nodeId));
     });
+    // The change journal, read forward from a stable position (#620). `nodes/read` and nothing new:
+    // an audit row about a node says the same thing the node says, so a second capability would be a
+    // second answer to one question. The per-row check is the service's, and it is the same tree walk
+    // the node reads go through.
+    //
+    // ⚠️ GET with the cursor in the query string, because the verb is one of the four in the grammar
+    // and the method carries it. `limit` arrives as a string and is coerced here — the contract
+    // wants a number, and a query string has none.
+    app.get("/audit", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        const limit = context.req.query("limit");
+        const after = context.req.query("after");
+        const input = AuditListRequest.parse({
+            resourceType: context.req.query("resourceType"),
+            ...(after === undefined ? {} : { after }),
+            ...(limit === undefined ? {} : { limit: Number(limit) }),
+        });
+        return context.json(await deps.audit.list(asActor(auth), input));
+    });
+    // The whole board in one answer (#648). `nodes/read` and nothing new: a board is a node, and a
+    // card is a node — a second capability would be a second answer to one question.
+    //
+    // ⚠️ Every filter is a query parameter and every one of them reaches the WHERE. Filtering after
+    // the read would have carried other people's cards over the wire first.
+    app.get("/boards/:boardId", async (context) => {
+        const auth = requireCapability(context, "nodes", "read");
+        const query = context.req.query();
+        const input = BoardGetInput.parse({
+            boardId: context.req.param("boardId"),
+            ...(query.status === undefined ? {} : { status: query.status }),
+            ...(query.assigneeId === undefined ? {} : { assigneeId: query.assigneeId }),
+            ...(query.dueBefore === undefined ? {} : { dueBefore: query.dueBefore }),
+            ...(query.dependsOn === undefined ? {} : { dependsOn: query.dependsOn }),
+            ...(query.includeArchived === undefined
+                ? {}
+                : { includeArchived: query.includeArchived === "true" }),
+        });
+        return context.json(await deps.boards.get(asActor(auth), input));
+    });
+    app.patch("/boards/:boardId", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const input = BoardUpdateInput.parse(await context.req.json().catch(() => null));
+        if (input.boardId !== context.req.param("boardId")) {
+            throw new IntelError(400, "board_id_mismatch", "Path and body board IDs differ");
+        }
+        return context.json(await deps.boards.update(asActor(auth), input));
+    });
+    app.post("/boards/:boardId/tasks", async (context) => {
+        const auth = requireCapability(context, "nodes", "create");
+        const input = BoardTaskCreateInput.parse(await context.req.json().catch(() => null));
+        if (input.boardId !== context.req.param("boardId")) {
+            throw new IntelError(400, "board_id_mismatch", "Path and body board IDs differ");
+        }
+        return context.json(await deps.boards.createTask(asActor(auth), input), 201);
+    });
+    // ⚠️ `PATCH` on the task, not `POST …/move`. Moving a card IS an update of `status` and
+    // `position`; a second address for it would be a second way to write one row.
+    app.patch("/boards/:boardId/tasks/:taskId", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const input = BoardTaskUpdateInput.parse(await context.req.json().catch(() => null));
+        if (input.taskId !== context.req.param("taskId")) {
+            throw new IntelError(400, "task_id_mismatch", "Path and body task IDs differ");
+        }
+        return context.json(await deps.boards.updateTask(asActor(auth), input));
+    });
     app.get("/nodes/:nodeId/versions", async (context) => {
         const auth = requireCapability(context, "nodes", "read");
         return context.json(await deps.nodes.listVersions(asActor(auth), context.req.param("nodeId")));

package/dist/http/http.types.d.ts

@@ -1,5 +1,7 @@
 import type { GateClient } from "@anchrd/gate-sdk";
+import type { AuditService } from "../audit/audit.types.js";
 import type { BrowserAuth } from "../auth/auth.types.js";
+import type { BoardService } from "../boards/boards.types.js";
 import type { BundleService } from "../bundle/bundle.types.js";
 import type { FlowService } from "../flows/flows.types.js";
 import type { NodeService } from "../nodes/nodes.types.js";
@@ -10,6 +12,8 @@ export interface HttpDeps {
     flows: FlowService;
     tools: ToolService;
     bundle: BundleService;
+    audit: AuditService;
+    boards: BoardService;
     resource: string;
     resourceMetadataUrl: string;
     auth?: Pick<BrowserAuth, "resolve">;

package/dist/intel/intel.js

@@ -134,6 +134,8 @@ export function createIntel(deps) {
         flows: deps.flows,
         tools: deps.tools,
         bundle: deps.bundle,
+        audit: deps.audit,
+        boards: deps.boards,
         resource,
         resourceMetadataUrl,
         ...(deps.auth ? { auth: deps.auth } : {}),
@@ -181,6 +183,8 @@ export function createIntel(deps) {
             nodes: deps.nodes,
             tools: deps.tools,
             bundle: deps.bundle,
+            audit: deps.audit,
+            boards: deps.boards,
         });
     });
     return app;

package/dist/intel/intel.types.d.ts

@@ -1,5 +1,7 @@
 import type { GateClient } from "@anchrd/gate-sdk";
+import type { AuditService } from "../audit/audit.types.js";
 import type { BrowserAuth } from "../auth/auth.types.js";
+import type { BoardService } from "../boards/boards.types.js";
 import type { BundleService } from "../bundle/bundle.types.js";
 import type { FlowService } from "../flows/flows.types.js";
 import type { NodeService } from "../nodes/nodes.types.js";
@@ -12,5 +14,7 @@ export interface IntelDeps {
     flows: FlowService;
     tools: ToolService;
     bundle: BundleService;
+    audit: AuditService;
+    boards: BoardService;
     auth?: BrowserAuth;
 }

package/dist/mcp/mcp.js

@@ -1,4 +1,6 @@
 import { IdempotencyKey, IntelId } from "@anchrd/intel-contract";
+import { AuditListRequest } from "@anchrd/intel-contract/audit";
+import { BoardGetInput, BoardTaskCreateInput, BoardTaskUpdateInput, BoardUpdateInput, } from "@anchrd/intel-contract/board";
 import { ArchiveFlowInput, CreateFlowInput, GetFlowInput, GetFlowVersionInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, PurgeFlowInput, RelationGraphInput, SaveFlowVersionInput, UnpublishFlowInput, UpdateFlowInput, } from "@anchrd/intel-contract/flow";
 import { CancelFlowRunInput, CompleteFlowRunStepInput, GetFlowRunInput, ListFlowRunsInput, StartFlowRunInput, } from "@anchrd/intel-contract/flow-run";
 import { ArchiveNodeInput, CreateNodeInput, GetNodeInput, GetNodeVersionInput, ListNodesInput, NodeGraphInput, PurgeNodeInput, PurgeNodePreviewInput, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "@anchrd/intel-contract/node";
@@ -156,6 +158,76 @@ export async function handleMcp(request, deps) {
         name: deps.authorization.identity.name ?? null,
     }));
     if (permits(deps.authorization, "nodes", "read")) {
+        // The change journal, read forward from a stable position (#620). It is what makes Intel the
+        // simplest of all signal sources: a consumer keeps its own cursor and asks what happened since,
+        // and Intel never learns that the consumer exists. That is the D24 test passed rather than
+        // argued — remove every reader and nothing piles up here.
+        //
+        // ⚠️ `nodes/read`, not a capability of its own. An audit row about a node says the same thing
+        // the node says; a second capability would be a second answer to one question, and the two
+        // would drift.
+        // The board as one answer (#648). Four tools, not five: a move is an update of `status` and
+        // `position`, and deleting a task is `node_archive` — nothing here removes a `nodes` row.
+        server.registerTool("board_get", {
+            title: "Read a board",
+            description: "Read one board in a single answer: its columns and every card you may see, without the card bodies. Filter by column, assignee, due date or what a card waits for — each filter narrows the query itself. Open a card's text with node_version_get.",
+            inputSchema: BoardGetInput,
+            annotations: {
+                title: "Read a board",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, 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.",
+            inputSchema: BoardTaskCreateInput,
+            annotations: {
+                title: "Add a card to a board",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: false,
+            },
+        }, 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.",
+            inputSchema: BoardTaskUpdateInput,
+            annotations: {
+                title: "Change a card",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.boards.updateTask(actor, input)));
+        server.registerTool("board_update", {
+            title: "Set a board's columns",
+            description: "Replace a board's column list, in order. Columns are replaced rather than merged, so send the complete list. A column marked terminal is one where a card counts as finished.",
+            inputSchema: BoardUpdateInput,
+            annotations: {
+                title: "Set a board's columns",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.boards.update(actor, input)));
+        server.registerTool("audit_list", {
+            title: "List change events",
+            description: "Read the change journal forward from a stable position: what happened to the nodes you may read, oldest first. Pass `nextCursor` back as `after` to continue where you stopped; a null `nextCursor` means you have caught up. Only node events can be listed — flow events need their own visibility check and are refused rather than left out. Events about permanently deleted nodes are never returned, to anybody.",
+            inputSchema: AuditListRequest,
+            annotations: {
+                title: "List change events",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.audit.list(actor, input)));
         server.registerTool("node_list", {
             title: "List nodes",
             description: "List authorized folders, documents, attachments, and tables under one parent.",

package/dist/mcp/mcp.types.d.ts

@@ -1,4 +1,6 @@
 import type { Authorized } from "@anchrd/gate-sdk";
+import type { AuditService } from "../audit/audit.types.js";
+import type { BoardService } from "../boards/boards.types.js";
 import type { BundleService } from "../bundle/bundle.types.js";
 import type { FlowService } from "../flows/flows.types.js";
 import type { NodeService } from "../nodes/nodes.types.js";
@@ -14,4 +16,6 @@ export interface McpDeps {
     flows: FlowService;
     tools: ToolService;
     bundle: BundleService;
+    audit: AuditService;
+    boards: BoardService;
 }

package/dist/nodes/nodes.js

@@ -62,6 +62,55 @@ 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.
+ */
+function refuseWrongParent(childKind, parent, currentParentId) {
+    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") {
+            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) {
+            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 +495,36 @@ 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) {
+                    await deps.attachToBoard?.(actor, existing.id, existing.parentId, 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.
+            refuseWrongParent(input.kind, input.parentId === null ? null : await requireVisible(actor, input.parentId));
             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 +541,25 @@ 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.
+             */
+            if (created.kind === "task" && input.parentId !== null) {
+                await deps.attachToBoard?.(actor, created.id, input.parentId, timestamp);
+            }
+            return created;
         },
         async save(actor, input) {
             const existingId = await deps.repository.findIdempotentNode(actor.id, "node.save", input.idempotencyKey);
@@ -779,15 +870,16 @@ 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);
+                refuseWrongParent(current.kind, parent, current.parentId);
+                if (parent !== null && !(await deps.repository.can(actor, parent.id, "write"))) {
                     throw new IntelError(403, "node_forbidden", "Destination folder cannot be edited");
                 }
             }

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

@@ -213,6 +213,16 @@ 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>;
     content: ContentStore;
     id(): string;
     now(): Date;