@anchrd/intel-api 0.12.5 → 0.14.0

package/dist/nodes/nodes.js

@@ -2,7 +2,7 @@ import { AgentDefinition, AgentMediaType, agentReferenceAccepts, BoardDocument,
 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 { createBoard, upgradeStoredBoard } 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,
@@ -470,7 +470,11 @@ export function createNodes(deps) {
         catch {
             throw new IntelError(500, "board_unreadable", "The stored board cannot be read");
         }
-        const document = BoardDocument.safeParse(parsed);
+        // ⚠️ Upgraded BEFORE validation, not after. `terminal` is required now (anchrd/intel#311), and
+        // this parse is deliberately loud — so a board written before the flag existed would answer
+        // `board_unreadable` rather than "old", and every board in every installation would break on
+        // deploy. `upgradeStoredBoard` fills only what is missing; the next write persists it.
+        const document = BoardDocument.safeParse(upgradeStoredBoard(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.
@@ -685,6 +689,34 @@ export function createNodes(deps) {
             throw new IntelError(500, "board_unreadable", "The written task cannot be read back");
         return task;
     }
+    /**
+     * What the repair renumbered, read back out of the version it wrote (anchrd/intel#341).
+     *
+     * ⚠️ The pairs come from the audit metadata for the same reason the added task's id does: a
+     * replayed key has to answer with what the FIRST attempt actually did, and the document alone
+     * cannot say. After the write every id on that board is distinct and none of them says it is new.
+     *
+     * ⚠️ The metadata carries ids and no titles — audit is metadata, and a title is text somebody
+     * wrote (the same line `configureBoard` draws for its status labels). The tasks themselves are
+     * read out of the document, so the answer is the board's own truth rather than a copy made at
+     * write time.
+     */
+    function renumberedTasks(written) {
+        const recorded = written.metadata.renumbered;
+        if (!Array.isArray(recorded) || recorded.length === 0) {
+            throw new IntelError(500, "board_unreadable", "The repair did not record what it renumbered");
+        }
+        return recorded.map((entry) => {
+            const pair = entry;
+            const task = typeof pair.taskId === "string"
+                ? written.document.tasks.find((candidate) => candidate.id === pair.taskId)
+                : undefined;
+            if (typeof pair.previousId !== "string" || !task) {
+                throw new IntelError(500, "board_unreadable", "The repaired task cannot be read back");
+            }
+            return { previousId: pair.previousId, task };
+        });
+    }
     /**
      * What the grant just written does not cover: the documents the flows in this folder read that
      * the new principal still cannot.
@@ -880,11 +912,19 @@ export function createNodes(deps) {
             return (await deps.repository.can(actor, folder.id, "write")) ? "ok" : "forbidden";
         },
         async create(actor, input) {
-            // The generic path can file an agent row too — one without a definition or a principal — so
-            // the #190 gate stands here as well. Only where no runtime exists: with one, this path stays
-            // exactly as it was, which is part of the same ticket.
-            if (input.kind === "agent" && !deps.agentRuntimeAvailable()) {
-                throw new IntelError(503, "agent_runtime_not_configured", "This installation has no agent runtime, so agents cannot be created");
+            // ⚠️ An agent is never filed through the generic path, whatever the installation looks like
+            // (#193). The row it produced was an agent by kind and nothing else: no definition, and no
+            // Gate Application — so its first run failed with `agent_key_missing` in the runtime, and the
+            // repair was a second, easily forgotten step in Gate. `createAgent` makes both in one go and
+            // asks Gate BEFORE it writes anything, so a refusal leaves nothing behind.
+            //
+            // The refusal is here rather than on each surface for the reason every rule in this file is:
+            // `POST /nodes` and the `node_create` MCP tool are two doors into one service, and a check at
+            // a door is a check somebody adds a third door past. #190 put the runtime gate here and left
+            // this case open on purpose — the ticket demanded "exactly as today" where a runtime exists.
+            // This is that case, closed.
+            if (input.kind === "agent") {
+                throw new IntelError(400, "agent_needs_agent_endpoint", "An agent is created with its definition and its principal together — use the agent endpoint (POST /nodes/agents, or the agent_create tool) rather than the generic node create");
             }
             const existingId = await deps.repository.findIdempotentNode(actor.id, "node.create", input.idempotencyKey);
             if (existingId)
@@ -1506,6 +1546,38 @@ export function createNodes(deps) {
             }
             return { node: written.node, version: written.version, deleted };
         },
+        /**
+         * The way out of a board that names one task id twice (anchrd/intel#341).
+         *
+         * ⚠️ It goes through `applyToBoard` like the other five, so it is one version against the board
+         * as it stands, it replays on its key, and it loses a race the same way. What it does NOT do is
+         * name a task — see `repairTaskIds` in `board.ts` for why the pair is exactly what cannot be
+         * named, and for which entry keeps the id.
+         *
+         * ⚠️ No `checkBoardTargets`: nothing about `references` or `assignee` moves, so there is no
+         * fresh claim on the tree to check. Re-checking the ones already stored would refuse the repair
+         * over a reference somebody lost access to since the import — a board stuck for a second reason
+         * on the way out of the first.
+         */
+        async repairBoardTaskIds(actor, input) {
+            const written = await applyToBoard(actor, input, "node.board_task_repair", (document) => {
+                const repaired = board.repairTaskIds(document);
+                return {
+                    document: repaired.board,
+                    metadata: {
+                        renumbered: repaired.renumbered.map((entry) => ({
+                            previousId: entry.previousId,
+                            taskId: entry.task.id,
+                        })),
+                    },
+                };
+            });
+            return {
+                node: written.node,
+                version: written.version,
+                renumbered: renumberedTasks(written),
+            };
+        },
         async listVersions(actor, nodeId) {
             await requireVisible(actor, nodeId);
             return { items: await deps.repository.listVersions(nodeId) };
@@ -1621,6 +1693,26 @@ export function createNodes(deps) {
                 }
                 throw new IntelError(409, "update_conflict", "This node was changed by another editor");
             }
+            /**
+             * ⚠️ Both directions, through the same queue every save goes through (anchrd/intel#348). The
+             * pass reads the node's state and does the matching thing: an archived node has its vectors
+             * taken out of the index, a restored one is embedded again from a record that was emptied when
+             * it went. Two calls to one door rather than a purge written out here, because Vectorize is a
+             * second system and a call into it can fail — the queue is the only thing in this repository
+             * that comes back for it, and a deletion nobody retries is a deletion that quietly did not
+             * happen.
+             *
+             * ⚠️ The full-text half is deliberately NOT emptied on the way in, and the asymmetry is the
+             * point rather than an oversight: an FTS row costs storage and is already invisible (every
+             * read joins `nodes` and drops what is archived), while a vector costs a place in a candidate
+             * list Vectorize caps at 100 for the whole installation. The archived board pays with
+             * somebody else's search results.
+             *
+             * A replayed archive never reaches this line — it returned above, on the idempotency key — so
+             * repeating the same call does not ask the index to forget the same names twice.
+             */
+            if (updated.currentVersionId)
+                await deps.indexing.enqueue(updated.currentVersionId);
             return updated;
         },
         async listGrants(actor, resourceId) {
@@ -1768,18 +1860,50 @@ export function createNodes(deps) {
             if (!deps.semantic)
                 return { items: lexical.slice(0, input.limit) };
             try {
-                // ⚠️ The scope narrows the vector hits afterwards, in the same D1 statement that already
-                // re-checks the ACL — so the candidate set has to be wide enough for that cut to leave
-                // something. A folder holding a dozen documents inside a tree of thousands is not reached by
-                // the fan-out an unscoped search gets away with, and a starved scope looks like an empty
-                // folder. 100 is what the port clamps to, so a scoped search asks for all there is.
-                const candidates = input.scopeId === undefined ? Math.min(100, input.limit * 4) : 100;
+                /**
+                 * Every candidate Vectorize will give for one query, scoped or not (anchrd/intel#348).
+                 *
+                 * ⚠️ A candidate is a CARD since anchrd/intel#301, not a node, so a busy board can take a
+                 * large share of these places and push other nodes out before this code ever sees them —
+                 * the fold below cannot repair that, it runs on what came back. `limit * 4` was written when
+                 * a board was one vector and forty candidates were forty nodes; against one vector per card
+                 * it is a list a single board fills on its own. Asking for the ceiling is the one widening
+                 * available. Vectorize charges the query and not the depth, so that side is free; the price
+                 * is on the D1 side, where `hydrateVisibleCitations` batches 40 pairs per statement and the
+                 * ordinary unscoped search therefore goes from one statement to as many as three. Nothing
+                 * about the ceiling itself moves: a `limit` of 25 and every scoped search reached 100 before.
+                 *
+                 * ⚠️ It is a widening and not a fix, and the reason it is not is written down in
+                 * `packages/api/CLAUDE.md`: bounding the fan-out per NODE means filtering on a `nodeId`
+                 * metadata index, and Cloudflare only puts a vector into such an index when it is upserted
+                 * AFTER the index was created — so it would cost every installation a full re-embed of its
+                 * tree, plus an operational step no deployment has taken. That is anchrd/intel#356.
+                 *
+                 * ⚠️ 100 is the port's own clamp too, and it is Vectorize's documented ceiling for a query
+                 * that returns neither values nor metadata (50 for one that does). The scoped case has asked
+                 * for it since #126, because a scope cuts the candidates AFTERWARDS, in the D1 statement
+                 * that re-checks the ACL — a folder of a dozen documents inside a tree of thousands is not
+                 * reached by a narrow fan-out, and a starved scope looks like an empty folder.
+                 */
+                const candidates = 100;
                 const hits = await deps.semantic.search(input.query, candidates);
-                const semanticScores = new Map();
+                /**
+                 * The best-scoring chunk of each node, and its score (anchrd/intel#301).
+                 *
+                 * ⚠️ The best, not the sum and not the first. A board answers once per card whose vector
+                 * matched, and a citation names a node — so a board of three hundred mediocre cards must not
+                 * out-rank one document that actually answers, and the passage the reader is shown has to be
+                 * the card that scored, not the one that happened to come back first.
+                 */
+                const best = new Map();
                 for (const hit of hits) {
-                    semanticScores.set(hit.nodeId, Math.max(semanticScores.get(hit.nodeId) ?? 0, hit.score));
+                    const current = best.get(hit.nodeId);
+                    if (current === undefined || hit.score > current.score) {
+                        best.set(hit.nodeId, { chunkKey: hit.chunkKey, score: hit.score });
+                    }
                 }
-                const semantic = await deps.repository.hydrateVisibleCitations(actor, [...semanticScores.keys()], input.scopeId);
+                const semanticScores = new Map([...best].map(([nodeId, winner]) => [nodeId, winner.score]));
+                const semantic = await deps.repository.hydrateVisibleCitations(actor, [...best].map(([nodeId, winner]) => ({ nodeId, chunkKey: winner.chunkKey })), input.scopeId);
                 return {
                     items: mergeSearchResults(lexical, semantic, semanticScores, input.limit),
                 };
@@ -1792,6 +1916,18 @@ export function createNodes(deps) {
             if (actor.isAdmin !== true) {
                 throw new IntelError(403, "reindex_forbidden", "Reindex permission is required");
             }
+            /**
+             * ⚠️ First, and before a single version is enqueued: the record of what the vector index
+             * holds (anchrd/intel#301). Since #301 an indexing pass skips a chunk whose fingerprint has
+             * not moved, which is what keeps a board of three hundred cards from costing three hundred
+             * embeddings per save — and it would equally make `reindex` skip everything, so a vector
+             * index that had been emptied would stay empty while every version was dutifully requeued.
+             * That is the one failure this call exists to prevent, and it is a silent one: the answer
+             * would be a search that finds less and a `queued` count that says all is well.
+             *
+             * The full-text half needs no equivalent because its rows are overwritten, never skipped.
+             */
+            await deps.repository.invalidateVectors();
             let queued = 0;
             let after = null;
             for (;;) {

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

@@ -1,4 +1,4 @@
-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 { 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, RepairBoardTaskIdsInput, RepairBoardTaskIdsResult, 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,7 +27,7 @@ export interface NewTableVersion {
     idempotencyKey: string;
     auditId: string;
 }
-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";
+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" | "node.board_task_repair";
 /**
  * One version that replaces the readable state, written only against the state it replaces.
  *
@@ -145,7 +145,21 @@ export interface NodeRepository {
         occurredAt: string;
     }): Promise<boolean>;
     searchVisible(actor: Actor, input: SearchInput): Promise<NodeCitation[]>;
-    hydrateVisibleCitations(actor: Actor, nodeIds: string[], scopeId?: string): Promise<NodeCitation[]>;
+    /**
+     * `scopeId` cuts the candidates to one folder subtree, which is how the semantic half of a scoped
+     * search is narrowed (#126): the vector index answers over everything and this join is where the
+     * subtree — a relation in D1, not a value on a vector — is applied. The ACL still applies too.
+     *
+     * ⚠️ One entry per node, and it names WHICH chunk answered (anchrd/intel#301). The passage a
+     * searcher is shown is then that card rather than whichever one happens to be first in the board;
+     * a node whose winning chunk has no `node_vectors` row — every vector written before #301 — falls
+     * back on the first full-text passage, which is exactly what this returned before.
+     */
+    hydrateVisibleCitations(actor: Actor, hits: Array<{
+        nodeId: string;
+        chunkKey: string;
+    }>, scopeId?: string): Promise<NodeCitation[]>;
+    invalidateVectors(): Promise<void>;
     listCurrentVersionIds(input: {
         after: string | null;
         limit: number;
@@ -354,6 +368,15 @@ export interface NodeService {
     updateBoardTask(actor: Actor, input: UpdateBoardTaskInput): Promise<BoardTaskResult>;
     moveBoardTask(actor: Actor, input: MoveBoardTaskInput): Promise<BoardTaskResult>;
     deleteBoardTask(actor: Actor, input: DeleteBoardTaskInput): Promise<DeleteBoardTaskResult>;
+    /**
+     * The sixth, and the only one that is not about somebody's project (anchrd/intel#341).
+     *
+     * ⚠️ It names no task id, because a board that needs it holds two entries under one — the pair a
+     * bundle written before anchrd/intel#321 could carry in. Everything else here is unreachable for
+     * that second entry: the five operations above address a task by id and would take, write or
+     * remove both at once.
+     */
+    repairBoardTaskIds(actor: Actor, input: RepairBoardTaskIdsInput): Promise<RepairBoardTaskIdsResult>;
     getAgent(actor: Actor, input: GetAgentInput): Promise<NodeAgent>;
     /**
      * An agent node, its first definition, and the Gate Application it runs as (#182, D29).
@@ -435,12 +458,47 @@ export interface NodeIndexTarget {
  * task's own title, which is the text the FTS table weights highest.
  */
 export interface IndexChunk {
+    /**
+     * What this passage is called inside its node (anchrd/intel#301).
+     *
+     * `""` for a node that is one passage — every kind but `board` — and the task's own id for a card.
+     * The full-text index does not store it; the vector index is named by it, which is how a semantic
+     * hit can say WHICH card answered instead of only which board.
+     */
+    key: string;
     title: string;
     text: string;
 }
+/**
+ * What the vector index holds for one chunk of one node (anchrd/intel#301).
+ *
+ * `fingerprint` is over the exact text that was embedded, so the next pass can tell an untouched
+ * card from a changed one without asking Vectorize — whose writes are asynchronous and would answer
+ * about the save before last. `passage` is what a searcher is shown when this vector is the hit.
+ */
+export interface NodeVectorRecord {
+    chunkKey: string;
+    fingerprint: string;
+    passage: string;
+}
 export interface NodeIndexRepository {
     getTarget(versionId: string): Promise<NodeIndexTarget | null>;
+    /**
+     * The node behind this version when the reason `getTarget` refused it is that the node has been
+     * ARCHIVED — and null for every other reason (anchrd/intel#348).
+     *
+     * ⚠️ The distinction is the whole method. `getTarget` answers null for two very different
+     * situations: the node is archived, or this version has been superseded by a later save. The
+     * first one means "take this node out of the vector index"; the second is a queue message that
+     * arrived late — the ordinary case, because Cloudflare Queues deliver at least once — and acting
+     * on it would delete the vectors of a node that is perfectly alive. So this asks for the archived
+     * case by name and never infers it from an absence.
+     */
+    archivedNodeId(versionId: string): Promise<string | null>;
     replace(target: NodeIndexTarget, chunks: IndexChunk[]): Promise<void>;
+    listVectors(nodeId: string): Promise<NodeVectorRecord[]>;
+    replaceVectors(target: NodeIndexTarget, records: NodeVectorRecord[]): Promise<void>;
+    deleteVectors(nodeId: string): Promise<void>;
     markIndexed(versionId: string, occurredAt: string): Promise<void>;
     markError(versionId: string, message: string, occurredAt: string): Promise<void>;
 }

package/dist/tools/tools.js

@@ -260,7 +260,13 @@ export function createTools(deps) {
             if (!stored)
                 return { portalConnected: false, items: [] };
             try {
-                return { portalConnected: true, items: (await capabilities(who)).items };
+                const { items, serverOfTool } = await capabilities(who);
+                // ⚠️ Named only for a delegated caller, and it costs nothing there: the attribution had to
+                // be made anyway to cut the list. For an ordinary user it would mean a second portal
+                // request per call — `serverList` is not on their path — and their screen never asks the
+                // question. The runtime's is the one that does (#289).
+                const reached = who.delegation ? [...new Set(serverOfTool.values())].sort() : undefined;
+                return { portalConnected: true, items, ...(reached ? { reached } : {}) };
             }
             catch (error) {
                 if (disconnected(error))

package/migrations/0009_no_context_policy.sql

@@ -1,5 +1,13 @@
 -- #76. `context_policy` leaves the contract, the UI and every MCP answer. The COLUMN stays.
 --
+-- ⚠️ HISTORY, and no longer an explanation of what is possible. The column was finally dropped by
+-- `0018_no_context_policy_at_last.sql` (#86), through an ordinary migration file — the very thing
+-- the conclusion at the bottom of this file says cannot be done. What changed is not D1 but the
+-- recipe: `0005`, `0013` and `0016` worked out that the new table has to be created under the FINAL
+-- name instead of renamed into place, and that `node_links` has to be carried out of the way
+-- because it is the one child declared ON DELETE CASCADE. Read on for the three failures that
+-- produced the lessons; read `0018` for the shape that works.
+--
 -- ⚠️ That is not the intent, it is what D1 permits. SQLite cannot drop a column a CHECK names, and
 -- this one names itself. The way around it is a table rebuild, and `knowledge_nodes` carries six
 -- foreign keys, one of them from itself.
@@ -22,6 +30,13 @@
 -- A table rebuild with foreign keys is therefore not possible inside a migration file. It needs a
 -- session that drives the transaction itself.
 --
+-- ⚠️ THAT CONCLUSION WAS WRONG, and the way it was wrong is worth more than the conclusion. The
+-- three lessons above are all correct; what they did not contain was the fourth — do not RENAME at
+-- all. Create the new table under the final name and insert the rows back under the name the
+-- children have referenced the whole time, and there is nothing left for a deferred check to
+-- complain about at COMMIT. `0005` found it, `0013` and `0016` repeated it, and `0018` used it to
+-- drop this column at last (#86).
+--
 -- What holds instead: the column sits in D1, nothing reads it, and `db.ts` writes a fixed value on
 -- insert because it is NOT NULL without a DEFAULT. The contract does not know it — for every
 -- consumer it is gone. What remains is one dead column, and that is the price of Intel running.

package/migrations/0017_a_vector_per_card.sql

@@ -0,0 +1,38 @@
+-- anchrd/intel#301: one vector per board card, and the record of which vectors a node has.
+--
+-- Vectorize is keyed by node id (`adapters/semantic-index`), so a board was ONE vector holding the
+-- whole document while the full-text half had held one row per card since #285. "Where do I stand
+-- with X" is the question a board exists to answer and it is an imprecise one: lexically it reaches
+-- a card only where the searched word is written on it verbatim. A vector id therefore becomes
+-- `<node id>#<task id>` for a board card and stays the bare node id for every other kind — no
+-- existing vector changes its name, so no installation re-embeds its whole tree to get this.
+--
+-- This table is the D1 side of that index and nothing more: which vectors a node has, what text
+-- each one was made from, and the passage a searcher is shown when that vector is the hit. It is
+-- DERIVED like `node_fts` beside it, and `reindex` empties it so that a rebuild really rebuilds.
+--
+-- ⚠️ `fingerprint` is what keeps a board of three hundred cards from costing three hundred
+-- embeddings per save. The indexing pass compares it against the text it is about to embed and
+-- upserts only what changed; a row is written ONLY AFTER the upsert it describes succeeded. That is
+-- why a fingerprint is stored rather than a timestamp: a pass that dies between the two leaves a
+-- row missing, never a row claiming a vector that was never written, so the next pass repairs
+-- itself instead of trusting a lie.
+--
+-- ⚠️ `chunk_key` is `''` for a node that has exactly one vector — every kind but `board`. NULL
+-- would be the honest spelling and is the wrong one: NULLs are distinct from one another inside a
+-- SQLite primary key, so two rows for the same node could both exist and neither would be found by
+-- the other's write.
+--
+-- ⚠️ No foreign key on `node_id`, deliberately, and for the same reason `node_fts` has none: a
+-- derived index must not be able to make a write to `nodes` fail, and every rebuild of `nodes`
+-- (0005, 0013, 0016, 0018) has to carry each declared child through the detour those files describe.
+-- A row that outlives its node is invisible anyway — hydration joins `nodes` and drops what is
+-- archived or gone, exactly as it does for `node_fts`.
+CREATE TABLE node_vectors (
+  node_id TEXT NOT NULL,
+  chunk_key TEXT NOT NULL,
+  version_id TEXT NOT NULL,
+  fingerprint TEXT NOT NULL,
+  passage TEXT NOT NULL,
+  PRIMARY KEY (node_id, chunk_key)
+);

package/migrations/0018_no_context_policy_at_last.sql

@@ -0,0 +1,90 @@
+-- #86: `context_policy` leaves `nodes` for good.
+--
+-- #76 removed it from the contract, the UI and every MCP answer — for every consumer it has been
+-- gone since. The COLUMN stayed because SQLite cannot drop one a CHECK names, and `db.ts` has been
+-- writing the fixed value `'relevant'` into it ever since so that inserting a node works at all.
+-- A dead column plus a line of code serving it: harmless, and ballast the next reader has to be
+-- told about.
+--
+-- ⚠️ THE reason this ticket sat open for weeks is that three earlier attempts failed against
+-- `--remote` while passing locally, and the file that recorded them (`0009_no_context_policy.sql`)
+-- concluded that a table rebuild with foreign keys needs "a session that runs the transaction
+-- itself, not a migration file". That conclusion is out of date, and the proof is in this
+-- directory: `0005`, `0013` and `0016` each rebuilt this very table through an ordinary migration
+-- file. `0016` did it against the live database on 2026-08-08 with 120 nodes, and every referencing
+-- table came out with the same count it went in with.
+--
+-- ⚠️ One thing about that run is worth knowing before it is quoted as a precedent: the installation
+-- held ZERO `node_links` rows, so the rescue below would have had nothing to rescue and the run
+-- would have passed without exercising it at all. The one row it did carry was created for the
+-- purpose, minutes before, by linking two throwaway documents. The proof was arranged, not found —
+-- and the next person rebuilding this table has to arrange it again, because the installation still
+-- has almost no links.
+--
+-- What the three of them worked out, and what this file copies rather than rediscovers:
+--
+--   1. `PRAGMA foreign_keys = OFF` is IGNORED by D1 over the HTTP API. Locally miniflare obeys it,
+--      so the integration test was green while the real database answered `FOREIGN KEY constraint
+--      failed`. That is why the proof of a migration here is a run against `--remote`.
+--   2. The new table is created under the FINAL name rather than built beside the old one and
+--      renamed over it. `ALTER TABLE ... RENAME` makes references FOLLOW the rename, so renaming
+--      the old table out of the way quietly re-points every other table at a table about to be
+--      dropped. Inserting the rows again under the name the children have referenced all along is
+--      what settles them.
+--   3. `DROP TABLE` on a parent runs an implicit `DELETE FROM` first, and `node_links` is the one
+--      child declared ON DELETE CASCADE — so that delete does not merely flag its rows, it REMOVES
+--      them. They are carried out of the way and put back. That is a rescue, not a decision about
+--      the data.
+--
+-- ⚠️ On an empty database neither detour is visible, because nothing points at anything. That is
+-- 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.
+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;
+
+-- The same table as `0016` left it, minus one column. Nothing else about it changes: same keys,
+-- same CHECKs, same six kinds — a rebuild is the only way to drop the column, not an invitation to
+-- change anything else while the table is open.
+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),
+  owner_id TEXT NOT NULL,
+  current_version_id TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  archived_at TEXT
+);
+
+-- Columns named on both sides rather than `SELECT *`: the holding table still HAS `context_policy`,
+-- and a positional insert would either fail or, worse, shift every value one place to the left.
+INSERT INTO nodes (
+  id, parent_id, kind, title, description, owner_id,
+  current_version_id, created_at, updated_at, archived_at
+)
+SELECT
+  id, parent_id, kind, title, description, owner_id,
+  current_version_id, created_at, updated_at, archived_at
+FROM nodes_carry;
+
+-- `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.5",
+  "version": "0.14.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@anchrd/gate-sdk": "^0.7.0",
-    "@anchrd/intel-contract": "^0.10.0",
+    "@anchrd/intel-contract": "^0.12.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",