@anchrd/intel-api 0.12.0 → 0.12.2

package/dist/nodes/nodes.js

@@ -1,7 +1,8 @@
-import { AgentDefinition, AgentMediaType, agentReferenceAccepts, TableMediaType, } from "@anchrd/intel-contract";
+import { AgentDefinition, AgentMediaType, agentReferenceAccepts, BoardDocument, BoardMediaType, TableMediaType, } from "@anchrd/intel-contract";
 import { encodeCsv, parseCsv } from "../shared/csv/csv.js";
 import { IntelError } from "../shared/intel-error/intel-error.js";
 import { plainTitle } from "../shared/plain-title/plain-title.js";
+import { createBoard } from "./board/board.js";
 import { documentLinkTargets } from "./document-links/document-links.js";
 // ⚠️ The R2 key of a version written before #125 begins `knowledge/`, and it stays that way. A key
 // is stored in `node_versions.content_key` and read back from there; nothing derives one from ids,
@@ -81,6 +82,9 @@ function decodeBase64(value) {
     }
 }
 export function createNodes(deps) {
+    // Made here rather than passed in: the board's rules need nothing this service does not already
+    // have, and a caller who could substitute them could substitute the cycle checks with them.
+    const board = createBoard({ id: () => deps.id() });
     function mergeSearchResults(lexical, semantic, semanticScores, limit) {
         const merged = new Map();
         for (const citation of lexical) {
@@ -246,7 +250,7 @@ export function createNodes(deps) {
         await deps.content.put(contentKey, input.body, TableMediaType);
         let saved;
         try {
-            saved = await deps.repository.appendTableSnapshot({
+            saved = await deps.repository.appendSnapshotVersion({
                 version,
                 actorId: input.actor.id,
                 baseVersionId: input.baseVersionId,
@@ -453,6 +457,234 @@ export function createNodes(deps) {
         }
         return node;
     }
+    // ── Boards (#285) ──────────────────────────────────────────────────────────────────────────────
+    // How often one task operation may meet a board that moved under it before it gives up. Every
+    // round is a fresh read and the SAME operation applied again — see `applyToBoard` for why that is
+    // the point rather than a retry loop hiding a race.
+    const boardWriteAttempts = 5;
+    function parseStoredBoard(body) {
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            throw new IntelError(500, "board_unreadable", "The stored board cannot be read");
+        }
+        const document = BoardDocument.safeParse(parsed);
+        // ⚠️ Loud, unlike the tolerant read the share warning makes of an agent definition. A board IS
+        // its document: answering with an empty one would show somebody a board with no tasks on it,
+        // and the next write would store that as the truth.
+        if (!document.success) {
+            throw new IntelError(500, "board_unreadable", "The stored board cannot be read");
+        }
+        return document.data;
+    }
+    /**
+     * The board a node currently holds.
+     *
+     * ⚠️ A board with no version yet answers with the DEFAULTS rather than with nothing (#285). A
+     * fresh board already has its five columns — the same way a fresh table answers with no header
+     * instead of refusing — and the first write is what puts them into R2. Nothing has to be created
+     * twice for a board to be usable the moment it exists.
+     */
+    async function boardDocumentOf(node) {
+        if (node.currentVersionId === null)
+            return board.defaultBoard();
+        const version = await deps.repository.getVersion(node.currentVersionId);
+        if (!version)
+            throw new IntelError(500, "version_missing", "Current version is missing");
+        const body = await deps.content.get(version.contentKey);
+        if (body === null)
+            throw new IntelError(500, "content_missing", "Version content is missing");
+        return parseStoredBoard(body);
+    }
+    async function requireBoard(actor, nodeId) {
+        const node = await requireVisible(actor, nodeId);
+        if (node.kind !== "board") {
+            throw new IntelError(409, "not_a_board", "Only boards accept task operations");
+        }
+        if (!(await deps.repository.can(actor, node.id, "write"))) {
+            throw new IntelError(403, "node_forbidden", "Board cannot be edited");
+        }
+        return node;
+    }
+    /**
+     * What a task points at outside its own board, checked before anything is written (#285).
+     *
+     * ⚠️ Here rather than in `board.ts`, because both questions are reads against the tree and its
+     * ACL, and the board module is deliberately pure. A reference is refused when this actor cannot
+     * see it — with one wording for "there is no such node" and "you may not see it", because telling
+     * them apart would confirm the existence of a node somebody has no access to (#41).
+     */
+    async function checkBoardTargets(actor, task) {
+        const references = [...new Set(task.references)];
+        if (references.length > 0) {
+            const visible = new Set((await deps.repository.resolveVisibleTitles(actor, references)).map((entry) => entry.nodeId));
+            const missing = references.filter((reference) => !visible.has(reference));
+            if (missing.length > 0) {
+                throw new IntelError(422, "board_reference_unknown", `A reference has to name a node you can see, and ${missing.length === 1 ? "one does" : `${missing.length} do`} not`);
+            }
+        }
+        if (task.assignee?.type === "agent") {
+            const assignee = await deps.repository.getVisible(actor, task.assignee.nodeId);
+            if (assignee?.kind !== "agent") {
+                throw new IntelError(422, "board_assignee_unknown", "An agent assignee has to name an agent you can see");
+            }
+        }
+    }
+    /**
+     * One new board version, or `null` when somebody wrote in between.
+     *
+     * ⚠️ `segment` is `null`, like a document's and unlike a table's (#135): every version here holds
+     * the whole board, so there is nothing for a snapshot to mark off from what came before it.
+     *
+     * ⚠️ `baseVersionId` is the version this service just read, never one a caller sent. It is the
+     * board's optimistic lock and it is entirely internal — see `applyToBoard`.
+     *
+     * ⚠️ The R2 object is written before the version row and deleted again if the row does not land,
+     * the same order `save` keeps: an orphaned object is invisible, while a version row pointing at
+     * nothing is a board that cannot be read at all.
+     */
+    async function writeBoardVersion(input) {
+        const body = JSON.stringify(input.document);
+        const versionId = deps.id();
+        const contentKey = contentKeyFor(input.node.id, versionId);
+        const version = {
+            id: versionId,
+            nodeId: input.node.id,
+            sequence: await nextSequence(input.node),
+            contentKey,
+            mediaType: BoardMediaType,
+            contentHash: await deps.hash(body),
+            size: new TextEncoder().encode(body).byteLength,
+            segment: null,
+            createdBy: input.actor.id,
+            createdAt: deps.now().toISOString(),
+        };
+        await deps.content.put(contentKey, body, BoardMediaType);
+        let saved;
+        try {
+            saved = await deps.repository.appendSnapshotVersion({
+                version,
+                actorId: input.actor.id,
+                baseVersionId: input.node.currentVersionId,
+                operation: input.operation,
+                metadata: input.metadata,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+        }
+        catch (error) {
+            await deps.content.delete(contentKey).catch(() => undefined);
+            // ⚠️ The same key at the same moment, from the caller's own retry. `idempotency_keys` is keyed
+            // by (actor, operation, key), so the second write's row collides and D1 rolls the whole batch
+            // back — which is the right outcome and the wrong error. The first write owns the act; this
+            // one reports a conflict so the caller answers with it, exactly as `appendTableVersion` does
+            // one layer down. Anything else is a real failure and still raises.
+            const owned = await deps.repository.findIdempotentNode(input.actor.id, input.operation, input.idempotencyKey);
+            if (owned === null)
+                throw error;
+            return null;
+        }
+        if (saved === "conflict") {
+            await deps.content.delete(contentKey);
+            return null;
+        }
+        // A board's `references` are links in the graph exactly like a document's inline ones, so the
+        // same reconciliation runs on the same body (#285, #41).
+        await reconcileTextLinks(input.actor, input.node.id, BoardMediaType, body);
+        await deps.indexing.enqueue(version.id);
+        return version;
+    }
+    /**
+     * One task operation, applied to the board and written as its next version (#285).
+     *
+     * ⚠️ THIS is why a board has no `baseVersionId` on its inputs. The caller names a task id; the
+     * service reads the current board, applies the change to THAT document and writes it against the
+     * version it read. When somebody else landed a write in between, the insert refuses, and the
+     * answer is not `version_conflict` but another round: read again, apply the same change to the
+     * board as it now stands, write again. Two agents moving two different cards therefore both get
+     * through, which is the whole difference to a table's positions (`TableRowPosition`) — those
+     * cannot survive a rewrite, a task id can.
+     *
+     * ⚠️ Bounded, and the bound is not decoration. A board somebody is hammering must eventually
+     * answer rather than loop; after `boardWriteAttempts` rounds the caller hears the same
+     * `version_conflict` any other contended write gives them.
+     *
+     * ⚠️ A replayed key answers out of the version it wrote AND the audit metadata beside it. The
+     * document alone cannot say which task an operation touched or how many a delete removed — it is
+     * the state after the write, and a deleted subtree is not in it.
+     */
+    async function applyToBoard(actor, input, operation, apply) {
+        let node = await requireBoard(actor, input.nodeId);
+        const replayed = await replayedBoardWrite(actor, node, operation, input.idempotencyKey);
+        if (replayed)
+            return replayed;
+        for (let attempt = 0; attempt < boardWriteAttempts; attempt += 1) {
+            const applied = apply(await boardDocumentOf(node));
+            const version = await writeBoardVersion({
+                actor,
+                node,
+                document: applied.document,
+                metadata: applied.metadata,
+                operation,
+                idempotencyKey: input.idempotencyKey,
+            });
+            if (version !== null) {
+                return {
+                    node: await requireVisible(actor, node.id),
+                    version,
+                    document: applied.document,
+                    metadata: applied.metadata,
+                };
+            }
+            node = await requireVisible(actor, input.nodeId);
+            /**
+             * ⚠️ Asked again after EVERY refused round, not only before the first (#285).
+             *
+             * A conflict says "somebody wrote in between" and usually that somebody was working on
+             * another task — retrying is then exactly right. But it can also have been this very call,
+             * arriving twice: a double click, or a client that retried before the first answer came back.
+             * Retrying THAT blindly would re-use an idempotency key the winning write already owns, and
+             * the second attempt would die on the primary key of `idempotency_keys` — an internal error
+             * where the caller was promised a replay. So the key is asked again first, and if it is spent
+             * the answer is the write that owns it.
+             */
+            const raced = await replayedBoardWrite(actor, node, operation, input.idempotencyKey);
+            if (raced)
+                return raced;
+        }
+        throw new IntelError(409, "version_conflict", "This board is being written to too quickly");
+    }
+    // The write this key already made, or `null` while it is unspent. The version, the document it
+    // holds and the metadata beside it — all three, or nothing: a half-readable replay would answer
+    // with a task the caller never got.
+    async function replayedBoardWrite(actor, node, operation, idempotencyKey) {
+        const replayedId = await deps.repository.findIdempotentNode(actor.id, operation, idempotencyKey);
+        if (replayedId === null)
+            return null;
+        const version = await deps.repository.getVersion(replayedId);
+        if (!version)
+            return null;
+        const metadata = await deps.repository.findSnapshotMetadata(actor.id, operation, idempotencyKey);
+        if (!metadata)
+            return null;
+        const body = await deps.content.get(version.contentKey);
+        if (body === null)
+            return null;
+        return { node, version, document: parseStoredBoard(body), metadata };
+    }
+    // The task an operation reports, read back out of the version it wrote. The id comes from the
+    // audit metadata, so a replay answers with exactly the task the first attempt created.
+    function writtenTask(written) {
+        const taskId = written.metadata.taskId;
+        const task = typeof taskId === "string"
+            ? written.document.tasks.find((candidate) => candidate.id === taskId)
+            : undefined;
+        if (!task)
+            throw new IntelError(500, "board_unreadable", "The written task cannot be read back");
+        return task;
+    }
     /**
      * What the grant just written does not cover: the documents the flows in this folder read that
      * the new principal still cannot.
@@ -1200,6 +1432,80 @@ export function createNodes(deps) {
             });
             return await tableOf(await requireVisible(actor, node.id));
         },
+        /**
+         * The board, as one document (#285).
+         *
+         * ⚠️ `read` and not `write`: seeing a board is the ordinary node read, and `requireBoard` — with
+         * its `write` check — is for the five operations that change it. A board nobody may edit is
+         * still a board they may look at.
+         */
+        async getBoard(actor, input) {
+            const node = await requireVisible(actor, input.nodeId);
+            if (node.kind !== "board") {
+                throw new IntelError(404, "board_not_found", "Board was not found");
+            }
+            return { node, board: await boardDocumentOf(node), versionId: node.currentVersionId };
+        },
+        async configureBoard(actor, input) {
+            const written = await applyToBoard(actor, input, "node.board_configure", (document) => ({
+                document: board.configure(document, input.statuses),
+                // The ids and not the labels: audit is metadata, and a label is text somebody wrote.
+                metadata: { statuses: input.statuses.map((status) => status.id) },
+            }));
+            return { node: written.node, version: written.version, statuses: written.document.statuses };
+        },
+        async addBoardTask(actor, input) {
+            // Before the document is touched at all: a task that names a node nobody can see is refused
+            // rather than stored, and the refusal costs no write (#285).
+            await checkBoardTargets(actor, { references: input.references, assignee: input.assignee });
+            const written = await applyToBoard(actor, input, "node.board_task_add", (document) => {
+                const added = board.addTask(document, input);
+                return { document: added.board, metadata: { taskId: added.task.id } };
+            });
+            return { node: written.node, version: written.version, task: writtenTask(written) };
+        },
+        async updateBoardTask(actor, input) {
+            await checkBoardTargets(actor, {
+                references: input.references ?? [],
+                assignee: input.assignee ?? null,
+            });
+            const written = await applyToBoard(actor, input, "node.board_task_update", (document) => {
+                const updated = board.updateTask(document, input);
+                return { document: updated.board, metadata: { taskId: updated.task.id } };
+            });
+            return { node: written.node, version: written.version, task: writtenTask(written) };
+        },
+        async moveBoardTask(actor, input) {
+            const written = await applyToBoard(actor, input, "node.board_task_move", (document) => {
+                const moved = board.moveTask(document, input);
+                return {
+                    document: moved.board,
+                    metadata: { taskId: moved.task.id, status: moved.task.status },
+                };
+            });
+            return { node: written.node, version: written.version, task: writtenTask(written) };
+        },
+        /**
+         * A task and everything under it (#285).
+         *
+         * ⚠️ The count is read back out of the write's own metadata rather than recomputed. A replay
+         * has to answer with what the first attempt actually removed, and by then the descendants are
+         * no longer in the document to be counted.
+         */
+        async deleteBoardTask(actor, input) {
+            const written = await applyToBoard(actor, input, "node.board_task_delete", (document) => {
+                const removed = board.deleteTask(document, input.taskId);
+                return {
+                    document: removed.board,
+                    metadata: { taskId: input.taskId, deleted: removed.deleted },
+                };
+            });
+            const deleted = written.metadata.deleted;
+            if (typeof deleted !== "number") {
+                throw new IntelError(500, "board_unreadable", "The delete did not record what it removed");
+            }
+            return { node: written.node, version: written.version, deleted };
+        },
         async listVersions(actor, nodeId) {
             await requireVisible(actor, nodeId);
             return { items: await deps.repository.listVersions(nodeId) };

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

@@ -1,4 +1,4 @@
-import type { AgentKeyRotated, AgentList, AppendTableRowsInput, AppendTableRowsResult, ArchiveNodeInput, CreateAgentInput, CreatedAgent, CreateNodeInput, DefineTableInput, DeleteTableRowsInput, DeleteTableRowsResult, Flow, FlowVersion, GetAgentInput, ListAgentsInput, ListNodesInput, Node, NodeAgent, NodeAttachment, NodeCitation, NodeDocument, NodeGraph, NodeGraphInput, NodeLink, NodeTable, NodeVersion, RedefineTableInput, ResolveNodeLinksInput, ResolveNodeLinksResult, ResourceGrant, ResourceGrantList, ResourceVerb, RevokeGrantInput, RotateAgentKeyInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, ShareInput, ShareResult, UpdateNodeInput, UpdateTableRowsInput, UpdateTableRowsResult } from "@anchrd/intel-contract";
+import type { AddBoardTaskInput, AgentKeyRotated, AgentList, AppendTableRowsInput, AppendTableRowsResult, ArchiveNodeInput, BoardTaskResult, ConfigureBoardInput, ConfigureBoardResult, CreateAgentInput, CreatedAgent, CreateNodeInput, DefineTableInput, DeleteBoardTaskInput, DeleteBoardTaskResult, DeleteTableRowsInput, DeleteTableRowsResult, Flow, FlowVersion, GetAgentInput, GetBoardInput, ListAgentsInput, ListNodesInput, MoveBoardTaskInput, Node, NodeAgent, NodeAttachment, NodeBoard, NodeCitation, NodeDocument, NodeGraph, NodeGraphInput, NodeLink, NodeTable, NodeVersion, RedefineTableInput, ResolveNodeLinksInput, ResolveNodeLinksResult, ResourceGrant, ResourceGrantList, ResourceVerb, RevokeGrantInput, RotateAgentKeyInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, ShareInput, ShareResult, UpdateBoardTaskInput, UpdateNodeInput, UpdateTableRowsInput, UpdateTableRowsResult } from "@anchrd/intel-contract";
 import type { SemanticIndex } from "../adapters/semantic-index/semantic-index.types.js";
 export interface Actor {
     id: string;
@@ -27,12 +27,25 @@ export interface NewTableVersion {
     idempotencyKey: string;
     auditId: string;
 }
-export type TableSnapshotOperation = "node.table_update" | "node.table_delete" | "node.table_redefine";
-export interface NewTableSnapshot {
+export type SnapshotOperation = "node.table_update" | "node.table_delete" | "node.table_redefine" | "node.board_configure" | "node.board_task_add" | "node.board_task_update" | "node.board_task_move" | "node.board_task_delete";
+/**
+ * One version that replaces the readable state, written only against the state it replaces.
+ *
+ * ⚠️ With `sequence` and with `baseVersionId`, unlike the table append. A snapshot replaces what is
+ * read, so it has to know which state it replaces — the same optimistic concurrency the document
+ * save uses, enforced in the same statement that inserts the row (#135).
+ *
+ * ⚠️ A board uses this too, and its `baseVersionId` is NOT the caller's (#285). The caller of a task
+ * operation never sends one; the service reads the current version, applies the change by task id
+ * and passes what it read. A refusal here therefore means "somebody wrote in between", which the
+ * service answers by reading again and re-applying, so two agents moving two different tasks both
+ * get through instead of one of them meeting `version_conflict`.
+ */
+export interface NewSnapshotVersion {
     version: NodeVersion;
     actorId: string;
-    baseVersionId: string;
-    operation: TableSnapshotOperation;
+    baseVersionId: string | null;
+    operation: SnapshotOperation;
     metadata: Record<string, unknown>;
     idempotencyKey: string;
     auditId: string;
@@ -51,8 +64,9 @@ export interface NodeRepository {
     getVisible(actor: Actor, nodeId: string): Promise<Node | null>;
     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" | TableSnapshotOperation, idempotencyKey: string): Promise<string | null>;
+    findIdempotentNode(actorId: string, operation: "node.create" | "node.save" | "node.append" | "node.update" | "node.archive" | "node.share" | "node.revoke" | SnapshotOperation, idempotencyKey: string): Promise<string | null>;
     findIdempotentRevocation(actorId: string, idempotencyKey: string): Promise<boolean | null>;
+    findSnapshotMetadata(actorId: string, operation: SnapshotOperation, idempotencyKey: string): Promise<Record<string, unknown> | null>;
     insertNode(input: NewNode): Promise<Node>;
     agentApplicationId(nodeId: string): Promise<string | null>;
     /**
@@ -78,7 +92,7 @@ export interface NodeRepository {
     getVersion(versionId: string): Promise<NodeVersion | null>;
     appendVersion(input: NewNodeVersion): Promise<"saved" | "conflict">;
     appendTableVersion(input: NewTableVersion): Promise<NodeVersion>;
-    appendTableSnapshot(input: NewTableSnapshot): Promise<"saved" | "conflict">;
+    appendSnapshotVersion(input: NewSnapshotVersion): Promise<"saved" | "conflict">;
     listVersionContentKeys(nodeId: string): Promise<string[]>;
     tableHeaderContentKey(nodeId: string): Promise<string | null>;
     listVersions(nodeId: string): Promise<NodeVersion[]>;
@@ -325,6 +339,21 @@ export interface NodeService {
     updateTableRows(actor: Actor, input: UpdateTableRowsInput): Promise<UpdateTableRowsResult>;
     deleteTableRows(actor: Actor, input: DeleteTableRowsInput): Promise<DeleteTableRowsResult>;
     redefineTable(actor: Actor, input: RedefineTableInput): Promise<NodeTable>;
+    /**
+     * A board and the five operations that change it (#285).
+     *
+     * ⚠️ Not one "save the board" call, deliberately. Every write here names a TASK ID and the server
+     * applies it to the document it just read, so two callers touching two different tasks both get
+     * through — the same problem `appendTableRows` solves for a table, arrived at from the other side.
+     * A whole-document write would put every concurrent editor into `version_conflict` and force each
+     * of them to read a board of thousands of tasks before changing one word on one card.
+     */
+    getBoard(actor: Actor, input: GetBoardInput): Promise<NodeBoard>;
+    configureBoard(actor: Actor, input: ConfigureBoardInput): Promise<ConfigureBoardResult>;
+    addBoardTask(actor: Actor, input: AddBoardTaskInput): Promise<BoardTaskResult>;
+    updateBoardTask(actor: Actor, input: UpdateBoardTaskInput): Promise<BoardTaskResult>;
+    moveBoardTask(actor: Actor, input: MoveBoardTaskInput): Promise<BoardTaskResult>;
+    deleteBoardTask(actor: Actor, input: DeleteBoardTaskInput): Promise<DeleteBoardTaskResult>;
     getAgent(actor: Actor, input: GetAgentInput): Promise<NodeAgent>;
     /**
      * An agent node, its first definition, and the Gate Application it runs as (#182, D29).
@@ -391,12 +420,27 @@ export interface NodeIndexTarget {
     description: string | null;
     contentKeys: string[];
     mediaType: string;
-    kind: "document" | "attachment" | "table" | "agent";
+    kind: "document" | "attachment" | "table" | "agent" | "board";
     updatedAt: string;
 }
+/**
+ * One passage of a node, as the full-text index holds it.
+ *
+ * ⚠️ A list, and most kinds put exactly one in it. A board puts one per TASK (#285): "where do I
+ * stand with X" has to find a card, and a board indexed as one blob would answer with the whole
+ * board every time — the passage a searcher is shown would be whichever thousand characters the
+ * snippet happened to cut, from a task that may have nothing to do with the question.
+ *
+ * `title` is what the passage is called rather than what the node is called: for a task it is the
+ * task's own title, which is the text the FTS table weights highest.
+ */
+export interface IndexChunk {
+    title: string;
+    text: string;
+}
 export interface NodeIndexRepository {
     getTarget(versionId: string): Promise<NodeIndexTarget | null>;
-    replace(target: NodeIndexTarget, content: string): Promise<void>;
+    replace(target: NodeIndexTarget, chunks: IndexChunk[]): Promise<void>;
     markIndexed(versionId: string, occurredAt: string): Promise<void>;
     markError(versionId: string, message: string, occurredAt: string): Promise<void>;
 }

package/migrations/0016_boards_in_the_tree.sql

@@ -0,0 +1,80 @@
+-- #285: a sixth kind in the shared tree — `board`. It is a node like the other five: same
+-- `parent_id`, same folder grants, same immutable `node_versions` rows, same R2 body (ADR-0004 §1).
+-- Its body happens to be a JSON project board rather than prose, which the schema neither knows nor
+-- needs to: nothing here creates a second content model, only the CHECK has to learn the word.
+--
+-- A board's tasks live INSIDE that one body and get no table of their own. That is the decision the
+-- ticket makes: a board with three hundred tasks is one node in the tree, not three hundred, and
+-- nothing about the tree has to behave differently because a board is filed in it.
+--
+-- SQLite cannot alter a CHECK constraint, so the table is rebuilt — the same rebuild 0005 and 0013
+-- performed for `table` and `agent`, written the same long way round for the same two reasons. Both
+-- detours below are copied from a file that earned them against a real database, not from caution.
+--
+-- ⚠️ First detour: the new table is created under the final name rather than built beside the old
+-- one and renamed over it. `DROP TABLE` on a parent runs an implicit `DELETE FROM` first, so the
+-- moment the old `nodes` goes, every row of `node_versions`, `tree_grants` and `flows` pointing at a
+-- node is a foreign-key violation. `defer_foreign_keys` postpones the complaint to COMMIT but does
+-- not withdraw it, and `ALTER TABLE ... RENAME` does not settle it either: a rename puts the name
+-- back, not the rows. Only inserting the nodes again, under the name the children have referenced
+-- all along, does. This is also why the self-reference below reads `REFERENCES nodes(id)` — the
+-- final name — which is lesson 2 of the three recorded in `0009_no_context_policy.sql`.
+--
+-- ⚠️ Second detour: `node_links` is the only child of `nodes` declared ON DELETE CASCADE, so that
+-- same implicit delete does not merely flag its rows, it removes them — the migration would commit
+-- with every relationship between two documents quietly gone. The rows are carried out of the way
+-- first and put back afterwards. That is a rescue, not a decision about the data: nothing is
+-- dropped, rewritten or reinterpreted here.
+--
+-- ⚠️ On an empty database neither detour is visible, because nothing points at anything. That is
+-- exactly how 0005's first version passed a green suite and then failed against the first database
+-- with content in it, and why the proof for this file is a row count of every referencing table
+-- before and after rather than a migration that merely ran.
+--
+-- `context_policy` is carried over unchanged and still NOT NULL. It is dead for every consumer
+-- (#76) and only D1's refusal to drop a column a CHECK names keeps it here; removing it is #86 and
+-- deliberately not smuggled into this rebuild.
+PRAGMA defer_foreign_keys = TRUE;
+
+-- Plain holding tables on purpose: no keys, no CHECKs, no foreign keys, and the column set taken
+-- from whatever the live table has. Anything enforced here would only be enforced a second time on
+-- the way back in, and a holding table that can reject a row is a holding table that can lose one.
+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', 'agent', 'board')),
+  title TEXT NOT NULL CHECK (length(title) BETWEEN 1 AND 240),
+  description TEXT CHECK (description IS NULL OR length(description) <= 2000),
+  context_policy TEXT NOT NULL CHECK (context_policy IN ('pinned', 'relevant', 'explicit')),
+  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, context_policy, owner_id,
+  current_version_id, created_at, updated_at, archived_at
+)
+SELECT
+  id, parent_id, kind, title, description, context_policy, owner_id,
+  current_version_id, created_at, updated_at, archived_at
+FROM nodes_carry;
+
+-- `OR IGNORE` because whether the cascade above actually fired is SQLite's business, not this
+-- migration's: if it did, this puts the rows back; if it did not, each one is already present under
+-- the same primary key and this is a no-op. Either way `node_links` ends up holding exactly what it
+-- held before, which is the only outcome this statement is permitted to have.
+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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -47,6 +47,7 @@
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",
+    "fractional-indexing": "^4.0.0",
     "hono": "^4.12.32",
     "openid-client": "^6.8.4",
     "ulid": "^3.0.2",