@anchrd/intel-api 0.25.0 → 0.26.0

package/dist/bundle/bundle.js

@@ -7,9 +7,33 @@ import { documentLinkTargets } from "../nodes/document-links/document-links.js";
 import { parseCsv } from "../shared/csv/csv.js";
 import { IntelError } from "../shared/intel-error/intel-error.js";
 import { plainTitle } from "../shared/plain-title/plain-title.js";
-// What every bundle leaves out, by decision rather than by accident (#136). The manifest says so,
-// because a backup that is silent about what it does not hold will be trusted with exactly that.
-const Excluded = ["version-history", "grants", "flow-runs", "archived-nodes"];
+/**
+ * What every bundle leaves out, by decision rather than by accident (#136, ADR-0006). The manifest
+ * says so, because a backup that is silent about what it does not hold will be trusted with exactly
+ * that.
+ *
+ * ⚠️ ONE list, read by both halves of the round trip: the export writes it into `manifest.json`,
+ * and the import answers with it in `BundleImportResult.excluded` (#433). The import does NOT read
+ * the word back out of the manifest it was handed — a bundle claiming `excluded: []` would
+ * otherwise make the import report that nothing was left behind, and a naked folder carries no
+ * manifest to ask at all. Every one of the five holds for every import this build performs: a node
+ * arrives with `sequence: 1` and nothing older, an import mints no grants, it starts no runs,
+ * nothing it creates is archived, and a published flow's graph is the one that was published.
+ *
+ * ⚠️ `unpublished-flow-changes` is a CONSTANT of the build like the other four, not a report about
+ * this particular bundle (#585). It says what a bundle never carries — the edits made to a flow
+ * after it was published — in the same way `version-history` says so for a node with a single
+ * version. A list that named only the losses this one export happens to suffer would be a different
+ * kind of statement, and the import could not make it at all: it answers before it knows what is in
+ * the zip, and from a naked folder it never finds out.
+ */
+const Excluded = [
+    "version-history",
+    "grants",
+    "flow-runs",
+    "archived-nodes",
+    "unpublished-flow-changes",
+];
 /**
  * A title as a file name. Titles are free text and zip paths are not: a separator would move the
  * entry, a control character corrupts the archive listing, and a trailing dot breaks extraction on
@@ -498,6 +522,27 @@ export function createBundle(deps) {
                 : { type: "text", load: textLoader(version.contentKey) },
         };
     }
+    /**
+     * Which graph of a flow travels: the PUBLISHED one when the flow has one, the draft otherwise.
+     * Three call sites read it through this function rather than spelling the fallback out, because
+     * it is one decision and not three (#585).
+     *
+     * ⚠️ For a flow that was published and edited afterwards, this deliberately leaves the newer draft
+     * behind — and that is NOT the `version-history` case, which is why `Excluded` names it with a
+     * word of its own. The draft is the newest state there is; what decides against it is that the
+     * import cannot carry both. It creates rather than restores (ADR-0006): every flow arrives as a
+     * draft with one version and `publishedVersionId: null`, so "published v1 plus draft v2" has no
+     * shape on the far side, and carrying both would be flow version history — the thing that ADR
+     * refuses for exactly the reasons it lists.
+     *
+     * Of the two single answers the published one wins because it is the one that was IN EFFECT. A
+     * draft need never have been validated — publishing is what checks a graph — so moving the draft
+     * instead would replace a running process with somebody's unfinished edit, silently, at the one
+     * moment nobody can compare against the source any more.
+     */
+    function exportedVersionId(flow) {
+        return flow.publishedVersionId ?? flow.currentVersionId;
+    }
     function plannedFlow(flow, version, directory, used) {
         const path = `${directory}${uniqueName(used, sanitizeName(flow.title), ".json")}`;
         return {
@@ -547,9 +592,7 @@ export function createBundle(deps) {
         if (actor.canReadFlows) {
             const folderIds = new Set(rows.filter((row) => row.node.kind === "folder").map((row) => row.node.id));
             const visible = (await deps.flows.listVisible(asFlowActor(actor))).filter((flow) => flow.parentId === null ? rootId === null : folderIds.has(flow.parentId));
-            const versionIds = visible
-                .map((flow) => flow.publishedVersionId ?? flow.currentVersionId)
-                .filter((id) => id !== null);
+            const versionIds = visible.map(exportedVersionId).filter((id) => id !== null);
             for (const version of await deps.flows.getVersions(versionIds)) {
                 flowVersions.set(version.id, version);
             }
@@ -591,7 +634,7 @@ export function createBundle(deps) {
                     continue;
                 }
                 if (item.flow !== null) {
-                    const versionId = item.flow.publishedVersionId ?? item.flow.currentVersionId;
+                    const versionId = exportedVersionId(item.flow);
                     entries.push(plannedFlow(item.flow, versionId === null ? undefined : flowVersions.get(versionId), directory, used));
                 }
             }
@@ -823,6 +866,9 @@ export function createBundle(deps) {
             flows: typeof metadata.flows === "number" ? metadata.flows : 0,
             rootNodeIds: Array.isArray(metadata.rootNodeIds) ? metadata.rootNodeIds : [],
             replayed: true,
+            // Not read out of the stored metadata: a replay answers for an import this build performed,
+            // and the list is what this build leaves behind rather than something an earlier row said.
+            excluded: Excluded,
         });
     }
     return {
@@ -840,7 +886,7 @@ export function createBundle(deps) {
             if (!flow || flow.archivedAt !== null) {
                 throw new IntelError(404, "flow_not_found", "Flow was not found");
             }
-            const versionId = flow.publishedVersionId ?? flow.currentVersionId;
+            const versionId = exportedVersionId(flow);
             const version = versionId === null ? undefined : (await deps.flows.getVersions([versionId]))[0];
             const entries = [plannedFlow(flow, version, "", new Set())];
             // A single flow's bundle is rooted at the flow itself: the manifest names it as the root the
@@ -1124,7 +1170,13 @@ export function createBundle(deps) {
             for (const version of versions) {
                 await deps.indexing.enqueue(version.id);
             }
-            return { nodes: nodes.length, flows: flows.length, rootNodeIds, replayed: false };
+            return {
+                nodes: nodes.length,
+                flows: flows.length,
+                rootNodeIds,
+                replayed: false,
+                excluded: Excluded,
+            };
         },
     };
 }

package/dist/flows/flows.js

@@ -1,4 +1,5 @@
 import { flowNodeLayer } from "@anchrd/intel-contract/flow";
+import { callersPhrase, namedOrCounted } from "../shared/callers/callers.js";
 import { requireFutureExpiry } from "../shared/grant-expiry/grant-expiry.js";
 import { IntelError } from "../shared/intel-error/intel-error.js";
 import { plainTitle } from "../shared/plain-title/plain-title.js";
@@ -111,20 +112,28 @@ function toolStepDetail(missing) {
         ? `You do not reach this tool server in the portal: ${missing.join(", ")}`
         : `You do not reach these tool servers in the portal: ${missing.join(", ")}`;
 }
+/**
+ * ⚠️ How every refusal on this file names a node: by the label the canvas draws, because the id
+ * appears nowhere on screen. `Node n-doc is a link and must be attached to a step` sent an author
+ * looking for a string the editor never draws, and the way to the cause led through the contract
+ * schema instead of through the sentence (#508). The id stays beside it: a graph arrives over MCP
+ * as readily as from the canvas, and there the id is what the caller holds.
+ *
+ * ⚠️ One function rather than one spelling per call site (#551): the publish-time refusals name a
+ * node too, and two places building the same string by hand is how the two halves of one sentence
+ * drift while both keep looking right.
+ */
+function nodeName(node) {
+    return `"${node.label}" (${node.id})`;
+}
 export function compileFlow(graph) {
     const nodes = new Map();
-    // ⚠️ A refusal names a node the way the canvas does — by its label — because the id appears
-    // nowhere on screen. `Node n-doc is a link and must be attached to a step` sent an author looking
-    // for a string the editor never draws, and the way to the cause led through the contract schema
-    // instead of through the sentence (#508). The id stays beside it: a graph arrives over MCP as
-    // readily as from the canvas, and there the id is what the caller holds.
-    //
     // ⚠️ It stands ABOVE the loop that fills the map on purpose, so the duplicate-id refusal reaches
     // it too — that one names the node the map already holds, which is the FIRST of the two. An id
     // nothing knows falls back to the bare id, which is what the dangling-edge case wants anyway.
     const named = (id) => {
         const node = nodes.get(id);
-        return node ? `"${node.label}" (${id})` : id;
+        return node ? nodeName(node) : id;
     };
     for (const node of graph.nodes) {
         if (nodes.has(node.id))
@@ -314,14 +323,14 @@ function decodeCursor(cursor) {
     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).
+// refusal follows, out of the same place (`callersPhrase`): a refusal must not become a way of
+// learning that a flow one cannot see exists (ADR-0004 §3).
+//
+// ⚠️ The SENTENCE stays its own, and that is deliberate (#593): the folder's says a grant cannot be
+// narrowed yet, this one says a flow cannot be deleted for good. Same facts, different consequence
+// — a single parameterised sentence would save a string and cost each refusal its reason.
 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.`;
+    return `Published flows still call this one: ${callersPhrase(callers)}. Change or unpublish them first.`;
 }
 export function createFlows(deps) {
     async function requireFlow(actor, flowId) {
@@ -1372,9 +1381,13 @@ export function createFlows(deps) {
                 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.
+            // ⚠️ The callers travel as DATA beside the sentence (#593, the second half of #448): the
+            // archive shows this refusal, and a German or Spanish screen could otherwise do nothing but
+            // print the English one. The sentence stays for a model over MCP, which has nothing to
+            // formulate with.
             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));
+                throw new IntelError(409, "flow_in_use_by_flow", callersDetail(callers), namedOrCounted(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
@@ -1518,9 +1531,18 @@ export function createFlows(deps) {
             compileFlow(version.graph);
             const wanted = [...new Set(treeLinkNodes(version.graph).map(resourceIdOf))];
             const reachable = new Set((await reachableNodes(actor, wanted)).map((reference) => reference.id));
-            for (const resourceId of wanted) {
-                if (!reachable.has(resourceId)) {
-                    throw new IntelError(409, "flow_node_unavailable", `Node reference is unavailable: ${resourceId}`);
+            // ⚠️ Asked over the deduplicated resource ids and REFUSED over the nodes (#551). The resource
+            // id is what the ACL answers about, and it is also the one thing the author cannot look up:
+            // it stands in no place the editor draws, so `Node reference is unavailable: n-01H…` named
+            // the failure after the only participant nobody can find. The link node beside it carries the
+            // label on the canvas, so the refusal names that instead.
+            //
+            // ⚠️ Naming the label reveals nothing the ACL is keeping: it is the author's own text in
+            // their own graph, already on their screen — unlike the run-time refusal, which counts the
+            // documents rather than naming them because there the READER may not see them (#17, #19).
+            for (const node of treeLinkNodes(version.graph)) {
+                if (!reachable.has(resourceIdOf(node))) {
+                    throw new IntelError(409, "flow_node_unavailable", `Node ${nodeName(node)} names a document you cannot reach`);
                 }
             }
             for (const node of version.graph.nodes) {

package/dist/http/http.js

@@ -8,7 +8,7 @@ import { Hono } from "hono";
 import { z } from "zod";
 import { authorizeBearer, bearer, permits, } from "../shared/gate-authorization/gate-authorization.js";
 import { IntelError } from "../shared/intel-error/intel-error.js";
-import { problemDetails as problem } from "../shared/problem-details/problem-details.js";
+import { intelProblem, problemDetails as problem, } from "../shared/problem-details/problem-details.js";
 import { reportUnexpectedError } from "../shared/report-unexpected-error/report-unexpected-error.js";
 // A query string is a door to the outside like a body is, so what arrives through it is closed
 // rather than tolerated: `z.strictObject` refuses an unknown field, and this is that refusal for the
@@ -94,7 +94,7 @@ export function createHttp(deps) {
     }
     app.onError((error, context) => {
         if (error instanceof IntelError) {
-            return context.json(problem(error.status, error.code, error.message), error.status);
+            return context.json(intelProblem(error), error.status);
         }
         if (error instanceof z.ZodError) {
             return context.json(problem(400, "invalid_request", "Request validation failed", z.prettifyError(error)), 400);
@@ -440,8 +440,28 @@ export function createHttp(deps) {
         const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
         return context.json(await deps.flows.get(asFlowActor(auth), input.flowId));
     });
-    // A single flow as the same bundle shape a node export makes: one entry plus the manifest
-    // (#136). `flows/read` like every other read of the graph.
+    /**
+     * A single flow as the same bundle shape a node export makes: one entry plus the manifest
+     * (#136). `flows/read` like every other read of the graph.
+     *
+     * ⚠️ Deliberately no `flow_export` tool beside it, and the reason is NOT the one `node_export`
+     * carries (#436). There the memory argument decides — a subtree's zip would have to fit in Worker
+     * memory twice — and a flow bundle is one entry plus the manifest, so that argument does not
+     * reach here.
+     *
+     * What decides here is that the manifest of ONE entry answers nothing MCP does not already
+     * answer. `node_export` is worth a tool because its manifest is the PLAN of a subtree: every
+     * readable entry with its path, kind and media type, which is the map for fetching each one. For
+     * a single flow that map has one row, whose id the caller already holds — and the substance, the
+     * graph, is `flow_version_get` and `flow_graph`, with the record itself in `flow_get`. A tool
+     * whose whole answer is two other tools' answers costs bytes in every `tools/list` and makes the
+     * other names less reliable as a guide, which `packages/api/CLAUDE.md` treats as the cost it is.
+     *
+     * ⚠️ This is not the case `.claude/rules/destructive.md` warns about — "a way only the surface
+     * has is a way an agent works around". Nothing about a flow is unreachable over MCP; only the zip
+     * CONTAINER is HTTP-only, exactly as it is for nodes. `mcp.e2e.ts` pins that this exception is
+     * named rather than merely absent.
+     */
     app.get("/flows/:flowId/export", async (context) => {
         const auth = requireCapability(context, "flows", "read");
         const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });

package/dist/intel/intel.js

@@ -3,7 +3,7 @@ import { createHttp } from "../http/http.js";
 import { handleMcp } from "../mcp/mcp.js";
 import { authorize, authorizeBearer, bearer, } from "../shared/gate-authorization/gate-authorization.js";
 import { IntelError } from "../shared/intel-error/intel-error.js";
-import { problemDetails } from "../shared/problem-details/problem-details.js";
+import { intelProblem, problemDetails } from "../shared/problem-details/problem-details.js";
 import { reportUnexpectedError } from "../shared/report-unexpected-error/report-unexpected-error.js";
 export function createIntel(deps) {
     const baseUrl = deps.baseUrl.replace(/\/+$/, "");
@@ -16,7 +16,7 @@ export function createIntel(deps) {
     const app = new Hono();
     app.onError((error, context) => {
         if (error instanceof IntelError) {
-            return context.json(problemDetails(error.status, error.code, error.message), error.status);
+            return context.json(intelProblem(error), error.status);
         }
         // An IntelError is an expected refusal and explains itself; the unknown exception must leave a
         // trace, or the 500 is undiagnosable — the worker answered, so the platform records no

package/dist/mcp/mcp.js

@@ -1,8 +1,8 @@
 import { IdempotencyKey, IntelId } from "@anchrd/intel-contract";
 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 { ListFlowGrantsInput, ListGrantsInput, RevokeFlowGrantInput, RevokeGrantInput, ShareFlowInput, ShareInput, } from "@anchrd/intel-contract/share";
+import { ArchiveNodeInput, CreateNodeInput, GetNodeInput, GetNodeVersionInput, ListNodesInput, NodeGraphInput, PurgeNodeInput, PurgeNodePreviewInput, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "@anchrd/intel-contract/node";
+import { ListEffectiveAccessInput, ListFlowEffectiveAccessInput, ListFlowGrantsInput, ListGrantsInput, RevokeFlowGrantInput, RevokeGrantInput, ShareFlowInput, 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";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -13,6 +13,44 @@ import { IntelError } from "../shared/intel-error/intel-error.js";
 function text(value) {
     return { content: [{ type: "text", text: JSON.stringify(value) }], isError: false };
 }
+/**
+ * ⚠️ The one thing a tool error loses on its way out, and the whole reason this `catch` exists
+ * (#597).
+ *
+ * A thrown `IntelError` is turned into a tool error by the SDK's `createToolError`, which keeps
+ * `error instanceof Error ? error.message : String(error)` and nothing else — so `callers`, the
+ * structured half of a refusal that NAMES flows (#448, #593), never reaches a model over MCP.
+ *
+ * It arrives here as a SECOND content block. The first one is the sentence, byte for byte what the
+ * SDK would have sent, so a reader that only takes text loses nothing: the machine-readable half
+ * stands beside the prose rather than instead of it.
+ *
+ * ⚠️ It wraps the handlers whose service can refuse WITH data — `node_grant_revoke` and
+ * `flow_purge` today — and deliberately NOT all sixty. For every other refusal there is nothing to
+ * carry, and turning each of their errors into JSON would change every tool for the sake of two.
+ * What keeps that from becoming a place to forget is where the rule is written down: at the field
+ * itself (`IntelError.callers`), in `packages/api/CLAUDE.md`, and as two tests in `mcp.e2e.ts` —
+ * whoever attaches `callers` to a new refusal wraps its handler here.
+ */
+async function refusing(run) {
+    try {
+        return text(await run());
+    }
+    catch (error) {
+        if (!(error instanceof IntelError) || !error.callers)
+            throw error;
+        return {
+            content: [
+                { type: "text", text: error.message },
+                {
+                    type: "text",
+                    text: JSON.stringify({ code: error.code, callers: error.callers }),
+                },
+            ],
+            isError: true,
+        };
+    }
+}
 /**
  * ⚠️ One name per tool, and the second one is gone for good (#149).
  *
@@ -464,6 +502,34 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.archive(actor, input)));
+        /**
+         * ⚠️ The look before the irreversible step, and it is on this surface because the step itself
+         * is (#586). `node_purge` has stood here since #457 for the reason #436 states — a way only the
+         * interface has is a way an agent goes around — but until now the COUNT did not, so an agent
+         * could delete for good without being able to see first what went with it. A person in the
+         * interface is shown both numbers and then confirms.
+         *
+         * That is exactly the state `.claude/rules/destructive.md` refuses in its own words: a cascade
+         * turns one confirmed click into an unknown number of deletions, and "the question can no
+         * longer name what disappears". Here the question could not be ASKED, which is the same gap one
+         * step earlier — and the half that was missing was the safe half.
+         *
+         * ⚠️ It answers about a tree, not about one row: `totalItems` counts the nodes AND the flows
+         * beneath it, the same two tables the purge itself walks. `inboundLinks` is the other kind of
+         * consequence — mentions elsewhere that will break and are deliberately not refused.
+         */
+        server.registerTool("node_purge_preview", {
+            title: "Preview a permanent deletion",
+            description: "Count what deleting one ARCHIVED node for good would take with it: every item in its subtree, documents and flows alike, and how many documents elsewhere link to it. It changes nothing. Ask before node_purge — afterwards there is no row left to count, and the links that break are not refused, only reported.",
+            inputSchema: PurgeNodePreviewInput,
+            annotations: {
+                title: "Preview a permanent deletion",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.purgePreview(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
@@ -498,6 +564,35 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.nodes.listGrants(actor, input.resourceId)));
+        /**
+         * ⚠️ The neighbour above answers a NARROWER question, and that is why this one has to be here
+         * (#586). `node_grant_list` reads the rows on this node; this resolves the inheritance — every
+         * grant along the folders above plus the owners, who reach it without a grant row existing at
+         * all. On the everyday node, whose access comes from the folder it sits in, the first answer is
+         * empty and this one is not.
+         *
+         * Two queries with similar names are two different questions, and `.claude/rules/destructive.md`
+         * records what it costs to confuse them: in #457 a refusal asked the one that sounded right and
+         * never fired. Here the cost is the same shape and lands on the sharing path — an agent asked
+         * "who can see this" reaches for the only name it has, is answered `[]`, and reports that
+         * nobody can, about a document the whole organization opens. Silence would not be a missing
+         * answer here, it would be a confident wrong one.
+         *
+         * ⚠️ The list is for reading, never for revoking: only the entries whose `resourceId` is this
+         * node can be revoked here, the rest belong to the folder that granted them.
+         */
+        server.registerTool("node_effective_access_list", {
+            title: "List effective node access",
+            description: "List everybody who reaches one node once inheritance is resolved: the grants on it AND on every folder above it, plus the owners, who need no grant. node_grant_list answers the narrower question — the rows sitting on this node alone — and on a node that inherits its access that answer is empty while this one is not. An entry whose resourceId is another node was granted there and can only be revoked there.",
+            inputSchema: ListEffectiveAccessInput,
+            annotations: {
+                title: "List effective node access",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.listEffectiveAccess(actor, input.resourceId)));
         server.registerTool("node_grant_create", {
             title: "Grant node access",
             description: "Grant inherited node access to a Gate user, verified email, or the organization.",
@@ -521,7 +616,7 @@ export async function handleMcp(request, deps) {
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.nodes.revokeGrant(actor, input)));
+        }, async (input) => await refusing(() => deps.nodes.revokeGrant(actor, input)));
     }
     if (permits(deps.authorization, "flows", "read")) {
         server.registerTool("flow_list", {
@@ -681,6 +776,24 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.flows.listGrants(flowActor, input.flowId)));
+        // ⚠️ The flow half of the node tool three groups up, and it is a SECOND tool rather than a
+        // widened one because it is a second question (#586): the answer is assembled from `flow_grants`
+        // and from the node grants of the folders above, and the owners come from the flow itself as
+        // well as from those folders. One tool over a `resourceId` that means either would have to guess
+        // which table to ask, and a caller passing the wrong kind would be answered "nobody" instead of
+        // being told.
+        server.registerTool("flow_effective_access_list", {
+            title: "List effective flow access",
+            description: "List everybody who reaches one flow once inheritance is resolved: the grants on the flow AND on the folders it is filed under, plus the owners, who need no grant. flow_grant_list answers the narrower question — the rows sitting on the flow itself — and for a flow whose access comes from its folder that answer is empty while this one is not. An entry whose resourceId is a folder was granted there and can only be revoked there.",
+            inputSchema: ListFlowEffectiveAccessInput,
+            annotations: {
+                title: "List effective flow access",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.listEffectiveAccess(flowActor, input.flowId)));
         server.registerTool("flow_grant_create", {
             title: "Grant flow access",
             description: "Grant access to one flow for a Gate user, verified email, or the organization. The grant reaches this flow alone — not the folder it is filed in, and not the flows it calls; the answer names what it does not cover.",
@@ -761,7 +874,7 @@ export async function handleMcp(request, deps) {
                 idempotentHint: false,
                 openWorldHint: false,
             },
-        }, async (input) => text(await deps.flows.purge(flowActor, input)));
+        }, async (input) => await refusing(() => 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

@@ -1,4 +1,5 @@
 import { TableMediaType } from "@anchrd/intel-contract/table";
+import { callersPhrase, namedOrCounted } from "../shared/callers/callers.js";
 import { encodeCsv, parseCsv } from "../shared/csv/csv.js";
 import { requireFutureExpiry } from "../shared/grant-expiry/grant-expiry.js";
 import { IntelError } from "../shared/intel-error/intel-error.js";
@@ -28,13 +29,15 @@ function applicableVerbs(kind) {
 }
 // ⚠️ The refusal has to be actionable without becoming a directory of the tree. Whoever holds
 // `share` on one folder must not learn the titles of flows they may not see, so the ones they may
-// see are named and the rest are only counted (ADR-0004 §3, and #17's review).
+// see are named and the rest are only counted (ADR-0004 §3, and #17's review) — which is the whole
+// of what `callersPhrase` does, in the one place both refusals read it from.
+//
+// The sentence stays for whoever has nothing to formulate with — a model over MCP reads it as it
+// stands — and `namedOrCounted` carries the same decision as data, so a screen can say it in its
+// own language (#448). Both come out of one place: the split between named and counted is an
+// authorization answer, and a surface that recomputed it would be deciding what it may not.
 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 `Flows outside this folder call into it: ${named}${rest}. Change or unpublish them before narrowing the folder.`;
+    return `Flows outside this folder call into it: ${callersPhrase(callers)}. Change or unpublish them before narrowing the folder.`;
 }
 // The grantee as the ACL sees them, and as nothing else: an identity with no capability of its own,
 // never `isAdmin`. It answers for Intel's resource ACLs only — whether Gate hands this person
@@ -1085,7 +1088,7 @@ export function createNodes(deps) {
                 !(await deps.repository.organizationExecuteReaches(input.resourceId, input.grantId))) {
                 const callers = await deps.externalFlowCallers(actor, input.resourceId);
                 if (callers.visible.length || callers.hidden) {
-                    throw new IntelError(409, "folder_execute_in_use", callersDetail(callers));
+                    throw new IntelError(409, "folder_execute_in_use", callersDetail(callers), namedOrCounted(callers));
                 }
             }
             return {

package/dist/shared/callers/callers.d.ts

@@ -0,0 +1,28 @@
+import type { NamedOrCounted } from "@anchrd/intel-contract";
+type Callers = {
+    visible: string[];
+    hidden: number;
+};
+/**
+ * ⚠️ Named where the reader may see it, counted where they may not (ADR-0004 §3). A refusal has to
+ * be actionable without becoming a way of reading the tree: whoever holds one grant on one folder
+ * must not learn the titles of flows they are refused directly.
+ *
+ * This is the middle of both refusals that ask the question — narrowing a folder (`nodes.ts`) and
+ * deleting a flow for good (`flows.ts`). ⚠️ **The two SENTENCES around it stay two**, because they
+ * say different things to different people: one is about a folder that is about to lose a grant,
+ * the other about a flow that is about to be gone. Folding them into one parameterised sentence
+ * would buy a shared string and cost the reason each one gives.
+ */
+export declare function callersPhrase(callers: Callers): string;
+/**
+ * The same two facts the sentence is built from, in the shape a grant's own warning already uses
+ * (`UnreadableNodes`, #448). One question — what may you see, and of how much — deserves one answer
+ * shape on every surface, and a screen that has to write the sentence itself needs the facts and
+ * not the sentence.
+ *
+ * ⚠️ It reads the SAME argument the phrase above reads. A surface that recomputed the split would
+ * be deciding what it may not, and a second decision here would be the one that drifts.
+ */
+export declare function namedOrCounted(callers: Callers): NamedOrCounted;
+export {};

package/dist/shared/callers/callers.js

@@ -0,0 +1,30 @@
+/**
+ * ⚠️ Named where the reader may see it, counted where they may not (ADR-0004 §3). A refusal has to
+ * be actionable without becoming a way of reading the tree: whoever holds one grant on one folder
+ * must not learn the titles of flows they are refused directly.
+ *
+ * This is the middle of both refusals that ask the question — narrowing a folder (`nodes.ts`) and
+ * deleting a flow for good (`flows.ts`). ⚠️ **The two SENTENCES around it stay two**, because they
+ * say different things to different people: one is about a folder that is about to lose a grant,
+ * the other about a flow that is about to be gone. Folding them into one parameterised sentence
+ * would buy a shared string and cost the reason each one gives.
+ */
+export function callersPhrase(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 `${named}${rest}`;
+}
+/**
+ * The same two facts the sentence is built from, in the shape a grant's own warning already uses
+ * (`UnreadableNodes`, #448). One question — what may you see, and of how much — deserves one answer
+ * shape on every surface, and a screen that has to write the sentence itself needs the facts and
+ * not the sentence.
+ *
+ * ⚠️ It reads the SAME argument the phrase above reads. A surface that recomputed the split would
+ * be deciding what it may not, and a second decision here would be the one that drifts.
+ */
+export function namedOrCounted(callers) {
+    return { titles: callers.visible, hidden: callers.hidden };
+}

package/dist/shared/intel-error/intel-error.d.ts

@@ -1,5 +1,22 @@
+import type { NamedOrCounted } from "@anchrd/intel-contract";
 export declare class IntelError extends Error {
     readonly status: number;
     readonly code: string;
-    constructor(status: number, code: string, message: string);
+    readonly callers?: NamedOrCounted | undefined;
+    /**
+     * ⚠️ `callers` is what a refusal that NAMES flows carries beside its sentence — today
+     * `folder_execute_in_use` (#448) and `flow_in_use_by_flow` (#593). It rides on the error rather
+     * than on the route because the split it belongs to is an application-layer one: who may be named
+     * and who may only be counted is an authorization answer, and it must be the same over HTTP, over
+     * MCP and in the browser. A route that assembled it would be a second place for that rule to live.
+     *
+     * `message` still carries the finished English sentence — a reader that only takes text must lose
+     * nothing — and the field is what lets a screen say it in its own language instead.
+     *
+     * ⚠️ **Setting this field is only half of reaching MCP.** The SDK formats a thrown error through
+     * `createToolError`, which keeps `message` and drops everything else, so a tool whose handler is
+     * not wrapped in `refusing()` (`mcp/mcp.ts`) answers prose and nothing more (#597). Whoever
+     * attaches `callers` to a new refusal wraps that tool's handler in the same change.
+     */
+    constructor(status: number, code: string, message: string, callers?: NamedOrCounted | undefined);
 }

package/dist/shared/intel-error/intel-error.js

@@ -1,10 +1,27 @@
 export class IntelError extends Error {
     status;
     code;
-    constructor(status, code, message) {
+    callers;
+    /**
+     * ⚠️ `callers` is what a refusal that NAMES flows carries beside its sentence — today
+     * `folder_execute_in_use` (#448) and `flow_in_use_by_flow` (#593). It rides on the error rather
+     * than on the route because the split it belongs to is an application-layer one: who may be named
+     * and who may only be counted is an authorization answer, and it must be the same over HTTP, over
+     * MCP and in the browser. A route that assembled it would be a second place for that rule to live.
+     *
+     * `message` still carries the finished English sentence — a reader that only takes text must lose
+     * nothing — and the field is what lets a screen say it in its own language instead.
+     *
+     * ⚠️ **Setting this field is only half of reaching MCP.** The SDK formats a thrown error through
+     * `createToolError`, which keeps `message` and drops everything else, so a tool whose handler is
+     * not wrapped in `refusing()` (`mcp/mcp.ts`) answers prose and nothing more (#597). Whoever
+     * attaches `callers` to a new refusal wraps that tool's handler in the same change.
+     */
+    constructor(status, code, message, callers) {
         super(message);
         this.status = status;
         this.code = code;
+        this.callers = callers;
         this.name = "IntelError";
     }
 }

package/dist/shared/problem-details/problem-details.d.ts

@@ -1,3 +1,4 @@
+import type { IntelError } from "../intel-error/intel-error.js";
 export declare function problemDetails(status: number, code: string, title: string, detail?: string): {
     type: string;
     status: number;
@@ -5,4 +6,25 @@ export declare function problemDetails(status: number, code: string, title: stri
     detail?: string | undefined;
     instance?: string | undefined;
     code?: string | undefined;
+    callers?: {
+        titles: string[];
+        hidden: number;
+    } | undefined;
+};
+/**
+ * One refusal, one document — written here rather than at each `onError`, because two apps turn an
+ * `IntelError` into a body and an extension member added at one of them would silently be missing
+ * from the other (#448). Whatever the application layer decided to say travels with it.
+ */
+export declare function intelProblem(error: IntelError): {
+    type: string;
+    status: number;
+    title: string;
+    detail?: string | undefined;
+    instance?: string | undefined;
+    code?: string | undefined;
+    callers?: {
+        titles: string[];
+        hidden: number;
+    } | undefined;
 };

package/dist/shared/problem-details/problem-details.js

@@ -2,3 +2,17 @@ import { ProblemDetails } from "@anchrd/intel-contract";
 export function problemDetails(status, code, title, detail) {
     return ProblemDetails.parse({ type: "about:blank", status, code, title, detail });
 }
+/**
+ * One refusal, one document — written here rather than at each `onError`, because two apps turn an
+ * `IntelError` into a body and an extension member added at one of them would silently be missing
+ * from the other (#448). Whatever the application layer decided to say travels with it.
+ */
+export function intelProblem(error) {
+    return ProblemDetails.parse({
+        type: "about:blank",
+        status: error.status,
+        code: error.code,
+        title: error.message,
+        callers: error.callers,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -42,8 +42,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@anchrd/gate-sdk": "^0.19.0",
-    "@anchrd/intel-contract": "^0.21.0",
+    "@anchrd/gate-sdk": "^0.20.0",
+    "@anchrd/intel-contract": "^0.22.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",