@anchrd/intel-api 0.12.5 → 0.14.0

package/dist/nodes/board/board.js

@@ -1,6 +1,251 @@
-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";
+/**
+ * Statuses that answer whether standing in them means finished (anchrd/intel#311).
+ *
+ * ⚠️ This is the ONE place the old positional rule survives, and it survives as a data migration
+ * rather than as a reading. A board written before `terminal` existed has no answer to "which
+ * columns mean finished", and the honest answer is the one that board already behaved as: the last
+ * column before `archived`, plus the shelf. Filling `false` everywhere instead would quietly declare
+ * that nothing on any existing board is done — every finished task would become an open blocker
+ * overnight. Filling `true` everywhere would be the same lie the other way round.
+ *
+ * ⚠️ It touches only what is missing. A status that already carries the flag keeps it, whatever the
+ * position rule would have said — otherwise the migration would undo somebody's configuration every
+ * time their board was read.
+ *
+ * `undefined` means "nothing to do", which is what keeps an untouched document identical rather
+ * than merely equal.
+ */
+function upgradedStatuses(statuses) {
+    if (!Array.isArray(statuses))
+        return undefined;
+    const entries = statuses.filter((status) => typeof status === "object" && status !== null);
+    if (entries.every((status) => "terminal" in status))
+        return undefined;
+    // The end of the work as the board behaved before the flag: the last column that is not the shelf,
+    // read in the stored order rather than in array order, because `order` is what a surface draws by.
+    const working = entries
+        .filter((status) => status.id !== ArchivedBoardStatusId)
+        .sort((left, right) => Number(left.order ?? 0) - Number(right.order ?? 0));
+    const lastWorking = working.at(-1)?.id;
+    return statuses.map((status) => {
+        if (typeof status !== "object" || status === null || "terminal" in status)
+            return status;
+        const entry = status;
+        return {
+            ...entry,
+            terminal: entry.id === ArchivedBoardStatusId || entry.id === lastWorking,
+        };
+    });
+}
+/**
+ * The three task lists that have to be distinct, and how a stored entry is recognised again.
+ *
+ * ⚠️ `labels` are compared TRIMMED and the two id lists are not, and that mirrors the schema
+ * exactly: `BoardTaskLabel` carries `.trim()`, `BoardTaskId` and `IntelId` do not. Comparing raw
+ * here would leave `["Bug ", "Bug"]` untouched — and zod, which trims each entry BEFORE the
+ * distinctness check runs on the array, would then see one word twice and refuse the board. That is
+ * precisely the `board_unreadable` this function exists to prevent, arrived at through the fold.
+ */
+const distinctTaskLists = [
+    { field: "dependsOn", identity: (value) => value },
+    {
+        field: "labels",
+        identity: (value) => (typeof value === "string" ? value.trim() : value),
+    },
+    { field: "references", identity: (value) => value },
+];
+/**
+ * Tasks whose lists name nothing twice (anchrd/intel#318).
+ *
+ * ⚠️ `dependsOn`, `labels` and `references` are refused at the write boundary now, and that refusal
+ * reaches nothing already in R2 — boards have been writable since `c29fd12` and `board_task_update`
+ * took a repeat without complaint. A stored board carrying one would meet the strict `BoardTask` and
+ * answer `board_unreadable`: the whole board lost over a value that has no reading, which is the
+ * trap #311 walked into from the other side.
+ *
+ * ⚠️ Folded here and refused there, and the difference is not inconsistency — it is who is being
+ * answered. A caller handed back a shorter list than it sent learns nothing and repeats itself; a
+ * stored document has no caller to tell, and dropping the board instead would punish a reader for
+ * what some writer did months ago.
+ *
+ * ⚠️ The FIRST mention keeps its place. Every surface draws these lists in the order they stand in.
+ */
+function dedupedTaskLists(tasks) {
+    if (!Array.isArray(tasks))
+        return undefined;
+    let folded = false;
+    const next = tasks.map((task) => {
+        if (typeof task !== "object" || task === null)
+            return task;
+        const entry = task;
+        const lists = distinctTaskLists.flatMap(({ field, identity }) => {
+            const list = entry[field];
+            if (!Array.isArray(list))
+                return [];
+            const seen = new Set();
+            const distinct = list.filter((value) => {
+                const key = identity(value);
+                if (seen.has(key))
+                    return false;
+                seen.add(key);
+                return true;
+            });
+            return distinct.length === list.length ? [] : [[field, distinct]];
+        });
+        if (lists.length === 0)
+            return task;
+        folded = true;
+        return { ...entry, ...Object.fromEntries(lists) };
+    });
+    return folded ? next : undefined;
+}
+/**
+ * A stored board brought up to the current schema, before it is validated.
+ *
+ * ⚠️ It runs before `BoardDocument.parse`, on `unknown`, because after that parse a missing field or
+ * a repeated id is already a refusal — and `parseStoredBoard` is deliberately loud
+ * (`board_unreadable`), so an un-upgraded board would not read as "old", it would read as corrupt.
+ *
+ * The upgrade is persisted by the next write of any kind, because every write serialises the whole
+ * document. Nothing has to be migrated ahead of time and nothing has to be re-migrated.
+ */
+export function upgradeStoredBoard(parsed) {
+    if (typeof parsed !== "object" || parsed === null)
+        return parsed;
+    const document = parsed;
+    const statuses = upgradedStatuses(document.statuses);
+    const tasks = dedupedTaskLists(document.tasks);
+    if (statuses === undefined && tasks === undefined)
+        return parsed;
+    return {
+        ...document,
+        ...(statuses !== undefined && { statuses }),
+        ...(tasks !== undefined && { tasks }),
+    };
+}
+/**
+ * The first id a board document uses for two different things (anchrd/intel#321).
+ *
+ * ⚠️ Deliberately NOT a rule on `BoardDocument`, and that is the whole decision. A schema rule would
+ * reach every parse of a stored body — `parseStoredBoard`, `indexing.ts`, the link reader — and a
+ * board imported before this existed would stop answering with `board_unreadable`: the whole board
+ * gone over something that costs one view. It is the trap #311 walked into, and #318 walked into
+ * from the other side.
+ *
+ * ⚠️ And NOT folded in `upgradeStoredBoard` either, which is where the sibling rules of #318 went. A
+ * repeated `dependsOn`, label or reference carries no information, so dropping the second mention
+ * loses nothing. Two tasks under one id are two whole tasks — titles, dates, descriptions — and a
+ * fold on the READ is written back by the next save of any kind, because every write serialises the
+ * whole document. That is one task gone for good, for every board, without anybody having asked.
+ * The UI folds the same pair for a DRAWING (`orderedTasks`), which costs nothing: the document keeps
+ * both, and repairing the pair brings the second card back.
+ *
+ * ⚠️ What this does NOT rescue, and it is worth knowing: `replaced` matches a task by id, so the
+ * 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. 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()`)
+ * and takes its status list through `ConfigureBoardInput`, which has demanded distinct ids since
+ * #285.
+ */
+export function repeatedBoardId(document) {
+    for (const list of ["statuses", "tasks"]) {
+        const seen = new Set();
+        for (const entry of document[list]) {
+            if (seen.has(entry.id))
+                return { list, id: entry.id };
+            seen.add(entry.id);
+        }
+    }
+    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).
  *
@@ -16,9 +261,14 @@ import { IntelError } from "../../shared/intel-error/intel-error.js";
  */
 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;
@@ -185,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.
      *
@@ -214,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 {
@@ -260,6 +634,11 @@ export function createBoard(deps) {
                 id: status.id,
                 label: status.label,
                 order: index,
+                // ⚠️ The shelf is always terminal and the boundary refuses an explicit `false` for it, so
+                // this is not a silent correction of something a caller asked for — it is the same fact
+                // stated where the document is built. Everything else defaults to "not finished": a new
+                // column is work, and a column that ends work is a thing somebody says on purpose (#311).
+                terminal: status.id === ArchivedBoardStatusId ? true : (status.terminal ?? false),
             }));
             return { statuses: next, tasks: board.tasks };
         },
@@ -354,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/document-links/document-links.js

@@ -1,4 +1,5 @@
 import { BlockNoteDocument, BlockNoteMediaType, BoardDocument, BoardMediaType, DocumentLinkInlineType, } from "@anchrd/intel-contract";
+import { upgradeStoredBoard } from "../board/board.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
@@ -52,7 +53,17 @@ export function documentLinkTargets(mediaType, content) {
     }
     const found = new Set();
     if (mediaType === BoardMediaType) {
-        const board = BoardDocument.safeParse(parsed);
+        /**
+         * ⚠️ Upgraded first, like `parseStoredBoard` and `indexing.ts` — this is the FOURTH place a
+         * board body is parsed, and the only one that cannot complain (anchrd/intel#321).
+         *
+         * A board it fails to parse simply has no links, which reads exactly like a board that points
+         * at nothing — and the reconciliation this feeds removes the links a body no longer names, so
+         * an unparsed old board would quietly leave the link graph. Every caller hands it a body written
+         * moments earlier today, so it has never met one; the upgrade is what keeps that from being the
+         * only reason.
+         */
+        const board = BoardDocument.safeParse(upgradeStoredBoard(parsed));
         if (!board.success)
             return [];
         for (const task of board.data.tasks) {