@anchrd/intel-api 0.6.7 → 0.7.0

package/dist/knowledge/knowledge.js

@@ -1,761 +0,0 @@
-import { 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";
-// `execute` is meaningful only for flows, and only a folder can hold a flow. 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.
-function applicableVerbs(kind) {
-    return kind === "folder" ? ["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: "" };
-}
-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 createKnowledge(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.firstVersionContentKey(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, idempotencyKey) {
-        const versionId = deps.id();
-        const contentKey = `knowledge/${node.id}/versions/${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,
-                    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;
-        }
-    }
-    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, "knowledge_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 Knowledge 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 Knowledge 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.
-     */
-    async function unreadableForPrincipal(actor, folderId, principal) {
-        const grantee = asPrincipalActor(principal);
-        const titles = [];
-        let hidden = 0;
-        for (const resourceId of await deps.flowKnowledgeReferences(actor, folderId)) {
-            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 `knowledge_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, "knowledge_not_found", "Knowledge 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 Knowledge 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://knowledge/${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));
-        },
-        // Knowledge 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) {
-            const existingId = await deps.repository.findIdempotentNode(actor.id, "knowledge.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, "knowledge_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, "knowledge.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, "knowledge_forbidden", "Knowledge 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 = `knowledge/${node.id}/versions/${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,
-                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, "knowledge.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, "knowledge.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, "knowledge_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 = `knowledge/${node.id}/versions/${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,
-                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, "knowledge.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");
-            }
-            const body = encodeCsv([input.columns]);
-            const version = await writeTableSegment(actor, node, body, 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, "knowledge.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. A row that does not fit the header is a
-            // caller that believes the table has a different shape, and quietly filling the gap would
-            // store that misunderstanding as data nobody can tell apart from the real thing afterwards.
-            const wrong = input.rows.findIndex((row) => row.length !== header.length);
-            if (wrong !== -1) {
-                throw new IntelError(400, "table_row_shape", `Row ${wrong + 1} has ${input.rows[wrong]?.length ?? 0} cells but the table has ${header.length} columns: ${header.join(", ")}`);
-            }
-            const version = await writeTableSegment(actor, node, encodeCsv(input.rows), input.idempotencyKey);
-            await deps.indexing.enqueue(version.id);
-            return {
-                node: await requireVisible(actor, node.id),
-                version,
-                appended: input.rows.length,
-            };
-        },
-        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, "knowledge_forbidden", "Knowledge cannot be edited");
-            }
-            const replayedId = await deps.repository.findIdempotentNode(actor.id, "knowledge.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", "Knowledge cannot contain itself");
-                }
-                const parent = await requireVisible(actor, input.parentId);
-                if (parent.kind !== "folder") {
-                    throw new IntelError(409, "parent_not_folder", "Knowledge parent must be a folder");
-                }
-                if (!(await deps.repository.can(actor, parent.id, "write"))) {
-                    throw new IntelError(403, "knowledge_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", "Knowledge cannot be moved into its descendant");
-            }
-            if (updated === "conflict") {
-                throw new IntelError(409, "update_conflict", "Knowledge was changed by another editor");
-            }
-            if (updated.currentVersionId)
-                await deps.indexing.enqueue(updated.currentVersionId);
-            return updated;
-        },
-        async archive(actor, input) {
-            const current = await requireVisible(actor, input.nodeId);
-            if (!(await deps.repository.can(actor, current.id, "write"))) {
-                throw new IntelError(403, "knowledge_forbidden", "Knowledge cannot be edited");
-            }
-            const replayedId = await deps.repository.findIdempotentNode(actor.id, "knowledge.archive", input.idempotencyKey);
-            if (replayedId)
-                return await requireVisible(actor, replayedId);
-            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") {
-                throw new IntelError(409, "update_conflict", "Knowledge 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, "knowledge_forbidden", "Knowledge sharing 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 Knowledge 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
-        // Knowledge steps 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, "knowledge_forbidden", "Knowledge sharing 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, "knowledge.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, "knowledge_forbidden", "Knowledge sharing 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) {
-            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 {
-                const hits = await deps.semantic.search(input.query, Math.min(100, input.limit * 4));
-                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(),
-                ]);
-                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, "knowledge_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 };
-        },
-    };
-}