@anchrd/intel-api 0.20.0 → 0.22.0

package/dist/adapters/cloudflare/cloudflare.js

@@ -1,4 +1,5 @@
 import { createGateClient } from "@anchrd/gate-sdk";
+import { serverOf } from "@anchrd/intel-contract/tool";
 import { ulid } from "ulid";
 import { createBrowserAuth } from "../../auth/auth.js";
 import { createBundle } from "../../bundle/bundle.js";
@@ -156,13 +157,60 @@ export default {
             // requirements list and every tree link of every run read this one answer, so none of
             // them can be kinder than the others.
             visibleNodes: async (actor, nodeId) => await nodes.visibleNode(actor, nodeId),
-            toolFingerprint: async (actor, toolName) => {
+            /**
+             * ⚠️ The fingerprint of a whole SURFACE, not of one tool (#489). A step names a server and
+             * optionally the functions of it it may use, so what publishing freezes is that set — every
+             * covered function's own fingerprint, sorted so the order the portal happens to answer in
+             * cannot change the result, and hashed into one value.
+             *
+             * `null` in three cases, and all three have to refuse a publish: the catalog is unreachable,
+             * the server offers this user nothing, or a function the step explicitly allows is gone. The
+             * last one matters most — a narrowed step whose function disappeared is not a step that may
+             * quietly fall back to the rest of the server.
+             */
+            toolSurfaceFingerprint: async (actor, server, allow) => {
                 const catalog = await tools
                     .catalog({ id: actor.id, email: actor.email, canExecute: true })
                     .catch(() => null);
-                return catalog?.items.find((item) => item.name === toolName)?.fingerprint ?? null;
+                if (!catalog)
+                    return null;
+                const reachable = new Map(catalog.items.map((item) => [item.name, item.fingerprint]));
+                const covered = allow === null
+                    ? [...reachable.keys()].filter((name) => serverOf(name, [server]) !== null)
+                    : allow;
+                if (covered.length === 0)
+                    return null;
+                const parts = [];
+                for (const name of [...new Set(covered)].sort()) {
+                    const fingerprint = reachable.get(name);
+                    if (!fingerprint)
+                        return null;
+                    parts.push(`${name}:${fingerprint}`);
+                }
+                // ⚠️ The handle and the narrowing mode are part of what is hashed, not just the covered
+                // functions. Without them two different surfaces could collide: a server whose only
+                // function is allowed explicitly would hash the same as the same server left open, and the
+                // difference between "this one function" and "whatever this server offers" is exactly what
+                // publishing is meant to freeze.
+                const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode([server, allow === null ? "*" : "allow", ...parts].join("\n")));
+                return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+            },
+            // Which of the named servers this user does NOT reach. A server is reached when the live
+            // catalog carries at least one function of it — the same live answer the tool surface uses,
+            // never a mirrored table.
+            // ⚠️ The catalog error is NOT caught here, and that is the whole point. Answering an
+            // unreadable portal with "all of them are missing" turns an outage into a sentence about
+            // PERMISSIONS — the reader goes asking for access they already have, while the portal is
+            // simply down. `tools.catalog` already tells the two apart (`tool_catalog_unreadable`,
+            // `portal_not_connected`), and letting that answer through is the same rule the tool surface
+            // keeps one screen up: a sentence more specific than the evidence sends the reader looking in
+            // the wrong place.
+            unavailableServers: async (actor, servers) => {
+                if (servers.length === 0)
+                    return [];
+                const catalog = await tools.catalog({ id: actor.id, email: actor.email, canExecute: true });
+                return servers.filter((server) => !catalog.items.some((item) => serverOf(item.name, [server]) !== null));
             },
-            unavailableTools: async (actor, toolNames) => await tools.unavailable({ id: actor.id, email: actor.email, canExecute: true }, toolNames),
         });
         return await createIntel({
             baseUrl: env.INTEL_URL,

package/dist/adapters/db/db.js

@@ -649,16 +649,78 @@ export function createNodeRepository(deps) {
         },
         async countInboundLinks(nodeId) {
             const row = await deps.db
-                .prepare("SELECT COUNT(*) AS n FROM node_links WHERE target_node_id = ?")
+                .prepare(`WITH RECURSIVE tree(id) AS (
+          SELECT id FROM nodes WHERE id = ?
+          UNION ALL SELECT child.id FROM nodes child JOIN tree parent ON child.parent_id = parent.id
+        ) SELECT COUNT(*) AS n FROM node_links
+          WHERE target_node_id IN (SELECT id FROM tree)
+            AND source_node_id NOT IN (SELECT id FROM tree)`)
                 .bind(nodeId)
                 .first();
             return row?.n ?? 0;
         },
+        async inspectPurgeTree(nodeId) {
+            const tree = `WITH RECURSIVE tree(id) AS (
+        SELECT id FROM nodes WHERE id = ?
+        UNION ALL SELECT child.id FROM nodes child JOIN tree parent ON child.parent_id = parent.id
+      )`;
+            const nodes = await deps.db
+                .prepare(`${tree} SELECT n.id, n.kind FROM nodes n JOIN tree ON tree.id = n.id`)
+                .bind(nodeId)
+                .all();
+            const nodeIds = (nodes.results ?? []).map((row) => row.id);
+            const flows = await deps.db
+                .prepare(`${tree} SELECT f.id FROM flows f WHERE f.parent_id IN (SELECT id FROM tree)`)
+                .bind(nodeId)
+                .all();
+            const keys = await deps.db
+                .prepare(`${tree} SELECT v.content_key FROM node_versions v WHERE v.node_id IN (SELECT id FROM tree)`)
+                .bind(nodeId)
+                .all();
+            const vectors = await deps.db
+                .prepare(`${tree} SELECT v.node_id, v.chunk_key FROM node_vectors v WHERE v.node_id IN (SELECT id FROM tree)`)
+                .bind(nodeId)
+                .all();
+            const grouped = new Map();
+            for (const row of vectors.results ?? []) {
+                const current = grouped.get(row.node_id) ?? [];
+                current.push(row.chunk_key);
+                grouped.set(row.node_id, current);
+            }
+            const counts = { flow: flows.results?.length ?? 0 };
+            for (const row of nodes.results ?? [])
+                counts[row.kind] = (counts[row.kind] ?? 0) + 1;
+            return {
+                nodeIds,
+                flowIds: (flows.results ?? []).map((row) => row.id),
+                contentKeys: [...new Set((keys.results ?? []).map((row) => row.content_key))],
+                vectorKeys: nodeIds.map((id) => ({ nodeId: id, keys: grouped.get(id) ?? [] })),
+                counts,
+            };
+        },
+        async findPurgeReplay(actorId, idempotencyKey) {
+            const row = await deps.db
+                .prepare(`SELECT title, content_keys_json FROM node_purge_receipts
+          WHERE actor_id = ? AND idempotency_key = ?`)
+                .bind(actorId, idempotencyKey)
+                .first();
+            return row ? { title: row.title, contentKeys: JSON.parse(row.content_keys_json) } : null;
+        },
+        async completePurgeReplay(actorId, idempotencyKey, completedAt) {
+            await deps.db
+                .prepare(`UPDATE node_purge_receipts SET completed_at = ?
+          WHERE actor_id = ? AND idempotency_key = ?`)
+                .bind(completedAt, actorId, idempotencyKey)
+                .run();
+        },
         async purgeNode(input) {
             // The keys BEFORE anything falls: after the batch there is no version row left to read them
             // from, and an object nobody can name is an object nobody can delete.
             const keys = await deps.db
-                .prepare("SELECT content_key FROM node_versions WHERE node_id = ?")
+                .prepare(`WITH RECURSIVE tree(id) AS (
+          SELECT id FROM nodes WHERE id = ?
+          UNION ALL SELECT child.id FROM nodes child JOIN tree parent ON child.parent_id = parent.id
+        ) SELECT content_key FROM node_versions WHERE node_id IN (SELECT id FROM tree)`)
                 .bind(input.nodeId)
                 .all();
             // ⚠️ The guard belongs on EVERY statement, not only on the last one (found in review). A
@@ -669,6 +731,13 @@ export function createNodeRepository(deps) {
             // reader was told nothing had happened while the content was already gone. The audit row
             // carried the same condition, so it was not even booked.
             const alive = "EXISTS (SELECT 1 FROM nodes n WHERE n.id = ? AND n.archived_at IS NOT NULL)";
+            const tree = `WITH RECURSIVE tree(id) AS (
+        SELECT id FROM nodes WHERE id = ?
+        UNION ALL SELECT child.id FROM nodes child JOIN tree parent ON child.parent_id = parent.id
+      )`;
+            const treeFlows = `${tree}, tree_flows(id) AS (
+        SELECT id FROM flows WHERE parent_id IN (SELECT id FROM tree)
+      )`;
             const deleted = await deps.db.batch([
                 // ⚠️ FIRST, and reading the title out of the row that falls at the end of this batch. Its
                 // `WHERE EXISTS` is what makes it honest: no row, no entry — a purge that hit nothing does
@@ -680,40 +749,71 @@ export function createNodeRepository(deps) {
               json_patch(?, json_object('title', n.title, 'kind', n.kind)), ?
             FROM nodes n WHERE n.id = ? AND n.archived_at IS NOT NULL`)
                     .bind(input.auditId, input.actorId, JSON.stringify(input.metadata), input.occurredAt, input.nodeId),
+                deps.db
+                    .prepare(`INSERT INTO node_purge_receipts (
+            actor_id, idempotency_key, node_id, title, content_keys_json, completed_at
+          ) SELECT ?, ?, n.id, n.title, ?, NULL FROM nodes n
+            WHERE n.id = ? AND n.archived_at IS NOT NULL`)
+                    .bind(input.actorId, input.idempotencyKey, JSON.stringify([...new Set((keys.results ?? []).map((row) => row.content_key))]), input.nodeId),
                 // The derived indexes go with their source. ⚠️ A hit on a deleted document is not a blemish
                 // but a leak: the title stands in the result and the content is gone.
                 deps.db
-                    .prepare(`DELETE FROM node_fts WHERE node_id = ? AND ${alive}`)
+                    .prepare(`${tree} DELETE FROM node_fts WHERE node_id IN (SELECT id FROM tree) AND ${alive}`)
                     .bind(input.nodeId, input.nodeId),
                 deps.db
-                    .prepare(`DELETE FROM node_vectors WHERE node_id = ? AND ${alive}`)
+                    .prepare(`${tree} DELETE FROM node_vectors WHERE node_id IN (SELECT id FROM tree) AND ${alive}`)
                     .bind(input.nodeId, input.nodeId),
                 deps.db
-                    .prepare(`DELETE FROM node_index_state
-            WHERE version_id IN (SELECT id FROM node_versions WHERE node_id = ?) AND ${alive}`)
+                    .prepare(`${tree} DELETE FROM node_index_state
+            WHERE version_id IN (SELECT id FROM node_versions WHERE node_id IN (SELECT id FROM tree)) AND ${alive}`)
                     .bind(input.nodeId, input.nodeId),
                 // Both directions. Outgoing links belong to this node; incoming ones would otherwise point
                 // at a row that is gone, and a foreign key would refuse the delete anyway.
                 deps.db
-                    .prepare(`DELETE FROM node_links
-            WHERE (source_node_id = ? OR target_node_id = ?) AND ${alive}`)
-                    .bind(input.nodeId, input.nodeId, input.nodeId),
+                    .prepare(`${tree} DELETE FROM node_links
+            WHERE (source_node_id IN (SELECT id FROM tree) OR target_node_id IN (SELECT id FROM tree)) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
                 // A permission on a node that does not exist is a dangling permission.
                 deps.db
-                    .prepare(`DELETE FROM node_grants WHERE node_id = ? AND ${alive}`)
+                    .prepare(`${tree} DELETE FROM node_grants WHERE node_id IN (SELECT id FROM tree) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`${treeFlows} UPDATE flows SET published_version_id = NULL
+            WHERE id NOT IN (SELECT id FROM tree_flows) AND EXISTS (
+              SELECT 1 FROM flow_versions fv, json_tree(fv.graph_json) graph
+              WHERE fv.id IN (flows.current_version_id, flows.published_version_id)
+                AND ((graph.key = 'resourceId' AND graph.value IN (SELECT id FROM tree))
+                  OR (graph.key = 'flowId' AND graph.value IN (SELECT id FROM tree_flows)))
+            ) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`${treeFlows} DELETE FROM flow_run_steps
+            WHERE run_id IN (SELECT id FROM flow_runs WHERE flow_id IN (SELECT id FROM tree_flows)) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`${treeFlows} DELETE FROM flow_runs WHERE flow_id IN (SELECT id FROM tree_flows) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`${treeFlows} DELETE FROM flow_versions WHERE flow_id IN (SELECT id FROM tree_flows) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`${treeFlows} DELETE FROM idempotency_keys WHERE resource_id IN (SELECT id FROM tree_flows) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`${treeFlows} DELETE FROM flows WHERE id IN (SELECT id FROM tree_flows) AND ${alive}`)
                     .bind(input.nodeId, input.nodeId),
                 deps.db
-                    .prepare(`DELETE FROM node_versions WHERE node_id = ? AND ${alive}`)
+                    .prepare(`${tree} DELETE FROM node_versions WHERE node_id IN (SELECT id FROM tree) AND ${alive}`)
                     .bind(input.nodeId, input.nodeId),
                 // ⚠️ The replay keys of every earlier write to this node. Left behind, a later write reusing
                 // one of them would be answered with a resource id that no longer resolves.
                 deps.db
-                    .prepare(`DELETE FROM idempotency_keys WHERE resource_id = ? AND ${alive}`)
+                    .prepare(`${tree} DELETE FROM idempotency_keys WHERE resource_id IN (SELECT id FROM tree) AND ${alive}`)
                     .bind(input.nodeId, input.nodeId),
                 // LAST — and its count is what the caller reads as the verdict.
                 deps.db
-                    .prepare("DELETE FROM nodes WHERE id = ? AND archived_at IS NOT NULL")
-                    .bind(input.nodeId),
+                    .prepare(`${tree} DELETE FROM nodes WHERE id IN (SELECT id FROM tree) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
             ]);
             const removed = deleted.at(-1)?.meta?.changes ?? 0;
             if (removed === 0)
@@ -913,6 +1013,42 @@ export function createNodeRepository(deps) {
                 .all();
             return (result.results ?? []).map(mapGrant);
         },
+        async listEffectiveAccess(resourceId) {
+            // Owners and grants come from ONE statement, hence one D1 snapshot. Two parallel SELECTs are
+            // not atomic: a grant mutation between their snapshots can produce a principal list that
+            // never existed as a whole.
+            const row = await deps.db
+                .prepare(`WITH RECURSIVE ancestors(id, parent_id, owner_id) AS (
+            SELECT id, parent_id, owner_id FROM nodes WHERE id = ?
+            UNION
+            SELECT parent.id, parent.parent_id, parent.owner_id
+            FROM nodes parent
+            JOIN ancestors child ON child.parent_id = parent.id
+          )
+          SELECT
+            (SELECT json_group_array(owner_id)
+             FROM (SELECT DISTINCT owner_id FROM ancestors ORDER BY owner_id)) AS owner_ids_json,
+            (SELECT json_group_array(json_object(
+               'id', id, 'node_id', node_id, 'principal_type', principal_type,
+               'principal_id', principal_id, 'verb', verb, 'expires_at', expires_at,
+               'created_by', created_by, 'created_at', created_at
+             ))
+             FROM (
+               SELECT grant_row.id, grant_row.node_id, grant_row.principal_type,
+                 grant_row.principal_id, grant_row.verb, grant_row.expires_at,
+                 grant_row.created_by, grant_row.created_at
+               FROM node_grants grant_row
+               JOIN ancestors ON ancestors.id = grant_row.node_id
+               WHERE grant_row.expires_at IS NULL OR grant_row.expires_at > ?
+               ORDER BY grant_row.principal_type, grant_row.principal_id, grant_row.verb
+             )) AS grants_json`)
+                .bind(resourceId, deps.now().toISOString())
+                .first();
+            return {
+                ownerIds: JSON.parse(row?.owner_ids_json ?? "[]"),
+                items: JSON.parse(row?.grants_json ?? "[]").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) {

package/dist/flows/flows.d.ts

@@ -23,14 +23,18 @@ export declare function toolNodes(graph: FlowGraph): ToolStepNode[];
 export declare function resourceIdOf(node: TreeLinkNode): string;
 export declare function calleeIds(graph: FlowGraph): string[];
 /**
- * The documents a graph names and the tools it calls, flattened and without repetition.
+ * The documents a graph names and the tool SERVERS it reaches for, 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.
+ *
+ * ⚠️ Servers, not functions, since #489. A step no longer names one function, so "what does this
+ * flow need" cannot be answered with a function list any more — and answering it with the functions
+ * a step MIGHT call would be a guess about a choice that is made while the flow runs.
  */
 export declare function graphReferences(graph: FlowGraph): {
     nodes: string[];
-    tools: string[];
+    servers: string[];
 };
 export declare function compileFlow(graph: FlowGraph): CompiledFlow;
 export declare function createFlows(deps: FlowDeps): FlowService;

package/dist/flows/flows.js

@@ -46,24 +46,28 @@ export function calleeIds(graph) {
     return ids;
 }
 /**
- * The documents a graph names and the tools it calls, flattened and without repetition.
+ * The documents a graph names and the tool SERVERS it reaches for, 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.
+ *
+ * ⚠️ Servers, not functions, since #489. A step no longer names one function, so "what does this
+ * flow need" cannot be answered with a function list any more — and answering it with the functions
+ * a step MIGHT call would be a guess about a choice that is made while the flow runs.
  */
 export function graphReferences(graph) {
     const nodes = [];
-    const tools = [];
+    const servers = [];
     for (const node of treeLinkNodes(graph)) {
         if (!nodes.includes(node.configuration.resourceId)) {
             nodes.push(node.configuration.resourceId);
         }
     }
     for (const node of toolNodes(graph)) {
-        if (!tools.includes(node.configuration.toolName))
-            tools.push(node.configuration.toolName);
+        if (!servers.includes(node.configuration.server))
+            servers.push(node.configuration.server);
     }
-    return { nodes, tools };
+    return { nodes, servers };
 }
 // ⚠️ The reason, in the words the person can act on, and not one word more. How many documents a
 // step cannot reach is something they may know; which ones they are is the very thing the ACL is
@@ -76,10 +80,14 @@ function treeLinkStepDetail(label, missing) {
 // ⚠️ For tools this is the only honest moment there is. The catalog is a live tools/list with the
 // requesting user's own token (ADR-0003), so nobody can be told in advance what someone else would
 // see — but the person in front of the failure can be told exactly where to go.
+// ⚠️ Servers, not tools, since #489 — and the sentence says so. A step names a server, so a person
+// told "you do not have access to this tool: notion" would go looking for a function by that name
+// and find none. What they can act on is the server: it is what the portal grants and what they can
+// ask to be granted.
 function toolStepDetail(missing) {
     return missing.length === 1
-        ? `You do not have access to this tool in the portal: ${missing.join(", ")}`
-        : `You do not have access to these tools in the portal: ${missing.join(", ")}`;
+        ? `You do not reach this tool server in the portal: ${missing.join(", ")}`
+        : `You do not reach these tool servers in the portal: ${missing.join(", ")}`;
 }
 export function compileFlow(graph) {
     const nodes = new Map();
@@ -439,11 +447,11 @@ export function createFlows(deps) {
         // The one consequence to know about: `start` throws the FIRST entry, so it now names the first
         // missing tool rather than all of them — the same as it has always done for several
         // unpublished sub-flows below. `validate` is what lists every reason at once, and it does.
-        for (const tool of await deps.unavailableTools(actor, graphReferences(version.graph).tools)) {
+        for (const server of await deps.unavailableServers(actor, graphReferences(version.graph).servers)) {
             problems.push({
                 status: 403,
                 code: "flow_tools_unavailable",
-                detail: toolStepDetail([tool]),
+                detail: toolStepDetail([server]),
             });
         }
         try {
@@ -597,12 +605,12 @@ export function createFlows(deps) {
     async function requireToolsAuthorized(actor, node, graph) {
         if (!node)
             return;
-        const toolNames = attachedNodes(node, graph)
+        const servers = attachedNodes(node, graph)
             .filter((candidate) => candidate.kind === "tool")
-            .map((candidate) => candidate.configuration.toolName);
-        if (!toolNames.length)
+            .map((candidate) => candidate.configuration.server);
+        if (!servers.length)
             return;
-        const missing = await deps.unavailableTools(actor, [...new Set(toolNames)]);
+        const missing = await deps.unavailableServers(actor, [...new Set(servers)]);
         if (missing.length) {
             throw new IntelError(403, "flow_tools_unavailable", toolStepDetail(missing));
         }
@@ -773,6 +781,19 @@ export function createFlows(deps) {
         let changed = false;
         const nodes = [];
         for (const node of graph.nodes) {
+            // A tool step is frozen the same way a sub-flow call is: what it may reach is pinned at the
+            // moment of publishing (#489). The check above has already refused an unreachable server and
+            // a surface that moved since a previous publish, so this only writes down what it confirmed.
+            if (node.kind === "tool") {
+                const fingerprint = await deps.toolSurfaceFingerprint(actor, node.configuration.server, node.configuration.allow);
+                if (fingerprint !== null && fingerprint !== node.configuration.fingerprint) {
+                    nodes.push({ ...node, configuration: { ...node.configuration, fingerprint } });
+                    changed = true;
+                    continue;
+                }
+                nodes.push(node);
+                continue;
+            }
             if (node.kind !== "subflow") {
                 nodes.push(node);
                 continue;
@@ -1085,7 +1106,7 @@ export function createFlows(deps) {
                     versionId: null,
                     nodes: [],
                     hiddenNodes: 0,
-                    tools: [],
+                    servers: [],
                 };
             }
             const version = await requireVersion(versionId, flow.id);
@@ -1101,7 +1122,7 @@ export function createFlows(deps) {
                 versionId: version.id,
                 nodes: reachable,
                 hiddenNodes: referenced.nodes.length - reachable.length,
-                tools: referenced.tools,
+                servers: referenced.servers,
             };
         },
         async create(actor, input) {
@@ -1311,11 +1332,24 @@ export function createFlows(deps) {
             }
             for (const node of version.graph.nodes) {
                 if (node.kind === "tool") {
-                    const fingerprint = await deps.toolFingerprint(actor, node.configuration.toolName);
+                    // ⚠️ The fingerprint covers the whole surface this step may use — the server and, when
+                    // the step narrows it, exactly those functions with their schemas (#489). Freezing one
+                    // function was enough while a step named one; a step that may use any function of a
+                    // server would otherwise silently inherit functions the provider added AFTER publishing.
+                    const fingerprint = await deps.toolSurfaceFingerprint(actor, node.configuration.server, node.configuration.allow);
                     if (!fingerprint) {
-                        throw new IntelError(409, "flow_tool_unavailable", `Tool is unavailable: ${node.label}`);
+                        throw new IntelError(409, "flow_tool_unavailable", `Tool server is unavailable: ${node.label}`);
                     }
-                    if (node.configuration.fingerprint !== fingerprint) {
+                    // ⚠️ A step that has never been published carries no fingerprint, and that is not a
+                    // mismatch — it is the state every draft starts in. Publishing is what FREEZES the
+                    // surface, exactly as it turns a `latest` sub-flow call into a pinned one, and `freeze`
+                    // below writes the value in.
+                    //
+                    // Demanding it up front would mean the editor had to produce it, and nothing hands it
+                    // one: the value is derived from the asking user's own live catalog. Requiring it would
+                    // make every tool step unpublishable rather than safe.
+                    if (node.configuration.fingerprint !== null &&
+                        node.configuration.fingerprint !== fingerprint) {
                         throw new IntelError(409, "flow_tool_schema_changed", `Review the current schema before publishing: ${node.label}`);
                     }
                 }

package/dist/flows/flows.types.d.ts

@@ -209,8 +209,8 @@ export interface FlowDeps {
      * kinder than the door it describes — which is what #17 and #19 were sent back for.
      */
     visibleNodes(actor: FlowActor, nodeId: string): Promise<Node | null>;
-    toolFingerprint(actor: FlowActor, toolName: string): Promise<string | null>;
-    unavailableTools(actor: FlowActor, toolNames: string[]): Promise<string[]>;
+    toolSurfaceFingerprint(actor: FlowActor, server: string, allow: string[] | null): Promise<string | null>;
+    unavailableServers(actor: FlowActor, servers: string[]): Promise<string[]>;
 }
 export type FolderAccess = "ok" | "missing" | "not-a-folder" | "forbidden";
 export interface FlowService {

package/dist/http/http.js

@@ -1,6 +1,6 @@
 import { ArchiveFlowInput, CreateFlowInput, GetFlowInput, GetFlowVersionInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, PurgeFlowInput, RelationGraphInput, SaveFlowVersionInput, UnpublishFlowInput, UpdateFlowInput, } from "@anchrd/intel-contract/flow";
 import { CancelFlowRunInput, CompleteFlowRunStepInput, GetFlowRunInput, ListFlowRunsInput, StartFlowRunInput, } from "@anchrd/intel-contract/flow-run";
-import { ArchiveNodeInput, CreateNodeInput, GetNodeInput, GetNodeVersionInput, ListNodesInput, NodeGraphInput, PurgeNodeInput, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "@anchrd/intel-contract/node";
+import { ArchiveNodeInput, CreateNodeInput, GetNodeInput, GetNodeVersionInput, ListNodesInput, NodeGraphInput, PurgeNodeInput, PurgeNodePreviewInput, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "@anchrd/intel-contract/node";
 import { RevokeGrantInput, ShareInput } from "@anchrd/intel-contract/share";
 import { AppendTableRowsInput, DefineTableInput, DeleteTableRowsInput, RedefineTableInput, UpdateTableRowsInput, } from "@anchrd/intel-contract/table";
 import { ExecuteToolInput, TestToolInput } from "@anchrd/intel-contract/tool";
@@ -366,13 +366,25 @@ export function createHttp(deps) {
     // two steps and the first one is reversible.
     app.delete("/nodes/:nodeId", async (context) => {
         const auth = requireCapability(context, "nodes", "write");
-        const input = PurgeNodeInput.parse({ nodeId: context.req.param("nodeId") });
+        const input = PurgeNodeInput.parse(await context.req.json().catch(() => null));
+        if (input.nodeId !== context.req.param("nodeId")) {
+            throw new IntelError(400, "node_id_mismatch", "Path and body node IDs differ");
+        }
         return context.json(await deps.nodes.purge(asActor(auth), input));
     });
+    app.get("/nodes/:nodeId/purge-preview", async (context) => {
+        const auth = requireCapability(context, "nodes", "write");
+        const input = PurgeNodePreviewInput.parse({ nodeId: context.req.param("nodeId") });
+        return context.json(await deps.nodes.purgePreview(asActor(auth), input));
+    });
     app.get("/nodes/:nodeId/grants", async (context) => {
         const auth = requireCapability(context, "nodes", "share");
         return context.json(await deps.nodes.listGrants(asActor(auth), context.req.param("nodeId")));
     });
+    app.get("/nodes/:nodeId/effective-access", async (context) => {
+        const auth = requireCapability(context, "nodes", "share");
+        return context.json(await deps.nodes.listEffectiveAccess(asActor(auth), context.req.param("nodeId")));
+    });
     app.post("/nodes/:nodeId/grants", async (context) => {
         const auth = requireCapability(context, "nodes", "share");
         const input = ShareInput.parse(await context.req.json().catch(() => null));

package/dist/nodes/nodes.js

@@ -381,6 +381,20 @@ export function createNodes(deps) {
         async get(actor, nodeId) {
             return await getDocument(await requireVisible(actor, nodeId));
         },
+        async purgePreview(actor, input) {
+            const node = await requireVisible(actor, input.nodeId);
+            if (!(await deps.repository.can(actor, input.nodeId, "write"))) {
+                throw new IntelError(403, "node_forbidden", "This node cannot be edited");
+            }
+            if (!node.archivedAt) {
+                throw new IntelError(409, "node_not_archived", "Only an archived node can be deleted for good. Archive it first.");
+            }
+            const tree = await deps.repository.inspectPurgeTree(node.id);
+            return {
+                inboundLinks: await deps.repository.countInboundLinks(node.id),
+                totalItems: tree.nodeIds.length + tree.flowIds.length,
+            };
+        },
         /**
          * The content of one pinned version (#147). Search citations pin the version they quoted, and
          * without this read a citation could name text no surface can show any more.
@@ -855,6 +869,14 @@ export function createNodes(deps) {
          * chosen to the safer side.
          */
         async purge(actor, input) {
+            const idempotencyKey = `${input.nodeId}:${input.idempotencyKey}`;
+            const replay = await deps.repository.findPurgeReplay(actor.id, idempotencyKey);
+            if (replay) {
+                for (const key of replay.contentKeys)
+                    await deps.content.delete(key);
+                await deps.repository.completePurgeReplay(actor.id, idempotencyKey, deps.now().toISOString());
+                return { purged: true, title: replay.title };
+            }
             const node = await requireVisible(actor, input.nodeId);
             if (!(await deps.repository.can(actor, input.nodeId, "write"))) {
                 throw new IntelError(403, "node_forbidden", "This node cannot be edited");
@@ -866,28 +888,14 @@ export function createNodes(deps) {
             if (!node.archivedAt) {
                 throw new IntelError(409, "node_not_archived", "Only an archived node can be deleted for good. Archive it first.");
             }
-            // A folder is refused while anything is still inside — archived rows included. A cascade
-            // would turn ONE confirmed click into an unknown number of deletions, and the confirmation
-            // could then no longer name what disappears. `folder_execute_in_use` (#448) is the pattern:
-            // an answer with a reason beats an effect that reaches further than the question.
-            if (await deps.repository.hasAnyChild(node.id)) {
-                throw new IntelError(409, "folder_not_empty", "This folder still holds entries. Empty it before deleting it for good.");
-            }
-            // ⚠️ The other class of dependant, and the reason it refuses where a prose link does not: a
-            // flow would break at RUN TIME, in front of somebody who did not order this deletion.
-            //
-            // ⚠️ `flowsUsingNode`, NOT `externalFlowCallers` — the first version asked the second and
-            // therefore never refused anything (found in review). `externalFlowCallers` answers "who calls
-            // a FLOW filed inside this folder" (`kind: "subflow"`); a flow reads a NODE through a
-            // tree-link step (`configuration.resourceId`). Two different graph shapes, and only the second
-            // one is what a deleted document breaks.
-            const users = await deps.flowsUsingNode(actor, node.id);
-            if (users.visible.length || users.hidden) {
-                throw new IntelError(409, "node_in_use_by_flow", callersDetail(users));
-            }
+            // #492 replaces the refusal with owned cleanup. Flows inside the tree disappear with it;
+            // published flows outside it are depublished atomically before their dependency vanishes.
+            const tree = await deps.repository.inspectPurgeTree(node.id);
             // Not a refusal — a fact for the record. A prose reference is a mention, not an operation;
-            // refusing over one would make deleting a lottery, decided by whoever once linked to it. The
-            // surface names the number BEFORE the reader says yes.
+            // refusing over one would make deleting a lottery, decided by whoever once linked to it.
+            //
+            // The same count is exposed by `purgePreview`, so the surface can name the consequence before
+            // confirmation. It is counted again here because the audit records the state at deletion time.
             const inboundLinks = await deps.repository.countInboundLinks(node.id);
             // ⚠️ The vectors go FIRST, and the order is the correction of a wrong claim (found in review).
             // The comment here used to say Vectorize needed no call because archiving had already emptied
@@ -901,11 +909,14 @@ export function createNodes(deps) {
             // the rule behind both is the same: DO THE IRRECOVERABLE THING LAST. A failed batch after the
             // vectors are gone leaves an ARCHIVED node whose index can be rebuilt (`reindex`); a failed
             // removal after the batch leaves orphans nothing can name.
-            const vectorKeys = await deps.repository.listVectorKeys(node.id);
+            const vectorKeys = tree.vectorKeys;
             // The whole-node chunk carries the empty key and is never in the table — the pass writes it
             // and records the rest, so a purge that only sent the recorded ones would leave it behind.
-            if (deps.semantic)
-                await deps.semantic.remove(node.id, ["", ...vectorKeys]);
+            if (deps.semantic) {
+                for (const vector of vectorKeys) {
+                    await deps.semantic.remove(vector.nodeId, ["", ...vector.keys]);
+                }
+            }
             const purged = await deps.repository.purgeNode({
                 nodeId: node.id,
                 actorId: actor.id,
@@ -913,7 +924,8 @@ export function createNodes(deps) {
                 occurredAt: deps.now().toISOString(),
                 // ⚠️ The title travels INTO the record from the row itself (the repository reads it there),
                 // and this is what travels beside it. After the delete nothing can look either up.
-                metadata: { inboundLinks },
+                metadata: { inboundLinks, counts: tree.counts },
+                idempotencyKey,
             });
             // The row was restored or already gone between the check and the statement. Nothing was
             // deleted, and saying so is better than reporting a success that did not happen.
@@ -921,13 +933,13 @@ export function createNodes(deps) {
                 throw new IntelError(409, "update_conflict", "This node was changed by another editor");
             }
             // ⚠️ AFTER the database agreed, never before: it is the truth about what exists, and an object
-            // deleted ahead of a batch that then fails would leave a node whose content is gone.
-            //
-            // ⚠️ Vectorize needs no call here, and that follows from the guard above rather than from
-            // luck: archiving already takes a node's vectors out of the index (see `archive`), and only
-            // an archived node reaches this line. What is emptied above is Intel's own bookkeeping.
+            // deleted ahead of a batch that then fails would leave a node whose content is gone. This is
+            // the same rule the vectors follow in the other direction — do the irrecoverable thing last —
+            // and the directions differ because only one of the two can be rebuilt: an index can, an
+            // object cannot.
             for (const key of purged.contentKeys)
                 await deps.content.delete(key);
+            await deps.repository.completePurgeReplay(actor.id, idempotencyKey, deps.now().toISOString());
             return { purged: true, title: node.title };
         },
         async listGrants(actor, resourceId) {
@@ -941,6 +953,14 @@ export function createNodes(deps) {
                 items: await deps.repository.listGrants(resourceId),
             };
         },
+        async listEffectiveAccess(actor, resourceId) {
+            const node = await requireVisible(actor, resourceId);
+            if (!(await deps.repository.can(actor, resourceId, "share"))) {
+                throw new IntelError(403, "node_forbidden", "Sharing of this node cannot be managed");
+            }
+            const effective = await deps.repository.listEffectiveAccess(resourceId);
+            return { resourceId: node.id, ...effective };
+        },
         async listLinks(actor, nodeId) {
             await requireVisible(actor, nodeId);
             return { items: await deps.repository.listLinksVisible(actor, nodeId) };

package/dist/nodes/nodes.types.d.ts

@@ -87,16 +87,36 @@ export interface NodeRepository {
     hasAnyChild(nodeId: string): Promise<boolean>;
     listVectorKeys(nodeId: string): Promise<string[]>;
     countInboundLinks(nodeId: string): Promise<number>;
+    inspectPurgeTree(nodeId: string): Promise<{
+        nodeIds: string[];
+        flowIds: string[];
+        contentKeys: string[];
+        vectorKeys: Array<{
+            nodeId: string;
+            keys: string[];
+        }>;
+        counts: Record<string, number>;
+    }>;
+    findPurgeReplay(actorId: string, idempotencyKey: string): Promise<{
+        title: string;
+        contentKeys: string[];
+    } | null>;
+    completePurgeReplay(actorId: string, idempotencyKey: string, completedAt: string): Promise<void>;
     purgeNode(input: {
         nodeId: string;
         actorId: string;
         auditId: string;
         occurredAt: string;
         metadata: Record<string, unknown>;
+        idempotencyKey: string;
     }): Promise<"missing" | {
         contentKeys: string[];
     }>;
     listGrants(resourceId: string): Promise<ResourceGrant[]>;
+    listEffectiveAccess(resourceId: string): Promise<{
+        ownerIds: string[];
+        items: ResourceGrant[];
+    }>;
     organizationExecuteReaches(nodeId: string, exceptGrantId: string): Promise<boolean>;
     listLinksVisible(actor: Actor, nodeId: string): Promise<NodeLink[]>;
     resolveVisibleTitles(actor: Actor, nodeIds: string[]): Promise<Array<{
@@ -287,11 +307,19 @@ export interface NodeService {
     archive(actor: Actor, input: ArchiveNodeInput): Promise<Node>;
     purge(actor: Actor, input: {
         nodeId: string;
+        idempotencyKey: string;
     }): Promise<{
         purged: true;
         title: string;
     }>;
+    purgePreview(actor: Actor, input: {
+        nodeId: string;
+    }): Promise<{
+        inboundLinks: number;
+        totalItems: number;
+    }>;
     listGrants(actor: Actor, resourceId: string): Promise<ResourceGrantList>;
+    listEffectiveAccess(actor: Actor, resourceId: string): Promise<import("@anchrd/intel-contract/share").ResourceAccessList>;
     listLinks(actor: Actor, nodeId: string): Promise<{
         items: NodeLink[];
     }>;

package/dist/tools/tools.js

@@ -203,11 +203,5 @@ export function createTools(deps) {
             }
             return await call(actor, input);
         },
-        async unavailable(actor, names) {
-            if (names.length === 0)
-                return [];
-            const available = new Set((await capabilities(actor)).map((capability) => capability.name));
-            return names.filter((name) => !available.has(name));
-        },
     };
 }

package/dist/tools/tools.types.d.ts

@@ -53,5 +53,4 @@ export interface ToolService {
     servers(actor: ToolActor): Promise<ToolServerCatalog>;
     execute(actor: ToolActor, input: ExecuteToolInput): Promise<ToolTestResult>;
     test(actor: ToolActor, input: TestToolInput): Promise<ToolTestResult>;
-    unavailable(actor: ToolActor, names: string[]): Promise<string[]>;
 }

package/migrations/0020_cascade_purge_replay.sql

@@ -0,0 +1,11 @@
+-- #492: D1 commits before irreversible R2 deletion. This receipt keeps every object key reachable
+-- when an R2 call fails, and also makes a repeated purge key return the original result.
+CREATE TABLE node_purge_receipts (
+  actor_id TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL,
+  node_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  content_keys_json TEXT NOT NULL,
+  completed_at TEXT,
+  PRIMARY KEY (actor_id, idempotency_key)
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@anchrd/gate-sdk": "^0.15.0",
-    "@anchrd/intel-contract": "^0.16.0",
+    "@anchrd/intel-contract": "^0.18.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",