@anchrd/intel-api 0.3.1 → 0.3.2

package/dist/adapters/db/db.js

@@ -1,3 +1,8 @@
+import { nodeVerbBindings, nodeVerbQuery, subtreeBindings, subtreeCte } from "./db-grants.js";
+const grantColumns = `id, node_id, principal_type, principal_id, verb, expires_at,
+  created_by, created_at`;
+const linkColumns = `link.id, link.source_node_id, link.target_node_id, link.relation,
+  link.origin, link.label, link.created_by, link.created_at`;
 const nodeColumns = `n.id, n.parent_id, n.kind, n.title, n.description, n.context_policy,
   n.owner_id, n.current_version_id, n.created_at, n.updated_at, n.archived_at`;
 function mapNode(row) {
@@ -45,9 +50,9 @@ function mapGrant(row) {
     }
     return {
         id: row.id,
-        resourceId: row.resource_id,
+        resourceId: row.node_id,
         principal,
-        role: row.role,
+        verb: row.verb,
         expiresAt: row.expires_at,
         createdBy: row.created_by,
         createdAt: row.created_at,
@@ -59,6 +64,7 @@ function mapLink(row) {
         sourceNodeId: row.source_node_id,
         targetNodeId: row.target_node_id,
         relation: row.relation,
+        origin: row.origin,
         label: row.label,
         createdBy: row.created_by,
         createdAt: row.created_at,
@@ -72,40 +78,39 @@ function toFtsQuery(query) {
         .join(" AND ");
 }
 export function createKnowledgeRepository(deps) {
-    const visibleCte = `WITH RECURSIVE allowed(id, parent_id) AS (
-    SELECT seed.id, seed.parent_id
-    FROM knowledge_nodes seed
-    WHERE seed.owner_id = ?
-       OR EXISTS (
-         SELECT 1 FROM resource_grants grant_row
-         WHERE grant_row.resource_type = 'knowledge'
-           AND grant_row.resource_id = seed.id
-           AND (
-             (grant_row.principal_type = 'user' AND grant_row.principal_id = ?)
-             OR (grant_row.principal_type = 'email' AND lower(grant_row.principal_id) = lower(?))
-             OR (grant_row.principal_type = 'organization' AND grant_row.principal_id = '*')
-           )
-           AND (grant_row.expires_at IS NULL OR grant_row.expires_at > ?)
-       )
-    UNION
-    SELECT child.id, child.parent_id
-    FROM knowledge_nodes child
-    JOIN allowed parent ON child.parent_id = parent.id
-  )`;
+    // Reading is one verb among four; the tree walk itself lives in db-grants.ts so Flows asks the
+    // same question of the same table.
+    const visibleCte = subtreeCte;
+    const readBindings = (actor) => subtreeBindings(actor, "read", deps.now().toISOString());
+    /**
+     * One statement for the level the tree reads and for the bounded read the relation graph makes,
+     * so the visibility predicate cannot drift between them.
+     *
+     * ⚠️ In the bounded form `LIMIT` follows the `WHERE`, so the cut falls among the rows this actor
+     * may see and never before them, and `COUNT(*) OVER ()` counts those same rows alone (#30).
+     */
+    const visibleChildren = (bounded) => `${visibleCte}
+    SELECT ${nodeColumns}${bounded ? ", COUNT(*) OVER () AS total" : ""}
+    FROM knowledge_nodes n
+    JOIN allowed ON allowed.id = n.id
+    WHERE n.parent_id IS ? AND (? = 1 OR n.archived_at IS NULL)
+    ORDER BY CASE n.kind WHEN 'folder' THEN 0 ELSE 1 END, lower(n.title), n.id${bounded ? " LIMIT ?" : ""}`;
     return {
         async listVisible(actor, input) {
-            const now = deps.now().toISOString();
             const result = await deps.db
-                .prepare(`${visibleCte}
-          SELECT ${nodeColumns}
-          FROM knowledge_nodes n
-          JOIN allowed ON allowed.id = n.id
-          WHERE n.parent_id IS ? AND (? = 1 OR n.archived_at IS NULL)
-          ORDER BY CASE n.kind WHEN 'folder' THEN 0 ELSE 1 END, lower(n.title), n.id`)
-                .bind(actor.id, actor.id, actor.email, now, input.parentId, input.includeArchived ? 1 : 0)
+                .prepare(visibleChildren(false))
+                .bind(...readBindings(actor), input.parentId, input.includeArchived ? 1 : 0)
                 .all();
             return (result.results ?? []).map(mapNode);
         },
+        async listVisibleBounded(actor, input) {
+            const result = await deps.db
+                .prepare(visibleChildren(true))
+                .bind(...readBindings(actor), input.parentId, 0, input.limit)
+                .all();
+            const rows = result.results ?? [];
+            return { items: rows.map(mapNode), total: rows[0]?.total ?? 0 };
+        },
         async getVisible(actor, nodeId) {
             const row = await deps.db
                 .prepare(`${visibleCte}
@@ -113,65 +118,14 @@ export function createKnowledgeRepository(deps) {
           FROM knowledge_nodes n
           JOIN allowed ON allowed.id = n.id
           WHERE n.id = ?`)
-                .bind(actor.id, actor.id, actor.email, deps.now().toISOString(), nodeId)
+                .bind(...readBindings(actor), nodeId)
                 .first();
             return row ? mapNode(row) : null;
         },
-        async canEdit(actor, nodeId) {
+        async can(actor, nodeId, verb) {
             const row = await deps.db
-                .prepare(`WITH RECURSIVE ancestors(id, parent_id, owner_id) AS (
-          SELECT id, parent_id, owner_id FROM knowledge_nodes WHERE id = ?
-          UNION ALL
-          SELECT parent.id, parent.parent_id, parent.owner_id
-          FROM knowledge_nodes parent
-          JOIN ancestors child ON child.parent_id = parent.id
-        )
-        SELECT 1 AS allowed
-        FROM ancestors
-        WHERE owner_id = ?
-           OR EXISTS (
-             SELECT 1 FROM resource_grants grant_row
-             WHERE grant_row.resource_type = 'knowledge'
-               AND grant_row.resource_id = ancestors.id
-               AND (
-                 (grant_row.principal_type = 'user' AND grant_row.principal_id = ?)
-                 OR (grant_row.principal_type = 'email' AND lower(grant_row.principal_id) = lower(?))
-                 OR (grant_row.principal_type = 'organization' AND grant_row.principal_id = '*')
-               )
-               AND grant_row.role IN ('editor', 'manager')
-               AND (grant_row.expires_at IS NULL OR grant_row.expires_at > ?)
-           )
-        LIMIT 1`)
-                .bind(nodeId, actor.id, actor.id, actor.email, deps.now().toISOString())
-                .first();
-            return row?.allowed === 1;
-        },
-        async canManage(actor, nodeId) {
-            const row = await deps.db
-                .prepare(`WITH RECURSIVE ancestors(id, parent_id, owner_id) AS (
-          SELECT id, parent_id, owner_id FROM knowledge_nodes WHERE id = ?
-          UNION ALL
-          SELECT parent.id, parent.parent_id, parent.owner_id
-          FROM knowledge_nodes parent
-          JOIN ancestors child ON child.parent_id = parent.id
-        )
-        SELECT 1 AS allowed
-        FROM ancestors
-        WHERE owner_id = ?
-           OR EXISTS (
-             SELECT 1 FROM resource_grants grant_row
-             WHERE grant_row.resource_type = 'knowledge'
-               AND grant_row.resource_id = ancestors.id
-               AND (
-                 (grant_row.principal_type = 'user' AND grant_row.principal_id = ?)
-                 OR (grant_row.principal_type = 'email' AND lower(grant_row.principal_id) = lower(?))
-                 OR (grant_row.principal_type = 'organization' AND grant_row.principal_id = '*')
-               )
-               AND grant_row.role = 'manager'
-               AND (grant_row.expires_at IS NULL OR grant_row.expires_at > ?)
-           )
-        LIMIT 1`)
-                .bind(nodeId, actor.id, actor.id, actor.email, deps.now().toISOString())
+                .prepare(nodeVerbQuery)
+                .bind(...nodeVerbBindings(nodeId, actor, verb, deps.now().toISOString()))
                 .first();
             return row?.allowed === 1;
         },
@@ -228,7 +182,7 @@ export function createKnowledgeRepository(deps) {
               FROM knowledge_nodes n
               JOIN allowed ON allowed.id = n.id
               WHERE n.id = ?`)
-                        .bind(input.actorId, input.actorId, "", deps.now().toISOString(), replayedKey.resource_id)
+                        .bind(...readBindings({ id: input.actorId, email: "" }), replayedKey.resource_id)
                         .first();
                     if (replayed)
                         return mapNode(replayed);
@@ -245,6 +199,22 @@ export function createKnowledgeRepository(deps) {
                 .first();
             return row ? mapVersion(row) : null;
         },
+        async listVersionContentKeys(nodeId) {
+            const result = await deps.db
+                .prepare(`SELECT content_key FROM knowledge_versions
+          WHERE node_id = ? ORDER BY sequence`)
+                .bind(nodeId)
+                .all();
+            return (result.results ?? []).map((row) => row.content_key);
+        },
+        async firstVersionContentKey(nodeId) {
+            const row = await deps.db
+                .prepare(`SELECT content_key FROM knowledge_versions
+          WHERE node_id = ? ORDER BY sequence LIMIT 1`)
+                .bind(nodeId)
+                .first();
+            return row?.content_key ?? null;
+        },
         async listVersions(nodeId) {
             const result = await deps.db
                 .prepare(`SELECT id, node_id, sequence, content_key, media_type, content_hash,
@@ -429,122 +399,191 @@ export function createKnowledgeRepository(deps) {
                 .first();
             return row?.current_version_id === version.id ? "saved" : "conflict";
         },
-        async listGrants(resourceId) {
-            const result = await deps.db
-                .prepare(`SELECT id, resource_id, principal_type, principal_id, role, expires_at,
-          created_by, created_at
-          FROM resource_grants
-          WHERE resource_type = 'knowledge' AND resource_id = ?
-          ORDER BY created_at, id`)
-                .bind(resourceId)
-                .all();
-            return (result.results ?? []).map(mapGrant);
-        },
-        async listLinksVisible(actor, nodeId) {
-            const result = await deps.db
-                .prepare(`${visibleCte}
-          SELECT link.id, link.source_node_id, link.target_node_id, link.relation, link.label,
-            link.created_by, link.created_at
-          FROM knowledge_links link
-          JOIN allowed source_access ON source_access.id = link.source_node_id
-          JOIN allowed target_access ON target_access.id = link.target_node_id
-          WHERE link.source_node_id = ? OR link.target_node_id = ?
-          ORDER BY link.created_at, link.id`)
-                .bind(actor.id, actor.id, actor.email, deps.now().toISOString(), nodeId, nodeId)
-                .all();
-            return (result.results ?? []).map(mapLink);
-        },
-        async getLinkVisible(actor, linkId) {
-            const row = await deps.db
-                .prepare(`${visibleCte}
-          SELECT link.id, link.source_node_id, link.target_node_id, link.relation, link.label,
-            link.created_by, link.created_at
-          FROM knowledge_links link
-          JOIN allowed source_access ON source_access.id = link.source_node_id
-          JOIN allowed target_access ON target_access.id = link.target_node_id
-          WHERE link.id = ?`)
-                .bind(actor.id, actor.id, actor.email, deps.now().toISOString(), linkId)
-                .first();
-            return row ? mapLink(row) : null;
-        },
-        async findLinkVisible(actor, input) {
-            const row = await deps.db
-                .prepare(`${visibleCte}
-          SELECT link.id, link.source_node_id, link.target_node_id, link.relation, link.label,
-            link.created_by, link.created_at
-          FROM knowledge_links link
-          JOIN allowed source_access ON source_access.id = link.source_node_id
-          JOIN allowed target_access ON target_access.id = link.target_node_id
-          WHERE link.source_node_id = ? AND link.target_node_id = ? AND link.relation = ?`)
-                .bind(actor.id, actor.id, actor.email, deps.now().toISOString(), input.sourceNodeId, input.targetNodeId, input.relation)
+        /**
+         * One appended segment of a table (#40).
+         *
+         * ⚠️ The sequence is computed inside the INSERT, never read out and sent back in. Two appends
+         * that arrive together would otherwise both read the same `MAX(sequence)` and the second would
+         * lose to `UNIQUE (node_id, sequence)` — the very loss the ticket forbids.
+         *
+         * ⚠️ `current_version_id` only ever moves forward. It names the newest segment, and indexing
+         * keys off it; letting a slower append pull it back would leave the index describing a table
+         * that is missing its last rows.
+         */
+        async appendTableVersion(input) {
+            const version = input.version;
+            const stored = async () => await deps.db
+                .prepare(`SELECT id, node_id, sequence, content_key, media_type, content_hash,
+            size, created_by, created_at FROM knowledge_versions WHERE id = ?`)
+                .bind(version.id)
                 .first();
-            return row ? mapLink(row) : null;
-        },
-        async insertLink(input) {
-            const link = input.link;
             try {
                 await deps.db.batch([
                     deps.db
-                        .prepare(`INSERT INTO knowledge_links (
-              id, source_node_id, target_node_id, relation, label, created_by, created_at
-            ) VALUES (?, ?, ?, ?, ?, ?, ?)`)
-                        .bind(link.id, link.sourceNodeId, link.targetNodeId, link.relation, link.label, link.createdBy, link.createdAt),
+                        .prepare(`INSERT INTO knowledge_versions (
+              id, node_id, sequence, content_key, media_type, content_hash, size,
+              created_by, created_at
+            ) SELECT ?, ?, COALESCE(MAX(sequence), 0) + 1, ?, ?, ?, ?, ?, ?
+            FROM knowledge_versions WHERE node_id = ?`)
+                        .bind(version.id, version.nodeId, version.contentKey, version.mediaType, version.contentHash, version.size, version.createdBy, version.createdAt, version.nodeId),
+                    deps.db
+                        .prepare(`UPDATE knowledge_nodes
+              SET current_version_id = ?, updated_at = ?
+              WHERE id = ?
+                AND EXISTS (SELECT 1 FROM knowledge_versions WHERE id = ?)
+                AND (
+                  current_version_id IS NULL
+                  OR COALESCE((
+                    SELECT sequence FROM knowledge_versions
+                    WHERE id = knowledge_nodes.current_version_id
+                  ), 0) < (SELECT sequence FROM knowledge_versions WHERE id = ?)
+                )`)
+                        .bind(version.id, version.createdAt, version.nodeId, version.id, version.id),
                     deps.db
                         .prepare(`INSERT INTO idempotency_keys (
               actor_id, operation, idempotency_key, resource_id, created_at
-            ) VALUES (?, 'knowledge.link', ?, ?, ?)`)
-                        .bind(input.actorId, input.idempotencyKey, link.id, link.createdAt),
+            ) SELECT ?, 'knowledge.append', ?, ?, ?
+            WHERE EXISTS (SELECT 1 FROM knowledge_versions WHERE id = ?)`)
+                        .bind(input.actorId, input.idempotencyKey, version.id, version.createdAt, version.id),
+                    deps.db
+                        .prepare(`INSERT INTO knowledge_index_state (
+              version_id, status, attempt_count, last_error, updated_at
+            ) SELECT ?, 'pending', 0, NULL, ?
+            WHERE EXISTS (SELECT 1 FROM knowledge_versions WHERE id = ?)`)
+                        .bind(version.id, version.createdAt, version.id),
                     deps.db
                         .prepare(`INSERT INTO audit_events (
               id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
-            ) VALUES (?, ?, 'knowledge.link', 'knowledge', ?, ?, ?)`)
-                        .bind(input.auditId, input.actorId, link.sourceNodeId, JSON.stringify({
-                        linkId: link.id,
-                        targetNodeId: link.targetNodeId,
-                        relation: link.relation,
-                    }), link.createdAt),
+            ) SELECT ?, ?, 'knowledge.append', 'knowledge', ?, json_object(
+              'versionId', ?, 'size', ?
+            ), ?
+            WHERE EXISTS (SELECT 1 FROM knowledge_versions WHERE id = ?)`)
+                        .bind(input.auditId, input.actorId, version.nodeId, version.id, version.size, version.createdAt, version.id),
                 ]);
-                return link;
             }
             catch (error) {
+                // The same key twice at the same moment: the first write owns the row, and this call
+                // answers with it rather than with a failure the caller cannot act on.
                 const replayed = await deps.db
                     .prepare(`SELECT resource_id FROM idempotency_keys
-            WHERE actor_id = ? AND operation = 'knowledge.link' AND idempotency_key = ?`)
+            WHERE actor_id = ? AND operation = 'knowledge.append' AND idempotency_key = ?`)
                     .bind(input.actorId, input.idempotencyKey)
                     .first();
-                const row = await deps.db
-                    .prepare(`SELECT id, source_node_id, target_node_id, relation, label,
-            created_by, created_at FROM knowledge_links
-            WHERE id = ? OR (source_node_id = ? AND target_node_id = ? AND relation = ?)`)
-                    .bind(replayed?.resource_id ?? link.id, link.sourceNodeId, link.targetNodeId, link.relation)
-                    .first();
+                const row = replayed
+                    ? await deps.db
+                        .prepare(`SELECT id, node_id, sequence, content_key, media_type, content_hash,
+                size, created_by, created_at FROM knowledge_versions WHERE id = ?`)
+                        .bind(replayed.resource_id)
+                        .first()
+                    : null;
                 if (row)
-                    return mapLink(row);
+                    return mapVersion(row);
                 throw error;
             }
+            const row = await stored();
+            if (!row)
+                throw new Error("Knowledge table append did not store a version");
+            return mapVersion(row);
         },
-        async deleteLink(input) {
-            const existing = await deps.db
-                .prepare("SELECT id FROM knowledge_links WHERE id = ? AND source_node_id = ?")
-                .bind(input.linkId, input.sourceNodeId)
+        async listGrants(resourceId) {
+            const result = await deps.db
+                .prepare(`SELECT ${grantColumns} FROM tree_grants
+          WHERE node_id = ?
+          ORDER BY principal_type, principal_id, verb`)
+                .bind(resourceId)
+                .all();
+            return (result.results ?? []).map(mapGrant);
+        },
+        // ⚠️ `UNION`, never `UNION ALL`: a ring in `parent_id` must end the recursion rather than the
+        // database, the same reason every other walk of this tree gives.
+        async organizationExecuteReaches(nodeId, exceptGrantId) {
+            const row = await deps.db
+                .prepare(`WITH RECURSIVE ancestors(id, parent_id) AS (
+            SELECT id, parent_id FROM knowledge_nodes WHERE id = ?
+            UNION
+            SELECT parent.id, parent.parent_id
+            FROM knowledge_nodes parent
+            JOIN ancestors child ON child.parent_id = parent.id
+          )
+          SELECT 1 AS reaches
+          FROM tree_grants grant_row
+          JOIN ancestors ON ancestors.id = grant_row.node_id
+          WHERE grant_row.id <> ?
+            AND grant_row.principal_type = 'organization'
+            AND grant_row.verb = 'execute'
+            AND (grant_row.expires_at IS NULL OR grant_row.expires_at > ?)
+          LIMIT 1`)
+                .bind(nodeId, exceptGrantId, deps.now().toISOString())
                 .first();
-            const deleted = existing !== null;
+            return row?.reaches === 1;
+        },
+        async listLinksVisible(actor, nodeId) {
+            const result = await deps.db
+                .prepare(`${visibleCte}
+          SELECT ${linkColumns}
+          FROM knowledge_links link
+          JOIN allowed source_access ON source_access.id = link.source_node_id
+          JOIN allowed target_access ON target_access.id = link.target_node_id
+          WHERE link.source_node_id = ? OR link.target_node_id = ?
+          ORDER BY link.created_at, link.id`)
+                .bind(...readBindings(actor), nodeId, nodeId)
+                .all();
+            return (result.results ?? []).map(mapLink);
+        },
+        /**
+         * The titles of the nodes among these that this actor may see (#41).
+         *
+         * ⚠️ The same `allowed` walk as every other read, joined rather than filtered afterwards, and
+         * archived nodes are out. An unreachable or deleted target contributes no row at all — no
+         * placeholder, no id echoed back — because a row is already the statement "something is here".
+         */
+        async resolveVisibleTitles(actor, nodeIds) {
+            const uniqueIds = [...new Set(nodeIds)].slice(0, 200);
+            if (uniqueIds.length === 0)
+                return [];
+            const rows = [];
+            for (let offset = 0; offset < uniqueIds.length; offset += 96) {
+                const ids = uniqueIds.slice(offset, offset + 96);
+                const placeholders = ids.map(() => "?").join(", ");
+                const result = await deps.db
+                    .prepare(`${visibleCte}
+            SELECT n.id, n.title
+            FROM knowledge_nodes n
+            JOIN allowed ON allowed.id = n.id
+            WHERE n.id IN (${placeholders}) AND n.archived_at IS NULL`)
+                    .bind(...readBindings(actor), ...ids)
+                    .all();
+                rows.push(...(result.results ?? []));
+            }
+            return rows.map((row) => ({ nodeId: row.id, title: row.title }));
+        },
+        /**
+         * The `text` links of one document, replaced wholesale by what the saved text says (#41).
+         *
+         * ⚠️ `origin = 'text'` in the delete, and nowhere else. Links made in the removed dialog are
+         * `manual`; saving a document must not take away a relationship somebody entered before the
+         * text became the place to write one.
+         *
+         * The whole set is written in one batch, so a save never leaves the graph half-rewritten. There
+         * is no idempotency row: the operation is a replacement, and replaying it writes the same set.
+         */
+        async replaceTextLinks(input) {
             await deps.db.batch([
                 deps.db
-                    .prepare("DELETE FROM knowledge_links WHERE id = ? AND source_node_id = ?")
-                    .bind(input.linkId, input.sourceNodeId),
-                deps.db
-                    .prepare(`INSERT INTO idempotency_keys (
-            actor_id, operation, idempotency_key, resource_id, created_at
-          ) VALUES (?, 'knowledge.unlink', ?, ?, ?)`)
-                    .bind(input.actorId, input.idempotencyKey, `${deleted ? "1" : "0"}:${input.linkId}`, input.occurredAt),
+                    .prepare("DELETE FROM knowledge_links WHERE source_node_id = ? AND origin = 'text'")
+                    .bind(input.sourceNodeId),
+                ...input.links.map((link) => deps.db
+                    .prepare(`INSERT INTO knowledge_links (
+              id, source_node_id, target_node_id, relation, origin, label, created_by, created_at
+            ) VALUES (?, ?, ?, 'references', 'text', NULL, ?, ?)
+            ON CONFLICT (source_node_id, target_node_id, relation) DO NOTHING`)
+                    .bind(link.id, input.sourceNodeId, link.targetNodeId, input.actorId, input.occurredAt)),
                 deps.db
                     .prepare(`INSERT INTO audit_events (
             id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
-          ) VALUES (?, ?, 'knowledge.unlink', 'knowledge', ?, ?, ?)`)
-                    .bind(input.auditId, input.actorId, input.sourceNodeId, JSON.stringify({ linkId: input.linkId, deleted }), input.occurredAt),
+          ) VALUES (?, ?, 'knowledge.link', 'knowledge', ?, ?, ?)`)
+                    .bind(input.auditId, input.actorId, input.sourceNodeId, JSON.stringify({ targetNodeIds: input.links.map((link) => link.targetNodeId) }), input.occurredAt),
             ]);
-            return deleted;
         },
         async graphVisible(actor, input) {
             const nodeResult = await deps.db
@@ -555,7 +594,7 @@ export function createKnowledgeRepository(deps) {
           WHERE n.archived_at IS NULL
           ORDER BY lower(n.title), n.id
           LIMIT ?`)
-                .bind(actor.id, actor.id, actor.email, deps.now().toISOString(), input.limit)
+                .bind(...readBindings(actor), input.limit)
                 .all();
             const nodes = (nodeResult.results ?? []).map(mapNode);
             if (nodes.length === 0)
@@ -568,13 +607,12 @@ export function createKnowledgeRepository(deps) {
           ORDER BY lower(n.title), n.id
           LIMIT ?
         )
-          SELECT link.id, link.source_node_id, link.target_node_id, link.relation, link.label,
-            link.created_by, link.created_at
+          SELECT ${linkColumns}
           FROM knowledge_links link
           JOIN graph_nodes source_node ON source_node.id = link.source_node_id
           JOIN graph_nodes target_node ON target_node.id = link.target_node_id
           ORDER BY link.created_at, link.id`)
-                .bind(actor.id, actor.id, actor.email, deps.now().toISOString(), input.limit)
+                .bind(...readBindings(actor), input.limit)
                 .all();
             return { nodes, links: (linkResult.results ?? []).map(mapLink) };
         },
@@ -589,32 +627,31 @@ export function createKnowledgeRepository(deps) {
             try {
                 await deps.db.batch([
                     deps.db
-                        .prepare(`INSERT INTO resource_grants (
-              id, resource_type, resource_id, principal_type, principal_id, role,
+                        // The verb is part of the key, so re-granting the same verb only refreshes its expiry
+                        // and never turns one verb into another.
+                        .prepare(`INSERT INTO tree_grants (
+              id, node_id, principal_type, principal_id, verb,
               expires_at, created_by, created_at
-            ) VALUES (?, 'knowledge', ?, ?, ?, ?, ?, ?, ?)
-            ON CONFLICT (resource_type, resource_id, principal_type, principal_id)
-            DO UPDATE SET role = excluded.role, expires_at = excluded.expires_at`)
-                        .bind(grant.id, grant.resourceId, principalType, principalId, grant.role, grant.expiresAt, grant.createdBy, grant.createdAt),
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT (node_id, principal_type, principal_id, verb)
+            DO UPDATE SET expires_at = excluded.expires_at`)
+                        .bind(grant.id, grant.resourceId, principalType, principalId, grant.verb, grant.expiresAt, grant.createdBy, grant.createdAt),
                     deps.db
                         .prepare(`INSERT INTO idempotency_keys (
               actor_id, operation, idempotency_key, resource_id, created_at
-            ) SELECT ?, 'knowledge.share', ?, id, ? FROM resource_grants
-              WHERE resource_type = 'knowledge' AND resource_id = ?
-                AND principal_type = ? AND principal_id = ?`)
-                        .bind(input.actorId, input.idempotencyKey, grant.createdAt, grant.resourceId, principalType, principalId),
+            ) SELECT ?, 'knowledge.share', ?, id, ? FROM tree_grants
+              WHERE node_id = ? AND principal_type = ? AND principal_id = ? AND verb = ?`)
+                        .bind(input.actorId, input.idempotencyKey, grant.createdAt, grant.resourceId, principalType, principalId, grant.verb),
                     deps.db
                         .prepare(`INSERT INTO audit_events (
               id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
             ) VALUES (?, ?, 'knowledge.share', 'knowledge', ?, ?, ?)`)
-                        .bind(input.auditId, input.actorId, grant.resourceId, JSON.stringify({ principalType, role: grant.role }), grant.createdAt),
+                        .bind(input.auditId, input.actorId, grant.resourceId, JSON.stringify({ principalType, verb: grant.verb }), grant.createdAt),
                 ]);
                 const stored = await deps.db
-                    .prepare(`SELECT id, resource_id, principal_type, principal_id, role, expires_at,
-            created_by, created_at FROM resource_grants
-            WHERE resource_type = 'knowledge' AND resource_id = ?
-              AND principal_type = ? AND principal_id = ?`)
-                    .bind(grant.resourceId, principalType, principalId)
+                    .prepare(`SELECT ${grantColumns} FROM tree_grants
+            WHERE node_id = ? AND principal_type = ? AND principal_id = ? AND verb = ?`)
+                    .bind(grant.resourceId, principalType, principalId, grant.verb)
                     .first();
                 if (!stored)
                     throw new Error("Knowledge grant disappeared after upsert");
@@ -628,8 +665,7 @@ export function createKnowledgeRepository(deps) {
                     .first();
                 if (replayed) {
                     const row = await deps.db
-                        .prepare(`SELECT id, resource_id, principal_type, principal_id, role, expires_at,
-              created_by, created_at FROM resource_grants WHERE id = ?`)
+                        .prepare(`SELECT ${grantColumns} FROM tree_grants WHERE id = ?`)
                         .bind(replayed.resource_id)
                         .first();
                     if (row)
@@ -646,13 +682,11 @@ export function createKnowledgeRepository(deps) {
               actor_id, operation, idempotency_key, resource_id, created_at
             ) SELECT ?, 'knowledge.revoke', ?,
               (CASE WHEN EXISTS (
-                SELECT 1 FROM resource_grants
-                WHERE id = ? AND resource_type = 'knowledge' AND resource_id = ?
+                SELECT 1 FROM tree_grants WHERE id = ? AND node_id = ?
               ) THEN '1:' ELSE '0:' END) || ?, ?`)
                         .bind(input.actorId, input.idempotencyKey, input.grantId, input.resourceId, input.grantId, input.occurredAt),
                     deps.db
-                        .prepare(`DELETE FROM resource_grants
-              WHERE id = ? AND resource_type = 'knowledge' AND resource_id = ?`)
+                        .prepare("DELETE FROM tree_grants WHERE id = ? AND node_id = ?")
                         .bind(input.grantId, input.resourceId),
                     deps.db
                         .prepare(`INSERT INTO audit_events (
@@ -693,7 +727,7 @@ export function createKnowledgeRepository(deps) {
             AND n.archived_at IS NULL
           ORDER BY rank, n.updated_at DESC
           LIMIT ?`)
-                .bind(actor.id, actor.id, actor.email, deps.now().toISOString(), query, input.limit)
+                .bind(...readBindings(actor), query, input.limit)
                 .all();
             return (result.results ?? []).map((row) => ({
                 nodeId: row.node_id,
@@ -724,7 +758,7 @@ export function createKnowledgeRepository(deps) {
             JOIN knowledge_fts ON knowledge_fts.version_id = v.id
             JOIN allowed ON allowed.id = n.id
             WHERE n.id IN (${placeholders}) AND n.archived_at IS NULL`)
-                    .bind(actor.id, actor.id, actor.email, deps.now().toISOString(), ...ids)
+                    .bind(...readBindings(actor), ...ids)
                     .all();
                 rows.push(...(result.results ?? []));
             }

package/dist/flows/flows.d.ts

@@ -1,4 +1,34 @@
-import type { FlowGraph } from "@anchrd/intel-contract";
+import type { FlowGraph, FlowNode } from "@anchrd/intel-contract";
 import type { CompiledFlow, FlowDeps, FlowService } from "./flows.types.js";
+type SubflowNode = Extract<FlowNode, {
+    kind: "subflow";
+}>;
+type KnowledgeStepNode = Extract<FlowNode, {
+    kind: "knowledge";
+}>;
+type ToolStepNode = Extract<FlowNode, {
+    kind: "tool";
+}>;
+/**
+ * One place reads a graph for each kind of step it contains, and everything else is derived from
+ * these three. The publish-time rule, the freeze, the sidebar, the relation graph, the requirements
+ * list and the repository's cycle walk all ask about the same nodes; a second `kind === "…"` walk
+ * beside them would drift quietly, because both would keep returning something plausible.
+ */
+export declare function subflowNodes(graph: FlowGraph): SubflowNode[];
+export declare function knowledgeNodes(graph: FlowGraph): KnowledgeStepNode[];
+export declare function toolNodes(graph: FlowGraph): ToolStepNode[];
+export declare function calleeIds(graph: FlowGraph): string[];
+/**
+ * The Knowledge documents a graph names and the tools it calls, flattened and without repetition.
+ * The requirements list, the publish-time check and the run's first tool check read this one answer,
+ * so they cannot disagree about what a flow touches. A caller that needs to know *which step* names
+ * a document reads the node lists above instead — the relation graph draws exactly that edge.
+ */
+export declare function graphReferences(graph: FlowGraph): {
+    knowledge: string[];
+    tools: string[];
+};
 export declare function compileFlow(graph: FlowGraph): CompiledFlow;
 export declare function createFlows(deps: FlowDeps): FlowService;
+export {};