@anchrd/intel-api 0.6.6 → 0.7.0

package/dist/adapters/db/db.js

@@ -1,4 +1,6 @@
-import { nodeVerbBindings, nodeVerbQuery, subtreeBindings, subtreeCte } from "./db-grants.js";
+import { descendantsCte, nodeVerbBindings, nodeVerbQuery, subtreeBindings, subtreeCte, } from "./db-grants.js";
+const versionColumns = `id, node_id, sequence, content_key, media_type, content_hash,
+  size, segment, created_by, created_at`;
 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,
@@ -28,6 +30,7 @@ function mapVersion(row) {
         mediaType: row.media_type,
         contentHash: row.content_hash,
         size: row.size,
+        segment: row.segment,
         createdBy: row.created_by,
         createdAt: row.created_at,
     };
@@ -45,7 +48,7 @@ function mapGrant(row) {
             principal = { type: "organization" };
             break;
         default:
-            throw new Error("Unsupported knowledge grant principal type");
+            throw new Error("Unsupported node grant principal type");
     }
     return {
         id: row.id,
@@ -76,11 +79,24 @@ function toFtsQuery(query) {
         .map((token) => `"${token.replaceAll('"', '""')}"`)
         .join(" AND ");
 }
-export function createKnowledgeRepository(deps) {
+export function createNodeRepository(deps) {
     // 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());
+    /**
+     * The optional folder cut a search carries (#126), in the three places one statement needs it:
+     * the extra CTE, the extra join, and the one binding between the actor's and the query's. All
+     * three are absent together when there is no scope, so an unscoped search runs the exact
+     * statement it ran before.
+     *
+     * ⚠️ The join is added *beside* `allowed`, never instead of it. `descendants` is seeded from a
+     * caller-supplied id and knows nothing about grants; on its own it would answer "everything under
+     * this folder" to anyone who names the folder.
+     */
+    const scopeCte = (scopeId) => scopeId === undefined ? "" : `,\n${descendantsCte}`;
+    const scopeJoin = (scopeId) => scopeId === undefined ? "" : "\n          JOIN descendants ON descendants.id = n.id";
+    const scopeBindings = (scopeId) => (scopeId === undefined ? [] : [scopeId]);
     /**
      * 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.
@@ -94,19 +110,94 @@ export function createKnowledgeRepository(deps) {
       -- level down. A second rule written here would drift from the one above it, and the drift
       -- would show as a chevron that opens onto nothing.
       EXISTS (
-        SELECT 1 FROM knowledge_nodes child
+        SELECT 1 FROM nodes child
         JOIN allowed AS allowed_child ON allowed_child.id = child.id
         WHERE child.parent_id = n.id AND child.archived_at IS NULL
       ) AS has_children
-    FROM knowledge_nodes n
+    FROM 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 ?" : ""}`;
+    /**
+     * Everything archived that this actor may see, wherever it sits (#113).
+     *
+     * ⚠️ No `parent_id` at all, and that is the point rather than an omission: somebody looking for
+     * what they archived does not know which folder it was in. The visibility predicate is the same
+     * `allowed` set every other read uses, so the archive shows no more than the tree would have.
+     *
+     * `has_children` is answered as 0 without asking: an archived row is not expandable — its
+     * children are reached by restoring it, not by opening it here.
+     */
+    const archivedEverywhere = `${visibleCte}
+    SELECT ${nodeColumns}, 0 AS has_children
+    FROM nodes n
+    JOIN allowed ON allowed.id = n.id
+    WHERE n.archived_at IS NOT NULL
+    ORDER BY n.archived_at DESC, lower(n.title), n.id`;
+    /**
+     * The agents this actor may see, over the whole tree or under one folder (#139).
+     *
+     * ⚠️ The same `allowed` set every other read joins against, not a second predicate written for
+     * agents. An agent is a node, and the moment its list answers from its own rule it can answer
+     * differently from `list` about the very same row.
+     *
+     * Three scopes, matching the flow list: no clause at all for the whole tree, `IS NULL` for the
+     * root level, and one folder by ID.
+     */
+    const visibleAgents = (clause, includeArchived) => `${visibleCte}
+    SELECT ${nodeColumns}
+    FROM nodes n
+    JOIN allowed ON allowed.id = n.id
+    WHERE n.kind = 'agent' ${includeArchived ? "" : "AND n.archived_at IS NULL"} ${clause}
+    ORDER BY lower(n.title), n.id`;
+    const agentScopeOf = (parentId) => parentId === undefined
+        ? { clause: "", bindings: [] }
+        : parentId === null
+            ? { clause: "AND n.parent_id IS NULL", bindings: [] }
+            : { clause: "AND n.parent_id = ?", bindings: [parentId] };
     return {
+        async listVisibleAgents(actor, input) {
+            const scope = agentScopeOf(input.parentId);
+            const result = await deps.db
+                .prepare(visibleAgents(scope.clause, input.includeArchived === true))
+                .bind(...readBindings(actor), ...scope.bindings)
+                .all();
+            return (result.results ?? []).map(mapNode);
+        },
+        /**
+         * The R2 keys of the current definitions of every agent in this folder's subtree that this
+         * actor may see — the input to the share warning (#139, ADR-0005 §2).
+         *
+         * ⚠️ Keys, never bodies and never titles. Whether a referenced node may be NAMED to whoever is
+         * sharing is the tree's question and is asked afterwards through `getVisible`, exactly as the
+         * flow side does it. Answering it here would be the second rule that #17 and #19 got wrong.
+         *
+         * ⚠️ Agents this actor may not see contribute nothing, not even a count. Their references would
+         * otherwise be attributed to a folder this actor administers, which discloses that the agent is
+         * there at all.
+         */
+        async listVisibleAgentDefinitionKeys(actor, folderId) {
+            const result = await deps.db
+                .prepare(`${visibleCte},
+          scope(id) AS (
+            SELECT id FROM nodes WHERE id = ?
+            UNION
+            SELECT child.id FROM nodes child JOIN scope ON child.parent_id = scope.id
+          )
+          SELECT version.content_key AS content_key
+          FROM nodes n
+          JOIN allowed ON allowed.id = n.id
+          JOIN node_versions version ON version.id = n.current_version_id
+          WHERE n.kind = 'agent' AND n.archived_at IS NULL AND n.id IN (SELECT id FROM scope)
+          ORDER BY n.id`)
+                .bind(...readBindings(actor), folderId)
+                .all();
+            return (result.results ?? []).map((row) => row.content_key);
+        },
         async listVisible(actor, input) {
             const result = await deps.db
-                .prepare(visibleChildren(false))
-                .bind(...readBindings(actor), input.parentId, input.includeArchived ? 1 : 0)
+                .prepare(input.archivedOnly ? archivedEverywhere : visibleChildren(false))
+                .bind(...readBindings(actor), ...(input.archivedOnly ? [] : [input.parentId, input.includeArchived ? 1 : 0]))
                 .all();
             const rows = result.results ?? [];
             return {
@@ -126,13 +217,168 @@ export function createKnowledgeRepository(deps) {
             const row = await deps.db
                 .prepare(`${visibleCte}
           SELECT ${nodeColumns}
-          FROM knowledge_nodes n
+          FROM nodes n
           JOIN allowed ON allowed.id = n.id
           WHERE n.id = ?`)
                 .bind(...readBindings(actor), nodeId)
                 .first();
             return row ? mapNode(row) : null;
         },
+        /**
+         * The readable subtree as one statement (#136): the `allowed` walk says what the actor may
+         * read, and `walk` says what hangs together under the chosen root. Both joins apply at every
+         * step, so the walk neither descends into an archived node nor through an unreadable one — a
+         * child the actor may read under a folder they may not stays out, because the bundle would have
+         * no path to file it under.
+         *
+         * ⚠️ `UNION`, never `UNION ALL`, for the reason `nodeVerbQuery` gives: a cycle in `parent_id`
+         * can reach the table and this walks downwards into it.
+         */
+        async listVisibleSubtree(actor, rootId) {
+            const seed = rootId === null
+                ? // "Everything this actor may read": the top of every readable region, not only the top
+                    // of the tree. A reader who holds a grant on one nested folder has that folder as the
+                    // top of what they see, and their whole-installation export starts there.
+                    "(seed.parent_id IS NULL OR seed.parent_id NOT IN (SELECT id FROM allowed))"
+                : // The root node itself is the seed; whether it is a folder is the service's question.
+                    "seed.id = ?";
+            const result = await deps.db
+                .prepare(`${visibleCte},
+          walk(id) AS (
+            SELECT seed.id FROM nodes seed
+            JOIN allowed ON allowed.id = seed.id
+            WHERE ${seed} AND seed.archived_at IS NULL
+            UNION
+            SELECT child.id FROM nodes child
+            JOIN walk ON child.parent_id = walk.id
+            JOIN allowed AS allowed_child ON allowed_child.id = child.id
+            WHERE child.archived_at IS NULL
+          )
+          SELECT ${nodeColumns},
+            version.id AS version_id, version.media_type, version.content_key
+          FROM nodes n
+          JOIN walk ON walk.id = n.id
+          LEFT JOIN node_versions version ON version.id = n.current_version_id`)
+                .bind(...readBindings(actor), ...(rootId === null ? [] : [rootId]))
+                .all();
+            return (result.results ?? []).map((row) => ({
+                node: mapNode(row),
+                version: row.version_id === null || row.media_type === null || row.content_key === null
+                    ? null
+                    : { id: row.version_id, mediaType: row.media_type, contentKey: row.content_key },
+            }));
+        },
+        /**
+         * One bundle import as one transaction (#137). Every table takes its rows from a single JSON
+         * parameter through `json_each`, so the statement count stays constant however large the
+         * bundle is — the same reason `idList` exists in db-flows — and `db.batch` makes the whole
+         * import land or refuse as one.
+         *
+         * ⚠️ `nodes` arrive parents before children: `parent_id REFERENCES nodes(id)` is checked as
+         * each row lands, and a child before its parent would abort the batch that is otherwise valid.
+         * The service owns that order; this only writes what it is handed.
+         *
+         * `context_policy` is the dead column migration 0009 explains; 'relevant' is the fixed value
+         * `insertNode` writes for the same reason.
+         */
+        async importTree(input) {
+            const statements = [
+                deps.db
+                    .prepare(`INSERT INTO nodes (
+            id, parent_id, kind, title, description, context_policy, owner_id,
+            current_version_id, created_at, updated_at, archived_at
+          ) SELECT
+            json_extract(value, '$.id'), json_extract(value, '$.parentId'),
+            json_extract(value, '$.kind'), json_extract(value, '$.title'),
+            json_extract(value, '$.description'), 'relevant',
+            json_extract(value, '$.ownerId'), json_extract(value, '$.currentVersionId'),
+            json_extract(value, '$.createdAt'), json_extract(value, '$.updatedAt'), NULL
+          FROM json_each(?)`)
+                    .bind(JSON.stringify(input.nodes)),
+                deps.db
+                    .prepare(`INSERT INTO node_versions (
+            id, node_id, sequence, content_key, media_type, content_hash, size, segment,
+            created_by, created_at
+          ) SELECT
+            json_extract(value, '$.id'), json_extract(value, '$.nodeId'),
+            json_extract(value, '$.sequence'), json_extract(value, '$.contentKey'),
+            json_extract(value, '$.mediaType'), json_extract(value, '$.contentHash'),
+            json_extract(value, '$.size'), json_extract(value, '$.segment'),
+            json_extract(value, '$.createdBy'), json_extract(value, '$.createdAt')
+          FROM json_each(?)`)
+                    .bind(JSON.stringify(input.versions)),
+                deps.db
+                    .prepare(`INSERT INTO node_links (
+            id, source_node_id, target_node_id, relation, origin, label, created_by, created_at
+          ) SELECT
+            json_extract(value, '$.id'), json_extract(value, '$.sourceNodeId'),
+            json_extract(value, '$.targetNodeId'), 'references', 'text', NULL, ?, ?
+          FROM json_each(?)`)
+                    .bind(input.actorId, input.occurredAt, JSON.stringify(input.links)),
+                deps.db
+                    .prepare(`INSERT INTO flows (
+            id, parent_id, title, description, owner_id, current_version_id,
+            published_version_id, created_at, updated_at, archived_at
+          ) SELECT
+            json_extract(value, '$.id'), json_extract(value, '$.parentId'),
+            json_extract(value, '$.title'), json_extract(value, '$.description'),
+            json_extract(value, '$.ownerId'), json_extract(value, '$.currentVersionId'),
+            json_extract(value, '$.publishedVersionId'), json_extract(value, '$.createdAt'),
+            json_extract(value, '$.updatedAt'), NULL
+          FROM json_each(?)`)
+                    .bind(JSON.stringify(input.flows)),
+                deps.db
+                    .prepare(`INSERT INTO flow_versions (
+            id, flow_id, sequence, graph_json, created_by, created_at
+          ) SELECT
+            json_extract(value, '$.id'), json_extract(value, '$.flowId'),
+            -- json_extract of an object answers with its JSON text, which is exactly what the
+            -- graph_json column stores.
+            json_extract(value, '$.sequence'), json_extract(value, '$.graph'),
+            json_extract(value, '$.createdBy'), json_extract(value, '$.createdAt')
+          FROM json_each(?)`)
+                    .bind(JSON.stringify(input.flowVersions)),
+                // ⚠️ The idempotency row stores the AUDIT id, unlike its siblings that store the resource:
+                // one import creates many resources, and the collective audit event is where the summary a
+                // replay answers with is kept.
+                deps.db
+                    .prepare(`INSERT INTO idempotency_keys (
+            actor_id, operation, idempotency_key, resource_id, created_at
+          ) VALUES (?, 'node.import', ?, ?, ?)`)
+                    .bind(input.actorId, input.idempotencyKey, input.auditId, input.occurredAt),
+                deps.db
+                    .prepare(`INSERT INTO audit_events (
+            id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+          ) VALUES (?, ?, 'node.import', 'node', ?, ?, ?)`)
+                    .bind(input.auditId, input.actorId, input.auditResourceId, JSON.stringify(input.metadata), input.occurredAt),
+            ];
+            try {
+                await deps.db.batch(statements);
+                return "created";
+            }
+            catch (error) {
+                const replayed = await this.findImportReplay(input.actorId, input.idempotencyKey);
+                if (replayed !== null)
+                    return "replayed";
+                throw error;
+            }
+        },
+        async findImportReplay(actorId, idempotencyKey) {
+            const row = await deps.db
+                .prepare(`SELECT audit.metadata_json AS metadata_json
+          FROM idempotency_keys keys
+          JOIN audit_events audit ON audit.id = keys.resource_id
+          WHERE keys.actor_id = ? AND keys.operation = 'node.import'
+            AND keys.idempotency_key = ?`)
+                .bind(actorId, idempotencyKey)
+                .first();
+            if (!row)
+                return null;
+            const parsed = JSON.parse(row.metadata_json);
+            return typeof parsed === "object" && parsed !== null
+                ? parsed
+                : null;
+        },
         async can(actor, nodeId, verb) {
             const row = await deps.db
                 .prepare(nodeVerbQuery)
@@ -151,15 +397,26 @@ export function createKnowledgeRepository(deps) {
         async findIdempotentRevocation(actorId, idempotencyKey) {
             const row = await deps.db
                 .prepare(`SELECT resource_id FROM idempotency_keys
-          WHERE actor_id = ? AND operation = 'knowledge.revoke' AND idempotency_key = ?`)
+          WHERE actor_id = ? AND operation = 'node.revoke' AND idempotency_key = ?`)
                 .bind(actorId, idempotencyKey)
                 .first();
             if (!row)
                 return null;
             return row.resource_id.startsWith("1:");
         },
+        // ⚠️ Its own statement rather than a column on the node read: four of the five kinds can never
+        // have an Application, and the two joins every node read already carries are not going to grow
+        // a third for a question only agents ask (#182).
+        async agentApplicationId(nodeId) {
+            const row = await deps.db
+                .prepare("SELECT application_id FROM agent_applications WHERE node_id = ?")
+                .bind(nodeId)
+                .first();
+            return row?.application_id ?? null;
+        },
         async insertNode(input) {
             const node = input.node;
+            const application = input.application;
             try {
                 await deps.db.batch([
                     deps.db
@@ -167,7 +424,7 @@ export function createKnowledgeRepository(deps) {
                         // without a DEFAULT and D1 will not let it be dropped — migration 0009 carries the
                         // reason. The fixed value is the price; nothing reads it, and the contract no longer
                         // knows the field. When the column goes (anchrd/intel#86), this line goes with it.
-                        .prepare(`INSERT INTO knowledge_nodes (
+                        .prepare(`INSERT INTO nodes (
             id, parent_id, kind, title, description, context_policy, owner_id,
             current_version_id, created_at, updated_at, archived_at
           ) VALUES (?, ?, ?, ?, ?, 'relevant', ?, ?, ?, ?, ?)`)
@@ -175,26 +432,42 @@ export function createKnowledgeRepository(deps) {
                     deps.db
                         .prepare(`INSERT INTO idempotency_keys (
             actor_id, operation, idempotency_key, resource_id, created_at
-          ) VALUES (?, 'knowledge.create', ?, ?, ?)`)
+          ) VALUES (?, 'node.create', ?, ?, ?)`)
                         .bind(input.actorId, input.idempotencyKey, node.id, node.createdAt),
                     deps.db
                         .prepare(`INSERT INTO audit_events (
             id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
-          ) VALUES (?, ?, 'knowledge.create', 'knowledge', ?, ?, ?)`)
-                        .bind(input.auditId, input.actorId, node.id, JSON.stringify({ kind: node.kind, parentId: node.parentId }), node.createdAt),
+          ) VALUES (?, ?, 'node.create', 'node', ?, ?, ?)`)
+                        .bind(input.auditId, input.actorId, node.id, 
+                    // ⚠️ The Application ID is deliberately NOT in this metadata, and the key is not
+                    // within reach of it at all. An audit event is read back by people and by the
+                    // reindexer; what belongs in it is that an agent was created, not the name of the
+                    // principal behind it — the mapping row below is where that is kept, once (D27).
+                    JSON.stringify({ kind: node.kind, parentId: node.parentId }), node.createdAt),
+                    // Last in the batch, and in the SAME batch: D1 runs a batch as one transaction, so the
+                    // mapping cannot end up without its node or the node without its mapping. An agent whose
+                    // principal is recorded nowhere is one that archiving would quietly fail to switch off.
+                    ...(application
+                        ? [
+                            deps.db
+                                .prepare(`INSERT INTO agent_applications (node_id, application_id, created_at)
+                     VALUES (?, ?, ?)`)
+                                .bind(node.id, application.id, node.createdAt),
+                        ]
+                        : []),
                 ]);
             }
             catch (error) {
                 const replayedKey = await deps.db
                     .prepare(`SELECT resource_id FROM idempotency_keys
-            WHERE actor_id = ? AND operation = 'knowledge.create' AND idempotency_key = ?`)
+            WHERE actor_id = ? AND operation = 'node.create' AND idempotency_key = ?`)
                     .bind(input.actorId, input.idempotencyKey)
                     .first();
                 if (replayedKey) {
                     const replayed = await deps.db
                         .prepare(`${visibleCte}
               SELECT ${nodeColumns}
-              FROM knowledge_nodes n
+              FROM nodes n
               JOIN allowed ON allowed.id = n.id
               WHERE n.id = ?`)
                         .bind(...readBindings({ id: input.actorId, email: "" }), replayedKey.resource_id)
@@ -208,33 +481,38 @@ export function createKnowledgeRepository(deps) {
         },
         async getVersion(versionId) {
             const row = 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 = ?`)
+                .prepare(`SELECT ${versionColumns} FROM node_versions WHERE id = ?`)
                 .bind(versionId)
                 .first();
             return row ? mapVersion(row) : null;
         },
+        // From the newest snapshot on (#135). `COALESCE(..., 0)` keeps a table from before snapshots
+        // readable in full: without any snapshot row every segment still counts.
         async listVersionContentKeys(nodeId) {
             const result = await deps.db
-                .prepare(`SELECT content_key FROM knowledge_versions
-          WHERE node_id = ? ORDER BY sequence`)
-                .bind(nodeId)
+                .prepare(`SELECT content_key FROM node_versions
+          WHERE node_id = ? AND sequence >= COALESCE((
+            SELECT MAX(sequence) FROM node_versions
+            WHERE node_id = ? AND segment = 'snapshot'
+          ), 0)
+          ORDER BY sequence`)
+                .bind(nodeId, nodeId)
                 .all();
             return (result.results ?? []).map((row) => row.content_key);
         },
-        async firstVersionContentKey(nodeId) {
+        async tableHeaderContentKey(nodeId) {
             const row = await deps.db
-                .prepare(`SELECT content_key FROM knowledge_versions
-          WHERE node_id = ? ORDER BY sequence LIMIT 1`)
+                .prepare(`SELECT content_key FROM node_versions
+          WHERE node_id = ? AND segment = 'snapshot'
+          ORDER BY sequence DESC 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,
-          size, created_by, created_at
-          FROM knowledge_versions
+                .prepare(`SELECT ${versionColumns}
+          FROM node_versions
           WHERE node_id = ?
           ORDER BY sequence DESC`)
                 .bind(nodeId)
@@ -247,13 +525,13 @@ export function createKnowledgeRepository(deps) {
                 await deps.db.batch([
                     deps.db
                         .prepare(`WITH RECURSIVE descendants(id) AS (
-              SELECT id FROM knowledge_nodes WHERE id = ?
+              SELECT id FROM nodes WHERE id = ?
               UNION ALL
               SELECT child.id
-              FROM knowledge_nodes child
+              FROM nodes child
               JOIN descendants parent ON child.parent_id = parent.id
             )
-            UPDATE knowledge_nodes
+            UPDATE nodes
             SET parent_id = ?, title = ?, description = ?, updated_at = ?
             WHERE id = ? AND updated_at = ?
               AND (? IS NULL OR ? NOT IN (SELECT id FROM descendants))`)
@@ -261,9 +539,9 @@ export function createKnowledgeRepository(deps) {
                     deps.db
                         .prepare(`INSERT INTO idempotency_keys (
               actor_id, operation, idempotency_key, resource_id, created_at
-            ) SELECT ?, 'knowledge.update', ?, ?, ?
+            ) SELECT ?, 'node.update', ?, ?, ?
             WHERE EXISTS (
-              SELECT 1 FROM knowledge_nodes
+              SELECT 1 FROM nodes
               WHERE id = ? AND parent_id IS ? AND title = ? AND description IS ?
                 AND updated_at = ?
             )`)
@@ -271,10 +549,10 @@ export function createKnowledgeRepository(deps) {
                     deps.db
                         .prepare(`INSERT INTO audit_events (
               id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
-            ) SELECT ?, ?, 'knowledge.update', 'knowledge', ?, ?, ?
+            ) SELECT ?, ?, 'node.update', 'node', ?, ?, ?
             WHERE EXISTS (
               SELECT 1 FROM idempotency_keys
-              WHERE actor_id = ? AND operation = 'knowledge.update'
+              WHERE actor_id = ? AND operation = 'node.update'
                 AND idempotency_key = ? AND resource_id = ?
             )`)
                         .bind(input.auditId, input.actorId, node.id, JSON.stringify({
@@ -286,7 +564,7 @@ export function createKnowledgeRepository(deps) {
             catch (error) {
                 const replayed = await deps.db
                     .prepare(`SELECT resource_id FROM idempotency_keys
-            WHERE actor_id = ? AND operation = 'knowledge.update' AND idempotency_key = ?`)
+            WHERE actor_id = ? AND operation = 'node.update' AND idempotency_key = ?`)
                     .bind(input.actorId, input.idempotencyKey)
                     .first();
                 if (!replayed)
@@ -294,12 +572,12 @@ export function createKnowledgeRepository(deps) {
             }
             const replayed = await deps.db
                 .prepare(`SELECT resource_id FROM idempotency_keys
-          WHERE actor_id = ? AND operation = 'knowledge.update' AND idempotency_key = ?`)
+          WHERE actor_id = ? AND operation = 'node.update' AND idempotency_key = ?`)
                 .bind(input.actorId, input.idempotencyKey)
                 .first();
             if (replayed) {
                 const row = await deps.db
-                    .prepare(`SELECT ${nodeColumns} FROM knowledge_nodes n WHERE n.id = ?`)
+                    .prepare(`SELECT ${nodeColumns} FROM nodes n WHERE n.id = ?`)
                     .bind(replayed.resource_id)
                     .first();
                 if (row)
@@ -308,10 +586,10 @@ export function createKnowledgeRepository(deps) {
             if (node.parentId !== null) {
                 const cycle = await deps.db
                     .prepare(`WITH RECURSIVE descendants(id) AS (
-            SELECT id FROM knowledge_nodes WHERE id = ?
+            SELECT id FROM nodes WHERE id = ?
             UNION ALL
             SELECT child.id
-            FROM knowledge_nodes child
+            FROM nodes child
             JOIN descendants parent ON child.parent_id = parent.id
           )
           SELECT 1 AS found FROM descendants WHERE id = ? LIMIT 1`)
@@ -326,26 +604,26 @@ export function createKnowledgeRepository(deps) {
             try {
                 await deps.db.batch([
                     deps.db
-                        .prepare(`UPDATE knowledge_nodes
+                        .prepare(`UPDATE nodes
               SET archived_at = ?, updated_at = ?
               WHERE id = ? AND updated_at = ?`)
                         .bind(input.archivedAt, input.updatedAt, input.nodeId, input.baseUpdatedAt),
                     deps.db
                         .prepare(`INSERT INTO idempotency_keys (
               actor_id, operation, idempotency_key, resource_id, created_at
-            ) SELECT ?, 'knowledge.archive', ?, ?, ?
+            ) SELECT ?, 'node.archive', ?, ?, ?
             WHERE EXISTS (
-              SELECT 1 FROM knowledge_nodes
+              SELECT 1 FROM nodes
               WHERE id = ? AND archived_at IS ? AND updated_at = ?
             )`)
                         .bind(input.actorId, input.idempotencyKey, input.nodeId, input.updatedAt, input.nodeId, input.archivedAt, input.updatedAt),
                     deps.db
                         .prepare(`INSERT INTO audit_events (
               id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
-            ) SELECT ?, ?, 'knowledge.archive', 'knowledge', ?, ?, ?
+            ) SELECT ?, ?, 'node.archive', 'node', ?, ?, ?
             WHERE EXISTS (
               SELECT 1 FROM idempotency_keys
-              WHERE actor_id = ? AND operation = 'knowledge.archive'
+              WHERE actor_id = ? AND operation = 'node.archive'
                 AND idempotency_key = ? AND resource_id = ?
             )`)
                         .bind(input.auditId, input.actorId, input.nodeId, JSON.stringify({ archived: input.archivedAt !== null }), input.updatedAt, input.actorId, input.idempotencyKey, input.nodeId),
@@ -354,7 +632,7 @@ export function createKnowledgeRepository(deps) {
             catch (error) {
                 const replayed = await deps.db
                     .prepare(`SELECT resource_id FROM idempotency_keys
-            WHERE actor_id = ? AND operation = 'knowledge.archive' AND idempotency_key = ?`)
+            WHERE actor_id = ? AND operation = 'node.archive' AND idempotency_key = ?`)
                     .bind(input.actorId, input.idempotencyKey)
                     .first();
                 if (!replayed)
@@ -362,13 +640,13 @@ export function createKnowledgeRepository(deps) {
             }
             const replayed = await deps.db
                 .prepare(`SELECT resource_id FROM idempotency_keys
-          WHERE actor_id = ? AND operation = 'knowledge.archive' AND idempotency_key = ?`)
+          WHERE actor_id = ? AND operation = 'node.archive' AND idempotency_key = ?`)
                 .bind(input.actorId, input.idempotencyKey)
                 .first();
             if (!replayed)
                 return "conflict";
             const row = await deps.db
-                .prepare(`SELECT ${nodeColumns} FROM knowledge_nodes n WHERE n.id = ?`)
+                .prepare(`SELECT ${nodeColumns} FROM nodes n WHERE n.id = ?`)
                 .bind(replayed.resource_id)
                 .first();
             return row ? mapNode(row) : "conflict";
@@ -377,38 +655,39 @@ export function createKnowledgeRepository(deps) {
             const version = input.version;
             await deps.db.batch([
                 deps.db
-                    .prepare(`INSERT INTO knowledge_versions (
-            id, node_id, sequence, content_key, media_type, content_hash, size, created_by, created_at
-          ) SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?
-          FROM knowledge_nodes
+                    .prepare(`INSERT INTO node_versions (
+            id, node_id, sequence, content_key, media_type, content_hash, size, segment,
+            created_by, created_at
+          ) SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
+          FROM nodes
           WHERE id = ? AND current_version_id IS ?`)
-                    .bind(version.id, version.nodeId, version.sequence, version.contentKey, version.mediaType, version.contentHash, version.size, version.createdBy, version.createdAt, version.nodeId, input.baseVersionId),
+                    .bind(version.id, version.nodeId, version.sequence, version.contentKey, version.mediaType, version.contentHash, version.size, version.segment, version.createdBy, version.createdAt, version.nodeId, input.baseVersionId),
                 deps.db
-                    .prepare(`UPDATE knowledge_nodes
+                    .prepare(`UPDATE nodes
             SET current_version_id = ?, updated_at = ?
-            WHERE id = ? AND EXISTS (SELECT 1 FROM knowledge_versions WHERE id = ?)`)
+            WHERE id = ? AND EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
                     .bind(version.id, version.createdAt, version.nodeId, version.id),
                 deps.db
                     .prepare(`INSERT INTO idempotency_keys (
             actor_id, operation, idempotency_key, resource_id, created_at
-          ) SELECT ?, 'knowledge.save', ?, ?, ?
-          WHERE EXISTS (SELECT 1 FROM knowledge_versions WHERE id = ?)`)
+          ) SELECT ?, 'node.save', ?, ?, ?
+          WHERE EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
                     .bind(input.actorId, input.idempotencyKey, version.id, version.createdAt, version.id),
                 deps.db
-                    .prepare(`INSERT INTO knowledge_index_state (
+                    .prepare(`INSERT INTO node_index_state (
             version_id, status, attempt_count, last_error, updated_at
           ) SELECT ?, 'pending', 0, NULL, ?
-          WHERE EXISTS (SELECT 1 FROM knowledge_versions WHERE id = ?)`)
+          WHERE EXISTS (SELECT 1 FROM node_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
-          ) SELECT ?, ?, 'knowledge.save', 'knowledge', ?, ?, ?
-          WHERE EXISTS (SELECT 1 FROM knowledge_versions WHERE id = ?)`)
+          ) SELECT ?, ?, 'node.save', 'node', ?, ?, ?
+          WHERE EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
                     .bind(input.auditId, input.actorId, version.nodeId, JSON.stringify({ versionId: version.id, sequence: version.sequence }), version.createdAt, version.id),
             ]);
             const row = await deps.db
-                .prepare("SELECT current_version_id FROM knowledge_nodes WHERE id = ?")
+                .prepare("SELECT current_version_id FROM nodes WHERE id = ?")
                 .bind(version.nodeId)
                 .first();
             return row?.current_version_id === version.id ? "saved" : "conflict";
@@ -427,51 +706,50 @@ export function createKnowledgeRepository(deps) {
         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 = ?`)
+                .prepare(`SELECT ${versionColumns} FROM node_versions WHERE id = ?`)
                 .bind(version.id)
                 .first();
             try {
                 await deps.db.batch([
                     deps.db
-                        .prepare(`INSERT INTO knowledge_versions (
-              id, node_id, sequence, content_key, media_type, content_hash, size,
+                        .prepare(`INSERT INTO node_versions (
+              id, node_id, sequence, content_key, media_type, content_hash, size, segment,
               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),
+            ) SELECT ?, ?, COALESCE(MAX(sequence), 0) + 1, ?, ?, ?, ?, ?, ?, ?
+            FROM node_versions WHERE node_id = ?`)
+                        .bind(version.id, version.nodeId, version.contentKey, version.mediaType, version.contentHash, version.size, version.segment, version.createdBy, version.createdAt, version.nodeId),
                     deps.db
-                        .prepare(`UPDATE knowledge_nodes
+                        .prepare(`UPDATE nodes
               SET current_version_id = ?, updated_at = ?
               WHERE id = ?
-                AND EXISTS (SELECT 1 FROM knowledge_versions WHERE id = ?)
+                AND EXISTS (SELECT 1 FROM node_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 = ?)
+                    SELECT sequence FROM node_versions
+                    WHERE id = nodes.current_version_id
+                  ), 0) < (SELECT sequence FROM node_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
-            ) SELECT ?, 'knowledge.append', ?, ?, ?
-            WHERE EXISTS (SELECT 1 FROM knowledge_versions WHERE id = ?)`)
+            ) SELECT ?, 'node.append', ?, ?, ?
+            WHERE EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
                         .bind(input.actorId, input.idempotencyKey, version.id, version.createdAt, version.id),
                     deps.db
-                        .prepare(`INSERT INTO knowledge_index_state (
+                        .prepare(`INSERT INTO node_index_state (
               version_id, status, attempt_count, last_error, updated_at
             ) SELECT ?, 'pending', 0, NULL, ?
-            WHERE EXISTS (SELECT 1 FROM knowledge_versions WHERE id = ?)`)
+            WHERE EXISTS (SELECT 1 FROM node_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
-            ) SELECT ?, ?, 'knowledge.append', 'knowledge', ?, json_object(
+            ) SELECT ?, ?, 'node.append', 'node', ?, json_object(
               'versionId', ?, 'size', ?
             ), ?
-            WHERE EXISTS (SELECT 1 FROM knowledge_versions WHERE id = ?)`)
+            WHERE EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
                         .bind(input.auditId, input.actorId, version.nodeId, version.id, version.size, version.createdAt, version.id),
                 ]);
             }
@@ -480,13 +758,12 @@ export function createKnowledgeRepository(deps) {
                 // 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.append' AND idempotency_key = ?`)
+            WHERE actor_id = ? AND operation = 'node.append' AND idempotency_key = ?`)
                     .bind(input.actorId, input.idempotencyKey)
                     .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 = ?`)
+                        .prepare(`SELECT ${versionColumns} FROM node_versions WHERE id = ?`)
                         .bind(replayed.resource_id)
                         .first()
                     : null;
@@ -496,9 +773,61 @@ export function createKnowledgeRepository(deps) {
             }
             const row = await stored();
             if (!row)
-                throw new Error("Knowledge table append did not store a version");
+                throw new Error("Node table append did not store a version");
             return mapVersion(row);
         },
+        /**
+         * One snapshot of a table, written only against the state it replaces (#135).
+         *
+         * ⚠️ The shape of `appendVersion`, not of the append above it: the base check sits inside the
+         * INSERT's own WHERE, so a segment that landed between the service's read and this batch makes
+         * the INSERT store nothing and every guarded statement after it a no-op. The service reads the
+         * answer the same way `save` does — by asking whether the node now stands on the new version.
+         *
+         * The idempotency row carries the mutation's own operation, so a replayed update can never be
+         * confused with a delete that reused the key, and the audit trail names what was done.
+         */
+        async appendTableSnapshot(input) {
+            const version = input.version;
+            await deps.db.batch([
+                deps.db
+                    .prepare(`INSERT INTO node_versions (
+            id, node_id, sequence, content_key, media_type, content_hash, size, segment,
+            created_by, created_at
+          ) SELECT ?, ?, ?, ?, ?, ?, ?, 'snapshot', ?, ?
+          FROM nodes
+          WHERE id = ? AND current_version_id IS ?`)
+                    .bind(version.id, version.nodeId, version.sequence, version.contentKey, version.mediaType, version.contentHash, version.size, version.createdBy, version.createdAt, version.nodeId, input.baseVersionId),
+                deps.db
+                    .prepare(`UPDATE nodes
+            SET current_version_id = ?, updated_at = ?
+            WHERE id = ? AND EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
+                    .bind(version.id, version.createdAt, version.nodeId, version.id),
+                deps.db
+                    .prepare(`INSERT INTO idempotency_keys (
+            actor_id, operation, idempotency_key, resource_id, created_at
+          ) SELECT ?, ?, ?, ?, ?
+          WHERE EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
+                    .bind(input.actorId, input.operation, input.idempotencyKey, version.id, version.createdAt, version.id),
+                deps.db
+                    .prepare(`INSERT INTO node_index_state (
+            version_id, status, attempt_count, last_error, updated_at
+          ) SELECT ?, 'pending', 0, NULL, ?
+          WHERE EXISTS (SELECT 1 FROM node_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
+          ) SELECT ?, ?, ?, 'node', ?, ?, ?
+          WHERE EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
+                    .bind(input.auditId, input.actorId, input.operation, version.nodeId, JSON.stringify({ versionId: version.id, ...input.metadata }), version.createdAt, version.id),
+            ]);
+            const row = await deps.db
+                .prepare("SELECT current_version_id FROM nodes WHERE id = ?")
+                .bind(version.nodeId)
+                .first();
+            return row?.current_version_id === version.id ? "saved" : "conflict";
+        },
         async listGrants(resourceId) {
             const result = await deps.db
                 .prepare(`SELECT ${grantColumns} FROM tree_grants
@@ -513,10 +842,10 @@ export function createKnowledgeRepository(deps) {
         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 = ?
+            SELECT id, parent_id FROM nodes WHERE id = ?
             UNION
             SELECT parent.id, parent.parent_id
-            FROM knowledge_nodes parent
+            FROM nodes parent
             JOIN ancestors child ON child.parent_id = parent.id
           )
           SELECT 1 AS reaches
@@ -535,7 +864,7 @@ export function createKnowledgeRepository(deps) {
             const result = await deps.db
                 .prepare(`${visibleCte}
           SELECT ${linkColumns}
-          FROM knowledge_links link
+          FROM node_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 = ?
@@ -562,7 +891,7 @@ export function createKnowledgeRepository(deps) {
                 const result = await deps.db
                     .prepare(`${visibleCte}
             SELECT n.id, n.title
-            FROM knowledge_nodes n
+            FROM nodes n
             JOIN allowed ON allowed.id = n.id
             WHERE n.id IN (${placeholders}) AND n.archived_at IS NULL`)
                     .bind(...readBindings(actor), ...ids)
@@ -584,10 +913,10 @@ export function createKnowledgeRepository(deps) {
         async replaceTextLinks(input) {
             await deps.db.batch([
                 deps.db
-                    .prepare("DELETE FROM knowledge_links WHERE source_node_id = ? AND origin = 'text'")
+                    .prepare("DELETE FROM node_links WHERE source_node_id = ? AND origin = 'text'")
                     .bind(input.sourceNodeId),
                 ...input.links.map((link) => deps.db
-                    .prepare(`INSERT INTO knowledge_links (
+                    .prepare(`INSERT INTO node_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`)
@@ -595,7 +924,7 @@ export function createKnowledgeRepository(deps) {
                 deps.db
                     .prepare(`INSERT INTO audit_events (
             id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
-          ) VALUES (?, ?, 'knowledge.link', 'knowledge', ?, ?, ?)`)
+          ) VALUES (?, ?, 'node.link', 'node', ?, ?, ?)`)
                     .bind(input.auditId, input.actorId, input.sourceNodeId, JSON.stringify({ targetNodeIds: input.links.map((link) => link.targetNodeId) }), input.occurredAt),
             ]);
         },
@@ -603,7 +932,7 @@ export function createKnowledgeRepository(deps) {
             const nodeResult = await deps.db
                 .prepare(`${visibleCte}
           SELECT ${nodeColumns}
-          FROM knowledge_nodes n
+          FROM nodes n
           JOIN allowed ON allowed.id = n.id
           WHERE n.archived_at IS NULL
           ORDER BY lower(n.title), n.id
@@ -615,14 +944,14 @@ export function createKnowledgeRepository(deps) {
                 return { nodes, links: [] };
             const linkResult = await deps.db
                 .prepare(`${visibleCte}, graph_nodes(id) AS (
-          SELECT n.id FROM knowledge_nodes n
+          SELECT n.id FROM nodes n
           JOIN allowed ON allowed.id = n.id
           WHERE n.archived_at IS NULL
           ORDER BY lower(n.title), n.id
           LIMIT ?
         )
           SELECT ${linkColumns}
-          FROM knowledge_links link
+          FROM node_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`)
@@ -653,13 +982,13 @@ export function createKnowledgeRepository(deps) {
                     deps.db
                         .prepare(`INSERT INTO idempotency_keys (
               actor_id, operation, idempotency_key, resource_id, created_at
-            ) SELECT ?, 'knowledge.share', ?, id, ? FROM tree_grants
+            ) SELECT ?, 'node.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', ?, ?, ?)`)
+            ) VALUES (?, ?, 'node.share', 'node', ?, ?, ?)`)
                         .bind(input.auditId, input.actorId, grant.resourceId, JSON.stringify({ principalType, verb: grant.verb }), grant.createdAt),
                 ]);
                 const stored = await deps.db
@@ -668,13 +997,13 @@ export function createKnowledgeRepository(deps) {
                     .bind(grant.resourceId, principalType, principalId, grant.verb)
                     .first();
                 if (!stored)
-                    throw new Error("Knowledge grant disappeared after upsert");
+                    throw new Error("Node grant disappeared after upsert");
                 return mapGrant(stored);
             }
             catch (error) {
                 const replayed = await deps.db
                     .prepare(`SELECT resource_id FROM idempotency_keys
-            WHERE actor_id = ? AND operation = 'knowledge.share' AND idempotency_key = ?`)
+            WHERE actor_id = ? AND operation = 'node.share' AND idempotency_key = ?`)
                     .bind(input.actorId, input.idempotencyKey)
                     .first();
                 if (replayed) {
@@ -694,7 +1023,7 @@ export function createKnowledgeRepository(deps) {
                     deps.db
                         .prepare(`INSERT INTO idempotency_keys (
               actor_id, operation, idempotency_key, resource_id, created_at
-            ) SELECT ?, 'knowledge.revoke', ?,
+            ) SELECT ?, 'node.revoke', ?,
               (CASE WHEN EXISTS (
                 SELECT 1 FROM tree_grants WHERE id = ? AND node_id = ?
               ) THEN '1:' ELSE '0:' END) || ?, ?`)
@@ -705,13 +1034,13 @@ export function createKnowledgeRepository(deps) {
                     deps.db
                         .prepare(`INSERT INTO audit_events (
               id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
-            ) SELECT ?, ?, 'knowledge.revoke', 'knowledge', ?,
+            ) SELECT ?, ?, 'node.revoke', 'node', ?,
               json_object(
                 'grantId', ?,
                 'revoked', json(CASE WHEN substr(resource_id, 1, 2) = '1:' THEN 'true' ELSE 'false' END)
               ), ?
               FROM idempotency_keys
-              WHERE actor_id = ? AND operation = 'knowledge.revoke' AND idempotency_key = ?`)
+              WHERE actor_id = ? AND operation = 'node.revoke' AND idempotency_key = ?`)
                         .bind(input.auditId, input.actorId, input.resourceId, input.grantId, input.occurredAt, input.actorId, input.idempotencyKey),
                 ]);
             }
@@ -728,33 +1057,33 @@ export function createKnowledgeRepository(deps) {
             if (!query)
                 return [];
             const result = await deps.db
-                .prepare(`${visibleCte}
+                .prepare(`${visibleCte}${scopeCte(input.scopeId)}
           SELECT n.id AS node_id, v.id AS version_id, n.title,
-            snippet(knowledge_fts, 3, '', '', ' … ', 32) AS passage,
-            n.updated_at AS freshness, bm25(knowledge_fts, 0.0, 0.0, 4.0, 1.0) AS rank
-          FROM knowledge_fts
-          JOIN knowledge_nodes n ON n.id = knowledge_fts.node_id
-          JOIN knowledge_versions v ON v.id = knowledge_fts.version_id
-          JOIN allowed ON allowed.id = n.id
-          WHERE knowledge_fts MATCH ?
+            snippet(node_fts, 3, '', '', ' … ', 32) AS passage,
+            n.updated_at AS freshness, bm25(node_fts, 0.0, 0.0, 4.0, 1.0) AS rank
+          FROM node_fts
+          JOIN nodes n ON n.id = node_fts.node_id
+          JOIN node_versions v ON v.id = node_fts.version_id
+          JOIN allowed ON allowed.id = n.id${scopeJoin(input.scopeId)}
+          WHERE node_fts MATCH ?
             AND n.current_version_id = v.id
             AND n.archived_at IS NULL
           ORDER BY rank, n.updated_at DESC
           LIMIT ?`)
-                .bind(...readBindings(actor), query, input.limit)
+                .bind(...readBindings(actor), ...scopeBindings(input.scopeId), query, input.limit)
                 .all();
             return (result.results ?? []).map((row) => ({
                 nodeId: row.node_id,
                 versionId: row.version_id,
                 title: row.title,
                 passage: row.passage,
-                source: `intel://knowledge/${encodeURIComponent(row.node_id)}?version=${encodeURIComponent(row.version_id)}`,
+                source: `intel://nodes/${encodeURIComponent(row.node_id)}?version=${encodeURIComponent(row.version_id)}`,
                 freshness: row.freshness,
                 score: 1 / (1 + Math.abs(row.rank)),
                 match: "lexical",
             }));
         },
-        async hydrateVisibleCitations(actor, nodeIds) {
+        async hydrateVisibleCitations(actor, nodeIds, scopeId) {
             const uniqueIds = [...new Set(nodeIds)].slice(0, 100);
             if (uniqueIds.length === 0)
                 return [];
@@ -763,16 +1092,16 @@ export function createKnowledgeRepository(deps) {
                 const ids = uniqueIds.slice(offset, offset + 96);
                 const placeholders = ids.map(() => "?").join(", ");
                 const result = await deps.db
-                    .prepare(`${visibleCte}
+                    .prepare(`${visibleCte}${scopeCte(scopeId)}
             SELECT n.id AS node_id, v.id AS version_id, n.title,
-              substr(knowledge_fts.content, 1, 480) AS passage,
+              substr(node_fts.content, 1, 480) AS passage,
               n.updated_at AS freshness
-            FROM knowledge_nodes n
-            JOIN knowledge_versions v ON v.id = n.current_version_id
-            JOIN knowledge_fts ON knowledge_fts.version_id = v.id
-            JOIN allowed ON allowed.id = n.id
+            FROM nodes n
+            JOIN node_versions v ON v.id = n.current_version_id
+            JOIN node_fts ON node_fts.version_id = v.id
+            JOIN allowed ON allowed.id = n.id${scopeJoin(scopeId)}
             WHERE n.id IN (${placeholders}) AND n.archived_at IS NULL`)
-                    .bind(...readBindings(actor), ...ids)
+                    .bind(...readBindings(actor), ...scopeBindings(scopeId), ...ids)
                     .all();
                 rows.push(...(result.results ?? []));
             }
@@ -783,7 +1112,7 @@ export function createKnowledgeRepository(deps) {
                 versionId: row.version_id,
                 title: row.title,
                 passage: row.passage,
-                source: `intel://knowledge/${encodeURIComponent(row.node_id)}?version=${encodeURIComponent(row.version_id)}`,
+                source: `intel://nodes/${encodeURIComponent(row.node_id)}?version=${encodeURIComponent(row.version_id)}`,
                 freshness: row.freshness,
                 score: 0,
                 match: "semantic",
@@ -791,7 +1120,7 @@ export function createKnowledgeRepository(deps) {
         },
         async listCurrentVersionIds(input) {
             const result = await deps.db
-                .prepare(`SELECT current_version_id AS id FROM knowledge_nodes
+                .prepare(`SELECT current_version_id AS id FROM nodes
           WHERE current_version_id IS NOT NULL AND archived_at IS NULL
             AND (? IS NULL OR current_version_id > ?)
           ORDER BY id LIMIT ?`)