@anchrd/intel-api 0.3.1 → 0.3.3

package/dist/knowledge/knowledge.js

@@ -1,4 +1,35 @@
+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");
@@ -48,6 +79,51 @@ export function createKnowledge(deps) {
             .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 };
@@ -56,11 +132,129 @@ export function createKnowledge(deps) {
             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)
@@ -94,6 +288,12 @@ export function createKnowledge(deps) {
         async list(actor, input) {
             return { items: 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));
         },
@@ -106,13 +306,13 @@ export function createKnowledge(deps) {
                 return "missing";
             if (folder.kind !== "folder")
                 return "not-a-folder";
-            return (await deps.repository.canEdit(actor, folder.id)) ? "ok" : "forbidden";
+            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.canEdit(actor, input.parentId))) {
+            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();
@@ -146,7 +346,7 @@ export function createKnowledge(deps) {
             if (node.kind !== "document") {
                 throw new IntelError(409, "document_content_required", "Only documents accept editor content versions");
             }
-            if (!(await deps.repository.canEdit(actor, node.id))) {
+            if (!(await deps.repository.can(actor, node.id, "write"))) {
                 throw new IntelError(403, "knowledge_forbidden", "Knowledge cannot be edited");
             }
             if (node.currentVersionId !== input.baseVersionId) {
@@ -189,6 +389,7 @@ export function createKnowledge(deps) {
                 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 };
         },
@@ -203,7 +404,7 @@ export function createKnowledge(deps) {
             if (node.kind !== "attachment") {
                 throw new IntelError(409, "not_an_attachment", "Only attachment nodes accept file uploads");
             }
-            if (!(await deps.repository.canEdit(actor, node.id))) {
+            if (!(await deps.repository.can(actor, node.id, "write"))) {
                 throw new IntelError(403, "knowledge_forbidden", "Attachment cannot be edited");
             }
             if (node.currentVersionId !== input.baseVersionId) {
@@ -256,13 +457,78 @@ export function createKnowledge(deps) {
                 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.canEdit(actor, current.id))) {
+            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);
@@ -276,7 +542,7 @@ export function createKnowledge(deps) {
                 if (parent.kind !== "folder") {
                     throw new IntelError(409, "parent_not_folder", "Knowledge parent must be a folder");
                 }
-                if (!(await deps.repository.canEdit(actor, parent.id))) {
+                if (!(await deps.repository.can(actor, parent.id, "write"))) {
                     throw new IntelError(403, "knowledge_forbidden", "Destination folder cannot be edited");
                 }
             }
@@ -307,7 +573,7 @@ export function createKnowledge(deps) {
         },
         async archive(actor, input) {
             const current = await requireVisible(actor, input.nodeId);
-            if (!(await deps.repository.canEdit(actor, current.id))) {
+            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);
@@ -329,94 +595,81 @@ export function createKnowledge(deps) {
             return updated;
         },
         async listGrants(actor, resourceId) {
-            await requireVisible(actor, resourceId);
-            if (!(await deps.repository.canManage(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 { items: await deps.repository.listGrants(resourceId) };
+            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) };
         },
-        async createLink(actor, input) {
-            await requireVisible(actor, input.sourceNodeId);
-            await requireVisible(actor, input.targetNodeId);
-            if (!(await deps.repository.canEdit(actor, input.sourceNodeId))) {
-                throw new IntelError(403, "knowledge_forbidden", "Knowledge links cannot be edited");
-            }
-            const replayedId = await deps.repository.findIdempotentNode(actor.id, "knowledge.link", input.idempotencyKey);
-            if (replayedId) {
-                const replayed = await deps.repository.getLinkVisible(actor, replayedId);
-                if (replayed)
-                    return replayed;
-            }
-            const existing = await deps.repository.findLinkVisible(actor, input);
-            if (existing)
-                return existing;
-            const createdAt = deps.now().toISOString();
-            return await deps.repository.insertLink({
-                link: {
-                    id: deps.id(),
-                    sourceNodeId: input.sourceNodeId,
-                    targetNodeId: input.targetNodeId,
-                    relation: input.relation,
-                    label: input.label,
-                    createdBy: actor.id,
-                    createdAt,
-                },
-                actorId: actor.id,
-                idempotencyKey: input.idempotencyKey,
-                auditId: deps.id(),
-            });
-        },
-        async deleteLink(actor, input) {
-            await requireVisible(actor, input.sourceNodeId);
-            if (!(await deps.repository.canEdit(actor, input.sourceNodeId))) {
-                throw new IntelError(403, "knowledge_forbidden", "Knowledge links cannot be edited");
-            }
-            const replayed = await deps.repository.findIdempotentNode(actor.id, "knowledge.unlink", input.idempotencyKey);
-            if (replayed)
-                return { deleted: replayed.startsWith("1:") };
-            const link = await deps.repository.getLinkVisible(actor, input.linkId);
-            if (!link || link.sourceNodeId !== input.sourceNodeId) {
-                throw new IntelError(404, "knowledge_link_not_found", "Knowledge link was not found");
-            }
-            return {
-                deleted: await deps.repository.deleteLink({
-                    sourceNodeId: input.sourceNodeId,
-                    linkId: input.linkId,
-                    actorId: actor.id,
-                    idempotencyKey: input.idempotencyKey,
-                    auditId: deps.id(),
-                    occurredAt: deps.now().toISOString(),
-                }),
-            };
+        /**
+         * 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) {
-            await requireVisible(actor, input.resourceId);
-            if (!(await deps.repository.canManage(actor, input.resourceId))) {
+            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");
             }
-            const replayedId = await deps.repository.findIdempotentNode(actor.id, "knowledge.share", input.idempotencyKey);
-            if (replayedId) {
-                const replayed = (await deps.repository.listGrants(input.resourceId)).find((grant) => grant.id === replayedId);
-                if (replayed)
-                    return replayed;
+            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();
-            return await deps.repository.setGrant({
+            const grant = await deps.repository.setGrant({
                 grant: {
                     id: deps.id(),
                     resourceId: input.resourceId,
                     principal,
-                    role: input.role,
+                    verb: input.verb,
                     expiresAt: input.expiresAt,
                     createdBy: actor.id,
                     createdAt: timestamp,
@@ -425,15 +678,35 @@ export function createKnowledge(deps) {
                 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.canManage(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,
@@ -470,7 +743,7 @@ export function createKnowledge(deps) {
             }
         },
         async reindex(actor) {
-            if (actor.canReindex !== true) {
+            if (actor.isAdmin !== true) {
                 throw new IntelError(403, "knowledge_reindex_forbidden", "Reindex permission is required");
             }
             let queued = 0;