@anchrd/intel-api 0.3.3 → 0.5.0

package/README.md

@@ -72,8 +72,18 @@ uses PKCE and dynamic public-client registration; browser access tokens stay ins
 `node_modules/@anchrd/intel-api/examples/dev.vars.example` to `.dev.vars` for a local customer Worker.
 
 The portal endpoint exposes RFC 9728 metadata. The Tools UI follows that metadata, dynamically
-registers with Gate or Cloudflare Access, and completes a separate PKCE flow. The only tool secret
-Intel stores is the resulting per-user access token for its own portal endpoint, sealed with a key
+registers with Gate or Cloudflare Access, and completes a separate PKCE flow — silently, with
+`prompt=none`, as soon as a Gate session exists. Nobody is asked to connect anything.
+
+⚠️ **Two settings outside this repository decide whether that silent sign-in can work.** In
+Cloudflare Zero Trust → Access controls → AI controls → your portal → Edit → Advanced settings,
+`Managed OAuth` must be enabled, and an Access policy must carry the people who use Intel. Without
+both, every silent sign-in is refused and the Tools area shows "No access to the company portal" —
+correct behaviour for somebody outside every policy, and a misleading one for a deployment that
+simply never enabled the setting.
+
+The only tool secret Intel stores is the resulting per-user access token for its own portal
+endpoint — one per person, never one shared operator token — sealed with a key
 derived from `INTEL_SESSION_SECRET` and kept in the `portal_tokens` table of your D1; provider
 credentials stay with the portal and never reach Intel. The Intel audience token is never forwarded
 to another OAuth resource.

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,
@@ -153,10 +152,10 @@ export function createKnowledgeRepository(deps) {
                 await deps.db.batch([
                     deps.db
                         .prepare(`INSERT INTO knowledge_nodes (
-            id, parent_id, kind, title, description, context_policy, owner_id,
+            id, parent_id, kind, title, description, 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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                        .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 +238,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 +249,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 +264,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/adapters/openid/openid.js

@@ -141,6 +141,7 @@ export function createOpenId(deps) {
                 code_challenge: input.codeChallenge,
                 code_challenge_method: "S256",
                 state: input.state,
+                ...(input.prompt ? { prompt: input.prompt } : {}),
             });
         },
         async exchange(input) {

package/dist/adapters/session-cookie/session-cookie.js

@@ -27,6 +27,9 @@ const ConnectionPendingSession = z.strictObject({
     resource: z.url(),
     userId: z.string().min(1),
     user: UserSession,
+    // Older cookies carry no `silent`, and one in flight across a deploy must not become an invalid
+    // session: absent means the visible flow, which is what those attempts were.
+    silent: z.boolean().default(false),
     expiresAt: z.number().int().positive(),
 });
 const Session = z.discriminatedUnion("kind", [

package/dist/auth/auth.js

@@ -2,6 +2,22 @@ import { calculatePKCECodeChallenge, randomPKCECodeVerifier, randomState } from
 import { IntelError } from "../shared/intel-error/intel-error.js";
 import { SafeReturnPath } from "../shared/safe-return-path/safe-return-path.js";
 const cookieName = "intel_session";
+// What an authorization server answers when `prompt=none` would have worked, but only with somebody
+// looking at a screen. It is the expected answer to a silent attempt, not a broken deployment.
+const InteractionRequired = new Set([
+    "login_required",
+    "interaction_required",
+    "consent_required",
+    "account_selection_required",
+]);
+// One fixed marker, never the portal's own words. `error_description` is a sentence written by the
+// authorization server about somebody else's policy: putting it in the URL would hand whatever
+// renders the page next a string Intel does not control.
+function withConnectError(returnTo) {
+    const url = new URL(returnTo, "https://intel.invalid");
+    url.searchParams.set("connectError", "portal_sign_in_refused");
+    return `${url.pathname}${url.search}`;
+}
 function cookieValue(headers) {
     const values = headers.get("cookie")?.split(";") ?? [];
     for (const value of values) {
@@ -51,6 +67,15 @@ export function createBrowserAuth(deps) {
             createdAt: deps.now().toISOString(),
         });
     }
+    // The connection handoff parks the Intel session inside the pending cookie, so every way out of
+    // the callback has to put it back — the portal attempt must never cost somebody their Intel login.
+    async function restore(user, returnTo, location) {
+        const remaining = (user.expiresAt - deps.now().getTime()) / 1_000;
+        if (remaining <= 0) {
+            return redirect(`/auth/login?returnTo=${encodeURIComponent(returnTo)}`, sessionCookie("", secure, 0));
+        }
+        return redirect(location, sessionCookie(await deps.sessions.seal(user), secure, remaining));
+    }
     async function userSession(client, tokens) {
         return {
             version: 1,
@@ -93,6 +118,10 @@ export function createBrowserAuth(deps) {
                 throw new IntelError(401, "authentication_required", "Authentication is required");
             }
             const returnTo = SafeReturnPath.catch("/tools").parse(requestUrl.searchParams.get("returnTo") ?? "/tools");
+            // Gate is the OIDC provider Cloudflare Access consumes, so whoever holds a valid Intel
+            // session is already the person the portal would ask about. `prompt=none` says exactly that:
+            // answer from the session that exists, and refuse rather than show anybody a login (#60).
+            const silent = requestUrl.searchParams.get("silent") === "1";
             if (!deps.portalUrl) {
                 throw new IntelError(503, "portal_not_configured", "No MCP portal is configured for this deployment");
             }
@@ -113,6 +142,7 @@ export function createBrowserAuth(deps) {
                 resource: discovered.resource,
                 userId,
                 user,
+                silent,
                 expiresAt: deps.now().getTime() + 10 * 60 * 1_000,
             };
             const authorizationUrl = await deps.oauth.authorizationUrl({
@@ -123,6 +153,7 @@ export function createBrowserAuth(deps) {
                 codeChallenge,
                 state,
                 ...(discovered.scope ? { scope: discovered.scope } : {}),
+                ...(silent ? { prompt: "none" } : {}),
             });
             return redirect(authorizationUrl.href, sessionCookie(await deps.sessions.seal(pending), secure, 10 * 60));
         },
@@ -133,6 +164,19 @@ export function createBrowserAuth(deps) {
                 pending.expiresAt <= deps.now().getTime()) {
                 throw new IntelError(400, "oauth_session_invalid", "OAuth session is missing or expired");
             }
+            // ⚠️ An authorization server reports a refusal on the redirect URI, not by failing the token
+            // exchange. Reading it here is what keeps a refused silent attempt from surfacing as a raw
+            // OAuth error, and it is the only place that knows whether a visible attempt is still owed.
+            const refusal = requestUrl.searchParams.get("error");
+            if (pending.kind === "connection-pending" && refusal) {
+                // The silent attempt only asked whether the sign-in works without a screen. "Not without
+                // one" is an answer, so the visible flow runs once — and because that one is not silent, a
+                // second refusal ends in the message instead of a third attempt.
+                const visibleAttemptLeft = pending.silent && InteractionRequired.has(refusal);
+                return await restore(pending.user, pending.returnTo, visibleAttemptLeft
+                    ? `/auth/connect?returnTo=${encodeURIComponent(pending.returnTo)}`
+                    : withConnectError(pending.returnTo));
+            }
             const tokens = await deps.oauth.exchange({
                 issuer: pending.kind === "connection-pending" ? pending.issuer : gateIssuer,
                 clientId: pending.clientId,
@@ -151,11 +195,7 @@ export function createBrowserAuth(deps) {
                     clientId: pending.clientId,
                     resource: pending.resource,
                 });
-                const remaining = (pending.user.expiresAt - deps.now().getTime()) / 1_000;
-                if (remaining <= 0) {
-                    return redirect(`/auth/login?returnTo=${encodeURIComponent(pending.returnTo)}`, sessionCookie("", secure, 0));
-                }
-                return redirect(pending.returnTo, sessionCookie(await deps.sessions.seal(pending.user), secure, remaining));
+                return await restore(pending.user, pending.returnTo, pending.returnTo);
             }
             const session = await userSession(pending.clientId, tokens);
             return redirect(pending.returnTo, sessionCookie(await deps.sessions.seal(session), secure, (session.expiresAt - deps.now().getTime()) / 1_000));

package/dist/auth/auth.types.d.ts

@@ -24,6 +24,7 @@ export interface OAuthPort {
         codeChallenge: string;
         state: string;
         scope?: string;
+        prompt?: "none";
     }): Promise<URL>;
     exchange(input: {
         issuer: string;
@@ -76,6 +77,7 @@ export type AuthSession = {
     resource: string;
     userId: string;
     user: UserAuthSession;
+    silent: boolean;
     expiresAt: number;
 } | UserAuthSession;
 export interface SessionCodec {

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/intel/intel.js

@@ -32,7 +32,9 @@ export function createIntel(deps) {
     const browserAuth = deps.auth;
     if (browserAuth) {
         app.get("/auth/login", async (context) => await browserAuth.login(new URL(context.req.url)));
-        // One connect route for the one portal: there are no per-source connections any more.
+        // One connect route for the one portal: there are no per-source connections any more. With
+        // `?silent=1` it runs `prompt=none`, which is how the Tools screen reaches it without anybody
+        // clicking (#60); the route itself is unchanged otherwise, including who may use it.
         app.get("/auth/connect", async (context) => {
             const connectReturnTo = encodeURIComponent("/auth/connect?returnTo=/tools");
             const session = await browserAuth.resolve(context.req.raw.headers);

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/dist/tools/tools.js

@@ -12,20 +12,23 @@ export function createTools(deps) {
         return deps.portalUrl;
     }
     // Authorization for tools lives entirely in the portal, so "may this user act" reduces to "does
-    // this user have a usable portal token".
+    // this user have a usable portal token". ⚠️ The token is read per actor and never shared: one
+    // operator token for everybody would make every catalog the same one and the portal's Access
+    // policies decorative (ADR-0003).
     async function accessToken(actor) {
         const stored = await deps.tokens.read(actor.id);
         if (!stored) {
-            throw new IntelError(401, "portal_not_connected", "Connect the MCP portal to use tools");
+            throw new IntelError(401, "portal_not_connected", "The portal has not signed this user in yet");
         }
         if (stored.expiresAt > deps.now().getTime() + RefreshWindowMs)
             return stored.accessToken;
         const refreshed = stored.refreshToken ? await deps.refresh(stored) : null;
         if (!refreshed) {
             // A token that cannot be renewed is dropped: leaving it would keep failing every call with a
-            // stale credential instead of prompting a reconnect.
+            // stale credential. The browser answers this by signing in silently again (#60); an MCP
+            // client sees the code and repeats its own authorization.
             await deps.tokens.clear(actor.id);
-            throw new IntelError(401, "portal_reconnect_required", "Reconnect the MCP portal to continue");
+            throw new IntelError(401, "portal_reconnect_required", "The portal sign-in for this user has expired");
         }
         await deps.tokens.write(actor.id, refreshed);
         return refreshed.accessToken;
@@ -83,17 +86,18 @@ export function createTools(deps) {
     return {
         async catalog(actor) {
             const stored = await deps.tokens.read(actor.id);
-            // An unconnected portal is a normal state, not an error: the UI shows a connect prompt.
+            // No portal sign-in yet is a normal state, not an error: the browser answers it by running
+            // the silent sign-in and asking again (#60).
             if (!stored)
                 return { portalConnected: false, items: [] };
             try {
                 return { portalConnected: true, items: await capabilities(actor) };
             }
             catch (error) {
-                // A token that is gone or beyond renewal is the same answer as never having connected, so
+                // A token that is gone or beyond renewal is the same answer as never having signed in, so
                 // reading the catalog reports it as a state. Only a portal that does not answer stays an
-                // error — the view has to tell "connect the portal" apart from "the portal failed", and a
-                // 401 here would otherwise look like an expired Intel session to the browser.
+                // error — the view has to tell "sign in again" apart from "the portal failed", and a 401
+                // here would otherwise look like an expired Intel session to the browser.
                 if (error instanceof IntelError &&
                     (error.code === "portal_not_connected" || error.code === "portal_reconnect_required")) {
                     return { portalConnected: false, items: [] };

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,51 @@
+-- #76. `context_policy` leaves the tree. It was written, stored and handed back, and never once
+-- read to decide anything — and it could not have been: it instructed a retrieval Intel does not
+-- perform. Intel hands out references and the agent fetches what it needs (D24).
+--
+-- ⚠️ SQLite cannot drop a column that a CHECK constraint names, and this one names itself. The
+-- table has to be rebuilt, which for `knowledge_nodes` means six foreign keys pointing at it —
+-- including one from itself. The order below is SQLite's own twelve-step recipe, and every line of
+-- it is load-bearing:
+--
+--   * `PRAGMA foreign_keys` is turned off first. Without it the DROP below would either fail or
+--     cascade into the rows of every referencing table.
+--   * The new table is created under a different name and renamed afterwards, rather than the old
+--     one being renamed out of the way. Renaming the OLD table would silently re-point every
+--     foreign key in the other five tables at `knowledge_nodes_old` — SQLite updates references to
+--     follow a rename, and that is exactly what must not happen here.
+--   * The indexes are recreated, because dropping the table drops them with it.
+--   * `PRAGMA foreign_key_check` is the proof, not the hope. The integration test asserts it comes
+--     back empty.
+PRAGMA foreign_keys = OFF;
+
+CREATE TABLE knowledge_nodes_rebuilt (
+  id TEXT PRIMARY KEY NOT NULL,
+  parent_id TEXT REFERENCES knowledge_nodes(id),
+  kind TEXT NOT NULL CHECK (kind IN ('folder', 'document', 'attachment', 'table')),
+  title TEXT NOT NULL CHECK (length(title) BETWEEN 1 AND 240),
+  description TEXT CHECK (description IS NULL OR length(description) <= 2000),
+  owner_id TEXT NOT NULL,
+  current_version_id TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  archived_at TEXT
+);
+
+INSERT INTO knowledge_nodes_rebuilt (
+  id, parent_id, kind, title, description, owner_id,
+  current_version_id, created_at, updated_at, archived_at
+)
+SELECT id, parent_id, kind, title, description, owner_id,
+       current_version_id, created_at, updated_at, archived_at
+FROM knowledge_nodes;
+
+DROP TABLE knowledge_nodes;
+
+ALTER TABLE knowledge_nodes_rebuilt RENAME TO knowledge_nodes;
+
+CREATE INDEX knowledge_nodes_parent_idx ON knowledge_nodes(parent_id, archived_at, title);
+CREATE INDEX knowledge_nodes_owner_idx ON knowledge_nodes(owner_id, archived_at);
+
+PRAGMA foreign_key_check;
+
+PRAGMA foreign_keys = ON;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "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",