@anchrd/intel 0.59.0

package/dist/flows/flows.js

@@ -0,0 +1,2216 @@
+import { flowNodeLayer } from "../contract/flow.js";
+import { callersPhrase, namedOrCounted } from "../shared/callers/callers.js";
+import { requireFutureExpiry } from "../shared/grant-expiry/grant-expiry.js";
+import { IntelError } from "../shared/intel-error/intel-error.js";
+import { plainTitle } from "../shared/plain-title/plain-title.js";
+function invalid(detail) {
+    throw new IntelError(400, "flow_graph_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;
+// All four, and unlike a node this needs no lookup: every verb means something on a flow. `read`
+// opens it, `write` edits it, `execute` runs it, `share` passes access on (#530).
+const flowVerbs = ["read", "write", "execute", "share"];
+/**
+ * The grantee as the ACL sees them, and as nothing else: an identity with no capability of its own.
+ *
+ * ⚠️ Never `isAdmin` and never `canRun`. Whether Gate hands this person `intel/admin` or `flows/run`
+ * is Gate's to know, so the warning built on this can be pessimistic and never permissive — it may
+ * say "they will not be able to reach this" about somebody who turns out to be able to. The other
+ * direction would be a warning that stays silent about a real gap.
+ *
+ * A grant to an email address is judged as that address, which is what the grant will be attached
+ * to; a second grant the same person holds under their user id is not folded in.
+ */
+function asPrincipalActor(principal) {
+    if (principal.type === "user")
+        return { id: principal.id, email: "", canRun: false };
+    if (principal.type === "email")
+        return { id: "", email: principal.email, canRun: false };
+    return { id: "", email: "", canRun: false };
+}
+// 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.
+export const treeLinkKinds = ["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
+ * list and the repository's cycle walk all ask about the same nodes; a second `kind === "…"` walk
+ * beside them would drift quietly, because both would keep returning something plausible.
+ */
+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 treeLinkNodes(graph) {
+    return graph.nodes.filter((node) => treeLinkKinds.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.
+export function calleeIds(graph) {
+    const ids = [];
+    for (const node of subflowNodes(graph)) {
+        if (!ids.includes(node.configuration.flowId))
+            ids.push(node.configuration.flowId);
+    }
+    return ids;
+}
+/**
+ * The documents a graph names and the tool SERVERS it reaches for, flattened and without repetition.
+ * The requirements list, the publish-time check and the run's first tool check read this one answer,
+ * so they cannot disagree about what a flow touches. A caller that needs to know *which step* names
+ * a document reads the node lists above instead — the relation graph draws exactly that edge.
+ *
+ * ⚠️ Servers, not functions, since #489. A step no longer names one function, so "what does this
+ * flow need" cannot be answered with a function list any more — and answering it with the functions
+ * a step MIGHT call would be a guess about a choice that is made while the flow runs.
+ */
+export function graphReferences(graph) {
+    const nodes = [];
+    const servers = [];
+    for (const node of treeLinkNodes(graph)) {
+        if (!nodes.includes(node.configuration.resourceId)) {
+            nodes.push(node.configuration.resourceId);
+        }
+    }
+    for (const node of toolNodes(graph)) {
+        if (!servers.includes(node.configuration.server))
+            servers.push(node.configuration.server);
+    }
+    return { nodes, servers };
+}
+// ⚠️ The reason, in the words the person can act on, and not one word more. How many documents a
+// step cannot reach is something they may know; which ones they are is the very thing the ACL is
+// keeping from them, so the step is named and the documents are only counted (#17, #19).
+function treeLinkStepDetail(label, missing) {
+    return missing === 1
+        ? `One document this step needs is not readable for you: ${label}`
+        : `${missing} documents this step needs are not readable for you: ${label}`;
+}
+// ⚠️ For tools this is the only honest moment there is. The catalog is a live tools/list with the
+// requesting user's own token (ADR-0003), so nobody can be told in advance what someone else would
+// see — but the person in front of the failure can be told exactly where to go.
+// ⚠️ Servers, not tools, since #489 — and the sentence says so. A step names a server, so a person
+// told "you do not have access to this tool: notion" would go looking for a function by that name
+// and find none. What they can act on is the server: it is what the portal grants and what they can
+// ask to be granted.
+function toolStepDetail(missing) {
+    return missing.length === 1
+        ? `You do not reach this tool server in the portal: ${missing.join(", ")}`
+        : `You do not reach these tool servers in the portal: ${missing.join(", ")}`;
+}
+/**
+ * ⚠️ How every refusal on this file names a node: by the label the canvas draws, because the id
+ * appears nowhere on screen. `Node n-doc is a link and must be attached to a step` sent an author
+ * looking for a string the editor never draws, and the way to the cause led through the contract
+ * schema instead of through the sentence (#508). The id stays beside it: a graph arrives over MCP
+ * as readily as from the canvas, and there the id is what the caller holds.
+ *
+ * ⚠️ One function rather than one spelling per call site (#551): the publish-time refusals name a
+ * node too, and two places building the same string by hand is how the two halves of one sentence
+ * drift while both keep looking right.
+ */
+function nodeName(node) {
+    return `"${node.label}" (${node.id})`;
+}
+export function compileFlow(graph) {
+    const nodes = new Map();
+    // ⚠️ It stands ABOVE the loop that fills the map on purpose, so the duplicate-id refusal reaches
+    // it too — that one names the node the map already holds, which is the FIRST of the two. An id
+    // nothing knows falls back to the bare id, which is what the dangling-edge case wants anyway.
+    const named = (id) => {
+        const node = nodes.get(id);
+        return node ? nodeName(node) : id;
+    };
+    for (const node of graph.nodes) {
+        if (nodes.has(node.id))
+            invalid(`Duplicate node ID: ${named(node.id)}`);
+        nodes.set(node.id, node);
+    }
+    // ⚠️ Every arity rule below counts flow edges only. A context edge says "this belongs to that
+    // step", not "this runs after it" — counted in, it would give its target a second incoming edge
+    // and its source a second branch, and every graph carrying context would be rejected (#37).
+    const edgeIds = new Set();
+    const incoming = new Map();
+    const outgoing = new Map();
+    const attachments = new Map();
+    const attachedTo = new Map();
+    for (const edge of graph.edges) {
+        if (edgeIds.has(edge.id))
+            invalid(`Duplicate edge ID: ${edge.id}`);
+        edgeIds.add(edge.id);
+        if (!nodes.has(edge.source) || !nodes.has(edge.target))
+            invalid(`Dangling edge: ${edge.id}`);
+        if (edge.kind === "context") {
+            if (edge.source === edge.target)
+                invalid(`Context edge ${edge.id} cannot attach a node to itself`);
+            // One holder per attached node: two steps claiming the same material would make "what does
+            // this step work with" answerable two ways, and the second answer would never be shown.
+            if (attachedTo.has(edge.target))
+                invalid(`Node ${named(edge.target)} is already attached to ${named(attachedTo.get(edge.target) ?? "")}`);
+            attachedTo.set(edge.target, edge.source);
+            attachments.set(edge.source, [...(attachments.get(edge.source) ?? []), edge]);
+            continue;
+        }
+        incoming.set(edge.target, (incoming.get(edge.target) ?? 0) + 1);
+        outgoing.set(edge.source, [...(outgoing.get(edge.source) ?? []), edge]);
+    }
+    const triggers = graph.nodes.filter((node) => node.kind === "trigger");
+    if (triggers.length !== 1)
+        invalid("A flow requires exactly one trigger");
+    if (!graph.nodes.some((node) => node.kind === "output"))
+        invalid("A flow requires an output");
+    const trigger = triggers[0];
+    if (!trigger)
+        invalid("A flow requires exactly one trigger");
+    // The start is where the flow begins, not material a step works with. Attaching it would take it
+    // out of the run of steps below and leave the graph without a beginning.
+    if (attachedTo.has(trigger.id))
+        invalid("The trigger cannot be attached as context");
+    for (const node of graph.nodes) {
+        const parents = incoming.get(node.id) ?? 0;
+        const children = outgoing.get(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 ${named(node.id)} is a link and must be attached to a step`);
+        }
+        if (layer !== "link" && holderId !== undefined) {
+            invalid(`Node ${named(node.id)} is not a link and cannot be attached to another node`);
+        }
+        if (holderId !== undefined) {
+            if (parents !== 0 || children.length !== 0) {
+                invalid(`Node ${named(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 ${named(node.id)} can only be attached to an instruction or a condition`);
+            }
+            continue;
+        }
+        if (node.kind === "trigger" && parents !== 0)
+            invalid("The trigger cannot have an incoming edge");
+        if (node.kind !== "trigger" && parents !== 1) {
+            invalid(`Node ${named(node.id)} requires exactly one incoming edge`);
+        }
+        if (node.kind === "output" && children.length !== 0)
+            invalid(`Output ${named(node.id)} must be terminal`);
+        if (node.kind === "condition") {
+            if (children.length < 2)
+                invalid(`Node ${named(node.id)} requires at least two branches`);
+            const handles = new Set(children.map((edge) => edge.sourceHandle));
+            if (handles.has(null) || handles.size !== children.length) {
+                invalid(`Node ${named(node.id)} requires unique branch handles`);
+            }
+        }
+        else if (node.kind !== "output") {
+            if (children.length !== 1)
+                invalid(`Node ${named(node.id)} requires exactly one outgoing edge`);
+            if (children[0]?.sourceHandle !== null)
+                invalid(`Node ${named(node.id)} cannot define a branch handle`);
+        }
+    }
+    const visited = new Set();
+    const active = new Set();
+    function visit(nodeId) {
+        if (active.has(nodeId))
+            invalid("Flow graphs cannot contain cycles");
+        if (visited.has(nodeId))
+            return;
+        active.add(nodeId);
+        // Only flow edges are walked: the cycle rule is about the order of work, and context is not in
+        // it. Attachments are marked visited so reachability still accounts for them, but stepping
+        // through one could never come back around — an attached node carries no flow edges at all.
+        //
+        // ⚠️ Context is one level deep, on purpose. Marking an attachment visited without recursing
+        // means material hung off material is unreachable and the graph is refused. A chain of "what
+        // this works with, works with…" is a structure nobody asked for, and allowing it would make
+        // "what does this step work with" a traversal instead of a lookup.
+        for (const edge of outgoing.get(nodeId) ?? [])
+            visit(edge.target);
+        for (const edge of attachments.get(nodeId) ?? [])
+            visited.add(edge.target);
+        active.delete(nodeId);
+        visited.add(nodeId);
+    }
+    visit(trigger.id);
+    if (visited.size !== graph.nodes.length)
+        invalid("Every node must be reachable from the trigger");
+    return { graph, triggerId: trigger.id };
+}
+// What a step says when it failed and left no reason behind, and what a call says when the reason
+// belongs to a run the asker may not see. Both are written once and read from two places — the
+// moment a run records, and the moment somebody reads it back — so a list cannot invent a third
+// wording for the same event.
+const StepFailedDetail = "Flow step failed";
+function calledStepDetail(label) {
+    return `The called flow did not finish: ${label}`;
+}
+function nodeFor(version, nodeId) {
+    return nodeId ? (version.graph.nodes.find((node) => node.id === nodeId) ?? null) : null;
+}
+// Why a run started, read off the graph it ran rather than off a column. A called run says so
+// through `parentRunId`; everything else was started by hand, because `manual` is the only mode a
+// trigger node still has (#39).
+//
+// ⚠️ Still read from the graph rather than shortened to a constant. The graph is where the answer
+// belongs, and if a second way of starting a flow is ever added it is added there — a hard-coded
+// `manual` here would be a lie the day that happens, and nothing would point at this line.
+function triggerOf(version, run) {
+    if (run.parentRunId)
+        return "subflow";
+    const trigger = version.graph.nodes.find((node) => node.kind === "trigger");
+    // `compileFlow` insists on exactly one trigger before a version can be saved, so the fallback is
+    // unreachable for anything that ever ran — it exists because the type cannot say that.
+    return trigger?.configuration.mode ?? "manual";
+}
+// Wall-clock duration of a finished run. A run still going has no answer yet, and inventing "so far"
+// here would be a number that is stale the moment it is read.
+function durationOf(run) {
+    if (!run.completedAt)
+        return null;
+    return Math.max(0, Date.parse(run.completedAt) - Date.parse(run.createdAt));
+}
+// A call site is two identifiers, and a Map wants one key. Written once so the lookup and the fill
+// cannot disagree about how the pair is spelled; `\u0000` cannot occur in either half.
+function callKey(runId, nodeId) {
+    return `${runId}\u0000${nodeId}`;
+}
+// What a call step may say to this asker. A called run they may see hands its own text over whole;
+// otherwise the caller's step names itself and nothing else crosses the boundary. A step that
+// recorded no reason keeps none — that is a completed call, not a silent failure.
+function callDetail(calledRunId, label, stored) {
+    if (calledRunId)
+        return stored;
+    return stored === null ? null : calledStepDetail(label);
+}
+// The page marker of the run list. `created_at` alone is not unique — two runs of the same flow can
+// share a millisecond — so the row's ID rides along and the keyset stays exact.
+function encodeCursor(run) {
+    return `${run.createdAt}|${run.id}`;
+}
+function decodeCursor(cursor) {
+    if (!cursor)
+        return null;
+    const separator = cursor.indexOf("|");
+    if (separator <= 0)
+        throw new IntelError(400, "flow_run_cursor_invalid", "Page cursor is invalid");
+    const createdAt = cursor.slice(0, separator);
+    const id = cursor.slice(separator + 1);
+    if (!id)
+        throw new IntelError(400, "flow_run_cursor_invalid", "Page cursor is invalid");
+    return { createdAt, id };
+}
+// ⚠️ Named where the reader may see it, counted where they may not — the same rule the folder's
+// refusal follows, out of the same place (`callersPhrase`): a refusal must not become a way of
+// learning that a flow one cannot see exists (ADR-0004 §3).
+//
+// ⚠️ The SENTENCE stays its own, and that is deliberate (#593): the folder's says a grant cannot be
+// narrowed yet, this one says a flow cannot be deleted for good. Same facts, different consequence
+// — a single parameterised sentence would save a string and cost each refusal its reason.
+function callersDetail(callers) {
+    return `Published flows still call this one: ${callersPhrase(callers)}. Change or unpublish them first.`;
+}
+export function createFlows(deps) {
+    async function requireFlow(actor, flowId) {
+        const flow = await deps.repository.getVisible(actor, flowId);
+        if (!flow || flow.archivedAt)
+            throw new IntelError(404, "flow_not_found", "Flow was not found");
+        return flow;
+    }
+    // ⚠️ On the execution path a flow is resolved by `read` or `execute`, never by `read` alone. A
+    // library folder carries `execute` for everyone and nothing else (ADR-0004 §2/§3), so insisting on
+    // `read` here would turn every library flow into a 404 for exactly the people it exists for — and
+    // the call rule in section 3 would have nothing left to permit.
+    /**
+     * Which of these flows call another one that THIS actor may also see (#59).
+     *
+     * ⚠️ Per reader, and that is the point: a flow whose only call is hidden from this person has
+     * nothing to unfold, so a chevron there would promise what opening cannot deliver. `listCalls`
+     * filters the same way — asking the same question here, rather than reading the graph and hoping,
+     * is the only way the two cannot drift apart.
+     *
+     * ⚠️ Two reads for the whole level, never one per flow (#30): the versions come back together and
+     * the callees go out together.
+     */
+    async function callableCallers(actor, flows) {
+        const versionOf = new Map();
+        for (const flow of flows) {
+            const versionId = flow.currentVersionId ?? flow.publishedVersionId;
+            if (versionId)
+                versionOf.set(flow.id, versionId);
+        }
+        if (versionOf.size === 0)
+            return [];
+        const versions = new Map((await deps.repository.getVersions([...new Set(versionOf.values())])).map((version) => [
+            version.id,
+            version,
+        ]));
+        const wanted = new Map();
+        for (const [flowId, versionId] of versionOf) {
+            const version = versions.get(versionId);
+            if (version)
+                wanted.set(flowId, calleeIds(version.graph));
+        }
+        const everyCallee = [...new Set([...wanted.values()].flat())];
+        if (everyCallee.length === 0)
+            return [];
+        const reachable = new Set((await deps.repository.listCallable(actor, everyCallee))
+            .filter((callee) => !callee.archivedAt)
+            .map((callee) => callee.id));
+        return [...wanted.entries()]
+            .filter(([, callees]) => callees.some((callee) => reachable.has(callee)))
+            .map(([flowId]) => flowId);
+    }
+    /**
+     * The flow a run already belongs to, as this actor may see it.
+     *
+     * ⚠️ The same ACL as `requireRunnableFlow` and deliberately without its archived refusal. This is
+     * the answer to "what should archiving do to a run in flight" (#112): archiving decides what may
+     * be STARTED, never what happens to what is already going. The other reading — refusing here —
+     * is what produced the state that ticket was written about: the step was recorded and the caller
+     * was told 404, with no way to read the run afterwards to find out otherwise.
+     */
+    async function requireStartedFlow(actor, flowId) {
+        const flow = await deps.repository.getCallable(actor, flowId);
+        if (!flow)
+            throw new IntelError(404, "flow_not_found", "Flow was not found");
+        return flow;
+    }
+    // The same flow for something that is about to START — a run, a validation. An archived flow is
+    // absent here, which is the whole of what archiving does.
+    async function requireRunnableFlow(actor, flowId) {
+        const flow = await requireStartedFlow(actor, flowId);
+        if (flow.archivedAt)
+            throw new IntelError(404, "flow_not_found", "Flow was not found");
+        return flow;
+    }
+    // Every surface maps the Gate capability into the actor, so the rule lives here once instead of
+    // being restated per surface. Checked before any storage access.
+    function requireRun(actor) {
+        if (!actor.canRun) {
+            throw new IntelError(403, "flow_run_forbidden", "Flow run permission is required");
+        }
+    }
+    // Managing a flow's sharing is `share` on the flow — held directly, passed down by a folder above
+    // it, or held by owning it. Asked before any grant row is read or written, so a refusal leaves no
+    // trace and tells the caller nothing about what grants exist.
+    async function requireShareable(actor, flowId) {
+        const flow = await requireFlow(actor, flowId);
+        if (!(await deps.repository.can(actor, flow.id, "share"))) {
+            throw new IntelError(403, "flow_forbidden", "Sharing of this flow cannot be managed");
+        }
+        return flow;
+    }
+    /**
+     * What this grant does NOT reach, described to whoever just made it (ADR-0004 §4).
+     *
+     * Two halves, and the second is the one a folder grant never needed. A grant on a folder covered
+     * every flow beneath it, so the sub-flows were covered with it; a grant on ONE flow stops at that
+     * flow, and the flows it calls are then a separate grant somebody has to make.
+     *
+     * ⚠️ It is a warning and not a refusal, for the reason the node side gives: blocking would force
+     * everyone whose flow reads a central policy document to duplicate it. What makes the warning
+     * enough — and what makes this whole feature possible at all — is that `validate` answers the same
+     * question later, for the person about to run, at the moment they run (#530).
+     *
+     * ⚠️ Titles only where the SHARER may see them. Whoever holds `share` on one flow must not learn
+     * the titles of documents or flows they cannot reach themselves, so the rest is a number. A
+     * warning must not become a way of reading the tree (ADR-0004 §3, #17's review).
+     */
+    async function withShareWarnings(actor, flow, grant, principal) {
+        const grantee = asPrincipalActor(principal);
+        // What the published version does is what a grantee will run. A flow with nothing published
+        // has nothing to warn about yet, and the draft is not what `execute` would reach.
+        const versionId = flow.publishedVersionId;
+        const version = versionId ? await deps.repository.getVersion(versionId) : null;
+        if (!version) {
+            return { grant, unreadable: empty(), unrunnable: empty() };
+        }
+        const unreadable = empty();
+        // Deduplicated: a document two steps both name is one thing the grantee cannot read, not two.
+        for (const nodeId of [...new Set(graphReferences(version.graph).nodes)]) {
+            if (await deps.visibleNodes(grantee, nodeId))
+                continue;
+            const node = await deps.visibleNodes(actor, nodeId);
+            if (node)
+                unreadable.titles.push(node.title);
+            else
+                unreadable.hidden += 1;
+        }
+        const unrunnable = empty();
+        for (const calleeId of calleeIds(version.graph)) {
+            if (await deps.repository.can(grantee, calleeId, "execute"))
+                continue;
+            const callee = await deps.repository.getVisible(actor, calleeId);
+            if (callee)
+                unrunnable.titles.push(callee.title);
+            else
+                unrunnable.hidden += 1;
+        }
+        return { grant, unreadable, unrunnable };
+    }
+    function empty() {
+        return { titles: [], hidden: 0 };
+    }
+    async function requireEdit(actor, flowId) {
+        const flow = await requireFlow(actor, flowId);
+        if (!(await deps.repository.can(actor, flowId, "write"))) {
+            throw new IntelError(403, "flow_edit_forbidden", "Flow cannot be edited");
+        }
+        return flow;
+    }
+    // Seeing a flow and starting it are two grants, not one (ADR-0004 §2): /crm is readable for sales
+    // and executable only for billing. This is asked before anything a run would touch — no
+    // idempotency lookup, no portal call, no run row — so a refusal leaves no trace behind.
+    async function requireExecute(actor, flowId) {
+        if (!(await deps.repository.can(actor, flowId, "execute"))) {
+            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.
+        //
+        // ⚠️ ONE entry per missing TOOL, and the unit is the decision (#435). A problem list is a
+        // count, so the number of entries has to be the number of things left to do — and what a
+        // person does about a missing tool is grant it once in the portal, whether one step reaches
+        // for it or six. `graphReferences` already folds the graph down to distinct tool names, which
+        // is why a tool hanging off several steps arrives here once. Deliberately NOT one entry per
+        // step: the same portal click would then be listed several times, and the reader would go
+        // looking for several causes.
+        //
+        // The one consequence to know about: `start` throws the FIRST entry, so it now names the first
+        // missing tool rather than all of them — the same as it has always done for several
+        // unpublished sub-flows below. `validate` is what lists every reason at once, and it does.
+        for (const server of await deps.unavailableServers(actor, graphReferences(version.graph).servers)) {
+            problems.push({
+                status: 403,
+                code: "flow_tools_unavailable",
+                detail: toolStepDetail([server]),
+            });
+        }
+        try {
+            // ⚠️ Tree links only. The loop above has already asked about every tool in the graph — the
+            // first step's included — so the tool half of `requireNodeAuthorized` would answer a second
+            // time about the same names, which is the duplicate #435 reported. Every place that actually
+            // hands a step over still calls the whole of `requireNodeAuthorized`.
+            await requireTreeLinksAuthorized(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 folder of the tree, so the answer comes from the node service 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.
+    async function requireFolder(actor, parentId) {
+        if (parentId === null)
+            return;
+        const access = await deps.folderAccess(actor, parentId);
+        if (access === "missing") {
+            throw new IntelError(404, "flow_parent_not_found", "Parent folder was not found");
+        }
+        if (access === "not-a-folder") {
+            throw new IntelError(409, "parent_not_folder", "A flow's parent must be a folder");
+        }
+        if (access === "forbidden") {
+            throw new IntelError(403, "node_forbidden", "Destination folder cannot be edited");
+        }
+    }
+    async function requireVersion(versionId, flowId) {
+        const version = await deps.repository.getVersion(versionId);
+        if (!version || (flowId && version.flowId !== flowId)) {
+            throw new IntelError(404, "flow_version_not_found", "Flow version was not found");
+        }
+        return version;
+    }
+    // Which step of which flow is running, outermost caller first. Built from the stored chain rather
+    // than from the run at hand, so a caller looking at the outer run sees the step inside the called
+    // flow, and a caller looking at the called run sees who called it.
+    async function trailFor(run, known) {
+        const chain = await deps.repository.runChain(run.id);
+        const byId = new Map(chain.map((entry) => [entry.runId, entry]));
+        const child = new Map();
+        for (const entry of chain) {
+            if (entry.parentRunId && byId.has(entry.parentRunId))
+                child.set(entry.parentRunId, entry.runId);
+        }
+        let head = chain.find((entry) => !entry.parentRunId || !byId.has(entry.parentRunId));
+        const ordered = [];
+        while (head && ordered.length < MaxCallDepth) {
+            ordered.push(head);
+            const next = child.get(head.runId);
+            head = next ? byId.get(next) : undefined;
+        }
+        // ⚠️ The versions in one read, after the walk rather than inside it (#30). This function sits on
+        // the path every step of every run takes, so a query per level was a cost paid per step and
+        // growing with the depth of the call chain — invisible at two levels, linear at twenty. The
+        // version already in hand is not asked for again, and a label whose version is missing stays
+        // `null` exactly as it did.
+        const versions = new Map([[known.id, known]]);
+        const missing = [...new Set(ordered.map((entry) => entry.versionId))].filter((versionId) => !versions.has(versionId));
+        for (const version of await deps.repository.getVersions(missing)) {
+            versions.set(version.id, version);
+        }
+        return ordered.map((entry) => {
+            const version = versions.get(entry.versionId);
+            return {
+                runId: entry.runId,
+                flowId: entry.flowId,
+                flowTitle: entry.flowTitle,
+                nodeId: entry.currentNodeId,
+                nodeLabel: version ? (nodeFor(version, entry.currentNodeId)?.label ?? null) : null,
+            };
+        });
+    }
+    // The documents of a list this actor may reach, named. Distinct IDs only, so a reference written
+    // twice is one document; an ID that is missing from the answer is one they cannot reach.
+    //
+    // ⚠️ It is `deps.visibleNodes` and nothing else, which is what keeps the authorization check,
+    // the requirements list and the relation graph on one rule. Only `id` and `title` travel onwards:
+    // the node also carries `parentId`, `ownerId` and its version, and where a document sits in the
+    // tree is not part of the question "what does this flow need" (#17, #19).
+    async function reachableNodes(actor, resourceIds) {
+        const reachable = [];
+        for (const resourceId of new Set(resourceIds)) {
+            const node = await deps.visibleNodes(actor, resourceId);
+            if (node)
+                reachable.push({ id: node.id, title: node.title });
+        }
+        return reachable;
+    }
+    // ⚠️ ADR-0004 §4, and the reason a subflow is not a way around anything. Before a node or
+    // Tool step is handed to whoever will carry it out — first run, retry and resume alike — the
+    // 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.
+    // ⚠️ 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 tree link"
+    // would ask about a node the run can no longer reach, and every check here would silently pass.
+    async function requireNodeAuthorized(actor, node, graph) {
+        await requireTreeLinksAuthorized(actor, node, graph);
+        await requireToolsAuthorized(actor, node, graph);
+    }
+    // The material of one step: what hangs off it on a `context` edge, as nodes.
+    function attachedNodes(node, graph) {
+        return graph.edges
+            .filter((edge) => edge.kind === "context" && edge.source === node.id)
+            .flatMap((edge) => graph.nodes.filter((candidate) => candidate.id === edge.target));
+    }
+    // ⚠️ The two halves are separate functions only because `collectRunProblems` needs the first one
+    // without the second (#435): every tool of the whole graph is already asked about there, so
+    // asking again for the first step reported the same tool twice. `requireNodeAuthorized` above is
+    // what every execution boundary calls, and it is still both halves — splitting the CHECK would
+    // be the drift this file spends a page warning about; splitting the FUNCTION is not.
+    async function requireTreeLinksAuthorized(actor, node, graph) {
+        if (!node)
+            return;
+        const attached = attachedNodes(node, graph);
+        const wanted = [...new Set(treeLinkNodes({ ...graph, nodes: attached }).map(resourceIdOf))];
+        if (!wanted.length)
+            return;
+        const reachable = await reachableNodes(actor, wanted);
+        if (reachable.length !== wanted.length) {
+            throw new IntelError(403, "flow_node_forbidden", treeLinkStepDetail(node.label, wanted.length - reachable.length));
+        }
+    }
+    async function requireToolsAuthorized(actor, node, graph) {
+        if (!node)
+            return;
+        const servers = attachedNodes(node, graph)
+            .filter((candidate) => candidate.kind === "tool")
+            .map((candidate) => candidate.configuration.server);
+        if (!servers.length)
+            return;
+        const missing = await deps.unavailableServers(actor, [...new Set(servers)]);
+        if (missing.length) {
+            throw new IntelError(403, "flow_tools_unavailable", toolStepDetail(missing));
+        }
+    }
+    /**
+     * ⚠️ The boundary this whole slice turns on. A sub-flow step's reason for failing was written
+     * inside the *called* run, and that run is a run of its own with its own authorization — a library
+     * flow carries `execute` for everyone and `read` for nobody (ADR-0004 §3), so somebody who may
+     * read the calling flow can easily have no claim at all on what happened inside the called one.
+     *
+     * So the call sites are asked through the very predicate that opens a single run, and never
+     * through a second rule written for display. A site that comes back is one whose called run this
+     * actor may see: the stored text then travels and the called run is named so the reader can
+     * follow it. A site that stays out is reported by the *caller's* own label — the caller's to give
+     * — with a text that says no more than that the call did not finish. Named what they may see,
+     * counted the rest (#17, #19, #20).
+     *
+     * A whole page of sites in one read (#30): a list that asked per row would put two queries on
+     * every failed line, which is exactly the shape that ticket removed everywhere else.
+     */
+    async function visibleCalls(actor, sites) {
+        if (sites.length === 0)
+            return new Map();
+        const found = await deps.repository.visibleCallRuns(actor, sites);
+        return new Map(found.map((call) => [callKey(call.runId, call.nodeId), call.calledRunId]));
+    }
+    /**
+     * What a run looks like right now: the run as this actor may read it, the node it stands on, and
+     * the trail it belongs to. Data only — it asks nothing.
+     *
+     * ⚠️ Split out of `step` because of the order this used to be in (#112). `completeStep` writes
+     * the step and then shapes its answer, and shaping used to authorize a second time — so a check
+     * that failed AFTER the write told the caller "404" about work that had happened, and the retry
+     * replayed into the same 404 forever. Whoever just completed a step may be told what became of
+     * it. Whether they may run the NEXT one is asked when they run it, by the call that runs it.
+     *
+     * `narrowed` stays: it decides how much of a failure's text this reader may see, which is
+     * disclosure and not permission.
+     */
+    // ⚠️ The version is passed in rather than looked up. Both callers already hold it, and reading it
+    // again here cost one extra round trip per answer — which the query-count test caught (#30).
+    async function runState(actor, run, version) {
+        const node = nodeFor(version, run.currentNodeId);
+        return { run: await narrowed(actor, run, version), node, trail: await trailFor(run, version) };
+    }
+    // The same picture for somebody ASKING for it rather than having just acted: the flow has to
+    // resolve and the node they would be handed has to be one they may execute.
+    async function step(actor, run) {
+        await requireStartedFlow(actor, run.flowId);
+        const version = await requireVersion(run.versionId, run.flowId);
+        await requireNodeAuthorized(actor, nodeFor(version, run.currentNodeId), version.graph);
+        return await runState(actor, run, version);
+    }
+    // A failed run carries the text of the step that failed, and for a call that text came out of
+    // another run. It is narrowed here rather than at the door it entered through: what storage keeps
+    // is what happened, and who may read it is a question about the person asking, not about the row.
+    //
+    // Only a failed run pays for this, and then two reads at most — a run that is still going leaves
+    // before the first one.
+    async function narrowed(actor, run, version) {
+        if (run.status !== "failed" || !run.error)
+            return run;
+        const failed = (await deps.repository.failedSteps([run.id]))[0];
+        const node = failed ? nodeFor(version, failed.nodeId) : null;
+        if (!failed || node?.kind !== "subflow")
+            return run;
+        const calls = await visibleCalls(actor, [{ runId: run.id, nodeId: failed.nodeId }]);
+        const detail = callDetail(calls.get(callKey(run.id, failed.nodeId)), node.label, run.error);
+        return detail === run.error ? run : { ...run, error: detail };
+    }
+    // ADR-0004 §3, checked where it can still be answered honestly: at publish time, naming the reason
+    // rather than the error. A call is allowed into the caller's own folder or below it, or into a
+    // folder whose `execute` reaches at least as far as the caller's own — in practice `execute` for
+    // everyone, the library.
+    async function requireCallRule(actor, flow, graph) {
+        for (const calleeId of calleeIds(graph)) {
+            const callee = await deps.repository.getCallable(actor, calleeId);
+            if (!callee || callee.archivedAt) {
+                throw new IntelError(409, "flow_subflow_unavailable", `Called flow is unavailable: ${calleeId}`);
+            }
+            if (callee.id === flow.id)
+                continue;
+            if ((await deps.repository.callReach(flow.parentId, callee.parentId)) === "out-of-reach") {
+                throw new IntelError(409, "flow_subflow_out_of_reach", `${flow.title} may not call ${callee.title}: it is neither in ${flow.title}'s folder nor below it, and its folder is not executable for everyone. Move it into the calling flow's subtree, or share its folder's execute with the organization.`);
+            }
+        }
+    }
+    // Calls point downwards, so a cycle cannot form inside one subtree. It can come back over the
+    // library edge, and that is what this walks — once, at publish time, naming the whole chain
+    // instead of the one edge that closed it.
+    async function requireNoCallCycle(flow, graph) {
+        const titles = new Map([[flow.id, flow.title]]);
+        const settled = new Set();
+        const named = (ids) => ids.map((id) => titles.get(id) ?? id).join(" → ");
+        async function walk(callees, path) {
+            for (const calleeId of callees) {
+                const closes = path.indexOf(calleeId);
+                if (closes !== -1) {
+                    throw new IntelError(409, "flow_subflow_cycle", `Publishing would close a call cycle: ${named([...path.slice(closes), calleeId])}`);
+                }
+                if (settled.has(calleeId))
+                    continue;
+                const next = await deps.repository.publishedCallees(calleeId);
+                settled.add(calleeId);
+                if (!next)
+                    continue;
+                titles.set(calleeId, next.title);
+                if (path.length >= MaxCallDepth) {
+                    throw new IntelError(409, "flow_subflow_too_deep", `Calls are nested more than ${MaxCallDepth} deep: ${named([...path, calleeId])}`);
+                }
+                await walk(next.calleeIds, [...path, calleeId]);
+            }
+        }
+        await walk(calleeIds(graph), [flow.id]);
+    }
+    // What each call of a graph will take, as the publishing author may see it (ADR-0004 §5). One
+    // reader for the preview and the freeze alike: if the screen computed this and publishing computed
+    // it again, the two would drift and the author would have agreed to something else than what
+    // happened.
+    //
+    // ⚠️ A callee this actor cannot reach is left out rather than described. The preview is a list of
+    // titles, and a title is exactly what an unreachable flow must not hand out — the same mistake the
+    // review of #17 found in an error message.
+    async function calls(actor, graph) {
+        const seen = new Map();
+        const items = [];
+        for (const node of subflowNodes(graph)) {
+            const calleeId = node.configuration.flowId;
+            if (!seen.has(calleeId)) {
+                const found = await deps.repository.getCallable(actor, calleeId);
+                seen.set(calleeId, found && !found.archivedAt ? found : null);
+            }
+            const callee = seen.get(calleeId) ?? null;
+            if (!callee)
+                continue;
+            const selection = node.configuration.version;
+            const pinned = selection.mode === "pinned" ? selection.versionId : (callee.publishedVersionId ?? null);
+            // ⚠️ Resolved *against the callee*, never by identifier alone. `getVersion` returns whatever
+            // version carries that ID, whichever flow it belongs to — so a pin naming a foreign version
+            // would have its sequence reported here, a fact about a flow the reader was never shown, and
+            // the very same pin would then be frozen into the published graph. This is the check the
+            // freeze makes, made in the same words, so the two cannot drift apart.
+            const version = pinned ? await requireVersion(pinned, calleeId) : null;
+            items.push({
+                nodeId: node.id,
+                nodeLabel: node.label,
+                calleeId,
+                calleeTitle: callee.title,
+                mode: selection.mode,
+                // A call that follows has no answer until it runs, and saying "version 4" here would be a
+                // promise the next publication of the callee breaks.
+                versionId: selection.mode === "follows" ? null : pinned,
+                versionSequence: selection.mode === "follows" ? null : (version?.sequence ?? null),
+                freezes: selection.mode === "latest",
+                available: Boolean(callee.publishedVersionId),
+            });
+        }
+        return items;
+    }
+    // ⚠️ ADR-0004 §5, and the reason a published flow keeps doing what it did. `latest` is replaced by
+    // the callee's published version here and nowhere else; without it, changing a building block
+    // would silently change every flow that uses it. `follows` is left exactly as it is — it was
+    // chosen on purpose, and overwriting it would take that choice away again.
+    //
+    // Versions are immutable, so this cannot rewrite the one being published: it returns the frozen
+    // graph and the caller appends it as a new version.
+    async function freeze(actor, graph) {
+        let changed = false;
+        const nodes = [];
+        for (const node of graph.nodes) {
+            // A tool step is frozen the same way a sub-flow call is: what it may reach is pinned at the
+            // moment of publishing (#489). The check above has already refused an unreachable server and
+            // a surface that moved since a previous publish, so this only writes down what it confirmed.
+            if (node.kind === "tool") {
+                const fingerprint = await deps.toolSurfaceFingerprint(actor, node.configuration.server, node.configuration.allow);
+                if (fingerprint !== null && fingerprint !== node.configuration.fingerprint) {
+                    nodes.push({ ...node, configuration: { ...node.configuration, fingerprint } });
+                    changed = true;
+                    continue;
+                }
+                nodes.push(node);
+                continue;
+            }
+            if (node.kind !== "subflow") {
+                nodes.push(node);
+                continue;
+            }
+            const selection = node.configuration.version;
+            if (selection.mode === "pinned") {
+                // A pin is only worth anything while the version behind it is still there. Publishing a
+                // dangling pin would produce a flow that fails at its first call instead of at publish time.
+                await requireVersion(selection.versionId, node.configuration.flowId);
+                nodes.push(node);
+                continue;
+            }
+            // A call that rides along is left untouched, unpublished callee included: it resolves at run
+            // time by definition, and refusing here would forbid building a caller before its building
+            // block is finished — which is not what choosing "always latest" asked for.
+            if (selection.mode === "follows") {
+                nodes.push(node);
+                continue;
+            }
+            const callee = await deps.repository.getCallable(actor, node.configuration.flowId);
+            if (!callee?.publishedVersionId) {
+                // There is nothing to freeze to. Refused here, where the reason is readable, rather than at
+                // the first run of the call, where it would arrive as someone else's flow failing.
+                throw new IntelError(409, "flow_subflow_not_published", `The called flow has nothing published to freeze to: ${node.label}`);
+            }
+            changed = true;
+            nodes.push({
+                ...node,
+                configuration: {
+                    ...node.configuration,
+                    version: { mode: "pinned", versionId: callee.publishedVersionId },
+                },
+            });
+        }
+        return changed ? { ...graph, nodes } : null;
+    }
+    // The place a call is made from. It names a step, never a permission: the callee's `execute` was
+    // already asked of the user, and the caller's is asked again here, so a grant revoked while the
+    // outer run waited cannot be walked around by starting the inner one.
+    async function requireCallSite(actor, parent, calleeId) {
+        const run = await deps.repository.getRunVisible(actor, parent.runId);
+        if (!run)
+            throw new IntelError(404, "flow_run_not_found", "Flow run was not found");
+        if (run.initiatedBy !== actor.id) {
+            throw new IntelError(403, "flow_call_site_forbidden", "The calling run belongs to someone else");
+        }
+        await requireExecute(actor, run.flowId);
+        if (run.status !== "running") {
+            throw new IntelError(409, "flow_run_terminal", "Flow run is already terminal");
+        }
+        if (run.currentNodeId !== parent.nodeId) {
+            throw new IntelError(409, "flow_step_conflict", "A different step is currently active");
+        }
+        const version = await requireVersion(run.versionId, run.flowId);
+        const node = nodeFor(version, parent.nodeId);
+        if (node?.kind !== "subflow" || node.configuration.flowId !== calleeId) {
+            throw new IntelError(409, "flow_call_site_invalid", "That step does not call this flow");
+        }
+        // ⚠️ The version the call takes comes from the calling graph, which is immutable, and never from
+        // the request. A frozen call runs what it was frozen to however often the callee is published
+        // afterwards; a call that follows resolves to whatever is published at this moment, and the run
+        // row records which of the two it turned out to be (ADR-0004 §5).
+        const selection = node.configuration.version;
+        return { run, versionId: selection.mode === "pinned" ? selection.versionId : null };
+    }
+    return {
+        async list(actor, input = {}) {
+            const items = await deps.repository.listVisible(actor, input);
+            return { items, withCalls: await callableCallers(actor, items) };
+        },
+        async get(actor, flowId) {
+            const flow = await requireFlow(actor, flowId);
+            return {
+                flow,
+                version: flow.currentVersionId
+                    ? await requireVersion(flow.currentVersionId, flow.id)
+                    : null,
+            };
+        },
+        // The history of one flow, oldest first (#144). `requireFlow`, the same door as `get`: the
+        // history describes a flow this actor may already open, and it holds nothing a reader of the
+        // current graph could not learn — only when each edit happened and which one is live.
+        async listVersions(actor, flowId) {
+            const flow = await requireFlow(actor, flowId);
+            const items = await deps.repository.listVersions(flow.id);
+            return {
+                flowId: flow.id,
+                // Marked here, off the flow row already in hand: `published_version_id` is the flow's one
+                // answer, and asking storage to join it in would be a second place that could disagree.
+                items: items.map((version) => ({
+                    ...version,
+                    published: version.id === flow.publishedVersionId,
+                })),
+            };
+        },
+        // One version with its graph (#144). The flow resolves first, so a version ID belonging to a
+        // flow this actor may not see answers exactly like one that does not exist — `requireVersion`
+        // already refuses a version filed under another flow, in the same words.
+        async getVersion(actor, input) {
+            await requireFlow(actor, input.flowId);
+            return await requireVersion(input.versionId, input.flowId);
+        },
+        // What accesses what, for the WHOLE subtree a folder holds (#825; one level until then, #19).
+        // Flows answers it because the edges live in flow graphs; the node service answers which nodes
+        // exist and who may see them, because the tree and its ACLs are the node service's (ADR-0004 §1).
+        //
+        // ⚠️ Every node passes an authorization before it is drawn, and a node that fails it is left out
+        // entirely — no placeholder, no count, no edge. An edge to a grey box would already say that
+        // something is there and that this flow touches it, which is the whole of what was meant to stay
+        // hidden. `omitted` counts what the size limit cut, and nothing else.
+        async relationGraph(actor, input) {
+            const nodes = new Map();
+            const edges = [];
+            const dropped = new Set();
+            const nodesSeen = new Map();
+            const flowSeen = new Map();
+            // Every folder actually walked, and every id its own bounded read actually returned. The two
+            // together tell a later `place()` apart from a genuinely new omission: a node whose folder WAS
+            // walked but who never came back within THAT folder's own bound is already inside `unread`,
+            // and counting it again the moment a `reads`/`calls` edge reaches for it would make `omitted`
+            // drift away from the number of nodes actually left out (#30). This generalises what used to
+            // be a single `levelFolderId`/`levelIds` pair to the whole subtree the walk now covers (#825).
+            const visitedFolderIds = new Set();
+            const readIds = new Set();
+            let unread = 0;
+            // ⚠️ The radial tree's own structure (#825): a node reached again — first as a satellite of
+            // some other flow's `reads` edge, later as a real member of the walked subtree — keeps the
+            // TREE's placement, never the satellite's. `inScope` is what tells the two apart; depth and
+            // parent travel with it. `realParentId` is bookkeeping only, never drawn: it is the node's
+            // actual place in the tree, which for a satellite is not the same thing as the `null` parent
+            // in its own `RelationNode` (see `seenNode`).
+            function place(node, realParentId) {
+                const existing = nodes.get(node.id);
+                if (existing) {
+                    if (node.inScope && !existing.inScope)
+                        nodes.set(node.id, node);
+                    return true;
+                }
+                if (nodes.size >= input.limit) {
+                    if (!(visitedFolderIds.has(realParentId) && !readIds.has(node.id))) {
+                        dropped.add(node.id);
+                    }
+                    return false;
+                }
+                nodes.set(node.id, node);
+                return true;
+            }
+            // ⚠️ Archived is decided here rather than behind the port, beside the identical rule
+            // `calleeFlow` applies one function down. The port answers one question — may this actor see
+            // it — because the run path asks it too, and a document being archived must not start
+            // refusing steps under a message that names the wrong reason. What a drawing leaves out and
+            // what a run refuses are two decisions; only the first belongs to #19.
+            //
+            // ⚠️ A node reached only this way is never part of the tree (#825): its own `RelationNode`
+            // carries no parent and borrows the depth of whichever flow pointed at it, so the renderer
+            // draws it as a satellite on a dashed `reads` edge rather than inventing a membership arc for
+            // it. `parentId` in the RETURNED pair is the node's real parent all the same — `place` still
+            // needs it to tell a genuinely new omission from one `unread` already counted.
+            async function seenNode(nodeId, atDepth) {
+                if (!nodesSeen.has(nodeId)) {
+                    const found = await deps.visibleNodes(actor, nodeId);
+                    nodesSeen.set(nodeId, found && !found.archivedAt
+                        ? {
+                            node: {
+                                id: found.id,
+                                kind: found.kind,
+                                title: found.title,
+                                inScope: false,
+                                parentId: null,
+                                depth: atDepth,
+                            },
+                            parentId: found.parentId,
+                        }
+                        : null);
+                }
+                return nodesSeen.get(nodeId) ?? null;
+            }
+            // The rows are already in hand — every callee of the subtree was read in one statement below —
+            // so this is the archived rule and nothing else.
+            function calleeFlow(flowId) {
+                const found = flowSeen.get(flowId);
+                return found && !found.archivedAt ? found : null;
+            }
+            // The subtree itself first, so a big folder spends its budget on its own contents rather than
+            // on whatever the first flow in it happens to reach.
+            //
+            // ⚠️ `limit` bounds what is *read* as well as what is drawn (#30). Both reads stop at it, and
+            // what they stopped short of comes back as a count instead of as rows. The order inside those
+            // statements is the part that must not move: the visibility predicate first and the bound
+            // after it, so the cut falls among the rows this actor may see — a bound applied first would
+            // let a row they may never see take up a place in the picture, and the number below would then
+            // be saying that it is there.
+            const scopeFlows = [];
+            if (input.scope.of === "flow") {
+                const flow = await requireFlow(actor, input.scope.flowId);
+                place({ id: flow.id, kind: "flow", title: flow.title, inScope: true, parentId: null, depth: 0 }, null);
+                scopeFlows.push(flow);
+            }
+            else {
+                const rootFolderId = input.scope.folderId;
+                // The folder itself sits at the centre (depth 0). `null` names the whole tree, which has no
+                // single folder to put there — its top-level items become the first ring instead, exactly as
+                // a real root's children would (#825).
+                if (rootFolderId !== null) {
+                    const root = await deps.visibleNodes(actor, rootFolderId);
+                    if (root && !root.archivedAt) {
+                        place({
+                            id: root.id,
+                            kind: root.kind,
+                            title: root.title,
+                            inScope: true,
+                            parentId: null,
+                            depth: 0,
+                        }, root.parentId);
+                    }
+                }
+                // Breadth-first over the whole subtree, shallowest folders first, so the budget above is
+                // spent close to the root rather than on whichever branch happens to be walked first. A new
+                // folder is queued only while there is still room for what it might hold; one already queued
+                // is still visited in full, so what it could not fit is counted rather than silently dropped.
+                const queue = [
+                    { folderId: rootFolderId, childDepth: 1 },
+                ];
+                while (queue.length > 0) {
+                    const next = queue.shift();
+                    if (!next)
+                        break;
+                    const { folderId, childDepth } = next;
+                    visitedFolderIds.add(folderId);
+                    const children = await deps.nodeChildren(actor, folderId, input.limit);
+                    unread += children.total - children.items.length;
+                    for (const item of children.items) {
+                        readIds.add(item.id);
+                        const kept = place({
+                            id: item.id,
+                            kind: item.kind,
+                            title: item.title,
+                            inScope: true,
+                            parentId: folderId,
+                            depth: childDepth,
+                        }, folderId);
+                        if (kept && item.kind === "folder" && nodes.size < input.limit) {
+                            queue.push({ folderId: item.id, childDepth: childDepth + 1 });
+                        }
+                    }
+                    const filed = await deps.repository.listVisibleBounded(actor, folderId, input.limit);
+                    unread += filed.total - filed.items.length;
+                    for (const flow of filed.items) {
+                        readIds.add(flow.id);
+                        if (place({
+                            id: flow.id,
+                            kind: "flow",
+                            title: flow.title,
+                            inScope: true,
+                            parentId: folderId,
+                            depth: childDepth,
+                        }, folderId)) {
+                            scopeFlows.push(flow);
+                        }
+                    }
+                }
+            }
+            // The draft is what the author is looking at; the published graph is what a flow without one
+            // still does. Reading neither would leave a flow in the picture with no edges at all.
+            const versions = new Map((await deps.repository.getVersions([
+                ...new Set(scopeFlows
+                    .map((flow) => flow.currentVersionId ?? flow.publishedVersionId)
+                    .filter((versionId) => versionId !== null)),
+            ])).map((version) => [version.id, version]));
+            const drawable = scopeFlows.flatMap((flow) => {
+                const version = versions.get(flow.currentVersionId ?? flow.publishedVersionId ?? "");
+                return version ? [{ flow, version }] : [];
+            });
+            // One read for the versions of the subtree and one for everything it calls, instead of a pair
+            // per flow (#30). Both are bounded by the subtree, which is bounded by `limit`. Nothing below
+            // changes because of it: the walk is the same walk in the same order, over rows already in
+            // hand, so what is drawn and what is cut are what they were.
+            for (const callee of await deps.repository.listCallable(actor, [
+                ...new Set(drawable.flatMap(({ version }) => subflowNodes(version.graph).map((node) => node.configuration.flowId))),
+            ])) {
+                flowSeen.set(callee.id, callee);
+            }
+            for (const { flow, version } of drawable) {
+                // Already placed above — this only borrows its depth for whatever it reaches or calls.
+                const referrerDepth = nodes.get(flow.id)?.depth ?? 0;
+                // The node lists rather than a walk of `graph.nodes` with two `kind` tests: an edge has to
+                // 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 treeLinkNodes(version.graph)) {
+                    const resourceId = resourceIdOf(node);
+                    const target = await seenNode(resourceId, referrerDepth);
+                    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);
+                    if (!callee ||
+                        !place({
+                            id: callee.id,
+                            kind: "flow",
+                            title: callee.title,
+                            inScope: false,
+                            parentId: null,
+                            depth: referrerDepth,
+                        }, callee.parentId)) {
+                        continue;
+                    }
+                    edges.push({
+                        id: `calls:${flow.id}:${node.id}:${callee.id}`,
+                        source: flow.id,
+                        target: callee.id,
+                        relation: "calls",
+                    });
+                }
+            }
+            // The outer ring (#825). Only a node the viewer holds `share` on gets an access edge at all —
+            // `node_effective_access_list` refuses without it, and this graph must not hand out, node by
+            // node, an answer that tool refuses right next to it. Bounded to the three rings the renderer
+            // still draws as their own circles (depth 0 to 2, "drei Ringe offen"): the fourth ring on is
+            // bundled into one labelled sector (#825), which has nowhere for a line to land. `flow` nodes
+            // are skipped — sharing a flow and sharing a node are two different tables, and this reads only
+            // the second.
+            const users = new Map();
+            const access = [];
+            if (deps.nodeShareable && deps.nodeEffectiveAccess) {
+                const nodeShareable = deps.nodeShareable;
+                const nodeEffectiveAccess = deps.nodeEffectiveAccess;
+                const candidates = [...nodes.values()].filter((node) => node.kind !== "flow" && node.depth <= 2);
+                await Promise.all(candidates.map(async (node) => {
+                    if (!(await nodeShareable(actor, node.id)))
+                        return;
+                    const effective = await nodeEffectiveAccess(node.id);
+                    const userIds = new Set([
+                        ...effective.ownerIds,
+                        ...effective.items
+                            .map((grant) => grant.principal)
+                            .filter((principal) => principal.type === "user")
+                            .map((principal) => principal.id),
+                    ]);
+                    for (const userId of userIds) {
+                        users.set(userId, { id: userId });
+                        access.push({ userId, nodeId: node.id });
+                    }
+                }));
+            }
+            return {
+                scope: input.scope,
+                nodes: [...nodes.values()],
+                edges,
+                users: [...users.values()],
+                access,
+                // What did not fit and what was never read for lack of room: two ways of being left out,
+                // one number, and neither of them a permission (#19).
+                omitted: dropped.size + unread,
+                limit: input.limit,
+            };
+        },
+        // Read out of the graph, never out of `parent_id`: what a flow calls is what it does, and where
+        // it is filed is only where it is filed. A flow used by three callers is listed under all three.
+        async listCalls(actor, flowId) {
+            const flow = await requireFlow(actor, flowId);
+            const versionId = flow.currentVersionId ?? flow.publishedVersionId;
+            if (!versionId)
+                return { items: [], withCalls: [] };
+            const version = await requireVersion(versionId, flow.id);
+            const wanted = calleeIds(version.graph);
+            // One read for every callee rather than one per callee (#30). This is what the sidebar asks
+            // when a flow is unfolded, so it runs while somebody is only looking around.
+            //
+            // ⚠️ The order stays the graph's, restored here from the storage layer's. A call list answers
+            // "what do I run, and how", and that is the order the steps stand in; a callee this actor may
+            // neither open nor run is absent from the answer, exactly as it was.
+            const callable = new Map((await deps.repository.listCallable(actor, wanted)).map((callee) => [callee.id, callee]));
+            const items = [];
+            for (const calleeId of wanted) {
+                const callee = callable.get(calleeId);
+                if (callee && !callee.archivedAt)
+                    items.push(callee);
+            }
+            // A called flow calls flows of its own: the same question, one level deeper (#59).
+            return { items, withCalls: await callableCallers(actor, items) };
+        },
+        // "What this flow needs", straight out of the graph: no arithmetic, nothing that can go stale,
+        // 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
+            // nothing else to describe.
+            const versionId = flow.currentVersionId ?? flow.publishedVersionId;
+            if (!versionId) {
+                return {
+                    flowId: flow.id,
+                    versionId: null,
+                    nodes: [],
+                    invalidNodes: [],
+                    hiddenNodes: 0,
+                    servers: [],
+                };
+            }
+            const version = await requireVersion(versionId, flow.id);
+            const referenced = graphReferences(version.graph);
+            // ⚠️ The same lookup a tree link passes through, not a second rule written for a list.
+            // What it hands back is named; a title is exactly what someone without access may not learn
+            // (#17, #19). Tool names are not filtered: they come from a graph this actor may already
+            // read, and whether the portal offers them is a question only their own token can answer.
+            const reachable = await reachableNodes(actor, referenced.nodes);
+            const named = new Set(reachable.map((reference) => reference.id));
+            const unreachable = referenced.nodes.filter((resourceId) => !named.has(resourceId));
+            // ⚠️ What is left over used to be ONE number, and the panel read it out as "you cannot see
+            // it" — a sentence about a permission, in front of a link that names nothing at all (#509).
+            // The two suggest opposite actions and only one of them helps: with a permission one asks for
+            // access, with a dead reference the step has to be replaced before the flow can run.
+            //
+            // ⚠️ The second question is asked ONLY about what the visibility door already refused, and it
+            // is asked without an actor because its answer does not depend on one. That is the narrowest
+            // shape this distinction can have — the alternative, a lookup that is kinder than the door it
+            // describes, is what #17 and #19 were sent back for. It is still a disclosure and it is a
+            // deliberate one (#492): for an id the caller wrote into this graph themselves, they learn
+            // whether the tree still holds a row for it.
+            const alive = new Set(await deps.repository.existingNodes(unreachable));
+            const invalidNodes = unreachable.filter((resourceId) => !alive.has(resourceId));
+            return {
+                flowId: flow.id,
+                versionId: version.id,
+                nodes: reachable,
+                invalidNodes,
+                hiddenNodes: unreachable.length - invalidNodes.length,
+                servers: referenced.servers,
+            };
+        },
+        async listGrants(actor, flowId) {
+            const flow = await requireShareable(actor, flowId);
+            return {
+                resourceId: flow.id,
+                applicableVerbs: flowVerbs,
+                items: await deps.repository.listFlowGrants(flow.id),
+            };
+        },
+        async listEffectiveAccess(actor, flowId) {
+            const flow = await requireShareable(actor, flowId);
+            const effective = await deps.repository.listEffectiveFlowAccess(flow.id);
+            // ⚠️ **Empty here, and that is a gap rather than a decision** (anchrd/intel#807). A flow
+            // inherits its grants from the FOLDERS above it, and naming one means reading a node title
+            // through the node repository's visibility predicate — which this service deliberately does
+            // not hold (`FlowRepository` knows flows). The screen falls back to saying the access is
+            // inherited without saying from where, which is the same thing it says for a folder the
+            // reader may not see, so nothing here reads as broken.
+            return { resourceId: flow.id, ...effective, sources: [] };
+        },
+        async share(actor, input) {
+            const flow = await requireShareable(actor, input.flowId);
+            const replayedId = await deps.repository.findIdempotent(actor.id, "flows.share", input.idempotencyKey);
+            const principal = input.principal.type === "email"
+                ? { type: "email", email: input.principal.email.toLowerCase() }
+                : input.principal;
+            if (replayedId) {
+                const replayed = (await deps.repository.listFlowGrants(flow.id)).find((grant) => grant.id === replayedId);
+                // A replay describes the same access the first attempt did, so the warning is asked again
+                // rather than remembered: what the grantee can reach may have changed since.
+                if (replayed)
+                    return await withShareWarnings(actor, flow, replayed, replayed.principal);
+            }
+            // ⚠️ The same rule as on a node grant, in the same place and for the same two reasons (#442):
+            // in front of `setFlowGrant` so nothing that could never work is written, behind the replay so
+            // a retry with the same key still answers with the grant its first attempt made. The long
+            // form of the argument stands at the node grant in `nodes.ts`.
+            requireFutureExpiry(input.expiresAt, deps.now());
+            const timestamp = deps.now().toISOString();
+            const grant = await deps.repository.setFlowGrant({
+                grant: {
+                    id: deps.id(),
+                    resourceId: flow.id,
+                    principal,
+                    verb: input.verb,
+                    expiresAt: input.expiresAt,
+                    createdBy: actor.id,
+                    createdAt: timestamp,
+                },
+                flowId: flow.id,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            // ⚠️ After the grant is written, never before. The answer describes the access now in force,
+            // and a warning computed a moment earlier would still list what this very grant just opened.
+            return await withShareWarnings(actor, flow, grant, principal);
+        },
+        async revokeGrant(actor, input) {
+            const flow = await requireShareable(actor, input.flowId);
+            const replayed = await deps.repository.findIdempotentFlowRevocation(actor.id, input.idempotencyKey);
+            if (replayed !== null)
+                return { revoked: replayed };
+            return {
+                revoked: await deps.repository.revokeFlowGrant({
+                    flowId: flow.id,
+                    grantId: input.grantId,
+                    actorId: actor.id,
+                    idempotencyKey: input.idempotencyKey,
+                    auditId: deps.id(),
+                    occurredAt: deps.now().toISOString(),
+                }),
+            };
+        },
+        async create(actor, input) {
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.create", input.idempotencyKey);
+            if (replayed)
+                return await requireFlow(actor, replayed);
+            await requireFolder(actor, input.parentId);
+            const occurredAt = deps.now().toISOString();
+            return await deps.repository.insertFlow({
+                flow: {
+                    // A flow is offered at `flow_publish` and never at creation: publishing is the decision
+                    // that it is for other people, and an unpublished flow is in nobody's catalogue (#775).
+                    promptName: null,
+                    id: deps.id(),
+                    parentId: input.parentId,
+                    title: plainTitle(input.title),
+                    description: input.description,
+                    ownerId: actor.id,
+                    currentVersionId: null,
+                    publishedVersionId: null,
+                    createdAt: occurredAt,
+                    updatedAt: occurredAt,
+                    archivedAt: null,
+                },
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+        },
+        // Rename and move. It reads and writes the flow row alone: no version is appended, no published
+        // version is touched and no run is signalled, so tidying up the tree cannot change what a flow
+        // does (ADR-0004).
+        async update(actor, input) {
+            const current = await requireEdit(actor, input.flowId);
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.update", input.idempotencyKey);
+            if (replayed)
+                return await requireFlow(actor, replayed);
+            if (input.parentId !== undefined)
+                await requireFolder(actor, input.parentId);
+            const updated = await deps.repository.updateFlow({
+                flow: {
+                    ...current,
+                    parentId: input.parentId === undefined ? current.parentId : input.parentId,
+                    title: input.title === undefined ? current.title : plainTitle(input.title),
+                    description: input.description === undefined ? current.description : input.description,
+                    updatedAt: deps.now().toISOString(),
+                },
+                baseUpdatedAt: input.baseUpdatedAt,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            if (updated === "conflict") {
+                throw new IntelError(409, "flow_update_conflict", "Flow was changed by another editor");
+            }
+            return updated;
+        },
+        /**
+         * ⚠️ The flow half of #457 — after this a flow is really gone, with its versions and the record
+         * of every run it ever had. Read the decisions on that issue before touching it.
+         */
+        async purge(actor, input) {
+            const current = await deps.repository.getVisible(actor, input.flowId);
+            if (!current)
+                throw new IntelError(404, "flow_not_found", "Flow was not found");
+            if (!(await deps.repository.can(actor, input.flowId, "write"))) {
+                throw new IntelError(403, "flow_edit_forbidden", "Flow cannot be edited");
+            }
+            // ⚠️ THE structural guard, same as the node's: a living flow has no path into nothing.
+            if (!current.archivedAt) {
+                throw new IntelError(409, "flow_not_archived", "Only an archived flow can be deleted for good. Archive it first.");
+            }
+            // A published caller would break at RUN TIME, in front of somebody who did not order this.
+            // ⚠️ The callers travel as DATA beside the sentence (#593, the second half of #448): the
+            // archive shows this refusal, and a German or Spanish screen could otherwise do nothing but
+            // print the English one. The sentence stays for a model over MCP, which has nothing to
+            // formulate with.
+            const callers = await deps.repository.flowCallers(actor, current.id);
+            if (callers.visible.length || callers.hidden) {
+                throw new IntelError(409, "flow_in_use_by_flow", callersDetail(callers), namedOrCounted(callers));
+            }
+            // ⚠️ The one thing a flow has that a node does not: its runs can be the PARENT of runs
+            // belonging to other flows. Deleting them would take the record of who started those runs
+            // with it — a history with a hole is not a history, so this refuses instead.
+            if (await deps.repository.hasEntangledRuns(current.id)) {
+                throw new IntelError(409, "flow_runs_entangled", "Runs of this flow are tied to runs of other flows. Deleting them would leave those without the record of what started them, or without the run they are waiting for.");
+            }
+            // ⚠️ Archiving deliberately leaves a run in flight alone, because restoring the flow makes it
+            // readable again. A purge takes that way back with it — so an unfinished run refuses.
+            if (await deps.repository.hasUnfinishedRuns(current.id)) {
+                throw new IntelError(409, "flow_runs_unfinished", "This flow still has runs that have not finished. Wait for them or cancel them first.");
+            }
+            const purged = await deps.repository.purgeFlow({
+                flowId: current.id,
+                actorId: actor.id,
+                auditId: deps.id(),
+                occurredAt: deps.now().toISOString(),
+            });
+            if (purged === "missing") {
+                throw new IntelError(409, "flow_update_conflict", "Flow was changed by another editor");
+            }
+            return { purged: true, title: current.title };
+        },
+        /**
+         * Archive a flow, or take it back out again.
+         *
+         * ⚠️ The one place that resolves the flow through `getVisible` instead of `requireFlow`. Every
+         * other entry point treats an archived flow as absent — that is the whole point of archiving —
+         * but the call that restores one has to be able to find it, and `requireFlow` answers 404 for
+         * exactly the rows this call exists for. The visibility predicate is the same one; only the
+         * `archivedAt` refusal is left out.
+         *
+         * `write` and nothing more, asked before the row is touched: archiving is organization, the same
+         * grant that renames and moves (ADR-0004). It appends no version and withdraws no publication.
+         *
+         * ⚠️ It does NOT leave runs in flight alone, however much the word "archive" suggests it would.
+         * `completeStep` writes before it shapes its answer: the step is recorded, and `step()` then
+         * resolves the flow and throws 404 for the archived one. The caller is told the step failed
+         * while storage has it done, and a retry replays into the same 404. Restoring the flow is what
+         * makes the run readable again. That belongs to the run machine and has its own ticket
+         * (issue 112) — archiving is only the easiest way to walk into it.
+         */
+        async archive(actor, input) {
+            const current = await deps.repository.getVisible(actor, input.flowId);
+            if (!current)
+                throw new IntelError(404, "flow_not_found", "Flow was not found");
+            if (!(await deps.repository.can(actor, input.flowId, "write"))) {
+                throw new IntelError(403, "flow_edit_forbidden", "Flow cannot be edited");
+            }
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.archive", input.idempotencyKey);
+            // Read back the way this call reads anything, or replaying an archive would 404 on the row it
+            // just archived.
+            if (replayed) {
+                const flow = await deps.repository.getVisible(actor, replayed);
+                if (!flow)
+                    throw new IntelError(404, "flow_not_found", "Flow was not found");
+                return flow;
+            }
+            /**
+             * ⚠️ **A flow cannot be restored on its own into an archived folder** (D71, #733, found in
+             * review of #738). The same refusal `nodes.archive` carries, and for the same reason: a live
+             * flow under an archived folder is reached by a purge of that folder, which checks
+             * `archived_at` on its root alone and walks the whole subtree.
+             */
+            if (!input.archived && current.parentId !== null) {
+                // ⚠️ Asked WITHOUT the visibility predicate, and that is the difference between a guard and
+                // a decoration: a flow is reachable through `flow_grants` on its own, so its grantee may not
+                // see the folder it is filed in. `folderAccess` answers `missing` for such a folder, the
+                // guard would not fire, and a live flow would hang under an archived one — where the purge
+                // of that folder takes it through `parent_id IN tree`.
+                const folder = await deps.parentArchivedAt(current.parentId);
+                if (folder?.archivedAt) {
+                    throw new IntelError(409, "parent_archived", "The folder this flow is filed in is archived, so it cannot be restored on its own. Restore the folder first, and this comes back with it.");
+                }
+            }
+            const updatedAt = deps.now().toISOString();
+            const updated = await deps.repository.archiveFlow({
+                flowId: current.id,
+                baseUpdatedAt: input.baseUpdatedAt,
+                archivedAt: input.archived ? updatedAt : null,
+                updatedAt,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            if (updated === "conflict") {
+                throw new IntelError(409, "flow_update_conflict", "Flow was changed by another editor");
+            }
+            return updated;
+        },
+        async save(actor, input) {
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.save", input.idempotencyKey);
+            if (replayed) {
+                const version = await requireVersion(replayed, input.flowId);
+                return { flow: await requireFlow(actor, input.flowId), version };
+            }
+            const flow = await requireEdit(actor, input.flowId);
+            compileFlow(input.graph);
+            if (flow.currentVersionId !== input.baseVersionId) {
+                throw new IntelError(409, "flow_version_conflict", "Flow changed since it was loaded");
+            }
+            const previous = flow.currentVersionId
+                ? await requireVersion(flow.currentVersionId, flow.id)
+                : null;
+            const occurredAt = deps.now().toISOString();
+            const version = {
+                id: deps.id(),
+                flowId: flow.id,
+                sequence: (previous?.sequence ?? 0) + 1,
+                graph: input.graph,
+                createdBy: actor.id,
+                createdAt: occurredAt,
+            };
+            const result = await deps.repository.insertVersion({
+                version,
+                baseVersionId: input.baseVersionId,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            if (result === "conflict") {
+                throw new IntelError(409, "flow_version_conflict", "Flow changed since it was loaded");
+            }
+            return { flow: await requireFlow(actor, flow.id), version };
+        },
+        // What publishing will do to the calls, before it does it (ADR-0004 §5). It reads and writes
+        // nothing, and it asks for `write` rather than `read`: only someone who could publish has any
+        // business reading which versions a publication would pin.
+        async previewPublish(actor, input) {
+            const flow = await requireEdit(actor, input.flowId);
+            const version = await requireVersion(input.versionId, flow.id);
+            // ⚠️ `available` is asked with the VERY call that publishing uses, not with a cheaper one that
+            // answers a similar question. `unavailableServers` only says whether a server reaches
+            // anything; publishing asks whether THIS step's surface is whole — and those differ exactly
+            // where it hurts: a narrowed step whose allowed function disappeared keeps a reachable
+            // server, so the cheap question says "fine" and the confirmation then answers 409. A preview
+            // that promises a freeze the confirmation denies is worse than no preview.
+            const tools = await Promise.all(toolNodes(version.graph).map(async (node) => ({
+                nodeId: node.id,
+                nodeLabel: node.label,
+                server: node.configuration.server,
+                allow: node.configuration.allow,
+                available: (await deps.toolSurfaceFingerprint(actor, node.configuration.server, node.configuration.allow)) !== null,
+            })));
+            return {
+                flowId: flow.id,
+                versionId: version.id,
+                calls: await calls(actor, version.graph),
+                tools,
+            };
+        },
+        async publish(actor, input) {
+            const flow = await requireEdit(actor, input.flowId);
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.publish", input.idempotencyKey);
+            if (replayed)
+                return await requireFlow(actor, flow.id);
+            const version = await requireVersion(input.versionId, flow.id);
+            compileFlow(version.graph);
+            const wanted = [...new Set(treeLinkNodes(version.graph).map(resourceIdOf))];
+            const reachable = new Set((await reachableNodes(actor, wanted)).map((reference) => reference.id));
+            // ⚠️ Asked over the deduplicated resource ids and REFUSED over the nodes (#551). The resource
+            // id is what the ACL answers about, and it is also the one thing the author cannot look up:
+            // it stands in no place the editor draws, so `Node reference is unavailable: n-01H…` named
+            // the failure after the only participant nobody can find. The link node beside it carries the
+            // label on the canvas, so the refusal names that instead.
+            //
+            // ⚠️ Naming the label reveals nothing the ACL is keeping: it is the author's own text in
+            // their own graph, already on their screen — unlike the run-time refusal, which counts the
+            // documents rather than naming them because there the READER may not see them (#17, #19).
+            for (const node of treeLinkNodes(version.graph)) {
+                if (!reachable.has(resourceIdOf(node))) {
+                    throw new IntelError(409, "flow_node_unavailable", `Node ${nodeName(node)} names a document you cannot reach`);
+                }
+            }
+            for (const node of version.graph.nodes) {
+                if (node.kind === "tool") {
+                    // ⚠️ The fingerprint covers the whole surface this step may use — the server and, when
+                    // the step narrows it, exactly those functions with their schemas (#489). Freezing one
+                    // function was enough while a step named one; a step that may use any function of a
+                    // server would otherwise silently inherit functions the provider added AFTER publishing.
+                    const fingerprint = await deps.toolSurfaceFingerprint(actor, node.configuration.server, node.configuration.allow);
+                    if (!fingerprint) {
+                        throw new IntelError(409, "flow_tool_unavailable", `Tool server is unavailable: ${node.label}`);
+                    }
+                    // ⚠️ A step that has never been published carries no fingerprint, and that is not a
+                    // mismatch — it is the state every draft starts in. Publishing is what FREEZES the
+                    // surface, exactly as it turns a `latest` sub-flow call into a pinned one, and `freeze`
+                    // below writes the value in.
+                    //
+                    // Demanding it up front would mean the editor had to produce it, and nothing hands it
+                    // one: the value is derived from the asking user's own live catalog. Requiring it would
+                    // make every tool step unpublishable rather than safe.
+                    if (node.configuration.fingerprint !== null &&
+                        node.configuration.fingerprint !== fingerprint) {
+                        throw new IntelError(409, "flow_tool_schema_changed", `Review the current schema before publishing: ${node.label}`);
+                    }
+                }
+            }
+            // Both refusals happen before the flow is published, so a call that breaks the rule never
+            // becomes something a run could follow.
+            await requireCallRule(actor, flow, version.graph);
+            await requireNoCallCycle(flow, version.graph);
+            // ADR-0004 §5: `latest` becomes the concrete version here. A version is immutable, so the
+            // freeze cannot rewrite the one being published — it appends the frozen graph as the next
+            // version and publishes that. The author saw the same list through `previewPublish` first.
+            const frozenGraph = await freeze(actor, version.graph);
+            let publishable = version;
+            if (frozenGraph) {
+                // ⚠️ Keyed on the version being frozen, not on the request. Freezing version X is a
+                // function of X, so every attempt at it has to land on the one version the first attempt
+                // appended: a retry whose answer was lost, and a second confirmation of the same preview,
+                // are re-entries rather than repetitions. With a per-request key the second attempt would
+                // append a second version — and could then never publish, because the draft it was based on
+                // is no longer the current one and the guard below would refuse it forever.
+                const freezeKey = `freeze:${version.id}`;
+                const already = await deps.repository.findIdempotent(actor.id, "flows.save", freezeKey);
+                if (already) {
+                    publishable = await requireVersion(already, flow.id);
+                }
+                else {
+                    // Appending only ever continues the draft. Freezing an older version would fork the
+                    // chain and leave the editor holding a version that is no longer the flow's current one.
+                    if (flow.currentVersionId !== version.id) {
+                        throw new IntelError(409, "flow_publish_not_current", "Only the current version can be published while it still calls a latest sub-flow");
+                    }
+                    const frozen = {
+                        id: deps.id(),
+                        flowId: flow.id,
+                        sequence: version.sequence + 1,
+                        graph: frozenGraph,
+                        createdBy: actor.id,
+                        createdAt: deps.now().toISOString(),
+                    };
+                    const saved = await deps.repository.insertVersion({
+                        version: frozen,
+                        baseVersionId: version.id,
+                        actorId: actor.id,
+                        idempotencyKey: freezeKey,
+                        auditId: deps.id(),
+                    });
+                    if (saved === "conflict") {
+                        throw new IntelError(409, "flow_version_conflict", "Flow changed since it was loaded");
+                    }
+                    publishable = frozen;
+                }
+            }
+            const published = await deps.repository.publish({
+                flowId: flow.id,
+                versionId: publishable.id,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+                occurredAt: deps.now().toISOString(),
+                // ⚠️ Spread rather than assigned, and `exactOptionalPropertyTypes` is only half the reason.
+                // The repository distinguishes three states, and "the field is present carrying
+                // `undefined`" is not one of them: it has to be ABSENT for "leave the name alone".
+                ...(input.promptName === undefined ? {} : { promptName: input.promptName }),
+            });
+            if (published === "prompt_name_taken") {
+                /**
+                 * ⚠️ **The holder is named only to somebody who may see it** — the same sentence
+                 * `node_update` gives, out of the same query (`db-prompts.ts`). The catalogue is one across
+                 * documents and flows, so the name a flow is refused for may well be held by a document,
+                 * and the refusal has to be able to say so.
+                 */
+                const holder = await deps.repository.promptNameHolder(actor, input.promptName);
+                const held = holder === null
+                    ? "It is already taken."
+                    : holder.title === null
+                        ? `A ${holder.kind} you cannot see already uses it.`
+                        : `The ${holder.kind} "${holder.title}" already uses it.`;
+                throw new IntelError(409, "prompt_name_taken", `The slash command "${input.promptName}" is not free. ${held} Pick another name — names are never changed for you, because the catalogue would then mean a different thing to every reader.`);
+            }
+            if (!published)
+                throw new IntelError(409, "flow_publish_conflict", "Flow could not be published");
+            return await requireFlow(actor, flow.id);
+        },
+        /**
+         * Withdraw the publication (#146) — the operation the refusal in `knowledge.ts` has promised
+         * all along ("Change or unpublish them before narrowing the folder"). `published_version_id`
+         * goes back to null and nothing else moves: every version is kept, and republishing any of
+         * them is one `publish` away.
+         *
+         * What it means downstream is already decided by the checks that exist: new starts answer
+         * `flow_not_published`, a caller's `validate` reports `flow_subflow_not_published` for the
+         * dead call, and runs in flight keep their immutable version — publication decides what may
+         * START, never what happens to what is already going (#112). The narrowing guard reads only
+         * published graphs, so an unpublished caller frees its library folder.
+         */
+        async unpublish(actor, input) {
+            const flow = await requireEdit(actor, input.flowId);
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.unpublish", input.idempotencyKey);
+            if (replayed)
+                return await requireFlow(actor, flow.id);
+            if (!flow.publishedVersionId) {
+                throw new IntelError(409, "flow_not_published", "Flow has no published version");
+            }
+            const withdrawn = await deps.repository.unpublish({
+                flowId: flow.id,
+                versionId: flow.publishedVersionId,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+                occurredAt: deps.now().toISOString(),
+            });
+            // The write matched nothing: another writer withdrew the publication first. The state is
+            // what this call asked for, but saying "done" would hide that the race happened.
+            if (!withdrawn) {
+                throw new IntelError(409, "flow_not_published", "Flow has no published version");
+            }
+            return await requireFlow(actor, flow.id);
+        },
+        async start(actor, input) {
+            requireRun(actor);
+            // ⚠️ The whole guarantee of a subflow sits on this line staying where it is. A called run is
+            // started through the same door as any other: the user's own `execute` on the called flow is
+            // asked first, and the calling flow lends nothing. Without it a subflow node would be a way
+            // around every folder grant in the tree (ADR-0004 §4).
+            await requireExecute(actor, input.flowId);
+            const call = input.parent ? await requireCallSite(actor, input.parent, input.flowId) : null;
+            const parent = call?.run ?? null;
+            // One call site starts one run. A repeated call hands back the run it already made instead of
+            // a second one whose result nothing would ever read.
+            if (parent && input.parent) {
+                const existing = await deps.repository.findChildRun(parent.id, input.parent.nodeId);
+                if (existing)
+                    return await step(actor, existing);
+            }
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.run", input.idempotencyKey);
+            if (replayed) {
+                const run = await deps.repository.getRunVisible(actor, replayed);
+                if (run) {
+                    if (run.status === "running" || run.status === "queued")
+                        await deps.runtime.start(run.id);
+                    return await step(actor, run);
+                }
+            }
+            const flow = await requireRunnableFlow(actor, input.flowId);
+            // ⚠️ 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: empty ? "completed" : "running",
+                currentNodeId: empty ? null : first,
+                input: input.input,
+                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: empty ? occurredAt : null,
+            };
+            const inserted = await deps.repository.insertRun({
+                run,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            await deps.runtime.start(inserted.id);
+            return await step(actor, inserted);
+        },
+        async getRun(actor, runId) {
+            const run = await deps.repository.getRunVisible(actor, runId);
+            if (!run)
+                throw new IntelError(404, "flow_run_not_found", "Flow run was not found");
+            return await step(actor, run);
+        },
+        /**
+         * What this flow has done, newest first (#35). Until now a run could only be found by an ID
+         * somebody still had, and closing the tab lost it — with nothing to look at afterwards, a run
+         * that failed overnight was a run nobody heard about.
+         *
+         * ⚠️ Two rules meet here and they are deliberately different ones. Whether the *flow* exists for
+         * this actor is `read` or `execute`, exactly as the run path asks it — insisting on `read` would
+         * make a library flow's own runner unable to find their run back. Which *runs* then appear is
+         * `getRunVisible`, per row, in the repository: their own, plus every run of a flow they may
+         * read. So an execute-only runner sees their own and nobody else's, and the answer cannot drift
+         * from what opening a single run would say.
+         *
+         * What comes back is what a run did, never what it produced: `FlowRunSummary` carries no input
+         * and no output, because a run reaches nodes and tools with the rights of whoever started it.
+         */
+        async listRuns(actor, input) {
+            // The history of a flow that has since been archived stays readable — the runs happened, and
+            // archiving is about what may start next (#112).
+            //
+            // ⚠️ Without a flow there is nothing to require, and skipping the check does NOT widen the
+            // answer (#774): `requireStartedFlow` decides whether one named flow exists FOR this actor,
+            // while which runs appear is decided per row in the repository — their own, plus every run of
+            // a flow they may read. Asking it for a flow nobody named would mean inventing one.
+            const flowId = input.flowId === null ? null : (await requireStartedFlow(actor, input.flowId)).id;
+            // One row beyond the page: it answers "is there more" and is dropped rather than shown, so a
+            // count over the whole table is never needed to draw a "next" affordance.
+            const rows = await deps.repository.listRunsVisible(actor, {
+                flowId,
+                failedOnly: input.failedOnly,
+                limit: input.limit + 1,
+                cursor: decodeCursor(input.cursor),
+            });
+            const page = rows.slice(0, input.limit);
+            const failed = new Map((await deps.repository.failedSteps(page.map((run) => run.id))).map((row) => [
+                row.runId,
+                row,
+            ]));
+            // ⚠️ Four reads for a page, whatever its length: the runs, their failed steps, the versions
+            // they took, and the call sites among those failures. Runs of one flow mostly share a version
+            // and most failures are not calls, so all three follow-ups are asked once for the whole page
+            // rather than once per line (#30).
+            const versions = new Map((await deps.repository.getVersions([...new Set(page.map((run) => run.versionId))])).map((version) => [version.id, version]));
+            const sites = [];
+            for (const run of page) {
+                const record = failed.get(run.id);
+                const version = record ? versions.get(run.versionId) : undefined;
+                if (record && version && nodeFor(version, record.nodeId)?.kind === "subflow") {
+                    sites.push({ runId: run.id, nodeId: record.nodeId });
+                }
+            }
+            const calls = await visibleCalls(actor, sites);
+            const items = [];
+            for (const run of page) {
+                const version = versions.get(run.versionId) ?? null;
+                const record = failed.get(run.id);
+                let failure = null;
+                if (record) {
+                    const node = version ? nodeFor(version, record.nodeId) : null;
+                    const label = node?.label ?? record.nodeId;
+                    const stored = record.error ?? StepFailedDetail;
+                    const calledRunId = node?.kind === "subflow" ? calls.get(callKey(run.id, record.nodeId)) : undefined;
+                    failure = {
+                        nodeId: record.nodeId,
+                        nodeLabel: label,
+                        detail: node?.kind === "subflow"
+                            ? (callDetail(calledRunId, label, stored) ?? stored)
+                            : stored,
+                        calledRunId: calledRunId ?? null,
+                    };
+                }
+                items.push({
+                    id: run.id,
+                    flowId: run.flowId,
+                    versionId: run.versionId,
+                    status: run.status,
+                    // A version that has gone missing cannot say how the run was triggered, and `manual` is
+                    // what every run that was not a call was started by (#39).
+                    trigger: version ? triggerOf(version, run) : run.parentRunId ? "subflow" : "manual",
+                    startedAt: run.createdAt,
+                    completedAt: run.completedAt,
+                    durationMs: durationOf(run),
+                    initiatedBy: run.initiatedBy,
+                    parentRunId: run.parentRunId,
+                    failure,
+                });
+            }
+            const last = page.at(-1);
+            return {
+                items,
+                nextCursor: rows.length > page.length && last ? encodeCursor(last) : null,
+            };
+        },
+        /**
+         * One run step by step, which is the answer to "what went wrong" when the failure is three steps
+         * in. The failed node is reported rather than drawn onto the canvas: a run took an immutable
+         * version, the editor shows the current one, and marking a node in the wrong graph would point
+         * confidently at the wrong step. Shipping the run's own graph is a bigger slice than #35 asks
+         * for, so it stays a list of steps and the reason is written here rather than lost.
+         *
+         * ⚠️ `getRunVisible` alone opens this, and the current step is deliberately *not* re-authorized
+         * the way `getRun` does it. `getRun` hands out the next thing to do and must therefore ask again
+         * whether this person may still do it; history says what already happened, and a document
+         * withdrawn since must not rewrite the record of a run that read it while it was granted.
+         */
+        async listRunSteps(actor, runId) {
+            const run = await deps.repository.getRunVisible(actor, runId);
+            if (!run)
+                throw new IntelError(404, "flow_run_not_found", "Flow run was not found");
+            const version = await requireVersion(run.versionId, run.flowId);
+            const records = await deps.repository.runSteps(run.id);
+            // Every call this run made, asked once for the whole history rather than once per step (#30).
+            const calls = await visibleCalls(actor, records
+                .filter((record) => nodeFor(version, record.nodeId)?.kind === "subflow")
+                .map((record) => ({ runId: run.id, nodeId: record.nodeId })));
+            const steps = [];
+            for (const record of records) {
+                const node = nodeFor(version, record.nodeId);
+                const label = node?.label ?? record.nodeId;
+                const calledRunId = node?.kind === "subflow" ? calls.get(callKey(run.id, record.nodeId)) : undefined;
+                const detail = node?.kind === "subflow" ? callDetail(calledRunId, label, record.error) : record.error;
+                steps.push({
+                    nodeId: record.nodeId,
+                    nodeLabel: label,
+                    outcome: record.outcome,
+                    branch: record.branch,
+                    detail: record.outcome === "failed" ? (detail ?? StepFailedDetail) : detail,
+                    calledRunId: calledRunId ?? null,
+                    completedAt: record.completedAt,
+                });
+            }
+            return {
+                runId: run.id,
+                flowId: run.flowId,
+                status: run.status,
+                steps,
+                trail: await trailFor(run, version),
+            };
+        },
+        /**
+         * End a run on purpose (#145). Until this existed the only way off a parked manual step was
+         * `completeStep` with `outcome: "failed"`, which recorded a step failure that never happened.
+         * Cancelling writes no step row at all: the run ends, the step history stays true.
+         *
+         * ⚠️ Whoever may start a run may end it: the same Gate capability and the same `execute` the
+         * start asked for, asked again now — a grant revoked since the start must not keep the holder
+         * of an old run in control of it. Deliberately NOT `initiatedBy === actor.id`: a second person
+         * with `execute` on the flow may end a colleague's stuck run, exactly as they could have
+         * started the same run themselves.
+         *
+         * The child runs of a cancelled caller are cancelled with it, in the same write. A caller
+         * standing on a subflow node is waiting for its child by design; ending the caller alone would
+         * leave the child working for a result nobody will ever read.
+         */
+        async cancelRun(actor, input) {
+            requireRun(actor);
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.cancel", input.idempotencyKey);
+            if (replayed) {
+                const run = await deps.repository.getRunVisible(actor, replayed);
+                if (run)
+                    return await step(actor, run);
+            }
+            const current = await deps.repository.getRunVisible(actor, input.runId);
+            if (!current)
+                throw new IntelError(404, "flow_run_not_found", "Flow run was not found");
+            await requireExecute(actor, current.flowId);
+            if (current.status !== "running" && current.status !== "queued") {
+                throw new IntelError(409, "flow_run_terminal", "Flow run is already terminal");
+            }
+            const occurredAt = deps.now().toISOString();
+            const result = await deps.repository.cancelRun({
+                runId: current.id,
+                flowId: current.flowId,
+                actorId: actor.id,
+                occurredAt,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            if (result === "conflict") {
+                throw new IntelError(409, "flow_run_terminal", "Flow run is already terminal");
+            }
+            // Every durable wait among the ended runs is woken, children included: each workflow reads
+            // its terminal status and finishes now instead of stalling out on its own timeout.
+            for (const cancelledId of result.cancelled) {
+                await deps.runtime.signal(cancelledId);
+            }
+            const version = await requireVersion(current.versionId, current.flowId);
+            // ⚠️ `runState`, not `step`: the write has happened, and asking permission again AFTER a
+            // write is what turned completed work into a 404 for its own caller (#112).
+            return await runState(actor, {
+                ...current,
+                status: "cancelled",
+                currentNodeId: null,
+                updatedAt: occurredAt,
+                completedAt: occurredAt,
+            }, version);
+        },
+        async completeStep(actor, input) {
+            requireRun(actor);
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.complete", input.idempotencyKey);
+            if (replayed) {
+                const run = await deps.repository.getRunVisible(actor, replayed);
+                if (run)
+                    return await step(actor, run);
+            }
+            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 between two steps must
+            // stop the next one, not only the next run.
+            await requireExecute(actor, current.flowId);
+            if (current.status !== "running") {
+                throw new IntelError(409, "flow_run_terminal", "Flow run is already terminal");
+            }
+            if (current.currentNodeId !== input.nodeId) {
+                throw new IntelError(409, "flow_step_conflict", "A different step is currently active");
+            }
+            const version = await requireVersion(current.versionId, current.flowId);
+            const node = nodeFor(version, input.nodeId);
+            if (!node) {
+                throw new IntelError(500, "flow_version_corrupt", "Current run node is missing from the immutable version");
+            }
+            // 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, 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
+            // called flow never asked for. The state of a run belongs to the server.
+            let outcome = input.outcome;
+            let stepOutput = input.output;
+            let stepError = input.error;
+            if (node.kind === "subflow") {
+                const called = await deps.repository.findChildRun(current.id, node.id);
+                if (!called) {
+                    throw new IntelError(409, "flow_subflow_not_started", `Start the called flow before completing this step: ${node.label}`);
+                }
+                if (called.status === "completed") {
+                    outcome = "completed";
+                    stepOutput = called.output;
+                    stepError = null;
+                }
+                else if (called.status === "failed" || called.status === "cancelled") {
+                    outcome = "failed";
+                    stepOutput = null;
+                    stepError = called.error ?? calledStepDetail(node.label);
+                }
+                else {
+                    throw new IntelError(409, "flow_subflow_running", `The called flow is still running: ${node.label}`);
+                }
+            }
+            const occurredAt = deps.now().toISOString();
+            let status = "running";
+            let currentNodeId = null;
+            let output = current.output;
+            let error = null;
+            let completedAt = null;
+            if (outcome === "failed") {
+                status = "failed";
+                error = stepError ?? StepFailedDetail;
+                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"
+                    ? edges.find((candidate) => candidate.sourceHandle === input.branch)
+                    : edges[0];
+                if (!edge) {
+                    throw new IntelError(400, "flow_branch_invalid", "A valid branch is required");
+                }
+                // ⚠️ 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,
+                status,
+                currentNodeId,
+                output,
+                error,
+                updatedAt: occurredAt,
+                completedAt,
+            };
+            const advanced = await deps.repository.advanceRun({
+                run: next,
+                expectedNodeId: input.nodeId,
+                actorId: actor.id,
+                stepId: deps.id(),
+                outcome,
+                branch: input.branch,
+                output: stepOutput,
+                error: stepError,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            if (advanced === "conflict") {
+                throw new IntelError(409, "flow_step_conflict", "Flow step was already completed");
+            }
+            await deps.runtime.signal(next.id);
+            // ⚠️ `runState`, not `step`: the write above has happened. Asking again here is what turned a
+            // completed step into a 404 for the caller (#112).
+            return await runState(actor, next, version);
+        },
+    };
+}