@anchrd/intel-api 0.19.0 → 0.21.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,206 @@ 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(`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(`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
+            // `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 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
+                // 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),
+                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(`${tree} DELETE FROM node_fts WHERE node_id IN (SELECT id FROM tree) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`${tree} DELETE FROM node_vectors WHERE node_id IN (SELECT id FROM tree) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .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(`${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(`${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(`${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(`${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(`${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)
+                return "missing";
+            return { contentKeys: [...new Set((keys.results ?? []).map((row) => row.content_key))] };
+        },
         async appendVersion(input) {
             const version = input.version;
             await deps.db.batch([
@@ -813,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.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, 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";
@@ -360,10 +360,31 @@ 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(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));
@@ -475,6 +496,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

@@ -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.
@@ -849,6 +863,85 @@ 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 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");
+            }
+            // ⚠️ 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.");
+            }
+            // #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 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
+            // 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 = 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) {
+                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,
+                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, 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.
+            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. 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) {
             const node = await requireVisible(actor, resourceId);
             if (!(await deps.repository.can(actor, resourceId, "share"))) {
@@ -860,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

@@ -84,7 +84,39 @@ 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>;
+    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<{
@@ -189,6 +221,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,7 +305,21 @@ 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;
+        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/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.19.0",
+  "version": "0.21.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.17.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",