@anchrd/intel-api 0.4.0 → 0.5.1

package/dist/adapters/db/db.js

@@ -3,7 +3,7 @@ const grantColumns = `id, node_id, principal_type, principal_id, verb, expires_a
   created_by, created_at`;
 const linkColumns = `link.id, link.source_node_id, link.target_node_id, link.relation,
   link.origin, link.label, link.created_by, link.created_at`;
-const nodeColumns = `n.id, n.parent_id, n.kind, n.title, n.description, n.context_policy,
+const nodeColumns = `n.id, n.parent_id, n.kind, n.title, n.description,
   n.owner_id, n.current_version_id, n.created_at, n.updated_at, n.archived_at`;
 function mapNode(row) {
     return {
@@ -12,7 +12,6 @@ function mapNode(row) {
         kind: row.kind,
         title: row.title,
         description: row.description,
-        contextPolicy: row.context_policy,
         ownerId: row.owner_id,
         currentVersionId: row.current_version_id,
         createdAt: row.created_at,
@@ -152,11 +151,15 @@ export function createKnowledgeRepository(deps) {
             try {
                 await deps.db.batch([
                     deps.db
+                        // ⚠️ `context_policy` is dead and is written anyway (#76). The column is NOT NULL
+                        // without a DEFAULT and D1 will not let it be dropped — migration 0009 carries the
+                        // reason. The fixed value is the price; nothing reads it, and the contract no longer
+                        // knows the field. When the column goes (anchrd/intel#86), this line goes with it.
                         .prepare(`INSERT INTO knowledge_nodes (
             id, parent_id, kind, title, description, context_policy, owner_id,
             current_version_id, created_at, updated_at, archived_at
-          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-                        .bind(node.id, node.parentId, node.kind, node.title, node.description, node.contextPolicy, node.ownerId, node.currentVersionId, node.createdAt, node.updatedAt, node.archivedAt),
+          ) VALUES (?, ?, ?, ?, ?, 'relevant', ?, ?, ?, ?, ?)`)
+                        .bind(node.id, node.parentId, node.kind, node.title, node.description, node.ownerId, node.currentVersionId, node.createdAt, node.updatedAt, node.archivedAt),
                     deps.db
                         .prepare(`INSERT INTO idempotency_keys (
             actor_id, operation, idempotency_key, resource_id, created_at
@@ -239,10 +242,10 @@ export function createKnowledgeRepository(deps) {
               JOIN descendants parent ON child.parent_id = parent.id
             )
             UPDATE knowledge_nodes
-            SET parent_id = ?, title = ?, description = ?, context_policy = ?, updated_at = ?
+            SET parent_id = ?, title = ?, description = ?, updated_at = ?
             WHERE id = ? AND updated_at = ?
               AND (? IS NULL OR ? NOT IN (SELECT id FROM descendants))`)
-                        .bind(node.id, node.parentId, node.title, node.description, node.contextPolicy, node.updatedAt, node.id, input.baseUpdatedAt, node.parentId, node.parentId),
+                        .bind(node.id, node.parentId, node.title, node.description, node.updatedAt, node.id, input.baseUpdatedAt, node.parentId, node.parentId),
                     deps.db
                         .prepare(`INSERT INTO idempotency_keys (
               actor_id, operation, idempotency_key, resource_id, created_at
@@ -250,9 +253,9 @@ export function createKnowledgeRepository(deps) {
             WHERE EXISTS (
               SELECT 1 FROM knowledge_nodes
               WHERE id = ? AND parent_id IS ? AND title = ? AND description IS ?
-                AND context_policy = ? AND updated_at = ?
+                AND updated_at = ?
             )`)
-                        .bind(input.actorId, input.idempotencyKey, node.id, node.updatedAt, node.id, node.parentId, node.title, node.description, node.contextPolicy, node.updatedAt),
+                        .bind(input.actorId, input.idempotencyKey, node.id, node.updatedAt, node.id, node.parentId, node.title, node.description, node.updatedAt),
                     deps.db
                         .prepare(`INSERT INTO audit_events (
               id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
@@ -265,7 +268,6 @@ export function createKnowledgeRepository(deps) {
                         .bind(input.auditId, input.actorId, node.id, JSON.stringify({
                         parentId: node.parentId,
                         title: node.title,
-                        contextPolicy: node.contextPolicy,
                     }), node.updatedAt, input.actorId, input.idempotencyKey, node.id),
                 ]);
             }

package/dist/cli/cli.js

@@ -3,14 +3,18 @@ import { createPrepare } from "../prepare/prepare.js";
 const interfaces = [
     { handle: "intel", functions: ["use", "admin"] },
     { handle: "knowledge", functions: ["read", "create", "write", "share"] },
+    // ⚠️ No `approve`. The approval node is gone (#73), and this list is what Intel declares to Gate:
+    // a function nobody asks about is a permission an operator has to decide on for no reason. An
+    // installation that already granted it keeps a harmless leftover — bootstrap declares, it does
+    // not revoke.
     {
         handle: "flows",
-        functions: ["read", "create", "write", "publish", "run", "approve", "share"],
+        functions: ["read", "create", "write", "publish", "run", "share"],
     },
     { handle: "tools", functions: ["read", "test", "execute", "admin"] },
-    // `mcp:connect` heisst bei jedem MCP-Dienst dieser Installation gleich. Ein eigener Name fuer
-    // dieselbe Sache zwingt den Betreiber, pro Dienst nachzusehen, welches Recht den Portal-Zugang
-    // traegt.
+    // `mcp:connect` means the same thing at every MCP service of this installation. A separate name
+    // for the same thing forces the operator to check, service by service, which permission carries
+    // portal access.
     { handle: "mcp", functions: ["connect"] },
 ];
 const usage = `Usage: intel <prepare|bootstrap|build|doctor|reindex>

package/dist/flows/flows.d.ts

@@ -4,11 +4,13 @@ type SubflowNode = Extract<FlowNode, {
     kind: "subflow";
 }>;
 type KnowledgeStepNode = Extract<FlowNode, {
-    kind: "knowledge";
+    kind: KnowledgeLinkKind;
 }>;
 type ToolStepNode = Extract<FlowNode, {
     kind: "tool";
 }>;
+declare const knowledgeLinkKinds: readonly ["folder", "document", "upload", "table"];
+type KnowledgeLinkKind = (typeof knowledgeLinkKinds)[number];
 /**
  * One place reads a graph for each kind of step it contains, and everything else is derived from
  * these three. The publish-time rule, the freeze, the sidebar, the relation graph, the requirements
@@ -18,6 +20,7 @@ type ToolStepNode = Extract<FlowNode, {
 export declare function subflowNodes(graph: FlowGraph): SubflowNode[];
 export declare function knowledgeNodes(graph: FlowGraph): KnowledgeStepNode[];
 export declare function toolNodes(graph: FlowGraph): ToolStepNode[];
+export declare function resourceIdOf(node: KnowledgeStepNode): string;
 export declare function calleeIds(graph: FlowGraph): string[];
 /**
  * The Knowledge documents a graph names and the tools it calls, flattened and without repetition.

package/dist/flows/flows.js

@@ -1,3 +1,4 @@
+import { flowNodeLayer } from "@anchrd/intel-contract";
 import { IntelError } from "../shared/intel-error/intel-error.js";
 function invalid(detail) {
     throw new IntelError(400, "flow_graph_invalid", detail);
@@ -5,6 +6,10 @@ function invalid(detail) {
 // A call chain deeper than this is a runaway rather than a design. It also bounds the publish-time
 // walk and the run trail, both of which follow data that other writers can change.
 const MaxCallDepth = 20;
+// The four link kinds that name something in the shared tree (D25). `tool` is a link too, but it
+// names a portal tool rather than a resource, and every rule about reachability applies to these
+// four and not to it.
+const knowledgeLinkKinds = ["folder", "document", "upload", "table"];
 /**
  * One place reads a graph for each kind of step it contains, and everything else is derived from
  * these three. The publish-time rule, the freeze, the sidebar, the relation graph, the requirements
@@ -14,12 +19,20 @@ const MaxCallDepth = 20;
 export function subflowNodes(graph) {
     return graph.nodes.filter((node) => node.kind === "subflow");
 }
+// ⚠️ Kept as one list although it is now four kinds: every caller asks "what does this graph read
+// from the tree", never "which of the four". Splitting the callers to match the split in the schema
+// would multiply four ways at each of the six call sites for no answer anyone wants.
 export function knowledgeNodes(graph) {
-    return graph.nodes.filter((node) => node.kind === "knowledge");
+    return graph.nodes.filter((node) => knowledgeLinkKinds.includes(node.kind));
 }
 export function toolNodes(graph) {
     return graph.nodes.filter((node) => node.kind === "tool");
 }
+// The one resource a link names. Its own function because four kinds answer it the same way, and a
+// caller that switched on the kind to read the same field would invite a fifth kind to be forgotten.
+export function resourceIdOf(node) {
+    return node.configuration.resourceId;
+}
 // The flows a graph calls, in the order the nodes name them and without repetition. `subflowNodes`
 // answers "which calls", this answers "which flows" — a flow called twice with two different version
 // choices is two calls and one callee, and the freeze has to see both.
@@ -41,9 +54,8 @@ export function graphReferences(graph) {
     const knowledge = [];
     const tools = [];
     for (const node of knowledgeNodes(graph)) {
-        for (const resourceId of node.configuration.resourceIds) {
-            if (!knowledge.includes(resourceId))
-                knowledge.push(resourceId);
+        if (!knowledge.includes(node.configuration.resourceId)) {
+            knowledge.push(node.configuration.resourceId);
         }
     }
     for (const node of toolNodes(graph)) {
@@ -118,13 +130,30 @@ export function compileFlow(graph) {
     for (const node of graph.nodes) {
         const parents = incoming.get(node.id) ?? 0;
         const children = outgoing.get(node.id) ?? [];
-        // An attached node is material, not a step: it is not in the order of work, so the rules about
-        // what comes before and after it do not apply. It must not be in that order either — a node
-        // that is both would be two things at once, and the run would have to pick one.
-        if (attachedTo.has(node.id)) {
+        const layer = flowNodeLayer[node.kind];
+        const holderId = attachedTo.get(node.id);
+        // ⚠️ The layer rule of D25, and the reason it lives here rather than in the editor: a graph
+        // arrives over MCP as readily as from the canvas. A link is what a step works with and is never
+        // in the order of work; a marker and a step are the order of work and are never material.
+        // Before this, a link could stand in the chain — which is how a start with an attachment once
+        // began its run at the attachment (#37).
+        if (layer === "link" && holderId === undefined) {
+            invalid(`Node ${node.id} is a link and must be attached to a step`);
+        }
+        if (layer !== "link" && holderId !== undefined) {
+            invalid(`Node ${node.id} is not a link and cannot be attached to another node`);
+        }
+        if (holderId !== undefined) {
             if (parents !== 0 || children.length !== 0) {
                 invalid(`Node ${node.id} is attached as context and cannot also be a step`);
             }
+            const holder = nodes.get(holderId);
+            // Only a step holds material. A marker carries nothing at all, and a `subflow` is a call: the
+            // flow it names brings its own links, and lending it one from here would be steering another
+            // flow from outside.
+            if (holder && (flowNodeLayer[holder.kind] !== "step" || holder.kind === "subflow")) {
+                invalid(`Node ${node.id} can only be attached to an instruction or a condition`);
+            }
             continue;
         }
         if (node.kind === "trigger" && parents !== 0)
@@ -134,7 +163,7 @@ export function compileFlow(graph) {
         }
         if (node.kind === "output" && children.length !== 0)
             invalid(`Output ${node.id} must be terminal`);
-        if (node.kind === "condition" || node.kind === "approval") {
+        if (node.kind === "condition") {
             if (children.length < 2)
                 invalid(`Node ${node.id} requires at least two branches`);
             const handles = new Set(children.map((edge) => edge.sourceHandle));
@@ -279,6 +308,95 @@ export function createFlows(deps) {
             throw new IntelError(403, "flow_execute_forbidden", "Flow execute permission is required");
         }
     }
+    /**
+     * Everything that stands between this actor and a run of this flow, gathered rather than thrown.
+     *
+     * ⚠️ THE reason this function exists rather than a second list beside `start`: two lists drift.
+     * They drift silently, and the direction they drift in is the worst one — `validate` keeps saying
+     * "it would run" while `start` refuses, which sends the reader looking anywhere but at the
+     * problem. `start` calls this and throws on the first entry; `validate` calls it and returns all
+     * of them. A check added here is therefore added to both, or to neither.
+     */
+    async function collectRunProblems(actor, flow, pinnedVersionId) {
+        const problems = [];
+        if (!(await deps.repository.can(actor, flow.id, "execute"))) {
+            problems.push({
+                status: 403,
+                code: "flow_execute_forbidden",
+                detail: "Flow execute permission is required",
+            });
+        }
+        // Asked even for a frozen call: a flow whose publication was withdrawn is not something a
+        // pinned version may quietly keep running.
+        if (!flow.publishedVersionId) {
+            problems.push({
+                status: 409,
+                code: "flow_not_published",
+                detail: "Flow has no published version",
+            });
+            return { problems, version: null, first: null };
+        }
+        // A frozen call runs its own version; everything else runs what is published now.
+        const version = await requireVersion(pinnedVersionId ?? flow.publishedVersionId, flow.id);
+        let first = null;
+        try {
+            const compiled = compileFlow(version.graph);
+            // ⚠️ Flow edges only. A start carrying context would otherwise begin the run at the attached
+            // node, because that edge can come first in the list (#37).
+            first =
+                version.graph.edges.find((edge) => edge.kind === "flow" && edge.source === compiled.triggerId)?.target ?? null;
+            if (!first)
+                invalid("The trigger requires an outgoing edge");
+        }
+        catch (error) {
+            problems.push({
+                status: 400,
+                code: "flow_graph_invalid",
+                detail: error instanceof IntelError ? error.message : "The graph cannot be compiled",
+            });
+            return { problems, version, first: null };
+        }
+        // The flow may have been built by someone with wider portal access. Naming the missing tools
+        // before the first step beats failing halfway through with a portal error the user cannot
+        // place — and the portal is where they can do something about it.
+        const missing = await deps.unavailableTools(actor, graphReferences(version.graph).tools);
+        if (missing.length) {
+            problems.push({
+                status: 403,
+                code: "flow_tools_unavailable",
+                detail: toolStepDetail(missing),
+            });
+        }
+        try {
+            await requireNodeAuthorized(actor, nodeFor(version, first), version.graph);
+        }
+        catch (error) {
+            if (!(error instanceof IntelError))
+                throw error;
+            problems.push({ status: error.status, code: error.code, detail: error.message });
+        }
+        // Every flow this one calls has to be published, or the call fails halfway through a run rather
+        // than before it. `publish` refuses this at freeze time; a flow whose callee was un-published
+        // afterwards is the case only a check on demand can catch.
+        for (const node of subflowNodes(version.graph)) {
+            const callee = await deps.repository.getCallable(actor, node.configuration.flowId);
+            if (!callee || callee.archivedAt) {
+                problems.push({
+                    status: 409,
+                    code: "flow_subflow_unavailable",
+                    detail: `The called flow is not available: ${node.label}`,
+                });
+            }
+            else if (!callee.publishedVersionId) {
+                problems.push({
+                    status: 409,
+                    code: "flow_subflow_not_published",
+                    detail: `The called flow has no published version: ${node.label}`,
+                });
+            }
+        }
+        return { problems, version, first };
+    }
     // A flow's parent is a Knowledge folder, so the answer comes from Knowledge rather than from a
     // second permission model here. `null` is the root and needs no permission of its own — the same
     // as creating a folder at the root does.
@@ -363,16 +481,27 @@ export function createFlows(deps) {
     // current Gate identity and the resource ACL are asked again. A called flow's steps come through
     // this same function, so a document the user may not read stays unreadable however deep the call
     // sits, and a flow grant keeps protecting the procedure rather than the data.
-    async function requireNodeAuthorized(actor, node) {
-        if (node?.kind === "knowledge") {
-            const wanted = [...new Set(node.configuration.resourceIds)];
+    // ⚠️ Reads what hangs off the step, not the step itself (D25). A document or a tool is a link on a
+    // `context` edge now, and a run never stands on one — so asking "is this node a knowledge step"
+    // would ask about a node the run can no longer reach, and every check here would silently pass.
+    async function requireNodeAuthorized(actor, node, graph) {
+        if (!node)
+            return;
+        const attached = graph.edges
+            .filter((edge) => edge.kind === "context" && edge.source === node.id)
+            .flatMap((edge) => graph.nodes.filter((candidate) => candidate.id === edge.target));
+        const wanted = [...new Set(knowledgeNodes({ ...graph, nodes: attached }).map(resourceIdOf))];
+        if (wanted.length) {
             const reachable = await reachableKnowledge(actor, wanted);
             if (reachable.length !== wanted.length) {
                 throw new IntelError(403, "flow_knowledge_forbidden", knowledgeStepDetail(node.label, wanted.length - reachable.length));
             }
         }
-        if (node?.kind === "tool") {
-            const missing = await deps.unavailableTools(actor, [node.configuration.toolName]);
+        const toolNames = attached
+            .filter((candidate) => candidate.kind === "tool")
+            .map((candidate) => candidate.configuration.toolName);
+        if (toolNames.length) {
+            const missing = await deps.unavailableTools(actor, [...new Set(toolNames)]);
             if (missing.length) {
                 throw new IntelError(403, "flow_tools_unavailable", toolStepDetail(missing));
             }
@@ -404,7 +533,7 @@ export function createFlows(deps) {
         await requireRunnableFlow(actor, run.flowId);
         const version = await requireVersion(run.versionId, run.flowId);
         const node = nodeFor(version, run.currentNodeId);
-        await requireNodeAuthorized(actor, node);
+        await requireNodeAuthorized(actor, node, version.graph);
         return { run: await narrowed(actor, run, version), node, trail: await trailFor(run, version) };
     }
     // A failed run carries the text of the step that failed, and for a call that text came out of
@@ -571,7 +700,7 @@ export function createFlows(deps) {
             throw new IntelError(403, "flow_call_site_forbidden", "The calling run belongs to someone else");
         }
         await requireExecute(actor, run.flowId);
-        if (run.status !== "running" && run.status !== "waiting") {
+        if (run.status !== "running") {
             throw new IntelError(409, "flow_run_terminal", "Flow run is already terminal");
         }
         if (run.currentNodeId !== parent.nodeId) {
@@ -715,17 +844,16 @@ export function createFlows(deps) {
                 // name the step it comes from, so this is the one caller that needs the nodes themselves
                 // and not the flattened `graphReferences`.
                 for (const node of knowledgeNodes(version.graph)) {
-                    for (const resourceId of node.configuration.resourceIds) {
-                        const target = await knowledgeNode(resourceId);
-                        if (!target || !place(target.node, target.parentId))
-                            continue;
-                        edges.push({
-                            id: `reads:${flow.id}:${node.id}:${resourceId}`,
-                            source: flow.id,
-                            target: resourceId,
-                            relation: "reads",
-                        });
-                    }
+                    const resourceId = resourceIdOf(node);
+                    const target = await knowledgeNode(resourceId);
+                    if (!target || !place(target.node, target.parentId))
+                        continue;
+                    edges.push({
+                        id: `reads:${flow.id}:${node.id}:${resourceId}`,
+                        source: flow.id,
+                        target: resourceId,
+                        relation: "reads",
+                    });
                 }
                 for (const node of subflowNodes(version.graph)) {
                     const callee = calleeFlow(node.configuration.flowId);
@@ -779,6 +907,28 @@ export function createFlows(deps) {
         // and no claim about whether anyone may reach it. A standing "this flow has conflicts" badge
         // would be wrong for tools by construction — the catalog is a live query with the requesting
         // user's own token (ADR-0003) — and out of date for documents most of the time.
+        /**
+         * Would this flow start, for the person asking, right now? It answers and changes nothing: no
+         * run row, no idempotency key, no audit event (#72).
+         *
+         * ⚠️ `read` is enough, deliberately. Somebody who may see a flow but not run it is exactly who
+         * needs this — "you are missing execute" is the answer they came for, and refusing to answer
+         * would leave them guessing at the one thing that is easy to say. Nothing is named here that a
+         * reader could not already read out of the graph.
+         *
+         * ⚠️ Not cached and not stored anywhere. The tool catalog is a live query with the asking
+         * user's own token (ADR-0003); a kept answer would be a claim about a moment that has passed.
+         */
+        async validate(actor, flowId) {
+            const flow = await requireRunnableFlow(actor, flowId);
+            const { problems, version } = await collectRunProblems(actor, flow, null);
+            return {
+                flowId: flow.id,
+                versionId: version?.id ?? null,
+                problems: problems.map(({ code, detail }) => ({ code, detail })),
+                checkedAt: deps.now().toISOString(),
+            };
+        },
         async listRequirements(actor, flowId) {
             const flow = await requireFlow(actor, flowId);
             // The draft is what the editor is looking at; a flow with only a published version has
@@ -915,15 +1065,14 @@ export function createFlows(deps) {
                 return await requireFlow(actor, flow.id);
             const version = await requireVersion(input.versionId, flow.id);
             compileFlow(version.graph);
-            for (const node of version.graph.nodes) {
-                if (node.kind === "knowledge") {
-                    const reachable = new Set((await reachableKnowledge(actor, node.configuration.resourceIds)).map((reference) => reference.id));
-                    for (const resourceId of node.configuration.resourceIds) {
-                        if (!reachable.has(resourceId)) {
-                            throw new IntelError(409, "flow_knowledge_unavailable", `Knowledge reference is unavailable: ${resourceId}`);
-                        }
-                    }
+            const wanted = [...new Set(knowledgeNodes(version.graph).map(resourceIdOf))];
+            const reachable = new Set((await reachableKnowledge(actor, wanted)).map((reference) => reference.id));
+            for (const resourceId of wanted) {
+                if (!reachable.has(resourceId)) {
+                    throw new IntelError(409, "flow_knowledge_unavailable", `Knowledge reference is unavailable: ${resourceId}`);
                 }
+            }
+            for (const node of version.graph.nodes) {
                 if (node.kind === "tool") {
                     const fingerprint = await deps.toolFingerprint(actor, node.configuration.toolName);
                     if (!fingerprint) {
@@ -1020,46 +1169,41 @@ export function createFlows(deps) {
                 }
             }
             const flow = await requireRunnableFlow(actor, input.flowId);
-            // Asked even for a frozen call: a flow whose publication was withdrawn is not something a
-            // pinned version may quietly keep running.
-            if (!flow.publishedVersionId) {
-                throw new IntelError(409, "flow_not_published", "Flow has no published version");
-            }
-            // A frozen call runs its own version; everything else runs what is published now. Both land in
-            // `run.versionId` below, so a run always records which version actually ran (ADR-0004 §5).
-            const version = await requireVersion(call?.versionId ?? flow.publishedVersionId, flow.id);
-            const compiled = compileFlow(version.graph);
-            // ⚠️ Flow edges only. A start carrying context would otherwise begin the run at the attached
-            // node, because that edge can come first in the list (#37).
-            const first = version.graph.edges.find((edge) => edge.kind === "flow" && edge.source === compiled.triggerId)?.target;
-            if (!first)
-                invalid("The trigger requires an outgoing edge");
-            // The flow may have been built by someone with wider portal access. Naming the missing tools
-            // before the first step beats failing halfway through with a portal error the user cannot
-            // place — and the portal is where they can do something about it.
-            const missing = await deps.unavailableTools(actor, graphReferences(version.graph).tools);
-            if (missing.length) {
-                throw new IntelError(403, "flow_tools_unavailable", toolStepDetail(missing));
-            }
-            // The first step is authorized before a run row exists, so a refusal leaves nothing behind at
-            // all — not a run, not an idempotency key, not an audit event.
-            await requireNodeAuthorized(actor, nodeFor(version, first));
+            // ⚠️ The same list `validate` reads, and the reason it is one list: a check that only one of
+            // them knows is a check the other silently skips. Thrown here at the first entry, because a
+            // start is an action and an action either happens or says why not.
+            //
+            // Nothing has been written at this point, so a refusal leaves nothing behind at all — not a
+            // run, not an idempotency key, not an audit event.
+            const check = await collectRunProblems(actor, flow, call?.versionId ?? null);
+            const problem = check.problems[0];
+            if (problem)
+                throw new IntelError(problem.status, problem.code, problem.detail);
+            const version = check.version;
+            const first = check.first;
+            if (!version || !first)
+                invalid("The flow cannot be started");
             const occurredAt = deps.now().toISOString();
+            // ⚠️ A flow whose start leads straight to its end has nothing to carry out, and the end is a
+            // marker rather than a step (D25). It is the shape every flow has the moment it is created,
+            // so it must run rather than park a run on a node nobody can complete. What it hands back is
+            // its input: the only thing that passed through it.
+            const empty = nodeFor(version, first)?.kind === "output";
             const run = {
                 id: deps.id(),
                 flowId: flow.id,
                 versionId: version.id,
-                status: "running",
-                currentNodeId: first,
+                status: empty ? "completed" : "running",
+                currentNodeId: empty ? null : first,
                 input: input.input,
-                output: null,
+                output: empty ? input.input : null,
                 error: null,
                 initiatedBy: actor.id,
                 parentRunId: parent?.id ?? null,
                 parentNodeId: parent ? (input.parent?.nodeId ?? null) : null,
                 createdAt: occurredAt,
                 updatedAt: occurredAt,
-                completedAt: null,
+                completedAt: empty ? occurredAt : null,
             };
             const inserted = await deps.repository.insertRun({
                 run,
@@ -1218,10 +1362,10 @@ export function createFlows(deps) {
             const current = await deps.repository.getRunVisible(actor, input.runId);
             if (!current)
                 throw new IntelError(404, "flow_run_not_found", "Flow run was not found");
-            // Rechecked here rather than trusted from the start: a grant revoked while a run waits for an
-            // approval must stop the next step, not only the next run.
+            // Rechecked here rather than trusted from the start: a grant revoked between two steps must
+            // stop the next one, not only the next run.
             await requireExecute(actor, current.flowId);
-            if (current.status !== "running" && current.status !== "waiting") {
+            if (current.status !== "running") {
                 throw new IntelError(409, "flow_run_terminal", "Flow run is already terminal");
             }
             if (current.currentNodeId !== input.nodeId) {
@@ -1232,12 +1376,9 @@ export function createFlows(deps) {
             if (!node) {
                 throw new IntelError(500, "flow_version_corrupt", "Current run node is missing from the immutable version");
             }
-            if (node.kind === "approval" && !actor.canApprove) {
-                throw new IntelError(403, "flow_approval_forbidden", "Approval permission is required");
-            }
             // Asked again before the result is recorded, not only when the step was handed out: a grant
             // revoked while the step was being carried out must stop it from landing.
-            await requireNodeAuthorized(actor, node);
+            await requireNodeAuthorized(actor, node, version.graph);
             // ⚠️ A subflow step is finished by the run it started, and by nothing the caller of this
             // surface says. Outcome, output and error are all read back out of that run: the outcome too,
             // or a client could mark a call that succeeded as failed and send the flow down a branch the
@@ -1275,22 +1416,28 @@ export function createFlows(deps) {
                 error = stepError ?? StepFailedDetail;
                 completedAt = occurredAt;
             }
-            else if (node.kind === "output") {
-                status = "completed";
-                output = stepOutput;
-                completedAt = occurredAt;
-            }
             else {
                 // ⚠️ Flow edges only, for the same reason as the start above: what a step works with is not
                 // where the run goes next (#37).
                 const edges = version.graph.edges.filter((edge) => edge.kind === "flow" && edge.source === node.id);
-                const edge = node.kind === "condition" || node.kind === "approval"
+                const edge = node.kind === "condition"
                     ? edges.find((candidate) => candidate.sourceHandle === input.branch)
                     : edges[0];
                 if (!edge) {
                     throw new IntelError(400, "flow_branch_invalid", "A valid branch is required");
                 }
-                currentNodeId = edge.target;
+                // ⚠️ The end is reached, never carried out (D25). It marks where the flow stops and holds
+                // nothing to do, so handing it out as a step would ask the agent to perform an empty node
+                // and then wait for the answer. The run ends here instead, with what the step that just
+                // finished handed in — which is what "the result of a run" now means.
+                if (nodeFor(version, edge.target)?.kind === "output") {
+                    status = "completed";
+                    output = stepOutput;
+                    completedAt = occurredAt;
+                }
+                else {
+                    currentNodeId = edge.target;
+                }
             }
             const next = {
                 ...current,

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

@@ -1,4 +1,4 @@
-import type { CompleteFlowRunStepInput, CreateFlowInput, Flow, FlowDocument, FlowGraph, FlowPublishPreview, FlowRequirements, FlowRun, FlowRunHistory, FlowRunList, FlowRunStep, FlowVersion, KnowledgeNode, ListFlowRunsInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraph, RelationGraphInput, ResourceVerb, SaveFlowVersionInput, StartFlowRunInput, UpdateFlowInput } from "@anchrd/intel-contract";
+import type { CompleteFlowRunStepInput, CreateFlowInput, Flow, FlowDocument, FlowGraph, FlowPublishPreview, FlowRequirements, FlowRun, FlowRunHistory, FlowRunList, FlowRunStep, FlowValidation, FlowVersion, KnowledgeNode, ListFlowRunsInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraph, RelationGraphInput, ResourceVerb, SaveFlowVersionInput, StartFlowRunInput, UpdateFlowInput } from "@anchrd/intel-contract";
 export type FlowPrincipal = Pick<FlowActor, "id" | "email" | "isAdmin">;
 export type FlowCallReach = "subtree" | "library" | "out-of-reach";
 export interface FlowRunChainEntry {
@@ -37,7 +37,6 @@ export interface FlowActor {
     id: string;
     email: string;
     canRun: boolean;
-    canApprove: boolean;
     isAdmin?: boolean;
 }
 export type FlowVerb = Extract<ResourceVerb, "read" | "write" | "execute">;
@@ -163,6 +162,7 @@ export interface FlowService {
     listCalls(actor: FlowActor, flowId: string): Promise<{
         items: Flow[];
     }>;
+    validate(actor: FlowActor, flowId: string): Promise<FlowValidation>;
     relationGraph(actor: FlowActor, input: RelationGraphInput): Promise<RelationGraph>;
     listRequirements(actor: FlowActor, flowId: string): Promise<FlowRequirements>;
     create(actor: FlowActor, input: CreateFlowInput): Promise<Flow>;
@@ -180,3 +180,8 @@ export interface CompiledFlow {
     graph: FlowGraph;
     triggerId: string;
 }
+export interface RunProblem {
+    status: number;
+    code: string;
+    detail: string;
+}

package/dist/http/http.js

@@ -48,7 +48,6 @@ function asFlowActor(authorization) {
         id: authorization.identity.id,
         email: authorization.identity.email,
         canRun: permits(authorization, "flows", "run"),
-        canApprove: permits(authorization, "flows", "approve"),
         isAdmin: authorization.can("intel", "admin"),
     };
 }
@@ -283,6 +282,15 @@ export function createHttp(deps) {
         const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
         return context.json(await deps.flows.listCalls(asFlowActor(auth), input.flowId));
     });
+    // Would this flow start, for whoever is asking, right now (#72). `flows/read` and nothing more:
+    // the answer somebody without `execute` needs most is that they are missing `execute`, and it
+    // names nothing they could not read out of the graph. A GET because it changes nothing — no run,
+    // no key, no audit event.
+    app.get("/flows/:flowId/validation", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const input = GetFlowInput.parse({ flowId: context.req.param("flowId") });
+        return context.json(await deps.flows.validate(asFlowActor(auth), input.flowId));
+    });
     // What this flow needs: the documents and tools its graph names. `flows/read` and nothing more —
     // it describes a flow the caller may already open, and names only what they may already see.
     app.get("/flows/:flowId/requirements", async (context) => {

package/dist/knowledge/knowledge.js

@@ -323,7 +323,6 @@ export function createKnowledge(deps) {
                     kind: input.kind,
                     title: input.title,
                     description: input.description,
-                    contextPolicy: input.contextPolicy,
                     ownerId: actor.id,
                     currentVersionId: null,
                     createdAt: timestamp,
@@ -553,7 +552,6 @@ export function createKnowledge(deps) {
                     parentId: input.parentId === undefined ? current.parentId : input.parentId,
                     title: input.title ?? current.title,
                     description: input.description === undefined ? current.description : input.description,
-                    contextPolicy: input.contextPolicy ?? current.contextPolicy,
                     updatedAt,
                 },
                 baseUpdatedAt: input.baseUpdatedAt,

package/dist/mcp/mcp.js

@@ -39,7 +39,6 @@ export async function handleMcp(request, deps) {
         id: deps.authorization.identity.id,
         email: deps.authorization.identity.email,
         canRun: permits(deps.authorization, "flows", "run"),
-        canApprove: permits(deps.authorization, "flows", "approve"),
         isAdmin: deps.authorization.can("intel", "admin"),
     };
     const server = new McpServer({ name: "intel", version: "0.1.0" });
@@ -381,6 +380,18 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.flows.relationGraph(flowActor, input)));
+        server.registerTool("flow_validate", {
+            title: "Check whether a flow would start",
+            description: "Check whether this flow would start for the calling user right now, and name every reason it would not. Answers rather than acts: no run is created. The answer is a snapshot for this user at this moment, because tool reachability is a live query with their own portal token.",
+            inputSchema: GetFlowInput,
+            annotations: {
+                title: "Check whether a flow would start",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.validate(flowActor, input.flowId)));
         server.registerTool("flow_requirements_list", {
             title: "List what a flow needs",
             description: "List the Knowledge documents and MCP tools one flow's graph names. Documents the calling user cannot see are counted rather than named, and no claim is made about whether anyone may reach them: for tools that cannot be known in advance, because the catalog is a live query with each user's own portal token.",

package/migrations/0007_no_node_waits.sql

@@ -0,0 +1,69 @@
+-- #73. The approval node leaves the contract, so the graphs already stored are rewritten to match
+-- the schema that will read them. Without this an `approval` node makes `FlowGraph.parse` throw in
+-- `db-flows.ts`, and the flow cannot be opened at all — not even to repair it. A removal that locks
+-- people out of their own flows is worse than the node it removes.
+--
+-- ⚠️ Rewritten to a `condition`, not deleted. The node has two outgoing branches, and deleting it
+-- would leave two edges pointing nowhere and a graph that fails `compileFlow` for a second reason.
+-- A condition is the honest replacement: it branches the same way, and the question the approval
+-- asked — "may this go ahead?" — is one the agent carrying out the run can answer. The prompt is
+-- carried over into the instruction rather than dropped, so the author still reads what was meant.
+-- `timeout` disappears with the waiting it configured (D24).
+--
+-- ⚠️ The branch handles are rewritten with it: an approval branched on `approved`/`rejected`, a
+-- condition on `yes`/`no`. Left alone, `completeStep` would look for a handle that no edge carries
+-- and every run through that node would answer 400.
+--
+-- ⚠️ One pass over the arrays rather than targeted updates, for the same reason as 0005: re-running
+-- must change nothing. A graph with no approval node is written back identical to itself.
+UPDATE flow_versions
+SET graph_json = json_set(
+  json_set(
+    graph_json,
+    '$.nodes',
+    (
+      SELECT json_group_array(
+        CASE
+          WHEN json_extract(node.value, '$.kind') = 'approval'
+          THEN json_set(
+            json_set(node.value, '$.kind', 'condition'),
+            '$.configuration',
+            json_object(
+              'mode', 'semantic',
+              'instruction', json_extract(node.value, '$.configuration.prompt')
+            )
+          )
+          ELSE node.value
+        END
+      )
+      FROM json_each(flow_versions.graph_json, '$.nodes') AS node
+    )
+  ),
+  '$.edges',
+  (
+    SELECT json_group_array(
+      CASE json_extract(edge.value, '$.sourceHandle')
+        WHEN 'approved' THEN json_set(edge.value, '$.sourceHandle', 'yes')
+        WHEN 'rejected' THEN json_set(edge.value, '$.sourceHandle', 'no')
+        ELSE edge.value
+      END
+    )
+    FROM json_each(flow_versions.graph_json, '$.edges') AS edge
+  )
+)
+WHERE EXISTS (
+  SELECT 1 FROM json_each(flow_versions.graph_json, '$.nodes') AS node
+  WHERE json_extract(node.value, '$.kind') = 'approval'
+);
+
+-- `waiting` was written for the approval node and never set by anything: the two places that tested
+-- for it only ever saw `running`. It leaves `FlowRunStatus`, so a row carrying it would become a
+-- status the contract cannot parse. There should be none — this makes that true rather than hoped.
+--
+-- The column's CHECK constraint still allows the value, deliberately: changing it means rebuilding
+-- the table in D1 for a value nothing writes.
+UPDATE flow_runs
+SET status = 'failed',
+    error = 'Flow run was waiting for an approval that no longer exists',
+    completed_at = COALESCE(completed_at, updated_at)
+WHERE status = 'waiting';

package/migrations/0008_three_layers.sql

@@ -0,0 +1,130 @@
+-- #74. Three kinds change shape at once, so the stored graphs are rewritten before the schema that
+-- reads them changes. Without this they stop parsing in `db-flows.ts` and the flows become
+-- unopenable — the trap 0007 was written for, at a larger scale.
+--
+-- ⚠️ A `knowledge` node was BOTH a step and its material. Under D25 those are two layers, so it
+-- becomes two nodes: the step stays exactly where it stood in the chain and turns into an
+-- `instruction`, and each reference it held becomes a link hanging off it on a context edge.
+--
+--     ▶ ── knowledge[a,b] ── ▶        becomes        ▶ ── instruction ── ▶
+--                                                          │      │
+--                                                       link a   link b
+--
+-- Splitting this way rather than turning the node itself into a link is what keeps every existing
+-- edge valid: nothing is re-pointed, nothing is deleted, and a knowledge node sitting directly
+-- after the start still works — as a link it would have had to attach to the start, which is a
+-- marker and holds nothing. It is also the honest reading. The old node WAS a step; what it lacked
+-- was anything saying what to do with the material, which is exactly what the instruction now says.
+--
+-- ⚠️ The kind a reference points at was never stored in the graph — the node only held ids. The
+-- knowledge tree knows, so the rewrite reads it there. A reference whose target is gone becomes
+-- `document`, which is what the old node treated everything as.
+
+-- ── The edges: every old edge, plus one context edge per reference ───────────────────────────────
+-- ⚠️ Runs BEFORE the node rewrite, and that order is the whole reason it is readable: while the
+-- knowledge nodes are still knowledge nodes, the id of the step and the list of references sit in
+-- the same row, so the new edge can name both without taking anybody's id apart.
+UPDATE flow_versions
+SET graph_json = json_set(
+  graph_json,
+  '$.edges',
+  (
+    SELECT json_group_array(json(value)) FROM (
+      SELECT edge.key AS position, 0 AS tier, edge.value AS value
+      FROM json_each(flow_versions.graph_json, '$.edges') AS edge
+
+      UNION ALL
+
+      SELECT 1000000 + node.key AS position, reference.key + 1 AS tier,
+        json_object(
+          'id', json_extract(node.value, '$.id') || '-link-' || reference.key || '-context',
+          'source', json_extract(node.value, '$.id'),
+          'target', json_extract(node.value, '$.id') || '-link-' || reference.key,
+          'kind', 'context',
+          'label', NULL,
+          'sourceHandle', NULL
+        ) AS value
+      FROM json_each(flow_versions.graph_json, '$.nodes') AS node,
+           json_each(json_extract(node.value, '$.configuration.resourceIds')) AS reference
+      WHERE json_extract(node.value, '$.kind') = 'knowledge'
+      ORDER BY position, tier
+    )
+  )
+)
+WHERE EXISTS (
+  SELECT 1 FROM json_each(flow_versions.graph_json, '$.nodes') AS node
+  WHERE json_extract(node.value, '$.kind') = 'knowledge'
+);
+
+-- ── The nodes: every old node, plus one link per reference ───────────────────────────────────────
+UPDATE flow_versions
+SET graph_json = json_set(
+  graph_json,
+  '$.nodes',
+  (
+    SELECT json_group_array(json(value)) FROM (
+      -- The old nodes, in place and in order. A knowledge node becomes the instruction it always
+      -- half was; its retrieval hint becomes the prompt, because that is the only sentence the
+      -- author ever wrote about what should happen with the material.
+      SELECT node.key AS position, 0 AS tier,
+        CASE
+          WHEN json_extract(node.value, '$.kind') = 'knowledge'
+          THEN json_set(
+            json_set(node.value, '$.kind', 'instruction'),
+            '$.configuration',
+            json_object(
+              'prompt',
+              COALESCE(
+                NULLIF(json_extract(node.value, '$.configuration.query'), ''),
+                'Work with the attached material.'
+              )
+            )
+          )
+          -- The end marks and no longer makes: `template` was never read by anything.
+          WHEN json_extract(node.value, '$.kind') = 'output'
+          THEN json_set(node.value, '$.configuration', json_object())
+          ELSE node.value
+        END AS value
+      FROM json_each(flow_versions.graph_json, '$.nodes') AS node
+
+      UNION ALL
+
+      -- One link per reference, laid out below its step so the graph opens readable rather than
+      -- stacked. The id is derived from the node it came from, which keeps the rewrite idempotent:
+      -- running it twice produces the same ids, and there is no second knowledge node to expand.
+      SELECT node.key AS position, 1 AS tier,
+        json_object(
+          'id', json_extract(node.value, '$.id') || '-link-' || reference.key,
+          'kind', COALESCE(
+            (
+              SELECT CASE knowledge_nodes.kind
+                WHEN 'folder' THEN 'folder'
+                WHEN 'attachment' THEN 'upload'
+                WHEN 'table' THEN 'table'
+                ELSE 'document'
+              END
+              FROM knowledge_nodes WHERE knowledge_nodes.id = reference.value
+            ),
+            'document'
+          ),
+          'label', COALESCE(
+            (SELECT knowledge_nodes.title FROM knowledge_nodes WHERE knowledge_nodes.id = reference.value),
+            'Missing reference'
+          ),
+          'position', json_object(
+            'x', json_extract(node.value, '$.position.x') + (reference.key * 200),
+            'y', json_extract(node.value, '$.position.y') + 160
+          ),
+          'configuration', json_object('resourceId', reference.value)
+        ) AS value
+      FROM json_each(flow_versions.graph_json, '$.nodes') AS node,
+           json_each(json_extract(node.value, '$.configuration.resourceIds')) AS reference
+      WHERE json_extract(node.value, '$.kind') = 'knowledge'
+      ORDER BY position, tier
+    )
+  )
+)
+WHERE EXISTS (
+  SELECT 1 FROM json_each(flow_versions.graph_json, '$.nodes') AS node
+  WHERE json_extract(node.value, '$.kind') IN ('knowledge', 'output')
+);

package/migrations/0009_no_context_policy.sql

@@ -0,0 +1,33 @@
+-- #76. `context_policy` leaves the contract, the UI and every MCP answer. The COLUMN stays.
+--
+-- ⚠️ That is not the intent, it is what D1 permits. SQLite cannot drop a column a CHECK names, and
+-- this one names itself. The way around it is a table rebuild, and `knowledge_nodes` carries six
+-- foreign keys, one of them from itself.
+--
+-- Three attempts against the real database, three failures, each with its own lesson:
+--
+--   1. `PRAGMA foreign_keys = OFF` — **ignored** by D1 over its HTTP API. It works locally, because
+--      miniflare honours it, so the integration test was green while production answered
+--      `FOREIGN KEY constraint failed` on the DROP. ⚠️ A green migration test does not prove a D1
+--      migration runs.
+--   2. `PRAGMA defer_foreign_keys = true` — it works, but the self-reference was written as
+--      `REFERENCES knowledge_nodes(id)` and therefore pointed at the table this same migration was
+--      about to drop. SQLite rewrites a self-reference along with the rename, so the temporary name
+--      belongs there.
+--   3. Self-reference fixed → green through `wrangler d1 migrations apply --local`, still red
+--      against `--remote`. The reason is the execution model: D1 commits the statements of a
+--      migration file one at a time, and the deferral only lasts until the next COMMIT. After the
+--      first statement the reprieve is gone and `DROP TABLE` runs unprotected.
+--
+-- A table rebuild with foreign keys is therefore not possible inside a migration file. It needs a
+-- session that drives the transaction itself.
+--
+-- What holds instead: the column sits in D1, nothing reads it, and `db.ts` writes a fixed value on
+-- insert because it is NOT NULL without a DEFAULT. The contract does not know it — for every
+-- consumer it is gone. What remains is one dead column, and that is the price of Intel running.
+--
+-- How it disappears after all is anchrd/intel#86.
+--
+-- This file deliberately does nothing. It is where the above is written down; deleted, it would be
+-- a gap in the numbering that nobody explains.
+SELECT 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@anchrd/gate-sdk": "^0.7.0",
-    "@anchrd/intel-contract": "^0.2.0",
+    "@anchrd/intel-contract": "^0.3.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "ajv": "^8.20.0",
     "hono": "^4.12.32",