@anchrd/intel-api 0.6.6 → 0.7.0

package/dist/nodes/nodes.js

@@ -0,0 +1,1337 @@
+import { AgentDefinition, AgentMediaType, TableMediaType, } from "@anchrd/intel-contract";
+import { encodeCsv, parseCsv } from "../shared/csv/csv.js";
+import { IntelError } from "../shared/intel-error/intel-error.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 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: a folder, because only a folder can hold a
+// flow, and an agent, where it means being allowed to USE it (#139). Reading an agent's definition
+// and being permitted to put it to work are separate questions — the whole reason the verbs are
+// granted independently rather than as a ladder — and an agent is the case that makes the
+// difference obvious: its definition is inspectable by design (ADR-0005 §2), so `read` on it must
+// not imply the right to set it going.
+function applicableVerbs(kind) {
+    return kind === "folder" || kind === "agent"
+        ? ["read", "write", "execute", "share"]
+        : ["read", "write", "share"];
+}
+// ⚠️ 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).
+function callersDetail(callers) {
+    const named = callers.visible.map((title) => `“${title}”`).join(", ");
+    const rest = callers.hidden === 0
+        ? ""
+        : `${named ? " and " : ""}${callers.hidden} more flow${callers.hidden === 1 ? "" : "s"} you cannot see`;
+    return `Flows outside this folder call into it: ${named}${rest}. 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: "" };
+}
+/**
+ * A stored definition, parsed rather than trusted — the version boundary the repository rule names
+ * (`CLAUDE.md`, "stored Flow graphs read across a version boundary").
+ *
+ * ⚠️ It fails loudly on purpose. Intel is the only writer of this body, so a definition that does
+ * not parse is corruption, not an older shape to be coerced into the current one. Reading it
+ * leniently would hand the runtime an agent that has quietly forgotten its references, and the
+ * first sign of it would be an agent answering without the knowledge it was given.
+ */
+function parseStoredDefinition(body) {
+    let json;
+    try {
+        json = JSON.parse(body);
+    }
+    catch {
+        throw new IntelError(500, "agent_definition_invalid", "Agent definition is not valid JSON");
+    }
+    const parsed = AgentDefinition.safeParse(json);
+    if (!parsed.success) {
+        throw new IntelError(500, "agent_definition_invalid", "Agent definition does not match the contract");
+    }
+    return parsed.data;
+}
+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");
+    }
+}
+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 an agent 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;
+    }
+    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.appendTableSnapshot({
+                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 agentOf(node) {
+        if (node.kind !== "agent") {
+            throw new IntelError(409, "not_an_agent", "This node is not an agent");
+        }
+        // The Application ID rides on every agent read (#182). It is a name and not a credential, so
+        // there is nothing to withhold — and the surface that draws an agent has to be able to say
+        // whether it has a principal at all, because an agent without one runs nothing.
+        const applicationId = await deps.repository.agentApplicationId(node.id);
+        if (node.currentVersionId === null) {
+            return { node, version: null, definition: null, applicationId };
+        }
+        const version = await deps.repository.getVersion(node.currentVersionId);
+        if (!version)
+            throw new IntelError(500, "version_missing", "Current version is missing");
+        const body = await deps.content.get(version.contentKey);
+        if (body === null)
+            throw new IntelError(500, "content_missing", "Version content is missing");
+        return { node, version, definition: parseStoredDefinition(body), applicationId };
+    }
+    /**
+     * One immutable definition version, written exactly the way a document's content is (ADR-0005 §1).
+     *
+     * ⚠️ R2 object first, version row second, R2 object deleted again if the row does not land — the
+     * same order `save` keeps and for the same reason: an orphaned object is invisible, while a
+     * version row pointing at nothing is an agent that cannot be read at all.
+     *
+     * ⚠️ The body is serialized from the PARSED definition, never from the caller's JSON text. What
+     * is stored is therefore always what the contract accepted, and a field the strict schema refused
+     * cannot reach R2 by riding along in the original string.
+     *
+     * ⚠️ `segment` is `null`, like a document's and unlike a table's (#135): every version here holds
+     * the whole definition, so there is nothing for a snapshot to mark off from what came before it.
+     */
+    async function writeAgentVersion(actor, node, definition, baseVersionId, idempotencyKey) {
+        const body = JSON.stringify(definition);
+        const versionId = deps.id();
+        const contentKey = contentKeyFor(node.id, versionId);
+        const version = {
+            id: versionId,
+            nodeId: node.id,
+            sequence: await nextSequence(node),
+            contentKey,
+            mediaType: AgentMediaType,
+            contentHash: await deps.hash(body),
+            size: new TextEncoder().encode(body).byteLength,
+            segment: null,
+            createdBy: actor.id,
+            createdAt: deps.now().toISOString(),
+        };
+        await deps.content.put(contentKey, body, AgentMediaType);
+        let saved;
+        try {
+            saved = await deps.repository.appendVersion({
+                version,
+                actorId: actor.id,
+                baseVersionId,
+                idempotencyKey,
+                auditId: deps.id(),
+            });
+        }
+        catch (error) {
+            await deps.content.delete(contentKey).catch(() => undefined);
+            throw error;
+        }
+        if (saved === "conflict") {
+            await deps.content.delete(contentKey);
+            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,
+            definition,
+            applicationId: await deps.repository.agentApplicationId(node.id),
+        };
+    }
+    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;
+    }
+    /**
+     * What the grant just written does not cover: the documents the flows in this folder read that
+     * the new principal still cannot.
+     *
+     * ⚠️ It warns and never blocks. A node reference across the folder edge is a possible
+     * failure, not a way around permissions — that distinction is the whole of ADR-0004 §4, and a
+     * block here would force everyone using one central policy document to duplicate it.
+     *
+     * ⚠️ Which documents may be named is `getVisible`, the lookup every other node read goes
+     * through, and never a second rule written for a message: the ones this actor may see are named,
+     * the rest are counted. That is exactly where #17 and #19 went wrong in review.
+     *
+     * The flow side is filtered by the flow list's own predicate as well. It changes nothing today —
+     * sharing needs `read` on the folder and `read` inherits over the whole subtree, so every flow in
+     * it is already visible — but the verbs are independent by decision (ADR-0004 §2), and the day
+     * `share` stops implying `read` this must not be the place that quietly starts leaking.
+     *
+     * It does say one thing about the grantee: that a named document is not readable for them. That
+     * is the consequence of this actor's own decision, on their own folder, at the moment they make
+     * it, and it is the smallest answer that lets them make it — the alternative is the flow failing
+     * for someone else next week with nobody able to say why. It never enumerates the principal's
+     * access in general and never leaves the documents these flows actually name.
+     */
+    /**
+     * The nodes the agents in this folder's subtree name in their definitions (#139, ADR-0005 §2).
+     *
+     * ⚠️ Read from R2 and parsed, because an agent's references live in its definition body and not
+     * in D1 — unlike a flow's, which sit in `flow_versions.graph_json` and can be matched in SQL.
+     * There is no query that can answer this, and writing one against a guessed JSON shape is exactly
+     * how the flow side came to match a graph that migration 0008 had already abolished
+     * (anchrd/intel#153): the query kept returning nothing and the warning silently stopped arriving.
+     * Parsing the real contract schema is what makes this one fail loudly instead of quietly.
+     *
+     * ⚠️ A definition that will not parse is SKIPPED rather than thrown — the opposite of the read
+     * path above, deliberately. This runs while somebody is sharing a folder, and a warning that
+     * raises would turn one broken agent into a folder nobody can share. The read path is where a
+     * corrupt definition has to be loud; here the cost of loudness is paid by the wrong person.
+     */
+    async function agentNodeReferences(actor, folderId) {
+        const keys = await deps.repository.listVisibleAgentDefinitionKeys(actor, folderId);
+        const referenced = [];
+        for (const key of keys) {
+            const body = await deps.content.get(key);
+            if (body === null)
+                continue;
+            try {
+                const parsed = AgentDefinition.safeParse(JSON.parse(body));
+                if (!parsed.success)
+                    continue;
+                for (const reference of parsed.data.references)
+                    referenced.push(reference.nodeId);
+            }
+            catch {
+                // Unparsable JSON is skipped for the reason above: this runs inside a share, and one
+                // broken agent must not be able to make a folder unshareable.
+            }
+        }
+        return referenced;
+    }
+    async function unreadableForPrincipal(actor, folderId, principal) {
+        const grantee = asPrincipalActor(principal);
+        const titles = [];
+        let hidden = 0;
+        // Flows and agents reach for material the same way and the grant covers neither, so they are
+        // one list. Deduplicated, because a document that is both a flow's input and an agent's system
+        // message is one thing the new principal cannot read, not two.
+        const referenced = [
+            ...new Set([
+                ...(await deps.flowNodeReferences(actor, folderId)),
+                ...(await agentNodeReferences(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_save` 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));
+        },
+        /**
+         * 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);
+            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) {
+            // The generic path can file an agent row too — one without a definition or a principal — so
+            // the #190 gate stands here as well. Only where no runtime exists: with one, this path stays
+            // exactly as it was, which is part of the same ticket.
+            if (input.kind === "agent" && !deps.agentRuntimeAvailable()) {
+                throw new IntelError(503, "agent_runtime_not_configured", "This installation has no agent runtime, so agents cannot be created");
+            }
+            const existingId = await deps.repository.findIdempotentNode(actor.id, "node.create", input.idempotencyKey);
+            if (existingId)
+                return await requireVisible(actor, existingId);
+            if (input.parentId !== null && !(await deps.repository.can(actor, input.parentId, "write"))) {
+                throw new IntelError(403, "node_forbidden", "Parent folder cannot be edited");
+            }
+            const timestamp = deps.now().toISOString();
+            return await deps.repository.insertNode({
+                node: {
+                    id: deps.id(),
+                    parentId: input.parentId,
+                    kind: input.kind,
+                    title: 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(),
+            });
+        },
+        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 (node.kind !== "document") {
+                throw new IntelError(409, "document_content_required", "Only documents 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 getAgent(actor, input) {
+            return await agentOf(await requireVisible(actor, input.nodeId));
+        },
+        async listAgents(actor, input) {
+            return { items: await deps.repository.listVisibleAgents(actor, input) };
+        },
+        /**
+         * The Gate Application, the node, and its first definition, in that order.
+         *
+         * ⚠️ Two writes behind one call, so the replay has to be answered for both. The node
+         * carries the caller's key under `node.create`; the definition carries a derived one under
+         * `node.save`, because the two operations share an idempotency table and the same key twice
+         * would make the second write look like a replay of the first. A caller who repeats the
+         * request gets the agent that already exists rather than a second one beside it.
+         *
+         * ⚠️ A REPLAY MAKES NO SECOND APPLICATION and answers `applicationKey: null`. It still returns
+         * the agent that exists — that promise is not weakened — but a repeat that minted a fresh
+         * principal to fill the field would leave the installation with two machine accounts for one
+         * agent, one of which nobody would ever switch off. Gate is not asked at all on that path.
+         *
+         * ⚠️ Gate is asked BEFORE anything is written, and that ordering IS the answer to "what if Gate
+         * is down". Nothing exists yet at that moment, so a Gate that does not answer leaves no node, no
+         * version, no R2 object and no audit event — the agent simply does not come into being, and the
+         * caller repeats the request. The alternative, a node that exists without a principal plus a
+         * way to fill it in later, buys nothing: such an agent starts no run (`agent_key_missing` in the
+         * runtime), so it would be a broken row waiting for a second, easily forgotten step — and
+         * "somebody must remember to do it in Gate" is the exact chore this ticket removes.
+         *
+         * ⚠️ If the node write fails after Gate succeeded, the fresh Application is switched off again,
+         * best effort. A live principal nobody references is precisely the invisible access #182 exists
+         * to prevent, and disabling rather than deleting keeps the compensation consistent with what
+         * archiving does — Gate's `DELETE` would take the identity with it (`anchrd/gate#224`).
+         */
+        async createAgent(actor, input, caller) {
+            // Before anything else — before the idempotency read, before Gate (#190). An installation
+            // without a runtime refuses the agent by name, and the refusal costs no storage read, mints
+            // no principal, and is the same on every surface because it lives here.
+            if (!deps.agentRuntimeAvailable()) {
+                throw new IntelError(503, "agent_runtime_not_configured", "This installation has no agent runtime, so agents cannot be created");
+            }
+            const definitionKey = `${input.idempotencyKey}:definition`;
+            const existingId = await deps.repository.findIdempotentNode(actor.id, "node.create", input.idempotencyKey);
+            if (existingId) {
+                return {
+                    ...(await agentOf(await requireVisible(actor, existingId))),
+                    applicationKey: null,
+                };
+            }
+            if (input.parentId !== null && !(await deps.repository.can(actor, input.parentId, "write"))) {
+                throw new IntelError(403, "node_forbidden", "Parent folder cannot be edited");
+            }
+            const nodeId = deps.id();
+            // The Application's name is what a person reads in Gate's list, so it has to be enough to
+            // recognise the agent by. Title alone would leave two agents called "Research" indis-
+            // tinguishable; the node ID is what the runtime's key map is keyed by anyway.
+            const application = await deps.applications.create({
+                token: caller.token,
+                name: `Intel agent ${input.title} (${nodeId})`,
+            });
+            const timestamp = deps.now().toISOString();
+            let node;
+            try {
+                node = await deps.repository.insertNode({
+                    node: {
+                        id: nodeId,
+                        parentId: input.parentId,
+                        kind: "agent",
+                        title: 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(),
+                    application: { id: application.id },
+                });
+            }
+            catch (error) {
+                await deps.applications
+                    .setEnabled({ token: caller.token, applicationId: application.id, enabled: false })
+                    .catch(() => undefined);
+                throw error;
+            }
+            const agent = await writeAgentVersion(actor, node, input.definition, null, definitionKey);
+            return {
+                ...agent,
+                // ⚠️ The one place a credential is put into an answer, and it is assembled here rather than
+                // carried around: `application.key` has been in one local variable since Gate returned it
+                // and reaches no store, no audit row and no log on the way (D27).
+                applicationKey: {
+                    agentId: node.id,
+                    applicationId: application.id,
+                    key: application.key,
+                    notice: "This key is shown once. Add it to the agent runtime's AGENT_APPLICATION_KEYS secret as { agentId, key } — the whole list, not just this entry — and store it nowhere else. Intel keeps only the application ID; Gate keeps only a hash.",
+                },
+            };
+        },
+        async saveAgentDefinition(actor, input) {
+            const existingId = await deps.repository.findIdempotentNode(actor.id, "node.save", input.idempotencyKey);
+            if (existingId)
+                return await agentOf(await requireVisible(actor, input.nodeId));
+            const node = await requireVisible(actor, input.nodeId);
+            if (node.kind !== "agent") {
+                throw new IntelError(409, "not_an_agent", "Only agents accept a definition");
+            }
+            if (!(await deps.repository.can(actor, node.id, "write"))) {
+                throw new IntelError(403, "node_forbidden", "This agent cannot be edited");
+            }
+            if (node.currentVersionId !== input.baseVersionId) {
+                throw new IntelError(409, "version_conflict", "A newer version already exists");
+            }
+            return await writeAgentVersion(actor, node, input.definition, input.baseVersionId, input.idempotencyKey);
+        },
+        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);
+                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 };
+        },
+        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");
+            }
+            const replayedId = await deps.repository.findIdempotentNode(actor.id, "node.update", input.idempotencyKey);
+            if (replayedId)
+                return await requireVisible(actor, replayedId);
+            if (input.parentId !== undefined && input.parentId !== null) {
+                if (input.parentId === current.id) {
+                    throw new IntelError(409, "move_cycle", "A node cannot contain itself");
+                }
+                const parent = await requireVisible(actor, input.parentId);
+                if (parent.kind !== "folder") {
+                    throw new IntelError(409, "parent_not_folder", "A node's parent must be a folder");
+                }
+                if (!(await deps.repository.can(actor, parent.id, "write"))) {
+                    throw new IntelError(403, "node_forbidden", "Destination folder cannot be edited");
+                }
+            }
+            const updatedAt = deps.now().toISOString();
+            const updated = await deps.repository.updateNode({
+                node: {
+                    ...current,
+                    parentId: input.parentId === undefined ? current.parentId : input.parentId,
+                    title: input.title ?? current.title,
+                    description: input.description === undefined ? current.description : input.description,
+                    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 === "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 — and for an agent, its Gate Application with it (#182).
+         *
+         * ⚠️ Gate is switched BEFORE the node row, and the order is the whole safety argument. The state
+         * that must not exist is "archived agent, live principal": a machine account that still holds
+         * every grant the agent had, on a node nobody looks at any more. Writing the row first and then
+         * failing at Gate produces exactly that. The reverse leaves "live agent, switched-off
+         * principal" — the agent refuses its next run by name (`agent_principal_rejected` in the
+         * runtime), which somebody notices the same day and which repeating the call repairs.
+         *
+         * ⚠️ The optimistic check is made twice on purpose: cheaply here so a stale `baseUpdatedAt`
+         * never reaches Gate, and authoritatively in the statement that writes. Only a genuine race
+         * gets past the first, and that path puts Gate back the way it was before refusing.
+         *
+         * ⚠️ Gate is asked even when the node is already in the requested state. Both routes are
+         * idempotent there, and it is what makes a repeated call heal a run that died between the two
+         * writes — the alternative would be an agent stuck live because its node already said archived.
+         *
+         * ⚠️ Nothing here is skipped for an agent WITHOUT an Application. There is no principal to
+         * switch, Gate is not called, and the node archives like a document — the case of an agent
+         * imported, restored from a bundle, or written before #182.
+         */
+        async archive(actor, input, caller) {
+            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 switches nothing a second time: the first run already did, and Gate must not learn
+            // about a request that is not happening.
+            if (replayedId)
+                return await requireVisible(actor, replayedId);
+            const applicationId = current.kind === "agent" ? await deps.repository.agentApplicationId(current.id) : null;
+            if (applicationId !== null) {
+                if (current.updatedAt !== input.baseUpdatedAt) {
+                    throw new IntelError(409, "update_conflict", "This node was changed by another editor");
+                }
+                await deps.applications.setEnabled({
+                    token: caller.token,
+                    applicationId,
+                    enabled: !input.archived,
+                });
+            }
+            const updatedAt = deps.now().toISOString();
+            const updated = await deps.repository.archiveNode({
+                nodeId: current.id,
+                baseUpdatedAt: input.baseUpdatedAt,
+                archivedAt: input.archived ? updatedAt : null,
+                updatedAt,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            if (updated === "conflict") {
+                if (applicationId !== null) {
+                    // Back to what the node actually said, not to the inverse of what was asked: repeating an
+                    // archive on an already archived agent would otherwise switch its principal back ON.
+                    await deps.applications
+                        .setEnabled({
+                        token: caller.token,
+                        applicationId,
+                        enabled: current.archivedAt === null,
+                    })
+                        .catch(() => undefined);
+                }
+                throw new IntelError(409, "update_conflict", "This node was changed by another editor");
+            }
+            return updated;
+        },
+        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 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),
+                    };
+                }
+            }
+            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) };
+        },
+        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));
+                }
+            }
+            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 {
+                // ⚠️ The scope narrows the vector hits afterwards, in the same D1 statement that already
+                // re-checks the ACL — so the candidate set has to be wide enough for that cut to leave
+                // something. A folder holding a dozen documents inside a tree of thousands is not reached by
+                // the fan-out an unscoped search gets away with, and a starved scope looks like an empty
+                // folder. 100 is what the port clamps to, so a scoped search asks for all there is.
+                const candidates = input.scopeId === undefined ? Math.min(100, input.limit * 4) : 100;
+                const hits = await deps.semantic.search(input.query, candidates);
+                const semanticScores = new Map();
+                for (const hit of hits) {
+                    semanticScores.set(hit.nodeId, Math.max(semanticScores.get(hit.nodeId) ?? 0, hit.score));
+                }
+                const semantic = await deps.repository.hydrateVisibleCitations(actor, [...semanticScores.keys()], 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");
+            }
+            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 };
+        },
+    };
+}