@anchrd/intel 0.59.0

package/dist/nodes/nodes.js

@@ -0,0 +1,1667 @@
+import { TableMediaType } from "../contract/table.js";
+import { callersPhrase, namedOrCounted } from "../shared/callers/callers.js";
+import { encodeCsv, parseCsv } from "../shared/csv/csv.js";
+import { requireFutureExpiry } from "../shared/grant-expiry/grant-expiry.js";
+import { IntelError } from "../shared/intel-error/intel-error.js";
+import { plainTitle } from "../shared/plain-title/plain-title.js";
+import { documentLinkTargets } from "./document-links/document-links.js";
+// ⚠️ The R2 key of a version written before #125 begins `knowledge/`, and it stays that way. A key
+// is stored in `node_versions.content_key` and read back from there; nothing derives one from ids,
+// and nothing lists the bucket by prefix. So the two prefixes cost nothing, while rewriting the old
+// ones would mean copying every object in the bucket to change a string nobody reads.
+function contentKeyFor(nodeId, versionId) {
+    return `nodes/${nodeId}/versions/${versionId}`;
+}
+// A node grant covers every flow beneath the node it sits on, so there is never a sub-flow it fails
+// to reach and this half of the warning is empty here by construction (#530). Written out rather
+// than left to the schema's default: nothing parses a service's answer on the way out, so a default
+// would arrive at the UI as `undefined`.
+const nothingWithheld = { titles: [], hidden: 0 };
+// A verb that cannot apply to a node is neither offered on it nor accepted for it (ADR-0004 §2).
+// The answer lives here rather than in the screen so HTTP, MCP and the UI cannot disagree about it.
+//
+// `execute` is meaningful where something can be run, and since #390 that is the folder alone —
+// because only a folder can hold a flow. Reading something and being permitted to put it to work
+// stay separate questions, which is the whole reason the verbs are granted independently rather
+// than as a ladder (ADR-0004 §2).
+function applicableVerbs(kind) {
+    return kind === "folder" ? ["read", "write", "execute", "share"] : ["read", "write", "share"];
+}
+/**
+ * Which kinds hold an editor body — the text somebody types and `node_get` reads back.
+ *
+ * ⚠️ **A card is one of them, and that is the whole of D66 on the write side** (#785). A task is a
+ * node like every other: its text is a node version, in the same table, through the same route. The
+ * panel reaches this call through `POST /nodes/:id/versions` exactly as MCP does, so a list that
+ * omitted `task` closed BOTH surfaces at once — an agent could name a card and not describe it, and
+ * a reader typing into the card got "could not be saved" over a body the model says it should hold.
+ *
+ * ⚠️ **A set, not one more `||`.** The other four kinds each carry their content some other way —
+ * a folder and a board hold children, an attachment holds bytes, a table holds CSV segments — and
+ * naming the ones that DO take an editor version is what keeps the next kind from being waved
+ * through by a condition that only ever grew. The annotation ties it to the enum: a kind renamed in
+ * the contract stops this file from compiling instead of silently dropping out of the set.
+ */
+const EditorContentKinds = ["document", "task"];
+// ⚠️ The refusal has to be actionable without becoming a directory of the tree. Whoever holds
+// `share` on one folder must not learn the titles of flows they may not see, so the ones they may
+// see are named and the rest are only counted (ADR-0004 §3, and #17's review) — which is the whole
+// of what `callersPhrase` does, in the one place both refusals read it from.
+//
+// The sentence stays for whoever has nothing to formulate with — a model over MCP reads it as it
+// stands — and `namedOrCounted` carries the same decision as data, so a screen can say it in its
+// own language (#448). Both come out of one place: the split between named and counted is an
+// authorization answer, and a surface that recomputed it would be deciding what it may not.
+function callersDetail(callers) {
+    return `Flows outside this folder call into it: ${callersPhrase(callers)}. Change or unpublish them before narrowing the folder.`;
+}
+// The grantee as the ACL sees them, and as nothing else: an identity with no capability of its own,
+// never `isAdmin`. It answers for Intel's resource ACLs only — whether Gate hands this person
+// `intel/admin` is Gate's to know, so the warning below can be pessimistic and never permissive.
+// A grant to an email address is judged as that address, which is what the grant will be attached
+// to; a second grant the same person holds under their user ID is not folded in.
+function asPrincipalActor(principal) {
+    if (principal.type === "user")
+        return { id: principal.id, email: "" };
+    if (principal.type === "email")
+        return { id: "", email: principal.email };
+    return { id: "", email: "" };
+}
+function decodeBase64(value) {
+    if (value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
+        throw new IntelError(400, "attachment_invalid", "Attachment content is not valid base64");
+    }
+    try {
+        return Uint8Array.from(atob(value), (character) => character.charCodeAt(0));
+    }
+    catch {
+        throw new IntelError(400, "attachment_invalid", "Attachment content is not valid base64");
+    }
+}
+/**
+ * Where a kind may be filed, and it is one rule read by two callers — `create` and the move inside
+ * `update` (#377).
+ *
+ * ⚠️ **Three cases, and the first version had only one of them.** It handled "wrong parent that
+ * exists" and left two doors open, both of which produced exactly the state the rule exists against:
+ *
+ *   * **No parent at all.** `parentId: null` is the ROOT, and the root is not a board. The first
+ *     version skipped the check entirely for `null`, so `node_create({ kind: "task", parentId:
+ *     null })` made a task with no board — and `attachToBoard` did not run either, for the same
+ *     reason. A task on no board, created through the front door.
+ *   * **Right kind, wrong board.** Every `kind === "board"` was accepted as a destination, so a
+ *     task could be moved to ANOTHER board while its `board_tasks.board_id` stayed behind. That
+ *     divergence was reachable only by writing D1 by hand before this rule existed (the join in
+ *     `db-boards.ts` guards against it); the first version of this rule opened a real code path to
+ *     it. **A change that widens what is allowed has to be read for what it now permits, not only
+ *     for what it now refuses.**
+ *
+ * ⚠️ The refusal names the KIND in the sentence rather than a bare "not a folder". Somebody
+ * dragging a card into a folder has to learn what went wrong, not that something did.
+ */
+/**
+ * ⚠️ **Nothing may be filed under an ARCHIVED node**, and this is not tidiness — it is what keeps
+ * the purge honest.
+ *
+ * Archiving takes the whole subtree since D71 (#733), so an archived node holds nothing live at the
+ * moment it is archived. Without this rule it could GAIN one afterwards, and `purge` — which asks
+ * only whether the node itself is archived — walks the whole subtree and takes that child with it.
+ * It would disappear for good without ever being named in the confirmation.
+ *
+ * Found in review of #669, against my own sentence claiming purge needed no rule of its own. That
+ * sentence was true only as long as an archived node could never gain a live child, and until #679
+ * and D71 nothing made it true: the guard covered tasks alone, and archiving covered one row.
+ */
+/**
+ * The board a node would be filed on: the board itself, or the board of the task it hangs under
+ * (#669).
+ *
+ * ⚠️ **One function, because there are three callers and they must not drift.** The create path,
+ * the move and the idempotent replay all ask the same question, and the replay was written when a
+ * task's parent was always its board — it passed `parentId` straight through as the board id. With
+ * nesting that files a subtask on a "board" that is another card, and `board_tasks.board_id` has no
+ * foreign key saying otherwise. Found in review of #669: the main path had been corrected and this
+ * one had not, which is the shape of `anchrd/intel#457` — two places answering one question, only
+ * one of them told about the change.
+ */
+async function boardFor(deps, actor, parent) {
+    if (parent === null)
+        return null;
+    if (parent.kind === "board")
+        return parent.id;
+    // ⚠️ Only a TASK can have a board, and asking for anything else costs a D1 round trip on every
+    // write in the whole tree — a document filed in a folder would pay for a board feature. The
+    // question is not "do we know the board" but "can this parent have one at all".
+    if (parent.kind !== "task")
+        return null;
+    return (await deps.boardOfTask?.(actor, parent.id)) ?? null;
+}
+// How many of the nodes a purge would take are named in the preview. High enough that an ordinary
+// folder is listed in full, low enough that a tree nobody can render is not built (#733).
+const PURGE_PREVIEW_NAMES = 50;
+function refuseArchivedParent(parent) {
+    // ⚠️ EVERY kind, not just tasks (#679). It was narrowed to tasks in #677 because widening it out
+    // of a board ticket would have changed the whole tree with no test outside `boards.int.ts`; the
+    // hole it left is older than that ticket and is what this one closes.
+    //
+    // ⚠️ **The DIRECT parent is enough since D71 (#733), and only since then.** Archiving cascades, so
+    // an archived node holds nothing live at the moment it is archived, and a restore under an
+    // archived parent is refused: there is no live node under an archived one for something to be
+    // filed beneath. Before that, this guard closed one level while `Aussen` archived over a live
+    // `Innen` still handed anything filed under `Innen` to the purge.
+    if (parent === null || parent.archivedAt === null)
+        return;
+    throw new IntelError(409, "parent_archived", `This ${parent.kind} is archived, so nothing new can be filed under it. Restore it first.`);
+}
+function refuseWrongParent(childKind, parent, boards) {
+    if (childKind === "task") {
+        if (parent === null) {
+            throw new IntelError(409, "task_belongs_to_a_board", "A task lives on a board. The top level is not one, so there is nowhere for it to sit there.");
+        }
+        // ⚠️ Since #669 a task may sit under a task — the hierarchy is the node tree. Everything else
+        // is still refused by name.
+        if (parent.kind !== "board" && parent.kind !== "task") {
+            throw new IntelError(409, "task_belongs_to_a_board", `A task lives on a board and cannot be filed under a ${parent.kind}. Move the board instead, or make a new task on the board you want it on.`);
+        }
+        /**
+         * ⚠️ **The same BOARD, not the same parent node — and that difference is what #669 changed.**
+         * Until then the two were interchangeable, because a task's parent always WAS its board; the
+         * check compared parent ids and was right by accident. With nesting, moving a card under a
+         * sibling changes its parent legitimately while the board stays the same, and comparing ids
+         * would refuse a move that is allowed.
+         *
+         * The rule it protects is unchanged: `board_tasks.board_id` does not travel with a move through
+         * the node path, so a card handed to another board would answer from one board's query while
+         * its row names the other — and the card would show up on neither, or on both.
+         */
+        if (boards?.destination === null || boards?.destination === undefined) {
+            throw new IntelError(409, "task_belongs_to_a_board", "This destination has no board, so a card cannot be filed under it.");
+        }
+        if (boards.current !== undefined &&
+            boards.current !== null &&
+            boards.destination !== boards.current) {
+            throw new IntelError(409, "task_cannot_change_board", "A card cannot be handed to another board this way. Make it on the board you want it on; its position, status and dependencies belong to the board it was filed on.");
+        }
+        return;
+    }
+    // The root takes everything else — that is what a top-level folder or document is.
+    if (parent === null)
+        return;
+    if (parent.kind === "board") {
+        throw new IntelError(409, "board_holds_only_tasks", `A board holds tasks and nothing else; a ${childKind} cannot be filed on one.`);
+    }
+    if (parent.kind !== "folder") {
+        throw new IntelError(409, "parent_not_folder", "A node's parent must be a folder");
+    }
+}
+export function createNodes(deps) {
+    function mergeSearchResults(lexical, semantic, semanticScores, limit) {
+        const merged = new Map();
+        for (const citation of lexical) {
+            merged.set(citation.nodeId, {
+                citation,
+                lexicalScore: citation.score,
+                semanticScore: undefined,
+            });
+        }
+        for (const citation of semantic) {
+            const current = merged.get(citation.nodeId);
+            merged.set(citation.nodeId, {
+                citation: current?.citation ?? citation,
+                lexicalScore: current?.lexicalScore,
+                semanticScore: semanticScores.get(citation.nodeId) ?? citation.score,
+            });
+        }
+        return [...merged.values()]
+            .map(({ citation, lexicalScore, semanticScore }) => {
+            const score = lexicalScore !== undefined && semanticScore !== undefined
+                ? lexicalScore * 0.45 + semanticScore * 0.55
+                : lexicalScore !== undefined
+                    ? lexicalScore * 0.9
+                    : (semanticScore ?? 0) * 0.85;
+            return {
+                ...citation,
+                score: Math.max(0, Math.min(1, score)),
+                match: lexicalScore !== undefined && semanticScore !== undefined
+                    ? "hybrid"
+                    : lexicalScore !== undefined
+                        ? "lexical"
+                        : "semantic",
+            };
+        })
+            .sort((left, right) => right.score - left.score || right.freshness.localeCompare(left.freshness))
+            .slice(0, limit);
+    }
+    /**
+     * A table's body: every version's R2 object joined in sequence order (#40).
+     *
+     * ⚠️ This is the price of appending without reading. Each `append` writes one immutable object
+     * holding only the rows it added, so the write is O(new rows) and two concurrent appends cannot
+     * overwrite one another — but a read of a table with k appends costs k R2 gets. That is the
+     * trade the ticket asks for by name: the write side is the hot path a flow uses on a schedule,
+     * the read side is a person opening a grid or one indexing pass. The gets are issued together
+     * rather than in a chain so the cost is k requests, not k round trips; compacting old segments
+     * into one object is a later ticket, and it can happen without changing anything a caller sees
+     * because the version rows stay the history either way.
+     */
+    async function tableContent(node) {
+        if (node.currentVersionId === null)
+            return "";
+        // ⚠️ One statement for every segment key, never one per segment, and only the keys rather than
+        // the whole version rows. The number of D1 round trips a table costs must not grow with the
+        // number of times it has been appended to (#30).
+        const keys = await deps.repository.listVersionContentKeys(node.id);
+        const segments = await Promise.all(keys.map(async (key) => await deps.content.get(key)));
+        if (segments.some((segment) => segment === null)) {
+            throw new IntelError(500, "content_missing", "Version content is missing");
+        }
+        return segments.join("");
+    }
+    /**
+     * The column names, read from the first version alone.
+     *
+     * ⚠️ Deliberately not `tableContent`, and deliberately not the version list either. Checking an
+     * append against the header runs on every append, so it must cost the same on a table of ten rows
+     * and on one of ten thousand: one statement that returns one key, and one small R2 read. Reading
+     * every version row to look at the first would be a cost that grows with the history — one query,
+     * but more of it every time (#30, #40).
+     */
+    async function tableHeader(node) {
+        if (node.currentVersionId === null)
+            return null;
+        const key = await deps.repository.tableHeaderContentKey(node.id);
+        if (key === null)
+            return null;
+        const body = await deps.content.get(key);
+        if (body === null)
+            throw new IntelError(500, "content_missing", "Version content is missing");
+        return parseCsv(body)[0] ?? null;
+    }
+    /**
+     * Whether the write this call lost was its OWN earlier attempt (#821).
+     *
+     * ⚠️ Both doors for an attachment ask this at their conflict, and the reason is a race the check
+     * at the top of each cannot see: two attempts with one idempotency key can both find nothing
+     * there, and then the second one's `appendVersion` refuses because the first one's version has
+     * become the current one in the meantime. Without this the caller who simply retried after a
+     * timeout is told somebody else wrote first — about a version that IS theirs. `save` has answered
+     * it this way since it was written; the attachment doors did not, and one of them is new.
+     */
+    async function replayedUpload(actor, nodeId, idempotencyKey) {
+        const replayed = await deps.repository.findIdempotentNode(actor.id, "node.save", idempotencyKey);
+        return replayed !== null && replayed !== undefined && replayed === nodeId;
+    }
+    async function getDocument(node) {
+        if (node.currentVersionId === null)
+            return { node, version: null, content: null };
+        const version = await deps.repository.getVersion(node.currentVersionId);
+        if (!version)
+            throw new IntelError(500, "version_missing", "Current version is missing");
+        if (node.kind === "attachment")
+            return { node, version, content: null };
+        // A table answers with the whole CSV, so downloading, citing and reading it over MCP all get
+        // the same bytes a person sees in the grid — the format is the export (#40).
+        if (node.kind === "table")
+            return { node, version, content: await tableContent(node) };
+        const content = await deps.content.get(version.contentKey);
+        if (content === null)
+            throw new IntelError(500, "content_missing", "Version content is missing");
+        return { node, version, content };
+    }
+    async function tableOf(node) {
+        const [header = [], ...rows] = parseCsv(await tableContent(node));
+        return { node, columns: header, rows, versionId: node.currentVersionId };
+    }
+    /**
+     * One immutable object holding only what this write adds, plus the version row that orders it.
+     *
+     * ⚠️ The R2 object is written before the version row and is deleted again if the row does not
+     * land, exactly as `save` does it. An orphaned object is invisible; a version row pointing at
+     * nothing is a table that cannot be read at all.
+     */
+    async function writeTableSegment(actor, node, body, segment, idempotencyKey) {
+        const versionId = deps.id();
+        const contentKey = contentKeyFor(node.id, versionId);
+        await deps.content.put(contentKey, body, TableMediaType);
+        try {
+            return await deps.repository.appendTableVersion({
+                version: {
+                    id: versionId,
+                    nodeId: node.id,
+                    contentKey,
+                    mediaType: TableMediaType,
+                    contentHash: await deps.hash(body),
+                    size: new TextEncoder().encode(body).byteLength,
+                    segment,
+                    createdBy: actor.id,
+                    createdAt: deps.now().toISOString(),
+                },
+                actorId: actor.id,
+                idempotencyKey,
+                auditId: deps.id(),
+            });
+        }
+        catch (error) {
+            await deps.content.delete(contentKey).catch(() => undefined);
+            throw error;
+        }
+    }
+    /**
+     * One snapshot — the complete table after a mutation — written only against the state the caller
+     * read (#135).
+     *
+     * ⚠️ The base check lives in the repository's INSERT, not in a read here: between reading the
+     * table and writing its replacement another segment can always land, and only the statement that
+     * inserts the row can refuse at the moment it matters. On "conflict" the R2 object is removed
+     * again and the idempotency table is asked once more, exactly as `save` does it — the conflict
+     * may be this very mutation, already written by a racing retry with the same key.
+     */
+    async function writeTableSnapshot(input) {
+        const versionId = deps.id();
+        const contentKey = contentKeyFor(input.node.id, versionId);
+        const version = {
+            id: versionId,
+            nodeId: input.node.id,
+            sequence: await nextSequence(input.node),
+            contentKey,
+            mediaType: TableMediaType,
+            contentHash: await deps.hash(input.body),
+            size: new TextEncoder().encode(input.body).byteLength,
+            segment: "snapshot",
+            createdBy: input.actor.id,
+            createdAt: deps.now().toISOString(),
+        };
+        await deps.content.put(contentKey, input.body, TableMediaType);
+        let saved;
+        try {
+            saved = await deps.repository.appendSnapshotVersion({
+                version,
+                actorId: input.actor.id,
+                baseVersionId: input.baseVersionId,
+                operation: input.operation,
+                metadata: input.metadata,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+        }
+        catch (error) {
+            await deps.content.delete(contentKey).catch(() => undefined);
+            throw error;
+        }
+        if (saved === "conflict") {
+            await deps.content.delete(contentKey);
+            const replayedId = await deps.repository.findIdempotentNode(input.actor.id, input.operation, input.idempotencyKey);
+            if (replayedId) {
+                const replayed = await deps.repository.getVersion(replayedId);
+                if (replayed)
+                    return replayed;
+            }
+            throw new IntelError(409, "version_conflict", "A newer version already exists");
+        }
+        await deps.indexing.enqueue(version.id);
+        return version;
+    }
+    /**
+     * The current state a mutation addresses: header and rows, read only after the base was checked.
+     *
+     * ⚠️ The refusal for a stale base comes before the content is read, so a caller with an outdated
+     * `baseVersionId` costs one D1 row and no R2 traffic — and the position validation that follows
+     * never runs against rows the caller was not looking at.
+     */
+    async function tableStateFor(node, baseVersionId) {
+        if (node.currentVersionId === null) {
+            throw new IntelError(409, "table_undefined", "This table has no header yet; define its columns before changing rows");
+        }
+        if (node.currentVersionId !== baseVersionId) {
+            throw new IntelError(409, "version_conflict", "A newer version already exists");
+        }
+        const [header, ...rows] = parseCsv(await tableContent(node));
+        if (!header)
+            throw new IntelError(500, "content_missing", "Table header is missing");
+        return { header, rows };
+    }
+    // The same refusal an append gives, for the same reason: a row that does not fit the header is a
+    // caller that believes the table has a different shape, and quietly filling or cutting the gap
+    // would store that misunderstanding as data (#40, unchanged by #135).
+    function requireRowShape(rows, header) {
+        const wrong = rows.findIndex((row) => row.length !== header.length);
+        if (wrong !== -1) {
+            throw new IntelError(400, "table_row_shape", `Row ${wrong + 1} has ${rows[wrong]?.length ?? 0} cells but the table has ${header.length} columns: ${header.join(", ")}`);
+        }
+    }
+    // A position that misses the table is the same kind of misunderstanding as a row that misses the
+    // header: refused whole, nothing written, and the message says what the table actually holds.
+    function requirePositions(positions, rowCount) {
+        const outside = positions.find((position) => position >= rowCount);
+        if (outside !== undefined) {
+            throw new IntelError(400, "table_row_position", `Row position ${outside} is out of range: the table has ${rowCount} row${rowCount === 1 ? "" : "s"}`);
+        }
+    }
+    async function requireTable(actor, nodeId) {
+        const node = await requireVisible(actor, nodeId);
+        if (node.kind !== "table") {
+            throw new IntelError(409, "not_a_table", "Only tables accept rows");
+        }
+        if (!(await deps.repository.can(actor, node.id, "write"))) {
+            throw new IntelError(403, "node_forbidden", "Table cannot be edited");
+        }
+        return node;
+    }
+    async function unreadableForPrincipal(actor, folderId, principal) {
+        const grantee = asPrincipalActor(principal);
+        const titles = [];
+        let hidden = 0;
+        // What a flow reaches for and the grant does not cover. Deduplicated, because a document two
+        // flows both name is one thing the new principal cannot read, not two.
+        const referenced = [...new Set(await deps.flowNodeReferences(actor, folderId))];
+        for (const resourceId of referenced) {
+            if (await deps.repository.can(grantee, resourceId, "read"))
+                continue;
+            const node = await deps.repository.getVisible(actor, resourceId);
+            if (node)
+                titles.push(node.title);
+            else
+                hidden += 1;
+        }
+        return { titles, hidden };
+    }
+    /**
+     * The graph, brought in line with what the saved document actually says (#41).
+     *
+     * A text link is the relationship — there is no second way to make one any more — so the links
+     * of a document are rewritten every time it is saved: what is no longer written is no longer
+     * there, and what was added is.
+     *
+     * ⚠️ Only targets this actor may see become links. The author can only insert what the picker
+     * offers them, but `node_version_create` takes any content over MCP, and an unfiltered write
+     * would turn the graph into a place where the existence of an unreachable document can be confirmed by
+     * anyone who guesses its ID. The filter is `resolveVisibleTitles`, the same lookup the reader's
+     * side goes through — one rule, not two.
+     *
+     * ⚠️ Rows made in the removed dialog are `manual` and are left alone. Saving a document must not
+     * silently delete a relationship somebody entered before there was another way to enter one.
+     */
+    async function reconcileTextLinks(actor, sourceNodeId, mediaType, content) {
+        const written = documentLinkTargets(mediaType, content).filter((id) => id !== sourceNodeId);
+        const visible = written.length === 0
+            ? []
+            : (await deps.repository.resolveVisibleTitles(actor, written)).map((entry) => entry.nodeId);
+        await deps.repository.replaceTextLinks({
+            sourceNodeId,
+            links: visible.map((targetNodeId) => ({ id: deps.id(), targetNodeId })),
+            actorId: actor.id,
+            auditId: deps.id(),
+            occurredAt: deps.now().toISOString(),
+        });
+    }
+    async function requireVisible(actor, nodeId) {
+        const node = await deps.repository.getVisible(actor, nodeId);
+        if (!node)
+            throw new IntelError(404, "node_not_found", "Node was not found");
+        return node;
+    }
+    async function nextSequence(node) {
+        if (!node.currentVersionId)
+            return 1;
+        const current = await deps.repository.getVersion(node.currentVersionId);
+        if (!current) {
+            throw new IntelError(500, "version_missing", "Current node version is missing");
+        }
+        return current.sequence + 1;
+    }
+    async function attachment(actor, nodeId) {
+        const node = await requireVisible(actor, nodeId);
+        if (node.kind !== "attachment" || !node.currentVersionId) {
+            throw new IntelError(404, "attachment_not_found", "Attachment was not found");
+        }
+        const version = await deps.repository.getVersion(node.currentVersionId);
+        if (!version)
+            throw new IntelError(500, "version_missing", "Current version is missing");
+        return {
+            node,
+            version,
+            resourceUri: `intel://nodes/${encodeURIComponent(node.id)}/attachment`,
+        };
+    }
+    return {
+        async list(actor, input) {
+            return await deps.repository.listVisible(actor, input);
+        },
+        // The same level under a bound, for the one caller that draws a bounded picture of it. It goes
+        // through the same predicate as `list`, so what is drawn is a prefix of what is listed and never
+        // a different selection (#30).
+        async childrenBounded(actor, input) {
+            return await deps.repository.listVisibleBounded(actor, input);
+        },
+        async get(actor, nodeId) {
+            return await getDocument(await requireVisible(actor, nodeId));
+        },
+        async purgePreview(actor, input) {
+            const node = await requireVisible(actor, input.nodeId);
+            if (!(await deps.repository.can(actor, input.nodeId, "write"))) {
+                throw new IntelError(403, "node_forbidden", "This node cannot be edited");
+            }
+            if (!node.archivedAt) {
+                throw new IntelError(409, "node_not_archived", "Only an archived node can be deleted for good. Archive it first.");
+            }
+            const tree = await deps.repository.inspectPurgeTree(node.id);
+            return {
+                inboundLinks: await deps.repository.countInboundLinks(node.id),
+                totalItems: tree.nodeIds.length + tree.flowIds.length,
+                /**
+                 * ⚠️ **Named, not just counted** (D71, #733), and the cap is stated rather than silent:
+                 * `totalItems` keeps counting past it, so a surface can always say "and 40 more". Whoever
+                 * confirms a purge is deciding about things, and "82 items" is not a thing.
+                 *
+                 * The node itself is in here too. It is the one the caller named, so it is the one they can
+                 * check the list against.
+                 */
+                items: tree.named.slice(0, PURGE_PREVIEW_NAMES).map((entry) => ({
+                    id: entry.id,
+                    kind: entry.kind,
+                    title: entry.title,
+                })),
+            };
+        },
+        /**
+         * The content of one pinned version (#147). Search citations pin the version they quoted, and
+         * without this read a citation could name text no surface can show any more.
+         *
+         * ⚠️ Authorization first, existence second: `requireVisible` answers 404 for a node this actor
+         * may not reach before the version table is asked anything, so probing version IDs proves
+         * nothing about nodes one cannot see. A version of ANOTHER node is the same 404 — a version ID
+         * is not an address of its own, only a position in the history of a node one may read.
+         *
+         * A table version answers with that segment's own rows (an append) or its snapshot state —
+         * deliberately not the assembled table of that moment, which is what `getTable` answers for
+         * the present. An attachment version answers with its metadata and `content: null`, the same
+         * shape `get` gives an attachment: old attachment bytes stay out of scope here (#147 allows
+         * that explicitly), because inlining them is the attachment resource's decision, not this one's.
+         */
+        async getVersion(actor, nodeId, versionId) {
+            const node = await requireVisible(actor, nodeId);
+            const version = await deps.repository.getVersion(versionId);
+            if (!version || version.nodeId !== node.id) {
+                throw new IntelError(404, "version_not_found", "Version was not found");
+            }
+            if (node.kind === "attachment")
+                return { node, version, content: null };
+            const content = await deps.content.get(version.contentKey);
+            if (content === null) {
+                throw new IntelError(500, "content_missing", "Version content is missing");
+            }
+            return { node, version, content };
+        },
+        // Nodes and Flows share one folder tree (ADR-0004), so Flows has to ask one question about
+        // it: may this actor file something in that folder. The answer stays here, with the tree and
+        // its ACLs, rather than being reimplemented on the flow side.
+        async folderAccess(actor, folderId) {
+            const folder = await deps.repository.getVisible(actor, folderId);
+            // ⚠️ An archived folder answers `missing` rather than a state of its own: filing into one is
+            // refused exactly like filing into one that is not there. The question "is the folder above
+            // archived" is asked by `parentArchivedAt` instead, because it must not run through the
+            // visibility predicate at all (#733).
+            if (!folder || folder.archivedAt)
+                return "missing";
+            if (folder.kind !== "folder")
+                return "not-a-folder";
+            return (await deps.repository.can(actor, folder.id, "write")) ? "ok" : "forbidden";
+        },
+        async create(actor, input) {
+            const existingId = await deps.repository.findIdempotentNode(actor.id, "node.create", input.idempotencyKey);
+            if (existingId) {
+                const existing = await requireVisible(actor, existingId);
+                /**
+                 * ⚠️ **The filing runs on the REPLAY path too, and that is what makes a retry a repair.**
+                 *
+                 * `insertNode` commits the node, its idempotency key and its audit row in one batch;
+                 * `attachToBoard` is a separate statement after it. If that one fails — a transient D1
+                 * error is enough — the node exists and its board row does not, and `create` throws. The
+                 * obvious response is the same call again with the same key, and until this line that call
+                 * returned here **without filing anything**: a task that is a task by kind, sits under a
+                 * board, and appears on no board, permanently, with nothing reporting it.
+                 *
+                 * `attach` is `ON CONFLICT DO NOTHING`, so running it on a node that is already filed costs
+                 * one statement and changes nothing. That asymmetry is why the repair belongs here rather
+                 * than in a sweeper somebody has to remember to write.
+                 */
+                if (existing.kind === "task" && existing.parentId !== null) {
+                    // ⚠️ The BOARD, resolved the same way the create path resolves it. Passing `parentId`
+                    // straight through was right only while a task's parent was always its board.
+                    const board = await boardFor(deps, actor, await requireVisible(actor, existing.parentId));
+                    if (board !== null) {
+                        await deps.attachToBoard?.(actor, existing.id, board, deps.now().toISOString());
+                    }
+                }
+                return existing;
+            }
+            if (input.parentId !== null && !(await deps.repository.can(actor, input.parentId, "write"))) {
+                throw new IntelError(403, "node_forbidden", "Parent folder cannot be edited");
+            }
+            // ⚠️ The same rule on the way IN, and it runs for the ROOT as well. Guarding only a named
+            // parent leaves `parentId: null` open, and that is not a smaller hole: the task is created,
+            // `attachToBoard` skips it for the same reason, and the card belongs to no board at all.
+            const destinationParent = input.parentId === null ? null : await requireVisible(actor, input.parentId);
+            const destinationBoard = await boardFor(deps, actor, destinationParent);
+            // ⚠️ Kind first, archive second. A task under an archived FOLDER is refused for the deeper
+            // reason — a task lives on a board — and saying "restore the folder first" would send the
+            // reader to do something that changes nothing: restored, the folder still cannot hold a task.
+            refuseWrongParent(input.kind, destinationParent, { destination: destinationBoard });
+            refuseArchivedParent(destinationParent);
+            const timestamp = deps.now().toISOString();
+            const created = await deps.repository.insertNode({
+                node: {
+                    // ⚠️ A node is never born offered (#775). Naming a slash command is a curation decision
+                    // about a document that already exists, and `node_create` takes no name: a creation that
+                    // could also take the last free name in the catalogue would fail for a reason that has
+                    // nothing to do with creating anything.
+                    promptName: null,
+                    id: deps.id(),
+                    parentId: input.parentId,
+                    kind: input.kind,
+                    title: plainTitle(input.title),
+                    description: input.description,
+                    ownerId: actor.id,
+                    currentVersionId: null,
+                    createdAt: timestamp,
+                    updatedAt: timestamp,
+                    archivedAt: null,
+                },
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            /**
+             * ⚠️ **A task created through the plain node path still gets its board row** (#648). Without
+             * this an agent calling `node_create` under a board makes a node that is a task by kind, has
+             * no row in `board_tasks`, and therefore appears on NO board — with nothing reporting an
+             * error. It is exactly the shape of failure this repository keeps writing rules about: not a
+             * refusal, an absence.
+             *
+             * ⚠️ It runs AFTER the node exists and is its own statement rather than part of the batch.
+             * The node is the truth; the board row is derived from it. A pass that dies in between leaves
+             * a task nobody filed — visible through `node_get`, repairable by filing it — while the other
+             * order would leave a board row pointing at a node that was never written.
+             *
+             * The port is optional because the node service must not require a board to exist: the CLI
+             * and the bundle importer build one without that half of the world.
+             */
+            // ⚠️ `destinationBoard`, not `input.parentId`. Since #669 the parent may be another task, and
+            // filing the card under its parent's ID would put a subtask on a "board" that is a card.
+            if (created.kind === "task" && destinationBoard !== null) {
+                await deps.attachToBoard?.(actor, created.id, destinationBoard, timestamp);
+            }
+            return created;
+        },
+        async save(actor, input) {
+            const existingId = await deps.repository.findIdempotentNode(actor.id, "node.save", input.idempotencyKey);
+            if (existingId) {
+                const document = await getDocument(await requireVisible(actor, input.nodeId));
+                await deps.indexing.enqueue(existingId);
+                return document;
+            }
+            const node = await requireVisible(actor, input.nodeId);
+            if (!EditorContentKinds.includes(node.kind)) {
+                throw new IntelError(409, "document_content_required", "Only documents and cards accept editor content versions");
+            }
+            if (!(await deps.repository.can(actor, node.id, "write"))) {
+                throw new IntelError(403, "node_forbidden", "This node cannot be edited");
+            }
+            if (node.currentVersionId !== input.baseVersionId) {
+                throw new IntelError(409, "version_conflict", "A newer version already exists");
+            }
+            const versionId = deps.id();
+            const contentKey = contentKeyFor(node.id, versionId);
+            const createdAt = deps.now().toISOString();
+            const version = {
+                id: versionId,
+                nodeId: node.id,
+                sequence: await nextSequence(node),
+                contentKey,
+                mediaType: input.mediaType,
+                contentHash: await deps.hash(input.content),
+                size: new TextEncoder().encode(input.content).byteLength,
+                segment: null,
+                createdBy: actor.id,
+                createdAt,
+            };
+            await deps.content.put(contentKey, input.content, input.mediaType);
+            let saved;
+            try {
+                saved = await deps.repository.appendVersion({
+                    version,
+                    actorId: actor.id,
+                    baseVersionId: input.baseVersionId,
+                    idempotencyKey: input.idempotencyKey,
+                    auditId: deps.id(),
+                });
+            }
+            catch (error) {
+                await deps.content.delete(contentKey).catch(() => undefined);
+                throw error;
+            }
+            if (saved === "conflict") {
+                await deps.content.delete(contentKey);
+                const replayed = await deps.repository.findIdempotentNode(actor.id, "node.save", input.idempotencyKey);
+                if (replayed)
+                    return await getDocument(await requireVisible(actor, node.id));
+                throw new IntelError(409, "version_conflict", "A newer version already exists");
+            }
+            const updated = await requireVisible(actor, node.id);
+            await reconcileTextLinks(actor, node.id, input.mediaType, input.content);
+            await deps.indexing.enqueue(version.id);
+            return { node: updated, version, content: input.content };
+        },
+        async saveAttachment(actor, input) {
+            const existingId = await deps.repository.findIdempotentNode(actor.id, "node.save", input.idempotencyKey);
+            if (existingId) {
+                const document = await getDocument(await requireVisible(actor, input.nodeId));
+                await deps.indexing.enqueue(existingId);
+                return document;
+            }
+            const node = await requireVisible(actor, input.nodeId);
+            if (node.kind !== "attachment") {
+                throw new IntelError(409, "not_an_attachment", "Only attachment nodes accept file uploads");
+            }
+            if (!(await deps.repository.can(actor, node.id, "write"))) {
+                throw new IntelError(403, "node_forbidden", "Attachment cannot be edited");
+            }
+            if (node.currentVersionId !== input.baseVersionId) {
+                throw new IntelError(409, "version_conflict", "A newer version already exists");
+            }
+            const bytes = decodeBase64(input.contentBase64);
+            const versionId = deps.id();
+            const contentKey = contentKeyFor(node.id, versionId);
+            const createdAt = deps.now().toISOString();
+            const version = {
+                id: versionId,
+                nodeId: node.id,
+                sequence: await nextSequence(node),
+                contentKey,
+                mediaType: input.mediaType,
+                contentHash: await deps.hash(bytes),
+                size: bytes.byteLength,
+                segment: null,
+                createdBy: actor.id,
+                createdAt,
+            };
+            await deps.content.putBytes(contentKey, bytes.buffer, input.mediaType);
+            let saved;
+            try {
+                saved = await deps.repository.appendVersion({
+                    version,
+                    actorId: actor.id,
+                    baseVersionId: input.baseVersionId,
+                    idempotencyKey: input.idempotencyKey,
+                    auditId: deps.id(),
+                });
+            }
+            catch (error) {
+                await deps.content.delete(contentKey).catch(() => undefined);
+                throw error;
+            }
+            if (saved === "conflict") {
+                await deps.content.delete(contentKey);
+                if (await replayedUpload(actor, node.id, input.idempotencyKey)) {
+                    return await getDocument(await requireVisible(actor, node.id));
+                }
+                throw new IntelError(409, "version_conflict", "A newer version already exists");
+            }
+            await deps.indexing.enqueue(version.id);
+            return { node: await requireVisible(actor, node.id), version, content: null };
+        },
+        /**
+         * The same version, written from a stream (#821).
+         *
+         * ⚠️ It is deliberately NOT `saveAttachment` with a different argument. Everything the two share
+         * is the order of the writes, and that order is written out twice on purpose: the base64 door
+         * knows its bytes before it starts and can hash them where it stands, while this one learns the
+         * hash and the length only once the last chunk has gone by. Folding them together would mean
+         * buffering here — the one thing this door exists to avoid.
+         */
+        async saveAttachmentBytes(actor, input, body) {
+            const existingId = await deps.repository.findIdempotentNode(actor.id, "node.save", input.idempotencyKey);
+            if (existingId) {
+                const document = await getDocument(await requireVisible(actor, input.nodeId));
+                await deps.indexing.enqueue(existingId);
+                return document;
+            }
+            const node = await requireVisible(actor, input.nodeId);
+            if (node.kind !== "attachment") {
+                throw new IntelError(409, "not_an_attachment", "Only attachment nodes accept file uploads");
+            }
+            if (!(await deps.repository.can(actor, node.id, "write"))) {
+                throw new IntelError(403, "node_forbidden", "Attachment cannot be edited");
+            }
+            if (node.currentVersionId !== input.baseVersionId) {
+                throw new IntelError(409, "version_conflict", "A newer version already exists");
+            }
+            const versionId = deps.id();
+            const contentKey = contentKeyFor(node.id, versionId);
+            const createdAt = deps.now().toISOString();
+            // ⚠️ A body that does not carry the announced number of bytes fails here, and the half-written
+            // object goes with it. Storing what arrived would file a truncated file under a name that says
+            // it is the whole one — and nothing later could tell the two apart.
+            let stored;
+            try {
+                stored = await deps.content.putStream(contentKey, body, input.mediaType, input.size);
+            }
+            catch (error) {
+                await deps.content.delete(contentKey).catch(() => undefined);
+                if (error instanceof IntelError)
+                    throw error;
+                throw new IntelError(400, "upload_incomplete", "The upload ended before the announced number of bytes had arrived");
+            }
+            const version = {
+                id: versionId,
+                nodeId: node.id,
+                sequence: await nextSequence(node),
+                contentKey,
+                mediaType: input.mediaType,
+                contentHash: stored.hash,
+                size: stored.size,
+                segment: null,
+                createdBy: actor.id,
+                createdAt,
+            };
+            let saved;
+            try {
+                saved = await deps.repository.appendVersion({
+                    version,
+                    actorId: actor.id,
+                    baseVersionId: input.baseVersionId,
+                    idempotencyKey: input.idempotencyKey,
+                    auditId: deps.id(),
+                });
+            }
+            catch (error) {
+                await deps.content.delete(contentKey).catch(() => undefined);
+                throw error;
+            }
+            if (saved === "conflict") {
+                await deps.content.delete(contentKey);
+                if (await replayedUpload(actor, node.id, input.idempotencyKey)) {
+                    return await getDocument(await requireVisible(actor, node.id));
+                }
+                throw new IntelError(409, "version_conflict", "A newer version already exists");
+            }
+            await deps.indexing.enqueue(version.id);
+            return { node: await requireVisible(actor, node.id), version, content: null };
+        },
+        async getAttachment(actor, nodeId) {
+            return await attachment(actor, nodeId);
+        },
+        async readAttachment(actor, nodeId) {
+            const metadata = await attachment(actor, nodeId);
+            const body = await deps.content.getStream(metadata.version.contentKey);
+            if (body === null)
+                throw new IntelError(500, "content_missing", "Attachment is missing");
+            return { attachment: metadata, body };
+        },
+        /**
+         * One page of readable attachments for the MCP resource listing (#773).
+         *
+         * ⚠️ It asks the repository for one row MORE than it hands back. Without that, a page that
+         * happens to be exactly full is indistinguishable from a page with more behind it, and the
+         * choice is between always sending a cursor (one wasted round trip per listing) or never
+         * sending one (a silently truncated list, which reads as complete).
+         */
+        async listAttachments(actor, input) {
+            const rows = await deps.repository.listVisibleAttachments(actor, {
+                limit: input.limit + 1,
+                after: input.after,
+            });
+            const items = rows.slice(0, input.limit);
+            const last = items.at(-1);
+            return { items, nextCursor: rows.length > input.limit && last ? last.id : null };
+        },
+        async getTable(actor, nodeId) {
+            const node = await requireVisible(actor, nodeId);
+            if (node.kind !== "table") {
+                throw new IntelError(404, "table_not_found", "Table was not found");
+            }
+            return await tableOf(node);
+        },
+        /**
+         * Writes the header, once. The columns are the contract every later append is measured against
+         * (#40), so a second definition is refused rather than merged: a table whose header changed
+         * would reinterpret every row already appended under the old one, silently and irreversibly.
+         */
+        async defineTable(actor, input) {
+            const replayedId = await deps.repository.findIdempotentNode(actor.id, "node.append", input.idempotencyKey);
+            const node = await requireTable(actor, input.nodeId);
+            if (replayedId)
+                return await tableOf(node);
+            if (node.currentVersionId !== null) {
+                throw new IntelError(409, "table_already_defined", "This table already has a header");
+            }
+            // The definition is the first snapshot (#135): the complete state of a table with no rows
+            // yet, and the anchor "read from the newest snapshot" starts from.
+            const body = encodeCsv([input.columns]);
+            const version = await writeTableSegment(actor, node, body, "snapshot", input.idempotencyKey);
+            await deps.indexing.enqueue(version.id);
+            return await tableOf({ ...node, currentVersionId: version.id });
+        },
+        /**
+         * Rows at the end, and nothing else touched.
+         *
+         * ⚠️ No `baseVersionId` and no conflict: each append writes its own immutable object and its
+         * own version row, so two appends that arrive together both land and neither can overwrite the
+         * other. This is the whole difference to `save`, which replaces content and therefore has to
+         * know what it replaces.
+         */
+        async appendTableRows(actor, input) {
+            const replayedId = await deps.repository.findIdempotentNode(actor.id, "node.append", input.idempotencyKey);
+            const node = await requireTable(actor, input.nodeId);
+            if (replayedId) {
+                const replayed = await deps.repository.getVersion(replayedId);
+                if (replayed) {
+                    return {
+                        node: await requireVisible(actor, node.id),
+                        version: replayed,
+                        appended: input.rows.length,
+                    };
+                }
+            }
+            const header = await tableHeader(node);
+            if (header === null) {
+                throw new IntelError(409, "table_undefined", "This table has no header yet; define its columns before appending");
+            }
+            // ⚠️ Refused, never padded and never truncated — see `requireRowShape`.
+            requireRowShape(input.rows, header);
+            const version = await writeTableSegment(actor, node, encodeCsv(input.rows), "append", input.idempotencyKey);
+            await deps.indexing.enqueue(version.id);
+            return {
+                node: await requireVisible(actor, node.id),
+                version,
+                appended: input.rows.length,
+            };
+        },
+        /**
+         * Rows replaced in place (#135). Position is the address — rows carry no identity on purpose —
+         * so the write is guarded the way `save` guards a document: against the version the caller
+         * read, and a table that moved on answers `version_conflict` rather than editing rows the
+         * positions no longer mean.
+         */
+        async updateTableRows(actor, input) {
+            const replayedId = await deps.repository.findIdempotentNode(actor.id, "node.table_update", input.idempotencyKey);
+            const node = await requireTable(actor, input.nodeId);
+            if (replayedId) {
+                const replayed = await deps.repository.getVersion(replayedId);
+                if (replayed) {
+                    return {
+                        node: await requireVisible(actor, node.id),
+                        version: replayed,
+                        updated: input.updates.length,
+                    };
+                }
+            }
+            const { header, rows } = await tableStateFor(node, input.baseVersionId);
+            requireRowShape(input.updates.map((update) => update.row), header);
+            requirePositions(input.updates.map((update) => update.position), rows.length);
+            for (const update of input.updates)
+                rows[update.position] = [...update.row];
+            const version = await writeTableSnapshot({
+                actor,
+                node,
+                body: encodeCsv([header, ...rows]),
+                baseVersionId: input.baseVersionId,
+                operation: "node.table_update",
+                metadata: {
+                    positions: input.updates.map((update) => update.position),
+                    updated: input.updates.length,
+                },
+                idempotencyKey: input.idempotencyKey,
+            });
+            return {
+                node: await requireVisible(actor, node.id),
+                version,
+                updated: input.updates.length,
+            };
+        },
+        async deleteTableRows(actor, input) {
+            const replayedId = await deps.repository.findIdempotentNode(actor.id, "node.table_delete", input.idempotencyKey);
+            const node = await requireTable(actor, input.nodeId);
+            if (replayedId) {
+                const replayed = await deps.repository.getVersion(replayedId);
+                if (replayed) {
+                    return {
+                        node: await requireVisible(actor, node.id),
+                        version: replayed,
+                        deleted: input.positions.length,
+                    };
+                }
+            }
+            const { header, rows } = await tableStateFor(node, input.baseVersionId);
+            requirePositions(input.positions, rows.length);
+            const removed = new Set(input.positions);
+            const remaining = rows.filter((_row, position) => !removed.has(position));
+            const version = await writeTableSnapshot({
+                actor,
+                node,
+                body: encodeCsv([header, ...remaining]),
+                baseVersionId: input.baseVersionId,
+                operation: "node.table_delete",
+                metadata: { positions: input.positions, deleted: input.positions.length },
+                idempotencyKey: input.idempotencyKey,
+            });
+            return {
+                node: await requireVisible(actor, node.id),
+                version,
+                deleted: input.positions.length,
+            };
+        },
+        /**
+         * A new header over the stored rows, through the explicit mapping and only through it (#135).
+         * The blind second definition stays refused in `defineTable` — this is the deliberate opposite:
+         * every new column names the current column that fills it, or names none and starts empty, and
+         * a current column no entry names is removed together with its cells.
+         */
+        async redefineTable(actor, input) {
+            const replayedId = await deps.repository.findIdempotentNode(actor.id, "node.table_redefine", input.idempotencyKey);
+            const node = await requireTable(actor, input.nodeId);
+            if (replayedId)
+                return await tableOf(node);
+            const { header, rows } = await tableStateFor(node, input.baseVersionId);
+            // ⚠️ Sources are matched against the header as it is stored, exactly. A forgiving match would
+            // make "which column did this take" depend on rules nobody can read off the table.
+            const sourceIndex = new Map(header.map((column, index) => [column, index]));
+            for (const column of input.columns) {
+                if (column.source !== null && !sourceIndex.has(column.source)) {
+                    throw new IntelError(400, "table_column_unknown", `Column ${column.source} does not exist: the table has ${header.join(", ")}`);
+                }
+            }
+            const remapped = rows.map((row) => input.columns.map((column) => {
+                if (column.source === null)
+                    return "";
+                const index = sourceIndex.get(column.source);
+                return index === undefined ? "" : (row[index] ?? "");
+            }));
+            await writeTableSnapshot({
+                actor,
+                node,
+                body: encodeCsv([input.columns.map((column) => column.name), ...remapped]),
+                baseVersionId: input.baseVersionId,
+                operation: "node.table_redefine",
+                metadata: { columns: input.columns },
+                idempotencyKey: input.idempotencyKey,
+            });
+            return await tableOf(await requireVisible(actor, node.id));
+        },
+        async listVersions(actor, nodeId) {
+            await requireVisible(actor, nodeId);
+            return { items: await deps.repository.listVersions(nodeId) };
+        },
+        async update(actor, input) {
+            const current = await requireVisible(actor, input.nodeId);
+            if (!(await deps.repository.can(actor, current.id, "write"))) {
+                throw new IntelError(403, "node_forbidden", "This node cannot be edited");
+            }
+            /**
+             * ⚠️ **Only a document can be offered as a slash command, and the refusal names the kind**
+             * (#775). A prompt is an instruction; a folder, a table, an attachment, a board or a task is
+             * material, and material is read through `node_get` rather than typed as a command.
+             *
+             * ⚠️ It stands BEFORE the idempotency replay on purpose: a call that is wrong about the kind
+             * is wrong on every attempt, and answering the second one out of the replay table would tell
+             * a caller their refused write had succeeded.
+             *
+             * ⚠️ Clearing it — `null` on a kind that could never have had one — is deliberately allowed.
+             * It changes nothing, and refusing a no-op would make "take the command off everything in
+             * this folder" a call that fails on the folder itself.
+             */
+            if (input.promptName != null && current.kind !== "document") {
+                throw new IntelError(409, "prompt_not_a_document", `Only a document can be offered as a slash command, and this is a ${current.kind}.`);
+            }
+            const replayedId = await deps.repository.findIdempotentNode(actor.id, "node.update", input.idempotencyKey);
+            if (replayedId)
+                return await requireVisible(actor, replayedId);
+            // ⚠️ `undefined` means "do not move" and is the only value that skips this. An explicit
+            // `null` IS a move — to the root — and has to be checked like any other destination; the
+            // first version of this treated the two the same and let a card be dragged to the top level.
+            if (input.parentId !== undefined) {
+                if (input.parentId === current.id) {
+                    throw new IntelError(409, "move_cycle", "A node cannot contain itself");
+                }
+                const parent = input.parentId === null ? null : await requireVisible(actor, input.parentId);
+                /**
+                 * ⚠️ **The write check on the destination comes FIRST, before the board is resolved.**
+                 * `boardOfTask` asks with the verb `write`, so for a destination this actor may only read
+                 * it answers `null` — and the refusal below would then say "this destination has no board"
+                 * about a card that has one perfectly well. The honest answer is 403, and it is the order
+                 * `packages/intel/CLAUDE.md` prescribes anyway: capability, then resource, then action.
+                 */
+                if (parent !== null && !(await deps.repository.can(actor, parent.id, "write"))) {
+                    throw new IntelError(403, "node_forbidden", "Destination folder cannot be edited");
+                }
+                const destinationBoard = await boardFor(deps, actor, parent);
+                /**
+                 * ⚠️ **A board that cannot be resolved is refused, not skipped.** Without this line an
+                 * installation whose board port is absent — or one where the actor may not write the
+                 * board — would answer `undefined`, the comparison below would read that as "not a move
+                 * between boards", and a card could be handed to any board at all. The integration test
+                 * `refuses the three ways a card could leave its board` caught exactly that: the test
+                 * harness did not wire the port, and door 3 stood open again.
+                 */
+                const currentBoard = current.kind === "task" ? ((await deps.boardOfTask?.(actor, current.id)) ?? null) : null;
+                if (current.kind === "task" && currentBoard === null) {
+                    throw new IntelError(409, "task_cannot_change_board", "This card's board cannot be resolved, so it cannot be moved. A card belongs to the board it was filed on.");
+                }
+                // Kind first, archive second — see the same pair in `create`.
+                refuseWrongParent(current.kind, parent, {
+                    destination: destinationBoard,
+                    current: currentBoard,
+                });
+                refuseArchivedParent(parent);
+            }
+            const updatedAt = deps.now().toISOString();
+            const updated = await deps.repository.updateNode({
+                node: {
+                    ...current,
+                    parentId: input.parentId === undefined ? current.parentId : input.parentId,
+                    title: input.title === undefined ? current.title : plainTitle(input.title),
+                    description: input.description === undefined ? current.description : input.description,
+                    promptName: input.promptName === undefined ? current.promptName : input.promptName,
+                    updatedAt,
+                },
+                baseUpdatedAt: input.baseUpdatedAt,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            if (updated === "cycle") {
+                throw new IntelError(409, "move_cycle", "A node cannot be moved into its descendant");
+            }
+            if (updated === "prompt_name_taken") {
+                /**
+                 * ⚠️ **The sentence names the holder only when this actor may see it.** That a name is
+                 * taken has to be said — otherwise the caller retries forever against a wall they cannot
+                 * see — but WHICH document holds it is a fact about the tree, and ADR-0004 §3 does not let
+                 * a refusal become a way of reading it. `promptNameHolder` answers `null` for the title in
+                 * that case, and the second sentence below is what the caller gets instead.
+                 */
+                const holder = await deps.repository.promptNameHolder(actor, input.promptName);
+                const held = holder === null
+                    ? "It is already taken."
+                    : holder.title === null
+                        ? `A ${holder.kind} you cannot see already uses it.`
+                        : `The ${holder.kind} "${holder.title}" already uses it.`;
+                throw new IntelError(409, "prompt_name_taken", `The slash command "${input.promptName}" is not free. ${held} Pick another name — names are never changed for you, because the catalogue would then mean a different thing to every reader.`);
+            }
+            if (updated === "conflict") {
+                throw new IntelError(409, "update_conflict", "This node was changed by another editor");
+            }
+            if (updated.currentVersionId)
+                await deps.indexing.enqueue(updated.currentVersionId);
+            return updated;
+        },
+        /**
+         * Archiving and restoring.
+         *
+         * ⚠️ Nothing in this repository removes a `nodes` row — `archived_at` is what "delete" means
+         * here, which is why a restore is the same call with `archived: false` and why both directions
+         * go through the indexing queue below.
+         *
+         * ⚠️ Until #390 this also switched an agent's Gate Application off with the node, and the ORDER
+         * of the two writes was the whole safety argument. With the agents parked there is no second
+         * system to keep in step, so #418 took the caller's bearer back out — a parameter kept "in
+         * case" is a parameter every surface has to find a value for, and both of them were passing a
+         * token nothing read.
+         */
+        async archive(actor, input) {
+            const current = await requireVisible(actor, input.nodeId);
+            if (!(await deps.repository.can(actor, current.id, "write"))) {
+                throw new IntelError(403, "node_forbidden", "This node cannot be edited");
+            }
+            const replayedId = await deps.repository.findIdempotentNode(actor.id, "node.archive", input.idempotencyKey);
+            // A replay does nothing a second time and answers with what the first run made.
+            if (replayedId)
+                return await requireVisible(actor, replayedId);
+            /**
+             * ⚠️ **Archiving takes the whole subtree, flows included** (D71, #733), and the refusal that
+             * used to stand here is gone with it. `task_has_subtasks` (#669) refused a card with live
+             * subtasks, on the reasoning that a cascade turns one confirmed click into an unknown number
+             * of disappearances.
+             *
+             * That reasoning holds for `purge` and not for this call. The two steps are not symmetric:
+             * archiving is REVERSIBLE, so cascading it costs nothing that cannot be undone, while `purge`
+             * has cascaded over the subtree since #492 and cannot be undone at all. With the cascade on
+             * this side, nothing live sits under an archived node any more — which is precisely what
+             * makes the purge honest, and what `refuseArchivedParent` below keeps true afterwards.
+             *
+             * ⚠️ The counterpart is the restore, and it is the part that can quietly do too much or too
+             * little. It brings back what fell with THIS operation **and hangs under the node being
+             * restored** — a child archived earlier keeps its own operation and stays archived, and
+             * restoring a leaf does not drag its whole former tree back with it.
+             */
+            /**
+             * ⚠️ **Archiving something that is already archived changes nothing, deliberately** (found in
+             * review of #738). Without this it mints a NEW operation on the root while the cascade skips
+             * every child (`archived_at IS NULL`), so the children keep the old one — and a later restore
+             * hands back an empty folder while its contents stay archived, with nothing saying so.
+             *
+             * The likeliest way there is not misuse but a retry after a timeout with a fresh idempotency
+             * key: the key does not catch it, and the operation is re-minted.
+             */
+            if (input.archived && current.archivedAt !== null)
+                return current;
+            /**
+             * ⚠️ **A restore under an archived parent is refused, and this is the other half of
+             * `refuseArchivedParent`** (found in review of #738). Without it the cascade closes nothing:
+             * archive a child alone, archive the folder over it, restore the child, and a LIVE node hangs
+             * under an archived one again — where `purge` reaches it, because it checks `archived_at` on
+             * the root alone and walks the whole subtree.
+             *
+             * The refusal names the way out rather than the rule: whoever wants this child back wants the
+             * folder back first, and then the child comes with it.
+             */
+            if (!input.archived && current.parentId !== null) {
+                // ⚠️ Read WITHOUT the visibility predicate, see `parentArchivedAt`: asked through
+                // `getVisible` this guard misses exactly the actor it exists for, the one holding a grant on
+                // the child alone.
+                const parent = await deps.repository.parentArchivedAt(current.parentId);
+                if (parent?.archivedAt) {
+                    throw new IntelError(409, "parent_archived", `This ${parent.kind} is archived, so nothing under it can be restored on its own. Restore it first, and this comes back with it.`);
+                }
+            }
+            const updatedAt = deps.now().toISOString();
+            const updated = await deps.repository.archiveNode({
+                nodeId: current.id,
+                baseUpdatedAt: input.baseUpdatedAt,
+                archivedAt: input.archived ? updatedAt : null,
+                operationId: deps.id(),
+                updatedAt,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            if (updated === "conflict") {
+                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. An archived node 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.
+             *
+             * ⚠️ **The whole subtree, not the root** (D71, #733, found in review of #738). Since archiving
+             * cascades, a folder with fifty documents takes fifty nodes out of sight — and every one of
+             * them would keep its place in the candidate list if only the root were enqueued. The pass
+             * reads each node's state, so a node that was already archived costs one no-op rather than a
+             * wrong answer.
+             *
+             * ⚠️ It is one enqueue per versioned node in the subtree, sequentially, and each one is a
+             * subrequest. A tree large enough runs into the Workers limit AFTER the batch has committed:
+             * archived tree, error to the caller, index half followed. That is #754, and it needs
+             * `sendBatch` or a sweeper rather than a cap here — a cap would be the silent kind.
+             */
+            for (const versionId of await deps.repository.versionIdsInSubtree(updated.id)) {
+                await deps.indexing.enqueue(versionId);
+            }
+            return updated;
+        },
+        /**
+         * ⚠️ The one call in Intel after which something is really gone (#457). Read the decisions on
+         * that issue before changing anything here: each refusal below is one of them, and each was
+         * chosen to the safer side.
+         */
+        async purge(actor, input) {
+            const idempotencyKey = `${input.nodeId}:${input.idempotencyKey}`;
+            const replay = await deps.repository.findPurgeReplay(actor.id, idempotencyKey);
+            if (replay) {
+                for (const key of replay.contentKeys)
+                    await deps.content.delete(key);
+                await deps.repository.completePurgeReplay(actor.id, idempotencyKey, deps.now().toISOString());
+                return { purged: true, title: replay.title };
+            }
+            const node = await requireVisible(actor, input.nodeId);
+            if (!(await deps.repository.can(actor, input.nodeId, "write"))) {
+                throw new IntelError(403, "node_forbidden", "This node cannot be edited");
+            }
+            // ⚠️ THE structural guard: only what is already archived may go. A stronger PERMISSION would
+            // not have made this safer, only rarer — whoever may archive can already make the content
+            // invisible. What makes it safe is that the destructive path has two steps and the first one
+            // is reversible.
+            if (!node.archivedAt) {
+                throw new IntelError(409, "node_not_archived", "Only an archived node can be deleted for good. Archive it first.");
+            }
+            // #492 replaces the refusal with owned cleanup. Flows inside the tree disappear with it;
+            // published flows outside it are depublished atomically before their dependency vanishes.
+            const tree = await deps.repository.inspectPurgeTree(node.id);
+            // Not a refusal — a fact for the record. A prose reference is a mention, not an operation;
+            // refusing over one would make deleting a lottery, decided by whoever once linked to it.
+            //
+            // The same count is exposed by `purgePreview`, so the surface can name the consequence before
+            // confirmation. It is counted again here because the audit records the state at deletion time.
+            const inboundLinks = await deps.repository.countInboundLinks(node.id);
+            // ⚠️ The vectors go FIRST, and the order is the correction of a wrong claim (found in review).
+            // The comment here used to say Vectorize needed no call because archiving had already emptied
+            // it. Archiving only ENQUEUES the purge, and that pass starts from `archivedNodeId(versionId)`
+            // — a join over `nodes`. Once this batch has run, that answers `null` and removes nothing,
+            // while `node_vectors`, the only record of what the vectors are CALLED, is gone with it. The
+            // orphans would then be unnameable forever, and each one keeps a place in the 100-candidate
+            // list Vectorize caps per installation.
+            //
+            // ⚠️ Before the batch rather than after, which inverts the order the content keys follow — and
+            // the rule behind both is the same: DO THE IRRECOVERABLE THING LAST. A failed batch after the
+            // vectors are gone leaves an ARCHIVED node whose index can be rebuilt (`reindex`); a failed
+            // removal after the batch leaves orphans nothing can name.
+            const vectorKeys = tree.vectorKeys;
+            // The whole-node chunk carries the empty key and is never in the table — the pass writes it
+            // and records the rest, so a purge that only sent the recorded ones would leave it behind.
+            if (deps.semantic) {
+                for (const vector of vectorKeys) {
+                    await deps.semantic.remove(vector.nodeId, ["", ...vector.keys]);
+                }
+            }
+            const purged = await deps.repository.purgeNode({
+                nodeId: node.id,
+                actorId: actor.id,
+                auditId: deps.id(),
+                occurredAt: deps.now().toISOString(),
+                // ⚠️ The title travels INTO the record from the row itself (the repository reads it there),
+                // and this is what travels beside it. After the delete nothing can look either up.
+                metadata: { inboundLinks, counts: tree.counts },
+                idempotencyKey,
+            });
+            // The row was restored or already gone between the check and the statement. Nothing was
+            // deleted, and saying so is better than reporting a success that did not happen.
+            if (purged === "missing") {
+                throw new IntelError(409, "update_conflict", "This node was changed by another editor");
+            }
+            // ⚠️ AFTER the database agreed, never before: it is the truth about what exists, and an object
+            // deleted ahead of a batch that then fails would leave a node whose content is gone. This is
+            // the same rule the vectors follow in the other direction — do the irrecoverable thing last —
+            // and the directions differ because only one of the two can be rebuilt: an index can, an
+            // object cannot.
+            for (const key of purged.contentKeys)
+                await deps.content.delete(key);
+            await deps.repository.completePurgeReplay(actor.id, idempotencyKey, deps.now().toISOString());
+            return { purged: true, title: node.title };
+        },
+        async listGrants(actor, resourceId) {
+            const node = await requireVisible(actor, resourceId);
+            if (!(await deps.repository.can(actor, resourceId, "share"))) {
+                throw new IntelError(403, "node_forbidden", "Sharing of this node cannot be managed");
+            }
+            return {
+                resourceId: node.id,
+                applicableVerbs: applicableVerbs(node.kind),
+                items: await deps.repository.listGrants(resourceId),
+            };
+        },
+        async listEffectiveAccess(actor, resourceId) {
+            const node = await requireVisible(actor, resourceId);
+            if (!(await deps.repository.can(actor, resourceId, "share"))) {
+                throw new IntelError(403, "node_forbidden", "Sharing of this node cannot be managed");
+            }
+            const effective = await deps.repository.listEffectiveAccess(resourceId);
+            // ⚠️ The folders the inherited grants sit on, named through the SAME predicate every other
+            // node read goes through (#803). Managing THIS node's sharing says nothing about whether the
+            // reader may see the folder above it: a grant can reach here from an ancestor they cannot
+            // open, and naming it would hand them an ancestor the tree never showed them.
+            //
+            // ⚠️ A folder that is absent from the answer is not reported as refused. The screen falls back
+            // to saying the access is inherited without saying from where — the same silence
+            // `resolveLinks` keeps, and for the same reason: "not yours to see" and "not there" must stay
+            // indistinguishable (#41).
+            const inheritedOn = [
+                ...new Set(effective.items.map((grant) => grant.resourceId).filter((id) => id !== resourceId)),
+            ];
+            const named = inheritedOn.length > 0
+                ? await deps.repository.resolveVisibleTitles(actor, inheritedOn)
+                : [];
+            return {
+                resourceId: node.id,
+                ...effective,
+                sources: named.map((entry) => ({ resourceId: entry.nodeId, title: entry.title })),
+            };
+        },
+        async listLinks(actor, nodeId) {
+            await requireVisible(actor, nodeId);
+            return { items: await deps.repository.listLinksVisible(actor, nodeId) };
+        },
+        /**
+         * The titles of linked documents, for the reader who is looking at the text (#41).
+         *
+         * ⚠️ The one place a document link gets a name, and it answers with what this reader may see —
+         * `getVisible`, the same predicate every other node read goes through — never with a
+         * lookup written specially for a label. What is missing from the answer is missing for two
+         * reasons that must stay indistinguishable: the target is gone, or it is not theirs to see. A
+         * shape that told them apart would let a document confirm the existence of one they may not
+         * reach, and that is what the link does not get to say.
+         *
+         * ⚠️ Archived targets are absent too. A link to a deleted document has to break visibly rather
+         * than point quietly at nothing, and "absent" is what the reader's side draws as broken.
+         */
+        async resolveLinks(actor, input) {
+            return { items: await deps.repository.resolveVisibleTitles(actor, input.nodeIds) };
+        },
+        async graph(actor, input) {
+            return await deps.repository.graphVisible(actor, input);
+        },
+        // ⚠️ The one shape of this question that answers `null` instead of throwing, and the only one a
+        // graph may be built from. `get` loads the body and turns a refusal into a 404 the caller has to
+        // catch; here "you cannot reach it" is a value, so a drawing can leave a node out rather than
+        // deciding what to do with an exception halfway through (#19).
+        //
+        // ⚠️ Visibility and nothing else — deliberately not "and not archived". A run authorizes its
+        // tree links through this same answer (#20), and archiving a document must not start
+        // refusing steps under a message that names the wrong reason. Callers that must not *draw* an
+        // archived node say so where they draw, the way the callee side already does.
+        async visibleNode(actor, nodeId) {
+            return await deps.repository.getVisible(actor, nodeId);
+        },
+        async share(actor, input) {
+            const node = await requireVisible(actor, input.resourceId);
+            if (!(await deps.repository.can(actor, input.resourceId, "share"))) {
+                throw new IntelError(403, "node_forbidden", "Sharing of this node cannot be managed");
+            }
+            if (!applicableVerbs(node.kind).includes(input.verb)) {
+                throw new IntelError(409, "verb_not_applicable", `A ${node.kind} cannot be granted ${input.verb}`);
+            }
+            const replayedId = await deps.repository.findIdempotentNode(actor.id, "node.share", input.idempotencyKey);
+            const principal = input.principal.type === "email"
+                ? { type: "email", email: input.principal.email.toLowerCase() }
+                : input.principal;
+            if (replayedId) {
+                const replayed = (await deps.repository.listGrants(input.resourceId)).find((grant) => grant.id === replayedId);
+                // A replay describes the same access as the first attempt did, so the warning is asked
+                // again rather than remembered: whether a document is readable can have changed since.
+                if (replayed) {
+                    return {
+                        grant: replayed,
+                        unreadable: await unreadableForPrincipal(actor, node.id, replayed.principal),
+                        unrunnable: nothingWithheld,
+                    };
+                }
+            }
+            /**
+             * ⚠️ Behind the replay and in front of `setGrant` — both halves matter (#442).
+             *
+             * In front of `setGrant` is the rule itself: nothing that could never work gets written, so
+             * no row, no idempotency key and no audit event. Every path that reaches the write passes
+             * here, including a replay whose grant was revoked in between and falls through.
+             *
+             * Behind the replay because otherwise this refusal would break the promise `IdempotencyKey`
+             * makes. A caller retries with the SAME key and the SAME body; if the retry arrives after the
+             * expiry the first attempt named, the value is no longer in the future — and the second call
+             * would be refused for a grant that is already written. The replay path writes nothing, so
+             * standing behind it costs the rule nothing and keeps the retry answering with what happened.
+             */
+            requireFutureExpiry(input.expiresAt, deps.now());
+            const timestamp = deps.now().toISOString();
+            const grant = await deps.repository.setGrant({
+                grant: {
+                    id: deps.id(),
+                    resourceId: input.resourceId,
+                    principal,
+                    verb: input.verb,
+                    expiresAt: input.expiresAt,
+                    createdBy: actor.id,
+                    createdAt: timestamp,
+                },
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            // ⚠️ After the grant is written, never before. The answer has to describe the access that is
+            // now in force — sharing `read` on this folder is exactly what makes the documents inside it
+            // readable, and a warning computed a moment earlier would name them all.
+            return {
+                grant,
+                unreadable: await unreadableForPrincipal(actor, node.id, principal),
+                unrunnable: nothingWithheld,
+            };
+        },
+        async revokeGrant(actor, input) {
+            await requireVisible(actor, input.resourceId);
+            if (!(await deps.repository.can(actor, input.resourceId, "share"))) {
+                throw new IntelError(403, "node_forbidden", "Sharing of this node cannot be managed");
+            }
+            const replayed = await deps.repository.findIdempotentRevocation(actor.id, input.idempotencyKey);
+            if (replayed !== null)
+                return { revoked: replayed };
+            // ⚠️ What makes a folder a library is `execute` for the whole organization: that is the one
+            // grant ADR-0004 §3 lets a flow call across a folder edge for. Taking it away while calls
+            // reach in from outside would leave those flows published and unrunnable, so the attempt names
+            // the callers instead of breaking them silently. A grant to one principal beside it narrows
+            // nothing while the organization-wide one stands, so only that one is guarded — and only when
+            // no second organization-wide `execute` above it keeps the reach alive, because then this
+            // revocation narrows nothing either and there is nothing to refuse.
+            const revoked = (await deps.repository.listGrants(input.resourceId)).find((grant) => grant.id === input.grantId);
+            if (revoked?.verb === "execute" &&
+                revoked.principal.type === "organization" &&
+                !(await deps.repository.organizationExecuteReaches(input.resourceId, input.grantId))) {
+                const callers = await deps.externalFlowCallers(actor, input.resourceId);
+                if (callers.visible.length || callers.hidden) {
+                    throw new IntelError(409, "folder_execute_in_use", callersDetail(callers), namedOrCounted(callers));
+                }
+            }
+            return {
+                revoked: await deps.repository.revokeGrant({
+                    resourceId: input.resourceId,
+                    grantId: input.grantId,
+                    actorId: actor.id,
+                    idempotencyKey: input.idempotencyKey,
+                    auditId: deps.id(),
+                    occurredAt: deps.now().toISOString(),
+                }),
+            };
+        },
+        async search(actor, input) {
+            // Authorization before access (ADR-0004 §2): a scope is resolved against the tree and its ACLs
+            // before FTS, the vector index, or any content is touched. A folder the actor may not read and
+            // one that does not exist give the same answer on purpose — `getVisible` cannot tell them
+            // apart, so a scope cannot be used to probe what is filed elsewhere.
+            if (input.scopeId !== undefined) {
+                const scope = await deps.repository.getVisible(actor, input.scopeId);
+                if (!scope || scope.archivedAt) {
+                    throw new IntelError(404, "scope_not_found", "Search scope was not found");
+                }
+                if (scope.kind !== "folder") {
+                    throw new IntelError(400, "scope_not_folder", "A search scope must be a folder");
+                }
+            }
+            const lexical = await deps.repository.searchVisible(actor, {
+                ...input,
+                limit: Math.min(50, input.limit * 2),
+            });
+            if (!deps.semantic)
+                return { items: lexical.slice(0, input.limit) };
+            try {
+                /**
+                 * 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/intel/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);
+                /**
+                 * 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) {
+                    const current = best.get(hit.nodeId);
+                    if (current === undefined || hit.score > current.score) {
+                        best.set(hit.nodeId, { chunkKey: hit.chunkKey, score: hit.score });
+                    }
+                }
+                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),
+                };
+            }
+            catch {
+                return { items: lexical.slice(0, input.limit) };
+            }
+        },
+        async reindex(actor) {
+            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 (;;) {
+                const versionIds = await deps.repository.listCurrentVersionIds({ after, limit: 100 });
+                for (const versionId of versionIds)
+                    await deps.indexing.enqueue(versionId);
+                queued += versionIds.length;
+                if (versionIds.length < 100)
+                    break;
+                after = versionIds.at(-1) ?? null;
+            }
+            return { queued };
+        },
+    };
+}