@anchrd/intel-api 0.13.0 → 0.14.0

package/dist/nodes/board/board.js

@@ -1,4 +1,4 @@
-import { ArchivedBoardStatusId, BoardDefaultStatuses, BoardMaxTaskDepth, } from "@anchrd/intel-contract";
+import { ArchivedBoardStatusId, BoardDefaultStatuses, BoardMaxTaskDepth, MaxBoardTaskOrderLength, } from "@anchrd/intel-contract";
 import { generateKeyBetween } from "fractional-indexing";
 import { IntelError } from "../../shared/intel-error/intel-error.js";
 /**
@@ -147,7 +147,9 @@ export function upgradeStoredBoard(parsed) {
  * 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()`)
@@ -165,6 +167,85 @@ export function repeatedBoardId(document) {
     }
     return null;
 }
+/**
+ * The two digits a key is extended with when `fractional-indexing` will not read its bounds
+ * (anchrd/intel#359).
+ *
+ * ⚠️ Both are chosen rather than convenient. `V` is the middle of the character class, so an
+ * extension leaves room on either side of itself, and it deliberately is not `0`: a fraction ending
+ * in zero is exactly what `generateKeyBetween` refuses to read afterwards. `0` is therefore used
+ * only where it is the one digit that still fits under an upper bound.
+ */
+const SmallestOrderDigit = "0";
+const MiddleOrderDigit = "V";
+/**
+ * A key strictly between two stored ones, spelled with nothing but the character class
+ * (anchrd/intel#359).
+ *
+ * ⚠️ It is the second half of `orderBetween`, reached only when the library refused, and it rests
+ * on the one property `BoardTaskOrder` really guarantees and `byOrder` already sorts by: keys are
+ * compared as strings.
+ *
+ * Two cases, and they are the whole alphabet:
+ *
+ * - `below` shares no prefix with `above`. Then the two already differ at a digit `above` wins, and
+ *   anything appended to `below` keeps losing at that same digit — so `below + "V"` is between them
+ *   however long either of them is.
+ * - `below` IS a prefix of `above`. Then every key after `below` starts with `below`, and the
+ *   smallest one that exists is `below + "0"`. If `above` is that key, the character class holds
+ *   NOTHING in between — `"a0"` and `"a00"` is the pair this ticket is named after — and the answer
+ *   is `null`, which the callers turn into a refusal rather than a card placed somewhere else.
+ */
+function extendedOrder(below, above) {
+    if (above === null)
+        return `${below}${MiddleOrderDigit}`;
+    if (below >= above)
+        return null;
+    if (!above.startsWith(below))
+        return `${below}${MiddleOrderDigit}`;
+    return above === `${below}${SmallestOrderDigit}` ? null : `${below}${SmallestOrderDigit}`;
+}
+/**
+ * A key strictly between two stored ones, or `null` when no key exists there (anchrd/intel#359).
+ *
+ * ⚠️ This is where "who decides what a valid order key is" is answered, and the answer is
+ * `BoardTaskOrder` — the character class — and NOT `fractional-indexing`. The two disagreed, and
+ * the disagreement WAS the bug: a stored board may spell `"0"`, `"a00"`, `"zzz"` or `"A"`, the
+ * library reads none of them, and it says so with a bare `Error` rather than an `IntelError` — a
+ * `500 internal_error` on an ordinary `board_task_add`, with one task on the board and no drag
+ * involved.
+ *
+ * ⚠️ Narrowing the schema to what the library reads was the other way round, and it is the trap
+ * #311, #318 and #321 each walked into from a different side: that would be a rule on the STORED
+ * document, and a stored board body is parsed in FOUR places — `parseStoredBoard`, `indexing.ts`,
+ * `document-links.ts` and the bundle import. A board carrying one such key would stop being
+ * drawable, searchable, linkable and movable, all at once, over a value that is server-assigned and
+ * that no caller ever sent.
+ *
+ * ⚠️ So the library is ASKED and not trusted. It is the only thing that knows how to keep keys
+ * short and dense, which is what every healthy board lives on, and it stays the first answer. But
+ * when it refuses a bound, that is a statement about the bound and not about the board, and the
+ * fallback carries on with string comparison alone.
+ *
+ * ⚠️ `null` is an answer and not a failure, and it is the one thing callers may not paper over. It
+ * means the character class holds no key in that interval at all, so the only alternatives are
+ * refusing and sliding a card past another one in silence — and the second is the mistake the
+ * second review round of anchrd/intel#341 produced.
+ *
+ * ⚠️ The `catch` drops the library's message on purpose, and this is not the swallowed cause
+ * `.claude/review-rules.md` names: nothing here is being reported to anybody. `generateKeyBetween`
+ * throws to say "I do not read this bound", which is a QUESTION ANSWERED and the whole reason the
+ * second half exists. The refusals a caller actually sees are built below from `null`, a state this
+ * function decided, and they name which side is at fault and what to do about it.
+ */
+function orderBetween(below, above) {
+    try {
+        return generateKeyBetween(below, above);
+    }
+    catch {
+        return extendedOrder(below ?? "", above);
+    }
+}
 /**
  * Every board operation, applied to the document rather than to the file (#285).
  *
@@ -180,9 +261,14 @@ export function repeatedBoardId(document) {
  */
 export function createBoard(deps) {
     function byOrder(left, right) {
-        // The id breaks a tie that cannot happen: two keys are distinct by construction. It is here so
-        // the sort is total, because an unstable order would make two readers of the same board
-        // disagree about which card comes first.
+        // ⚠️ The id breaks a tie that DOES happen, which is why it is not merely insurance
+        // (anchrd/intel#359). A board bundle written elsewhere may name one key twice, and a placement
+        // whose bounds are two neighbours the caller named but that are not next to each other can mint
+        // one that a card between them already holds — the second is anchrd/intel#380 and is not fixed
+        // here. What every placement taking its bounds from the nearest keys ACTUALLY there cannot do
+        // is create a repeat: such a key is strictly inside an interval no card occupies. The tie is
+        // broken at all because the sort has to be total — an unstable order would make two readers of
+        // the same board disagree about which card comes first.
         if (left.order === right.order)
             return left.id < right.id ? -1 : 1;
         return left.order < right.order ? -1 : 1;
@@ -349,6 +435,91 @@ export function createBoard(deps) {
         for (const id of stack)
             visit(id);
     }
+    /**
+     * The key a placement gets, or the refusal that names the way out (anchrd/intel#359).
+     *
+     * ⚠️ Everything that mints a key for a placement comes through here, so that the two answers
+     * `orderBetween` can give — a key, or "no key exists there" — are turned into an `IntelError`
+     * once rather than at every call site. What must never come out of it is a bare `Error`: that is
+     * `500 internal_error` at the surface, on a board whose keys somebody else wrote.
+     *
+     * ⚠️ The length is checked on BOTH paths, not only on the extension. `generateKeyBetween` happily
+     * answers a 64-character key with a 65-character one, and a key one over
+     * `MaxBoardTaskOrderLength` would be stored and then refused by the very next read
+     * (`board_unreadable`) — the whole board lost over one added card.
+     *
+     * ⚠️ The first refusal names the crowded neighbour by its ORDER KEY rather than by its id, the
+     * same way the repair's does: the key is what made it the neighbour, and `board_get` answers with
+     * both. The second cannot — a key that is already as long as one may be leaves no interval and so
+     * no single task to point at — so it names the move instead of the card.
+     */
+    function mintedKey(below, above) {
+        const key = orderBetween(below, above);
+        if (key === null) {
+            // ⚠️ Two sentences, because they are two different situations and only one of them can point
+            // at a card. Equal bounds mean the two neighbours ARE one place, and naming "the task whose
+            // order is a0" would name both of them; either one moving is what opens the place.
+            const reason = below === above
+                ? `The tasks named as neighbours both carry the order key “${below}”, so there is no place between them. Move either of them with board_task_move`
+                : `No order key fits ${below === null ? `before “${above}”` : `between “${below}” and “${above}”`}, so this task has nowhere to go. Move the task whose order is “${above}” with board_task_move`;
+            throw new IntelError(409, "board_task_order_unreadable", `${reason}, then place this one again.`);
+        }
+        if (key.length > MaxBoardTaskOrderLength) {
+            throw new IntelError(409, "board_task_order_unreadable", "The order key beside this place is already as long as an order key may be, so there is no room left after it. Move the neighbouring task with board_task_move, then place this one again.");
+        }
+        return key;
+    }
+    /**
+     * The next key that is really ABOVE the one at `index`, rather than the next task in the list.
+     *
+     * ⚠️ The difference only exists on a board whose keys came out of a file, and there it is the
+     * whole point: two cards under one key have no order between them — `BoardTaskOrder` says so and
+     * `byOrder` next door assumes it away — so "between them" is not a place, and a run of equal keys
+     * is ONE place rather than several. Taking `others[index + 1]` blindly hands `generateKeyBetween`
+     * a lower bound that is not below its upper, which is the bare `Error:  >= ` this ticket is about.
+     *
+     * ⚠️ Skipping the run moves nothing: the new card lands after the whole run instead of inside it,
+     * and every card that was on the board keeps its key.
+     */
+    function nextOrderAbove(others, index) {
+        const below = others[index]?.order;
+        if (below === undefined)
+            return null;
+        return others.slice(index + 1).find((task) => task.order > below)?.order ?? null;
+    }
+    /**
+     * The mirror of `nextOrderAbove`: the nearest key really BELOW the one at `index`.
+     *
+     * ⚠️ It is what a placement that names only a SUCCESSOR has to stand on, and forgetting it was a
+     * bug of its own rather than a detail of anchrd/intel#359. A drop at the top of a column names no
+     * predecessor (`board-kanban.ts` sends `rest[landing - 1] ?? null`), and answering that with "no
+     * lower bound at all" hands `generateKeyBetween` the whole key space: `(null, "a1")` mints `"a0"`
+     * — a key the card below may already hold, in this column or another. Intel then writes two tasks
+     * under one order key on an ordinary drag, which is the very state anchrd/intel#341 and this
+     * ticket exist to answer.
+     *
+     * ⚠️ Without it the extension is worse than wrong, it is silent: `extendedOrder("", above)` sees
+     * `above.startsWith("")` and answers `"0"`, the smallest key the character class can spell, so a
+     * card dropped above one task lands above NONE of them and nothing says so.
+     *
+     * ⚠️ Against a run of equal keys it answers the key below the WHOLE run, so the new card lands
+     * before all of them — the exact mirror of what `nextOrderAbove` does upward, and for the same
+     * reason: cards sharing a key have no order between them, so the run is one place.
+     *
+     * ⚠️ It answers about the bound the caller did NOT name. Where they named both and the two are
+     * not next to each other, the bounds are their cards and a key between them can be one that a
+     * card in the gap already holds — anchrd/intel#380, not closed here.
+     */
+    function previousOrderBelow(others, index) {
+        const above = others[index]?.order;
+        if (above === undefined)
+            return null;
+        // `reverse` mutates, and the slice it mutates is this call's own copy.
+        return (others
+            .slice(0, index)
+            .reverse()
+            .find((task) => task.order < above)?.order ?? null);
+    }
     /**
      * The order key for a task's new place.
      *
@@ -378,16 +549,55 @@ export function createBoard(deps) {
             const column = others.filter((task) => task.status === placement.status && task.parentId === placement.parentId);
             const last = column.at(-1);
             if (!last)
-                return generateKeyBetween(others.at(-1)?.order ?? null, null);
+                return mintedKey(others.at(-1)?.order ?? null, null);
             afterIndex = others.indexOf(last);
         }
-        const lower = afterIndex === null ? null : (others[afterIndex]?.order ?? null);
+        // Each bound is the named neighbour where the caller gave one, and the nearest key really on
+        // the other side of the other neighbour where they did not. Reading an absent bound as "the end
+        // of the key space" is what let a drop at the top of a column mint a key another card holds.
+        const lower = afterIndex !== null
+            ? (others[afterIndex]?.order ?? null)
+            : beforeIndex !== null
+                ? previousOrderBelow(others, beforeIndex)
+                : null;
         const upper = beforeIndex !== null
             ? (others[beforeIndex]?.order ?? null)
             : afterIndex !== null
-                ? (others[afterIndex + 1]?.order ?? null)
+                ? nextOrderAbove(others, afterIndex)
                 : null;
-        return generateKeyBetween(lower, upper);
+        return mintedKey(lower, upper);
+    }
+    /**
+     * A key strictly after `below` and strictly under `above`, for the repair (anchrd/intel#341).
+     *
+     * ⚠️ The same `orderBetween` the placements use, because there is one answer to "how is an order
+     * key made" and it should not be given twice — this only says it in the repair's own words. What
+     * differs is the sentence a caller reads: they came here from a refused import, not from a drag.
+     *
+     * ⚠️ Refused rather than written, in both directions. Over `MaxBoardTaskOrderLength` the key would
+     * be stored and then rejected by the very next read (`board_unreadable`); with no key in the
+     * interval at all it would take a silent slide past the task above to carry on. Either way the
+     * board keeps its pair and hears why.
+     *
+     * ⚠️ And the refusal says what to DO, for the same reason the refused import does: the crowded
+     * neighbour is usually one `board_task_move` from being out of the way, and the repair then goes
+     * through. Since anchrd/intel#359 that move is a real way out rather than a second 500 — it meets
+     * the same unreadable keys and answers them, which is what closed the one dead end this exit did
+     * not reach.
+     *
+     * ⚠️ Nothing checks the key against the ones the board already holds, and nothing needs to:
+     * `above` is the SMALLEST key above `below`, so every other key on the board is at or below
+     * `below` or at or above `above`, and `orderBetween` answers strictly inside that interval.
+     */
+    function keyAfter(below, above) {
+        const key = orderBetween(below, above);
+        if (key === null) {
+            throw new IntelError(409, "board_task_order_unreadable", `Nothing fits between the repeated task and the one ordered after it. Move the task whose order is “${above}” with board_task_move, then repair again.`);
+        }
+        if (key.length > MaxBoardTaskOrderLength) {
+            throw new IntelError(409, "board_task_order_unreadable", "The order key beside the repeated task is already as long as an order key may be, so a repair has nowhere to put the second entry");
+        }
+        return key;
     }
     function replaced(board, task) {
         return {
@@ -523,6 +733,94 @@ export function createBoard(deps) {
             });
             return { board: { statuses: board.statuses, tasks }, deleted: removed.size };
         },
+        /**
+         * The way out of a board that names one task id twice (anchrd/intel#341).
+         *
+         * ⚠️ Nobody chooses which of the two survives, because nothing is lost: both entries stay,
+         * whole, and only the id of the later one changes. That is the entire repair, and it is what
+         * lets it happen at all — #321 refused to fold such a pair on the READ precisely because a fold
+         * throws one of two real tasks away, and the next save of any kind writes that away for good.
+         * Here somebody asked, one field of one entry moves, and the answer says exactly which.
+         *
+         * ⚠️ The FIRST stored entry keeps the id, and that is not a coin toss. Every read here already
+         * means that one by it: `taskOf` is a `find`, so `updateTask`, `moveTask` and `deleteTask` have
+         * always taken the first entry's content as "the task with this id". Renumbering the first
+         * instead would hand the id to a task the server never meant by it, and every `parentId` and
+         * `dependsOn` on the board would silently start pointing at a different card.
+         *
+         * ⚠️ The UI's fold picks a different entry, and that is not a disagreement to repair.
+         * `orderedTasks` (packages/ui) folds AFTER sorting, so the card on screen is whichever of the
+         * pair would be drawn first — which can be the second stored one. That rule is about a DRAWING
+         * and #321 chose it so the card a reader clicks is the one `byId` answers with; this one is
+         * about what the id MEANS, and the two only differ for as long as the pair exists. After the
+         * repair every id is distinct, both cards are drawn, and their titles say which is which.
+         *
+         * ⚠️ `parentId` and `dependsOn` are left exactly as they stand, on both entries and on every
+         * other task — they are NOT copied onto the renumbered one. Two tasks cannot inherit one edge:
+         * a `parentId` is one id, so "both" is not a thing the document can say. What the pointers
+         * meant while the pair existed is what they mean now — the entry that kept the id — and the
+         * renumbered task therefore comes out with nothing hanging off it. That is visible on the
+         * board, and `board_task_move` moves a subtask under it in one call; inventing the edges here
+         * would be the silent change this repair exists to avoid.
+         *
+         * ⚠️ The `order` key is re-minted with the id, and it HAS to be. A duplicate is a copy, so both
+         * entries usually carry the same fractional index — harmless while they were one card, and a
+         * broken board the moment they are two: `BoardTaskOrder` says a shared key leaves two tasks with
+         * no defined order at all, and `byOrder` next door assumes keys are distinct by construction.
+         * Both cards are drawn after the repair, so a drop between them sends the pair as its two
+         * neighbours and `generateKeyBetween` refuses a lower bound that is not below its upper — an
+         * `Error:  >= ` rather than an `IntelError`, which is a 500 on an ordinary drag. Re-minting is
+         * not content anybody gave up: `order` is server-assigned and a caller can never send one, and
+         * the key is minted where the entry already stood.
+         *
+         * ⚠️ It is minted against the next key STRICTLY above, not against the neighbour. A file that
+         * repeats an id can repeat an order key three times over, and anchoring on an equal key would
+         * make the way out throw exactly what it exists to prevent.
+         *
+         * ⚠️ Neither `requireParent` nor `requireDependencies` runs. Such a board arrived through a
+         * bundle written elsewhere and may break other rules too — a dependency on a task it does not
+         * hold, a chain deeper than `BoardMaxTaskDepth` — and refusing the repair over one of those
+         * would leave the board stuck for a reason the caller did not come about. Nothing here can
+         * create one of THOSE either: a fresh id has nothing pointing at it, so no cycle can close
+         * through the task that changed and no chain grows.
+         *
+         * ⚠️ There is no sibling for `statuses`, and none is needed: `configure` writes the whole list
+         * and `ConfigureBoardInput` has demanded distinct ids since #285, so one `board_configure` with
+         * the repeated id spelled differently repairs a duplicate column — with the caller choosing the
+         * label, which is a thing only they can know.
+         */
+        repairTaskIds(board) {
+            const seen = new Set();
+            const renumbered = [];
+            // Both grow as keys are minted: `generateKeyBetween` is deterministic, so a third entry under
+            // one id anchored on the same key as the second would be handed the second's key back. It
+            // anchors on the last one minted for that id instead, which is also what keeps the entries in
+            // the order the file listed them.
+            const orders = board.tasks.map((task) => task.order);
+            const lastMinted = new Map();
+            const tasks = board.tasks.map((task) => {
+                if (!seen.has(task.id)) {
+                    seen.add(task.id);
+                    return task;
+                }
+                const below = lastMinted.get(task.id) ?? task.order;
+                const above = orders.filter((order) => order > below).sort();
+                const order = keyAfter(below, above.at(0) ?? null);
+                orders.push(order);
+                lastMinted.set(task.id, order);
+                const renamed = { ...task, id: deps.id(), order };
+                seen.add(renamed.id);
+                renumbered.push({ previousId: task.id, task: renamed });
+                return renamed;
+            });
+            // Refused rather than answered with an empty list: a caller sent here by a refused import
+            // learns that this board is not the one holding the pair, and a board that needs nothing does
+            // not get a version, an audit event and a reindex for a document that did not change.
+            if (renumbered.length === 0) {
+                throw new IntelError(409, "board_task_ids_distinct", "This board names every task once, so there is nothing to repair");
+            }
+            return { board: { statuses: board.statuses, tasks }, renumbered };
+        },
         sorted,
     };
 }

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

@@ -27,5 +27,12 @@ export interface BoardOperations {
         board: BoardDocument;
         deleted: number;
     };
+    repairTaskIds(board: BoardDocument): {
+        board: BoardDocument;
+        renumbered: {
+            previousId: string;
+            task: BoardTask;
+        }[];
+    };
     sorted(tasks: readonly BoardTask[]): BoardTask[];
 }

package/dist/nodes/nodes.js

@@ -689,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.
@@ -884,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)
@@ -1510,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) };
@@ -1625,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) {
@@ -1772,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),
                 };
@@ -1796,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 (;;) {