@anchrd/intel-api 0.13.0 → 0.14.0

package/dist/bundle/bundle.js

@@ -926,6 +926,20 @@ export function createBundle(deps) {
                         if (header.length === 0 || header.every((column) => column.trim().length === 0)) {
                             throw new IntelError(400, "import_invalid_table", `Bundle entry is not a table with a header row: ${entry.path}`);
                         }
+                        // ⚠️ Distinct column names, read the same way `DefineTableInput` and
+                        // `RedefineTableInput` read them — case-insensitively (#322). Both refuse a duplicate,
+                        // and the import used to walk past both: a table could only enter the tree this way
+                        // with two columns of one name.
+                        //
+                        // The consumer assumes the opposite and says so. `packages/ui/src/node-table` keys its
+                        // header cells and every row cell with the column name and carries the comment
+                        // "Column names are distinct by contract (`DefineTableInput`)" — true for the two write
+                        // paths, and false for this one. Two equal names are two React keys with one value, in
+                        // the header AND in every row.
+                        const seen = new Set(header.map((column) => column.trim().toLowerCase()));
+                        if (seen.size !== header.length) {
+                            throw new IntelError(400, "import_invalid_table", `Bundle entry has two columns of the same name: ${entry.path}`);
+                        }
                         // The whole file as one snapshot: the same shape a definition or a redefine writes
                         // (#135), so reading starts here and nothing older is expected to exist.
                         version = versionRowFor(entry, text, TableMediaType, await deps.hash(text), "snapshot");
@@ -957,12 +971,19 @@ export function createBundle(deps) {
                          * Outside the catch above on purpose: swallowed into `import_invalid_board` this would
                          * read as "that file is not a board", and whoever is holding the file would look for
                          * the wrong thing. `repeatedBoardId` names the id, which is the line they have to fix.
+                         *
+                         * ⚠️ And it names the way out, not only the fault (anchrd/intel#341). The usual holder
+                         * of such a file is not its author but somebody moving a tree between installations,
+                         * and the pair is in the BOARD the export came from — where `board_repair_task_ids`
+                         * and `board_configure` each remove one kind of it. Told only what is wrong, they were
+                         * left editing JSON by hand or leaving the board behind, and an import is all or
+                         * nothing: one such board stops the whole move.
                          */
                         const repeated = repeatedBoardId(document);
                         if (repeated !== null) {
                             throw new IntelError(400, "import_duplicate_board_id", repeated.list === "tasks"
-                                ? `Bundle entry names the task “${repeated.id}” twice: ${entry.path}`
-                                : `Bundle entry names the status “${repeated.id}” twice: ${entry.path}`);
+                                ? `Bundle entry names the task “${repeated.id}” twice: ${entry.path}. Repair that board with board_repair_task_ids where it came from, then export it again.`
+                                : `Bundle entry names the status “${repeated.id}” twice: ${entry.path}. Repair that board with board_configure — the status list written whole, with distinct ids — where it came from, then export it again.`);
                         }
                         // ⚠️ `references` are remapped the way a document's inline links are, and `dependsOn`
                         // and `parentId` are NOT (#285). A task's references point at NODES, which the import

package/dist/http/http.js

@@ -486,6 +486,10 @@ export function createHttp(deps) {
         }
         return context.json(await deps.nodes.deleteBoardTask(asActor(auth), input), 201);
     });
+    // ⚠️ There is deliberately no route for the sixth board operation. `board_repair_task_ids`
+    // (anchrd/intel#341) is MCP-only until a screen calls it: the routes here are what the browser
+    // reaches, nothing in `intel-data-provider` asks for it, and a route with no caller is the thing
+    // YAGNI is about. The screen is anchrd/intel#358, and it brings this route with it.
     app.get("/nodes/:nodeId/links", async (context) => {
         const auth = requireCapability(context, "knowledge", "read");
         return context.json(await deps.nodes.listLinks(asActor(auth), context.req.param("nodeId")));

package/dist/indexing/indexing.js

@@ -1,7 +1,14 @@
-import { BlockNoteDocument, BlockNoteMediaType, BoardDocument } from "@anchrd/intel-contract";
+import { ArchivedBoardStatusId, BlockNoteDocument, BlockNoteMediaType, BoardDocument, } from "@anchrd/intel-contract";
 import { upgradeStoredBoard } from "../nodes/board/board.js";
 export class PermanentIndexingError extends Error {
 }
+// The key under which a node that has exactly one vector is filed — every kind but `board`. It is
+// the bare node id in the index itself, which is why nothing written before anchrd/intel#301 has to
+// be renamed or embedded again.
+const wholeNodeChunkKey = "";
+// What the pass hands to `purgeVectors` at its end: the names it has just written, in case the node
+// was archived while it worked and the record of them was refused (anchrd/intel#348).
+const writtenKeys = (chunks) => chunks.map((chunk) => chunk.key);
 function indexText(mediaType, content) {
     if (mediaType !== BlockNoteMediaType)
         return content;
@@ -15,7 +22,8 @@ function indexText(mediaType, content) {
     }
 }
 /**
- * One passage per task, never one per board (#285).
+ * One passage per task, never one per board (#285) — and since anchrd/intel#301 one VECTOR per task
+ * too, which is what `key` carries.
  *
  * ⚠️ This is the whole reason a board is chunked at all. "Where do I stand with X" has to land on a
  * CARD: indexed as one blob, a board of three hundred tasks matches on any of them and answers with
@@ -23,8 +31,17 @@ function indexText(mediaType, content) {
  * have nothing to do with the question. Each chunk carries the task's own title, which is the
  * column the FTS table weights highest.
  *
- * ⚠️ The status list is not indexed. "Backlog" and "Done" appear on every board in the
- * installation, so they are the words most likely to match and the least likely to mean anything.
+ * ⚠️ The status list is not indexed, and neither is a task's own status. "Backlog" and "Done" appear
+ * on every board in the installation, so they are the words most likely to match and the least
+ * likely to mean anything — and in the semantic half they would drag every card of every board
+ * towards every question phrased as a state.
+ *
+ * ⚠️ A task on the `archived` shelf is left out of BOTH halves (anchrd/intel#301). That shelf is
+ * what a board has instead of deleting a card (`ArchivedBoardStatusId`), so it is the same statement
+ * `archived_at` makes about a node one level up — and an archived node has never been searchable.
+ * Answering "where do I stand with X" out of a card somebody swept away is the failure the ticket
+ * names. A card in a `terminal` status is NOT swept: "we finished it" is an answer to where the work
+ * stands, and the only thing that says a card no longer counts is the shelf.
  */
 function boardChunks(content) {
     let parsed;
@@ -48,11 +65,125 @@ function boardChunks(content) {
     if (!board.success) {
         throw new PermanentIndexingError("Node version content is not a valid board document");
     }
-    return board.data.tasks.map((task) => ({
+    return board.data.tasks
+        .filter((task) => task.status !== ArchivedBoardStatusId)
+        .map((task) => ({
+        key: task.id,
         title: task.title,
         text: [task.title, ...task.labels, task.description].filter(Boolean).join("\n\n"),
     }));
 }
+/**
+ * What one chunk is embedded as (anchrd/intel#301).
+ *
+ * The node's title in front of a whole-node chunk, which is the exact string the semantic adapter
+ * used to compose on its own side. It moved here because the fingerprint has to cover what is
+ * embedded and nothing else: a prefix added downstream would sit outside the comparison and change
+ * nothing when it changed. The vector it produces therefore keeps the same name AND the same
+ * content it had before this — an upgrading installation loses no answer, though its first pass
+ * over any node does embed once more, because `node_vectors` starts empty and has no fingerprint to
+ * compare against. That cost is one embedding per node, paid when that node is next saved or when
+ * an administrator runs `reindex`, and never per card.
+ *
+ * ⚠️ A card is NOT prefixed with the board's title. It brings its own title as the first line of its
+ * text already, and the board's would put a value into all three hundred fingerprints that moves
+ * when somebody renames the board — one rename, three hundred embeddings.
+ */
+function embeddedText(target, chunk) {
+    return chunk.key === wholeNodeChunkKey ? `${target.title}\n\n${chunk.text}` : chunk.text;
+}
+/**
+ * The vectors this node needs, minus the ones it already has (anchrd/intel#301).
+ *
+ * ⚠️ This is the answer to "a changed card must not reindex the board". A save writes the whole
+ * document — that is what a board version IS — so without this every keystroke-save of a board with
+ * three hundred cards would cost three hundred embeddings. The fingerprint of the exact text that
+ * was embedded is what tells an untouched card from a changed one.
+ *
+ * ⚠️ The comparison is against D1 and deliberately not against Vectorize. Vectorize writes are
+ * asynchronous — a vector upserted a moment ago is not readable yet — so a check made there would
+ * answer about the save before last and re-embed a board that had just been saved twice.
+ *
+ * ⚠️ The record is written only after the upsert returned, in the caller. A pass that dies in
+ * between leaves the record short, so the next one embeds again; the opposite order would leave a
+ * record claiming a vector nobody ever wrote, and nothing would ever notice.
+ */
+async function replaceVectors(deps, target, chunks) {
+    const semantic = deps.semantic;
+    if (!semantic)
+        return;
+    const stored = await deps.repository.listVectors(target.nodeId);
+    const known = new Map(stored.map((record) => [record.chunkKey, record.fingerprint]));
+    const records = [];
+    const changed = [];
+    for (const chunk of chunks) {
+        const text = embeddedText(target, chunk);
+        const fingerprint = await deps.hash(text);
+        if (known.get(chunk.key) !== fingerprint)
+            changed.push({ key: chunk.key, text });
+        records.push({ chunkKey: chunk.key, fingerprint, passage: chunk.text });
+    }
+    const wanted = new Set(chunks.map((chunk) => chunk.key));
+    const stale = stored.map((record) => record.chunkKey).filter((key) => !wanted.has(key));
+    // ⚠️ The one-time sweep of the vector this node had BEFORE it was chunked. An empty record with a
+    // chunked node means this is the first pass since anchrd/intel#301 (or since `reindex` emptied
+    // the record), and the whole-board vector written under the bare node id is still sitting there —
+    // matching questions and answering with the wrong card's passage. Once a record exists this
+    // branch is never taken again, so it costs one call per board rather than one per save.
+    if (stored.length === 0 && !wanted.has(wholeNodeChunkKey))
+        stale.push(wholeNodeChunkKey);
+    await semantic.upsert(target, changed);
+    if (stale.length > 0)
+        await semantic.remove(target.nodeId, stale);
+    await deps.repository.replaceVectors(target, records);
+}
+/**
+ * Everything an archived node had in the vector index, taken out of it (anchrd/intel#348).
+ *
+ * ⚠️ The ORDER is the whole safety argument, and it is the exact mirror of the one above. There the
+ * record is written last, because a row claiming a vector nobody wrote would make the next pass skip
+ * that card forever. Here the record is DELETED last, because the row is the only thing that knows
+ * what a vector is called: drop it first and the vectors stay in the index under names nothing left
+ * anywhere can produce. A pass that dies in between leaves vectors already gone and a record that
+ * still names them — which costs the next pass one embedding per card and nothing else, because the
+ * queue redelivers this message and the second run asks Vectorize to forget names it has already
+ * forgotten. Both failures are repaired by repeating; neither ends in a wrong answer.
+ *
+ * ⚠️ The bare node id goes with them whether or not it is in the record. That name is the ONE vector
+ * a node can hold without any record of it — everything written before anchrd/intel#301 is filed
+ * under it — and an archived node has no later pass in which the one-time sweep in `replaceVectors`
+ * could find it. The standing cost of that is one `deleteByIds` of a single name on a redelivered
+ * message, which Vectorize answers without complaint for an id it no longer holds.
+ *
+ * ⚠️ `alsoNamed` is what makes this run after a NORMAL pass too, and it closes the one hole a purge
+ * driven from `archive` alone cannot. A pass that has already upserted its vectors when somebody
+ * archives the node writes no record at all — `replaceVectors` refuses on `archived_at IS NULL` —
+ * so those vectors would sit in the index with nothing anywhere able to name them, and no message
+ * left to repair it. The pass knows the names it just wrote, so it hands them over.
+ *
+ * ⚠️ Without a semantic index configured nothing happens at all, `node_vectors` included. The rows
+ * can only have been written while one WAS configured, so a deployment that has temporarily lost the
+ * binding must not take the record away — that would leave the vectors behind it unnameable, which
+ * is the failure this whole function exists to avoid.
+ *
+ * ⚠️ One race is left and it is the harmless direction: a restore that lands between the read below
+ * and the deletion loses the vectors that restore's own pass had just written. The node keeps
+ * answering out of the lexical half — `hydrateVisibleCitations` falls back on the full-text passage
+ * when there is no `node_vectors` row — and the next save or `reindex` puts the vectors back. The
+ * record is gone with them, so nothing claims otherwise in the meantime.
+ */
+async function purgeVectors(deps, versionId, alsoNamed = []) {
+    const semantic = deps.semantic;
+    if (!semantic)
+        return;
+    const nodeId = await deps.repository.archivedNodeId(versionId);
+    if (nodeId === null)
+        return;
+    const recorded = (await deps.repository.listVectors(nodeId)).map((record) => record.chunkKey);
+    const keys = [...new Set([wholeNodeChunkKey, ...recorded, ...alsoNamed])];
+    await semantic.remove(nodeId, keys);
+    await deps.repository.deleteVectors(nodeId);
+}
 async function readCanonical(deps, target) {
     if (target.kind === "attachment") {
         const key = target.contentKeys[0];
@@ -67,8 +198,15 @@ export function createIndexing(deps) {
     return {
         async index(versionId) {
             const target = await deps.repository.getTarget(versionId);
-            if (!target)
+            // ⚠️ No target has meant "nothing to do" since the pass existed, and for a superseded version
+            // it still does. For an ARCHIVED node it never did: its vectors stayed in the index, invisible
+            // because every citation is hydrated through a join on `nodes` — and costing places in a
+            // candidate list that Vectorize caps at 100 for everybody (anchrd/intel#348). `purgeVectors`
+            // is the one that tells the two apart; this call cannot.
+            if (!target) {
+                await purgeVectors(deps, versionId);
                 return;
+            }
             // ⚠️ An agent's body is a definition, not something to read: node IDs, a cron line and a model
             // name (ADR-0005 §4). Indexing it verbatim would fill the index with identifiers and, worse,
             // put them into the passage a searcher is shown — the definition names nodes the searcher may
@@ -76,10 +214,12 @@ export function createIndexing(deps) {
             // the tree being asked. What makes an agent findable is what a person wrote about it, so the
             // text is its description, and the FTS table indexes the title on its own (#139).
             if (target.kind === "agent") {
-                await deps.repository.replace(target, [
-                    { title: target.title, text: target.description ?? "" },
-                ]);
-                await deps.semantic?.replace(target, target.description ?? "");
+                const chunks = [
+                    { key: wholeNodeChunkKey, title: target.title, text: target.description ?? "" },
+                ];
+                await deps.repository.replace(target, chunks);
+                await replaceVectors(deps, target, chunks);
+                await purgeVectors(deps, versionId, writtenKeys(chunks));
                 await deps.repository.markIndexed(versionId, deps.now().toISOString());
                 return;
             }
@@ -100,12 +240,21 @@ export function createIndexing(deps) {
                 if (text === undefined) {
                     throw new PermanentIndexingError(`No document converter is configured for ${target.mediaType}`);
                 }
-                // ⚠️ The semantic index stays per NODE while the lexical one gains a row per task. Vectorize
-                // is keyed by node id (`semantic-index.ts`), so a board would need its own key space there
-                // before it could carry one vector per card — a bigger change than #285, and one nothing
-                // asks for yet: the lexical half is what "find the card" needs today.
-                await deps.repository.replace(target, target.kind === "board" ? boardChunks(text) : [{ title: target.title, text }]);
-                await deps.semantic?.replace(target, text);
+                // Both halves are chunked the same way now (anchrd/intel#301): a board is one passage and
+                // one vector per card, everything else is one of each for the node. The two indexes read the
+                // same list, so they cannot come to disagree about what a board is made of.
+                const chunks = target.kind === "board"
+                    ? boardChunks(text)
+                    : [{ key: wholeNodeChunkKey, title: target.title, text }];
+                await deps.repository.replace(target, chunks);
+                await replaceVectors(deps, target, chunks);
+                // ⚠️ Asked again, at the END of a pass that started on a live node (anchrd/intel#348). The
+                // node may have been archived while this pass was embedding, and then `replaceVectors` above
+                // wrote no record at all — its statements refuse on `archived_at IS NULL`. The vectors are in
+                // the index either way, so without this they would stay there with nothing anywhere able to
+                // name them and no message left to try again: the archive's own pass has an empty record to
+                // read from. One extra `SELECT` per pass buys that, and on a live node it answers null.
+                await purgeVectors(deps, versionId, writtenKeys(chunks));
                 await deps.repository.markIndexed(versionId, deps.now().toISOString());
             }
             catch (error) {

package/dist/indexing/indexing.types.d.ts

@@ -6,5 +6,6 @@ export interface IndexingDeps {
     content: ContentStore;
     semantic?: SemanticIndex | undefined;
     converter?: DocumentConverter | undefined;
+    hash(content: string): Promise<string>;
     now(): Date;
 }

package/dist/mcp/mcp.js

@@ -1,4 +1,4 @@
-import { AddBoardTaskInput, AppendTableRowsInput, ArchiveFlowInput, ArchiveNodeInput, CancelFlowRunInput, CompleteFlowRunStepInput, ConfigureBoardInput, CreateAgentInput, CreateFlowInput, CreateNodeInput, DefineTableInput, DeleteBoardTaskInput, DeleteTableRowsInput, ExecuteToolInput, GetAgentInput, GetBoardInput, GetFlowInput, GetFlowRunInput, GetFlowVersionInput, GetNodeInput, GetNodeVersionInput, GetTableInput, IntelId, ListAgentsInput, ListFlowRunsInput, ListFlowsInput, ListGrantsInput, ListNodesInput, MoveBoardTaskInput, NodeGraphInput, PauseAgentInput, PreviewFlowPublishInput, PublishFlowInput, RedefineTableInput, RelationGraphInput, ResolveNodeLinksInput, RevokeGrantInput, RotateAgentKeyInput, RunAgentNowInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveFlowVersionInput, SaveNodeVersionInput, SearchInput, ShareInput, StartFlowRunInput, TestToolInput, UnpublishFlowInput, UpdateBoardTaskInput, UpdateFlowInput, UpdateNodeInput, UpdateTableRowsInput, } from "@anchrd/intel-contract";
+import { AddBoardTaskInput, AppendTableRowsInput, ArchiveFlowInput, ArchiveNodeInput, CancelFlowRunInput, CompleteFlowRunStepInput, ConfigureBoardInput, CreateAgentInput, CreateFlowInput, CreateNodeInput, DefineTableInput, DeleteBoardTaskInput, DeleteTableRowsInput, ExecuteToolInput, GetAgentInput, GetBoardInput, GetFlowInput, GetFlowRunInput, GetFlowVersionInput, GetNodeInput, GetNodeVersionInput, GetTableInput, IntelId, ListAgentsInput, ListFlowRunsInput, ListFlowsInput, ListGrantsInput, ListNodesInput, MoveBoardTaskInput, NodeGraphInput, PauseAgentInput, PreviewFlowPublishInput, PublishFlowInput, RedefineTableInput, RelationGraphInput, RepairBoardTaskIdsInput, ResolveNodeLinksInput, RevokeGrantInput, RotateAgentKeyInput, RunAgentNowInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveFlowVersionInput, SaveNodeVersionInput, SearchInput, ShareInput, StartFlowRunInput, TestToolInput, UnpublishFlowInput, UpdateBoardTaskInput, UpdateFlowInput, UpdateNodeInput, UpdateTableRowsInput, } from "@anchrd/intel-contract";
 import { McpServer, ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { z } from "zod";
@@ -8,18 +8,18 @@ function text(value) {
     return { content: [{ type: "text", text: JSON.stringify(value) }], isError: false };
 }
 /**
- * Registers one tool twice: under its name, and under the `knowledge_*` name it carried before #125.
+ * ⚠️ One name per tool, and the second one is gone for good (#149).
  *
- * ⚠️ The alias is not politeness. A tool name lives in someone else's configuration — a Portal
- * endpoint, an agent, a saved prompt — and renaming it here alone breaks them at the moment we
- * deploy rather than at a moment they chose. Both entries share one handler and one schema, so
- * there is no second behavior to keep in step; only the name and the first sentence of the
- * description differ. The aliases are removed in anchrd/intel#149.
+ * Every tool here carried a `knowledge_*` alias beside its name from #125 until today. The alias
+ * was never politeness: a tool name lives in somebody else's configuration — a portal endpoint, an
+ * agent definition, a saved prompt — so renaming it here alone breaks them at the moment we deploy
+ * rather than at a moment they chose. ADR-0005 §8 therefore kept both, **for a transition**.
+ *
+ * A transition without an end date is not a transition, it is a second permanent name — and two
+ * names for one tool is exactly the friction #125 removed. It ends here. What follows for anybody
+ * writing a tool: there is one name, and a rename is a breaking change that needs its own ticket
+ * and its own notice, not a quiet second entry.
  */
-function registerWithAlias(server, names, config, handler) {
-    server.registerTool(names.name, config, handler);
-    server.registerTool(names.deprecated, { ...config, description: `Deprecated: use ${names.name}. ${config.description}` }, handler);
-}
 // MCP returns resource payloads inline as base64, so an attachment cannot be streamed to the client
 // and must fit in Worker memory twice over. Refuse oversized attachments instead of losing the
 // isolate; HTTP still serves them as a stream.
@@ -112,7 +112,7 @@ export async function handleMcp(request, deps) {
         name: deps.authorization.identity.name ?? null,
     }));
     if (permits(deps.authorization, "knowledge", "read")) {
-        registerWithAlias(server, { name: "node_list", deprecated: "knowledge_list" }, {
+        server.registerTool("node_list", {
             title: "List nodes",
             description: "List authorized folders, documents, attachments, and tables under one parent.",
             inputSchema: ListNodesInput,
@@ -124,7 +124,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.list(actor, input)));
-        registerWithAlias(server, { name: "node_get", deprecated: "knowledge_get" }, {
+        server.registerTool("node_get", {
             title: "Get node",
             description: "Get one authorized node and its current immutable content version.",
             inputSchema: GetNodeInput,
@@ -136,7 +136,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.get(actor, input.nodeId)));
-        registerWithAlias(server, { name: "node_versions_list", deprecated: "knowledge_versions_list" }, {
+        server.registerTool("node_versions_list", {
             title: "List node versions",
             description: "List immutable versions of one authorized node.",
             inputSchema: GetNodeInput,
@@ -163,7 +163,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.getVersion(actor, input.nodeId, input.versionId)));
-        registerWithAlias(server, { name: "node_attachment_get", deprecated: "knowledge_attachment_get" }, {
+        server.registerTool("node_attachment_get", {
             title: "Get node attachment",
             description: "Get authorized immutable attachment metadata and its explicit MCP resource URI.",
             inputSchema: GetNodeInput,
@@ -199,7 +199,7 @@ export async function handleMcp(request, deps) {
                 ],
             };
         });
-        registerWithAlias(server, { name: "search", deprecated: "knowledge_search" }, {
+        server.registerTool("search", {
             title: "Search nodes",
             description: "Search only authorized indexed nodes and return version-pinned citations. Pass scopeId " +
                 "with a folder node id to search that folder and everything beneath it instead of " +
@@ -240,7 +240,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.getAgent(actor, input)));
-        registerWithAlias(server, { name: "node_table_get", deprecated: "knowledge_table_get" }, {
+        server.registerTool("node_table_get", {
             title: "Get node table",
             description: "Read one authorized table as column names and rows.",
             inputSchema: GetTableInput,
@@ -267,7 +267,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.getBoard(actor, input)));
-        registerWithAlias(server, { name: "node_links_list", deprecated: "knowledge_links_list" }, {
+        server.registerTool("node_links_list", {
             title: "List node links",
             description: "List authorized outgoing links and backlinks for one node.",
             inputSchema: GetNodeInput,
@@ -286,7 +286,7 @@ export async function handleMcp(request, deps) {
         // ⚠️ A target this caller may not reach, or one that is gone, is simply absent from the answer.
         // The two are indistinguishable on purpose: telling them apart would confirm that a document
         // exists somewhere they cannot look.
-        registerWithAlias(server, { name: "node_links_resolve", deprecated: "knowledge_links_resolve" }, {
+        server.registerTool("node_links_resolve", {
             title: "Resolve node links",
             description: "Resolve document link targets to the titles this caller is authorized to see. Targets that are unreachable or deleted are absent from the result.",
             inputSchema: ResolveNodeLinksInput,
@@ -298,7 +298,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.resolveLinks(actor, input)));
-        registerWithAlias(server, { name: "node_graph", deprecated: "knowledge_graph" }, {
+        server.registerTool("node_graph", {
             title: "Get node graph",
             description: "Get the authorized nodes and explicit relationships for discovery.",
             inputSchema: NodeGraphInput,
@@ -330,7 +330,7 @@ export async function handleMcp(request, deps) {
         }, async (input) => text(await deps.bundle.manifest(bundleActor, input.nodeId)));
     }
     if (deps.authorization.can("intel", "admin")) {
-        registerWithAlias(server, { name: "node_reindex", deprecated: "knowledge_reindex" }, {
+        server.registerTool("node_reindex", {
             title: "Reindex nodes",
             description: "Queue every current canonical node version for derived index rebuild.",
             inputSchema: EmptyInput,
@@ -344,7 +344,7 @@ export async function handleMcp(request, deps) {
         }, async () => text(await deps.nodes.reindex(actor)));
     }
     if (permits(deps.authorization, "knowledge", "create")) {
-        registerWithAlias(server, { name: "node_create", deprecated: "knowledge_create" }, {
+        server.registerTool("node_create", {
             title: "Create node",
             description: "Create a governed folder, document, attachment, or table node.",
             inputSchema: CreateNodeInput,
@@ -415,7 +415,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: true,
             },
         }, async (input) => text(await deps.nodes.rotateAgentKey(actor, input, { token: deps.bearer })));
-        registerWithAlias(server, { name: "node_save", deprecated: "knowledge_save" }, {
+        server.registerTool("node_save", {
             title: "Save node version",
             description: "Append an immutable content version using an optimistic base version.",
             inputSchema: SaveNodeVersionInput,
@@ -427,7 +427,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.save(actor, input)));
-        registerWithAlias(server, { name: "node_attachment_save", deprecated: "knowledge_attachment_save" }, {
+        server.registerTool("node_attachment_save", {
             title: "Save node attachment",
             description: "Append immutable base64 file bytes to an attachment node.",
             inputSchema: SaveAttachmentInput,
@@ -459,7 +459,7 @@ export async function handleMcp(request, deps) {
             zip: decodeZipBase64(input.zipBase64),
             idempotencyKey: input.idempotencyKey,
         })));
-        registerWithAlias(server, { name: "node_table_define", deprecated: "knowledge_table_define" }, {
+        server.registerTool("node_table_define", {
             title: "Define node table columns",
             description: "Write the column names of an empty table. The header is the contract every append is checked against and cannot be rewritten.",
             inputSchema: DefineTableInput,
@@ -473,7 +473,7 @@ export async function handleMcp(request, deps) {
         }, async (input) => text(await deps.nodes.defineTable(actor, input)));
         // The tool #40 exists for: an agent collecting findings on a schedule appends them without
         // reading or resending what is already there, and two agents appending at once lose nothing.
-        registerWithAlias(server, { name: "node_table_append", deprecated: "knowledge_table_append" }, {
+        server.registerTool("node_table_append", {
             title: "Append node table rows",
             description: "Append rows to a table without reading or resending its existing content. Each row must have exactly as many cells as the table has columns; a row that does not is rejected and nothing is written.",
             inputSchema: AppendTableRowsInput,
@@ -601,7 +601,21 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.deleteBoardTask(actor, input)));
-        registerWithAlias(server, { name: "node_update", deprecated: "knowledge_update" }, {
+        server.registerTool("board_repair_task_ids", {
+            title: "Repair repeated board task ids",
+            description: "Give a fresh id to every task entry on a board that repeats an id another entry already used. Only a board imported from a hand-written or foreign bundle can hold such a pair, and it cannot be repaired with the other calls: they address a task by id, so they would read, write or remove both entries at once. The first entry under an id keeps it — that is the one every parentId and dependsOn on the board already means — and each later one becomes its own task with everything else it carries, so nothing is lost and no edge is invented. The answer names each pair. A board that names every task once is refused rather than rewritten. Repeated STATUS ids are repaired with board_configure instead, by writing the status list with distinct ids.",
+            inputSchema: RepairBoardTaskIdsInput,
+            annotations: {
+                title: "Repair repeated board task ids",
+                readOnlyHint: false,
+                // Nothing is removed and nothing is overwritten: one entry gains an id of its own and
+                // every other field on every task stays exactly as it stood.
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.repairBoardTaskIds(actor, input)));
+        server.registerTool("node_update", {
             title: "Update node",
             description: "Rename, move, or describe a node.",
             inputSchema: UpdateNodeInput,
@@ -613,7 +627,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.update(actor, input)));
-        registerWithAlias(server, { name: "node_archive", deprecated: "knowledge_archive" }, {
+        server.registerTool("node_archive", {
             title: "Archive node",
             description: "Archive or restore one node using optimistic concurrency. Archiving an agent also switches off its Gate application; restoring switches it back on.",
             inputSchema: ArchiveNodeInput,
@@ -632,7 +646,7 @@ export async function handleMcp(request, deps) {
         async (input) => text(await deps.nodes.archive(actor, input, { token: deps.bearer })));
     }
     if (permits(deps.authorization, "knowledge", "share")) {
-        registerWithAlias(server, { name: "node_shares_list", deprecated: "knowledge_shares_list" }, {
+        server.registerTool("node_shares_list", {
             title: "List node shares",
             description: "List direct grants for nodes the caller is allowed to manage.",
             inputSchema: ListGrantsInput,
@@ -644,7 +658,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.listGrants(actor, input.resourceId)));
-        registerWithAlias(server, { name: "node_share", deprecated: "knowledge_share" }, {
+        server.registerTool("node_share", {
             title: "Share node",
             description: "Grant inherited node access to a Gate user, verified email, or the organization.",
             inputSchema: ShareInput,
@@ -656,7 +670,7 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.share(actor, input)));
-        registerWithAlias(server, { name: "node_revoke_share", deprecated: "knowledge_revoke_share" }, {
+        server.registerTool("node_revoke_share", {
             title: "Revoke node share",
             description: "Revoke one direct node grant by ID.",
             inputSchema: RevokeGrantInput,

package/dist/nodes/board/board.d.ts

@@ -32,7 +32,9 @@ export declare function upgradeStoredBoard(parsed: unknown): unknown;
  * first `board_task_update` against such a pair writes the SAME task into both entries. The stored
  * board is then two identical tasks rather than two different ones. That is a consequence of
  * addressing a board by task id at all (#285) and predates this rule; the reason the rule is at the
- * import is to stop the pair from existing, not to make it survivable.
+ * import is to stop the pair from existing, not to make it survivable. A board that already holds
+ * one is repaired by `repairTaskIds` below — asked for, never done on the quiet — and the refusal
+ * here names it, because "your file is wrong" without a way out is where anchrd/intel#341 started.
  *
  * So it is asked exactly where there is a caller to answer: the bundle import, the one door a board
  * document written elsewhere comes in through. Everything else mints task ids itself (`deps.id()`)