@anchrd/intel-api 0.19.0 → 0.20.0

package/dist/adapters/cloudflare/cloudflare.js

@@ -117,6 +117,9 @@ export default {
             semantic,
             externalFlowCallers: async (who, folderId) => await flowRepository.externalCallers(who, folderId),
             flowNodeReferences: async (who, folderId) => await flowRepository.nodeReferences(who, folderId),
+            // ⚠️ The real one, like its two neighbours: the refusal is only worth anything if it reads
+            // real published graphs and the real visibility predicate (#457).
+            flowsUsingNode: async (who, nodeId) => await flowRepository.flowsUsingNode({ ...who, canRun: true }, nodeId),
             // ⚠️ `canExecute: true` is not a permission being granted here — the servers list touches
             // nothing and executes nothing. It exists because `ToolActor` carries the flag for the one
             // method that needs it, and a `false` would read as if listing were gated on execution.

package/dist/adapters/db/db-flows.js

@@ -275,6 +275,120 @@ export function createFlowRepository(deps) {
                 hidden: rows.filter((row) => row.visible !== 1).length,
             };
         },
+        // Who calls THIS flow — the sibling of `externalCallers`, which asks the same question about a
+        // whole folder (#457). Same shape: what the actor may see by name, the rest as a number, because
+        // a refusal must not become a way of learning that a flow one cannot see exists.
+        async flowCallers(actor, flowId) {
+            const result = await deps.db
+                .prepare(`${subtreeCte}
+          SELECT DISTINCT ${qualifiedFlowColumns("flow")},
+            CASE WHEN ${flowInSubtree} THEN 1 ELSE 0 END AS visible
+          FROM flows flow
+          JOIN flow_versions version ON version.id = flow.published_version_id
+          JOIN json_each(version.graph_json, '$.nodes') node
+          WHERE json_extract(node.value, '$.kind') = 'subflow'
+            AND json_extract(node.value, '$.configuration.flowId') = ?
+            AND flow.archived_at IS NULL
+            AND flow.id <> ?
+          ORDER BY lower(flow.title), flow.id`)
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), ...flowInSubtreeBindings(actor), flowId, flowId)
+                .all();
+            const rows = result.results ?? [];
+            return {
+                visible: rows.filter((row) => row.visible === 1).map((row) => mapFlow(row).title),
+                hidden: rows.filter((row) => row.visible !== 1).length,
+            };
+        },
+        // Published flows whose graph reads THIS node as a step (#457) — the mirror of `nodeReferences`,
+        // which asks the same graph the other way round ("which documents do the flows in this folder
+        // read"). Same visible/hidden shape as every other refusal: a title only where the actor may see
+        // it, the rest counted, so a refusal never becomes a directory of the tree (ADR-0004 §3).
+        async flowsUsingNode(actor, nodeId) {
+            const result = await deps.db
+                .prepare(`${subtreeCte}
+          SELECT DISTINCT ${qualifiedFlowColumns("flow")},
+            CASE WHEN ${flowInSubtree} THEN 1 ELSE 0 END AS visible
+          FROM flows flow
+          JOIN flow_versions version ON version.id = flow.published_version_id
+          JOIN json_each(version.graph_json, '$.nodes') node
+          WHERE json_extract(node.value, '$.kind') IN (${treeLinkKindList})
+            AND json_extract(node.value, '$.configuration.resourceId') = ?
+            AND flow.archived_at IS NULL
+          ORDER BY lower(flow.title), flow.id`)
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), ...flowInSubtreeBindings(actor), nodeId)
+                .all();
+            const rows = result.results ?? [];
+            return {
+                visible: rows.filter((row) => row.visible === 1).map((row) => mapFlow(row).title),
+                hidden: rows.filter((row) => row.visible !== 1).length,
+            };
+        },
+        // ⚠️ BOTH directions, and the second one was missing (found in review). A run of this flow can be
+        // the PARENT of somebody else's run — deleting it takes the record of what started theirs. It can
+        // just as well be the CHILD of somebody else's run, and deleting that leaves the caller standing
+        // on a sub-flow node whose callee is gone: it can never be completed, and migration 0010's stall
+        // rule then sweeps the caller to `failed`. A history with a hole is not a history, in either
+        // direction.
+        async hasEntangledRuns(flowId) {
+            const row = await deps.db
+                .prepare(`SELECT 1 AS found
+          FROM flow_runs mine
+          JOIN flow_runs other
+            ON other.parent_run_id = mine.id OR other.id = mine.parent_run_id
+          WHERE mine.flow_id = ? AND other.flow_id <> ?
+          LIMIT 1`)
+                .bind(flowId, flowId)
+                .first();
+            return row !== null;
+        },
+        // ⚠️ Archiving deliberately leaves runs in flight alone — restoring the flow is what makes them
+        // readable again (`flows.ts`). A purge takes that way back with it, so a run that has not
+        // finished refuses the deletion rather than being deleted mid-execution.
+        async hasUnfinishedRuns(flowId) {
+            const row = await deps.db
+                .prepare(`SELECT 1 AS found FROM flow_runs
+          WHERE flow_id = ? AND status IN ('queued', 'running', 'waiting') LIMIT 1`)
+                .bind(flowId)
+                .first();
+            return row !== null;
+        },
+        async purgeFlow(input) {
+            const aliveFlow = "EXISTS (SELECT 1 FROM flows f WHERE f.id = ? AND f.archived_at IS NOT NULL)";
+            const deleted = await deps.db.batch([
+                // ⚠️ FIRST, reading the title out of the row that falls at the end of this batch. Afterwards
+                // nothing can look a name up, and an entry carrying only an id names something nobody can
+                // find again (`anchrd/gate#146`).
+                deps.db
+                    .prepare(`INSERT INTO audit_events (
+            id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+          ) SELECT ?, ?, 'flows.purge', 'flow', f.id, json_object('title', f.title), ?
+            FROM flows f WHERE f.id = ? AND f.archived_at IS NOT NULL`)
+                    .bind(input.auditId, input.actorId, input.occurredAt, input.flowId),
+                // The runs are this flow's history: the steps hang off the runs, the runs off the flow.
+                // ⚠️ The guard belongs on EVERY statement, not only the last: a batch whose final statement
+                // matches nothing still COMMITS, so a restore in between would empty a living flow's history
+                // and answer `409` as if nothing had happened.
+                deps.db
+                    .prepare(`DELETE FROM flow_run_steps
+            WHERE run_id IN (SELECT id FROM flow_runs WHERE flow_id = ?) AND ${aliveFlow}`)
+                    .bind(input.flowId, input.flowId),
+                deps.db
+                    .prepare(`DELETE FROM flow_runs WHERE flow_id = ? AND ${aliveFlow}`)
+                    .bind(input.flowId, input.flowId),
+                deps.db
+                    .prepare(`DELETE FROM flow_versions WHERE flow_id = ? AND ${aliveFlow}`)
+                    .bind(input.flowId, input.flowId),
+                deps.db
+                    .prepare(`DELETE FROM idempotency_keys WHERE resource_id = ? AND ${aliveFlow}`)
+                    .bind(input.flowId, input.flowId),
+                // ⚠️ LAST, and still guarded — a restore between the service's check and this statement
+                // would otherwise cost a living flow.
+                deps.db
+                    .prepare("DELETE FROM flows WHERE id = ? AND archived_at IS NOT NULL")
+                    .bind(input.flowId),
+            ]);
+            return (deleted.at(-1)?.meta?.changes ?? 0) === 0 ? "missing" : { purged: true };
+        },
         // The documents the flows in this folder's subtree read, so whoever shares the folder
         // can be told what the grant does not cover (ADR-0004 §4).
         //

package/dist/adapters/db/db.js

@@ -620,6 +620,106 @@ export function createNodeRepository(deps) {
                 .first();
             return row ? mapNode(row) : "conflict";
         },
+        async hasAnyChild(nodeId) {
+            // ⚠️ Without a visibility predicate and without an archived filter, both on purpose: this
+            // answers whether the row can be deleted at all, not what somebody may look at (#457).
+            //
+            // ⚠️ BOTH tables, and that is not defensive breadth: knowledge and flows share ONE tree
+            // (ADR-0004), `flows.parent_id` references `nodes(id)` since migration 0002, and a folder whose
+            // only content is a flow answered "empty" while it was not. Purging it left the flow with a
+            // parent that no longer exists — invisible in the tree, unreachable, unmovable.
+            const row = await deps.db
+                .prepare(`SELECT 1 AS found FROM nodes WHERE parent_id = ?
+          UNION ALL
+          SELECT 1 AS found FROM flows WHERE parent_id = ?
+          LIMIT 1`)
+                .bind(nodeId, nodeId)
+                .first();
+            return row !== null;
+        },
+        // The names this node's vectors carry in the external index. They are read BEFORE the row falls,
+        // because `node_vectors` is the only thing that knows them — and once it is gone, an orphan in
+        // Vectorize can never be named again (#457).
+        async listVectorKeys(nodeId) {
+            const rows = await deps.db
+                .prepare("SELECT chunk_key FROM node_vectors WHERE node_id = ?")
+                .bind(nodeId)
+                .all();
+            return (rows.results ?? []).map((row) => row.chunk_key);
+        },
+        async countInboundLinks(nodeId) {
+            const row = await deps.db
+                .prepare("SELECT COUNT(*) AS n FROM node_links WHERE target_node_id = ?")
+                .bind(nodeId)
+                .first();
+            return row?.n ?? 0;
+        },
+        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 = ?")
+                .bind(input.nodeId)
+                .all();
+            // ⚠️ The guard belongs on EVERY statement, not only on the last one (found in review). A
+            // `D1.batch` is one implicit transaction, but a final statement that changes ZERO rows is not
+            // an error — the transaction commits. With the condition only at the end, a restore between
+            // the service's check and this batch deleted every version, grant, link and index row of a
+            // node that was alive again, left its row standing, and answered `409 update_conflict`: the
+            // 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 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
+                // not book one.
+                deps.db
+                    .prepare(`INSERT INTO audit_events (
+            id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+          ) SELECT ?, ?, 'node.purge', 'node', n.id,
+              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),
+                // 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}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`DELETE FROM node_vectors WHERE node_id = ? 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}`)
+                    .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),
+                // 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}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`DELETE FROM node_versions WHERE node_id = ? 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}`)
+                    .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),
+            ]);
+            const removed = deleted.at(-1)?.meta?.changes ?? 0;
+            if (removed === 0)
+                return "missing";
+            return { contentKeys: [...new Set((keys.results ?? []).map((row) => row.content_key))] };
+        },
         async appendVersion(input) {
             const version = input.version;
             await deps.db.batch([

package/dist/flows/flows.js

@@ -270,6 +270,16 @@ function decodeCursor(cursor) {
         throw new IntelError(400, "flow_run_cursor_invalid", "Page cursor is invalid");
     return { createdAt, id };
 }
+// ⚠️ Named where the reader may see it, counted where they may not — the same rule the folder's
+// refusal follows (`callersDetail` in nodes.ts): a refusal must not become a way of learning that a
+// flow one cannot see exists (ADR-0004 §3).
+function callersDetail(callers) {
+    const named = callers.visible.map((title) => `“${title}”`).join(", ");
+    const rest = callers.hidden === 0
+        ? ""
+        : `${named ? " and " : ""}${callers.hidden} more flow${callers.hidden === 1 ? "" : "s"} you cannot see`;
+    return `Published flows still call this one: ${named}${rest}. Change or unpublish them first.`;
+}
 export function createFlows(deps) {
     async function requireFlow(actor, flowId) {
         const flow = await deps.repository.getVisible(actor, flowId);
@@ -1146,6 +1156,48 @@ export function createFlows(deps) {
             }
             return updated;
         },
+        /**
+         * ⚠️ The flow half of #457 — after this a flow is really gone, with its versions and the record
+         * of every run it ever had. Read the decisions on that issue before touching it.
+         */
+        async purge(actor, input) {
+            const current = await deps.repository.getVisible(actor, input.flowId);
+            if (!current)
+                throw new IntelError(404, "flow_not_found", "Flow was not found");
+            if (!(await deps.repository.can(actor, input.flowId, "write"))) {
+                throw new IntelError(403, "flow_edit_forbidden", "Flow cannot be edited");
+            }
+            // ⚠️ THE structural guard, same as the node's: a living flow has no path into nothing.
+            if (!current.archivedAt) {
+                throw new IntelError(409, "flow_not_archived", "Only an archived flow can be deleted for good. Archive it first.");
+            }
+            // A published caller would break at RUN TIME, in front of somebody who did not order this.
+            const callers = await deps.repository.flowCallers(actor, current.id);
+            if (callers.visible.length || callers.hidden) {
+                throw new IntelError(409, "flow_in_use_by_flow", callersDetail(callers));
+            }
+            // ⚠️ The one thing a flow has that a node does not: its runs can be the PARENT of runs
+            // belonging to other flows. Deleting them would take the record of who started those runs
+            // with it — a history with a hole is not a history, so this refuses instead.
+            if (await deps.repository.hasEntangledRuns(current.id)) {
+                throw new IntelError(409, "flow_runs_entangled", "Runs of this flow are tied to runs of other flows. Deleting them would leave those without the record of what started them, or without the run they are waiting for.");
+            }
+            // ⚠️ Archiving deliberately leaves a run in flight alone, because restoring the flow makes it
+            // readable again. A purge takes that way back with it — so an unfinished run refuses.
+            if (await deps.repository.hasUnfinishedRuns(current.id)) {
+                throw new IntelError(409, "flow_runs_unfinished", "This flow still has runs that have not finished. Wait for them or cancel them first.");
+            }
+            const purged = await deps.repository.purgeFlow({
+                flowId: current.id,
+                actorId: actor.id,
+                auditId: deps.id(),
+                occurredAt: deps.now().toISOString(),
+            });
+            if (purged === "missing") {
+                throw new IntelError(409, "flow_update_conflict", "Flow was changed by another editor");
+            }
+            return { purged: true, title: current.title };
+        },
         /**
          * Archive a flow, or take it back out again.
          *

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

@@ -88,6 +88,24 @@ export interface FlowRepository {
         idempotencyKey: string;
         auditId: string;
     }): Promise<"conflict" | Flow>;
+    flowsUsingNode(actor: FlowActor, nodeId: string): Promise<{
+        visible: string[];
+        hidden: number;
+    }>;
+    flowCallers(actor: FlowActor, flowId: string): Promise<{
+        visible: string[];
+        hidden: number;
+    }>;
+    hasEntangledRuns(flowId: string): Promise<boolean>;
+    hasUnfinishedRuns(flowId: string): Promise<boolean>;
+    purgeFlow(input: {
+        flowId: string;
+        actorId: string;
+        auditId: string;
+        occurredAt: string;
+    }): Promise<"missing" | {
+        purged: true;
+    }>;
     getVersion(versionId: string): Promise<FlowVersion | null>;
     listVersions(flowId: string): Promise<Omit<FlowVersionSummary, "published">[]>;
     getVersions(versionIds: string[]): Promise<FlowVersion[]>;
@@ -213,6 +231,12 @@ export interface FlowService {
     create(actor: FlowActor, input: CreateFlowInput): Promise<Flow>;
     update(actor: FlowActor, input: UpdateFlowInput): Promise<Flow>;
     archive(actor: FlowActor, input: ArchiveFlowInput): Promise<Flow>;
+    purge(actor: FlowActor, input: {
+        flowId: string;
+    }): Promise<{
+        purged: true;
+        title: string;
+    }>;
     save(actor: FlowActor, input: SaveFlowVersionInput): Promise<FlowDocument>;
     previewPublish(actor: FlowActor, input: PreviewFlowPublishInput): Promise<FlowPublishPreview>;
     publish(actor: FlowActor, input: PublishFlowInput): Promise<Flow>;

package/dist/http/http.js

@@ -1,6 +1,6 @@
-import { ArchiveFlowInput, CreateFlowInput, GetFlowInput, GetFlowVersionInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraphInput, SaveFlowVersionInput, UnpublishFlowInput, UpdateFlowInput, } from "@anchrd/intel-contract/flow";
+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, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "@anchrd/intel-contract/node";
+import { ArchiveNodeInput, CreateNodeInput, GetNodeInput, GetNodeVersionInput, ListNodesInput, NodeGraphInput, PurgeNodeInput, 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";
@@ -360,6 +360,15 @@ export function createHttp(deps) {
         // Application behind an agent (#182). Every other kind never reaches it.
         return context.json(await deps.nodes.archive(asActor(auth), input));
     });
+    // ⚠️ DELETE, and it means it (#457). Every other "delete" in this surface is `archived_at`; this
+    // one leaves nothing behind. The same capability as archiving — `nodes.write` — because the
+    // structural guard is elsewhere: only an archived node can be purged, so the destructive way has
+    // 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") });
+        return context.json(await deps.nodes.purge(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")));
@@ -475,6 +484,12 @@ export function createHttp(deps) {
         }
         return context.json(await deps.flows.archive(asFlowActor(auth), input));
     });
+    // ⚠️ DELETE, and it means it (#457) — the flow's versions and the record of every run it had.
+    app.delete("/flows/:flowId", async (context) => {
+        const auth = requireCapability(context, "flows", "write");
+        const input = PurgeFlowInput.parse({ flowId: context.req.param("flowId") });
+        return context.json(await deps.flows.purge(asFlowActor(auth), input));
+    });
     app.post("/flows/:flowId/versions", async (context) => {
         const auth = requireCapability(context, "flows", "write");
         const input = SaveFlowVersionInput.parse(await context.req.json().catch(() => null));

package/dist/mcp/mcp.js

@@ -1,7 +1,7 @@
 import { IdempotencyKey, IntelId } from "@anchrd/intel-contract";
-import { ArchiveFlowInput, CreateFlowInput, GetFlowInput, GetFlowVersionInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraphInput, SaveFlowVersionInput, UnpublishFlowInput, UpdateFlowInput, } from "@anchrd/intel-contract/flow";
+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, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "@anchrd/intel-contract/node";
+import { ArchiveNodeInput, CreateNodeInput, GetNodeInput, GetNodeVersionInput, ListNodesInput, NodeGraphInput, PurgeNodeInput, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "@anchrd/intel-contract/node";
 import { ListGrantsInput, RevokeGrantInput, ShareInput } from "@anchrd/intel-contract/share";
 import { AppendTableRowsInput, DefineTableInput, DeleteTableRowsInput, GetTableInput, RedefineTableInput, UpdateTableRowsInput, } from "@anchrd/intel-contract/table";
 import { ExecuteToolInput, TestToolInput } from "@anchrd/intel-contract/tool";
@@ -464,6 +464,26 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.archive(actor, input)));
+        // ⚠️ It exists on this surface for the reason #436 states: a way only the interface has is a way
+        // an agent goes around, by looking for the row in the database. What it may do is bounded by the
+        // same rules the interface obeys — only an archived node, only an empty folder, never one a flow
+        // still uses.
+        server.registerTool("node_purge", {
+            title: "Delete node for good",
+            description: "Delete one ARCHIVED node and everything belonging to it — every version, its content, its grants and its entries in the search index. This cannot be undone. A living node is refused: archive it first. A folder is refused while it still holds anything, and so is a node a published flow uses as a step; documents that merely LINK to it are not, and their links break.",
+            inputSchema: PurgeNodeInput,
+            annotations: {
+                title: "Delete node for good",
+                readOnlyHint: false,
+                destructiveHint: true,
+                // ⚠️ NOT idempotent, and that is the honest answer rather than a missing flag: calling it
+                // twice deletes once and then answers 404. A client that repeated it on a timeout would
+                // otherwise read the second answer as "already done" when it may mean "somebody else's
+                // node with that id is gone".
+                idempotentHint: false,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.purge(actor, input)));
     }
     if (permits(deps.authorization, "nodes", "share")) {
         server.registerTool("node_grant_list", {
@@ -689,6 +709,21 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.flows.archive(flowActor, input)));
+        // ⚠️ On this surface because a way only the UI has is a way an agent works around (#436). Its
+        // limits are the same as the UI's.
+        server.registerTool("flow_purge", {
+            title: "Delete flow for good",
+            description: "Delete one ARCHIVED flow together with every version and the record of every run it had. This cannot be undone. A living flow is refused: archive it first. So is a flow another published flow still calls, and one whose runs started runs of other flows.",
+            inputSchema: PurgeFlowInput,
+            annotations: {
+                title: "Delete flow for good",
+                readOnlyHint: false,
+                destructiveHint: true,
+                // Not idempotent, and that is the honest answer: twice deletes once and then answers 404.
+                idempotentHint: false,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.purge(flowActor, input)));
         server.registerTool("flow_version_create", {
             title: "Create flow version",
             description: "Append a validated immutable flow graph version with optimistic concurrency.",

package/dist/nodes/nodes.js

@@ -849,6 +849,87 @@ export function createNodes(deps) {
                 await deps.indexing.enqueue(updated.currentVersionId);
             return updated;
         },
+        /**
+         * ⚠️ The one call in Intel after which something is really gone (#457). Read the decisions on
+         * that issue before changing anything here: each refusal below is one of them, and each was
+         * chosen to the safer side.
+         */
+        async purge(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");
+            }
+            // ⚠️ THE structural guard: only what is already archived may go. A stronger PERMISSION would
+            // not have made this safer, only rarer — whoever may archive can already make the content
+            // invisible. What makes it safe is that the destructive path has two steps and the first one
+            // is reversible.
+            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));
+            }
+            // 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.
+            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
+            // it. Archiving only ENQUEUES the purge, and that pass starts from `archivedNodeId(versionId)`
+            // — a join over `nodes`. Once this batch has run, that answers `null` and removes nothing,
+            // while `node_vectors`, the only record of what the vectors are CALLED, is gone with it. The
+            // orphans would then be unnameable forever, and each one keeps a place in the 100-candidate
+            // list Vectorize caps per installation.
+            //
+            // ⚠️ Before the batch rather than after, which inverts the order the content keys follow — and
+            // 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);
+            // 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]);
+            const purged = await deps.repository.purgeNode({
+                nodeId: node.id,
+                actorId: actor.id,
+                auditId: deps.id(),
+                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 },
+            });
+            // 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.
+            if (purged === "missing") {
+                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.
+            for (const key of purged.contentKeys)
+                await deps.content.delete(key);
+            return { purged: true, title: node.title };
+        },
         async listGrants(actor, resourceId) {
             const node = await requireVisible(actor, resourceId);
             if (!(await deps.repository.can(actor, resourceId, "share"))) {

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

@@ -84,6 +84,18 @@ export interface NodeRepository {
         idempotencyKey: string;
         auditId: string;
     }): Promise<"conflict" | Node>;
+    hasAnyChild(nodeId: string): Promise<boolean>;
+    listVectorKeys(nodeId: string): Promise<string[]>;
+    countInboundLinks(nodeId: string): Promise<number>;
+    purgeNode(input: {
+        nodeId: string;
+        actorId: string;
+        auditId: string;
+        occurredAt: string;
+        metadata: Record<string, unknown>;
+    }): Promise<"missing" | {
+        contentKeys: string[];
+    }>;
     listGrants(resourceId: string): Promise<ResourceGrant[]>;
     organizationExecuteReaches(nodeId: string, exceptGrantId: string): Promise<boolean>;
     listLinksVisible(actor: Actor, nodeId: string): Promise<NodeLink[]>;
@@ -189,6 +201,19 @@ export interface NodesDeps {
         hidden: number;
     }>;
     flowNodeReferences(actor: Actor, folderId: string): Promise<string[]>;
+    /**
+     * Published flows that use THIS node as a step (#457).
+     *
+     * ⚠️ Not the same question as `externalFlowCallers`, and the difference cost a refusal that never
+     * fired: that one asks who calls a FLOW filed inside a folder (`kind: "subflow"`,
+     * `configuration.flowId`). A flow reads a NODE through a tree-link step (`configuration
+     * .resourceId`) — a different graph shape entirely, and the one a deletion breaks at run time, in
+     * front of somebody who did not order it.
+     */
+    flowsUsingNode(actor: Actor, nodeId: string): Promise<{
+        visible: string[];
+        hidden: number;
+    }>;
     /**
      * The handles of the MCP servers this actor reaches through the portal right now (D30).
      *
@@ -260,6 +285,12 @@ export interface NodeService {
      * is off, which stops working loudly and is repaired by repeating the call.
      */
     archive(actor: Actor, input: ArchiveNodeInput): Promise<Node>;
+    purge(actor: Actor, input: {
+        nodeId: string;
+    }): Promise<{
+        purged: true;
+        title: string;
+    }>;
     listGrants(actor: Actor, resourceId: string): Promise<ResourceGrantList>;
     listLinks(actor: Actor, nodeId: string): Promise<{
         items: NodeLink[];

package/package.json

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