@anchrd/intel-api 0.3.0 → 0.3.2

package/dist/flows/flows.js

@@ -2,6 +2,72 @@ import { IntelError } from "../shared/intel-error/intel-error.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;
+/**
+ * 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");
+}
+export function knowledgeNodes(graph) {
+    return graph.nodes.filter((node) => node.kind === "knowledge");
+}
+export function toolNodes(graph) {
+    return graph.nodes.filter((node) => node.kind === "tool");
+}
+// 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 Knowledge documents a graph names and the tools it calls, 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.
+ */
+export function graphReferences(graph) {
+    const knowledge = [];
+    const tools = [];
+    for (const node of knowledgeNodes(graph)) {
+        for (const resourceId of node.configuration.resourceIds) {
+            if (!knowledge.includes(resourceId))
+                knowledge.push(resourceId);
+        }
+    }
+    for (const node of toolNodes(graph)) {
+        if (!tools.includes(node.configuration.toolName))
+            tools.push(node.configuration.toolName);
+    }
+    return { knowledge, tools };
+}
+// ⚠️ 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 knowledgeStepDetail(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.
+function toolStepDetail(missing) {
+    return missing.length === 1
+        ? `You do not have access to this tool in the portal: ${missing.join(", ")}`
+        : `You do not have access to these tools in the portal: ${missing.join(", ")}`;
+}
 export function compileFlow(graph) {
     const nodes = new Map();
     for (const node of graph.nodes) {
@@ -9,15 +75,31 @@ export function compileFlow(graph) {
             invalid(`Duplicate node ID: ${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 ${edge.target} is already attached to ${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]);
     }
@@ -29,9 +111,22 @@ export function compileFlow(graph) {
     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) ?? [];
+        // An attached node is material, not a step: it is not in the order of work, so the rules about
+        // what comes before and after it do not apply. It must not be in that order either — a node
+        // that is both would be two things at once, and the run would have to pick one.
+        if (attachedTo.has(node.id)) {
+            if (parents !== 0 || children.length !== 0) {
+                invalid(`Node ${node.id} is attached as context and cannot also be a step`);
+            }
+            continue;
+        }
         if (node.kind === "trigger" && parents !== 0)
             invalid("The trigger cannot have an incoming edge");
         if (node.kind !== "trigger" && parents !== 1) {
@@ -62,8 +157,18 @@ export function compileFlow(graph) {
         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);
     }
@@ -72,9 +177,69 @@ export function compileFlow(graph) {
         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 };
+}
 export function createFlows(deps) {
     async function requireFlow(actor, flowId) {
         const flow = await deps.repository.getVisible(actor, flowId);
@@ -82,6 +247,16 @@ export function createFlows(deps) {
             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.
+    async function requireRunnableFlow(actor, flowId) {
+        const flow = await deps.repository.getCallable(actor, flowId);
+        if (!flow || 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) {
@@ -91,17 +266,35 @@ export function createFlows(deps) {
     }
     async function requireEdit(actor, flowId) {
         const flow = await requireFlow(actor, flowId);
-        if (!(await deps.repository.canEdit(actor, flowId))) {
+        if (!(await deps.repository.can(actor, flowId, "write"))) {
             throw new IntelError(403, "flow_edit_forbidden", "Flow cannot be edited");
         }
         return flow;
     }
-    async function requireManage(actor, flowId) {
-        const flow = await requireFlow(actor, flowId);
-        if (!(await deps.repository.canManage(actor, flowId))) {
-            throw new IntelError(403, "flow_manage_forbidden", "Flow sharing cannot be managed");
+    // 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");
+        }
+    }
+    // A flow's parent is a Knowledge folder, so the answer comes from Knowledge rather than from a
+    // second permission model here. `null` is the root and needs no permission of its own — the same
+    // as creating a folder at the root does.
+    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, "knowledge_forbidden", "Destination folder cannot be edited");
         }
-        return flow;
     }
     async function requireVersion(versionId, flowId) {
         const version = await deps.repository.getVersion(versionId);
@@ -110,14 +303,295 @@ export function createFlows(deps) {
         }
         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.visibleKnowledge` 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 reachableKnowledge(actor, resourceIds) {
+        const reachable = [];
+        for (const resourceId of new Set(resourceIds)) {
+            const node = await deps.visibleKnowledge(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 Knowledge 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.
+    async function requireNodeAuthorized(actor, node) {
+        if (node?.kind === "knowledge") {
+            const wanted = [...new Set(node.configuration.resourceIds)];
+            const reachable = await reachableKnowledge(actor, wanted);
+            if (reachable.length !== wanted.length) {
+                throw new IntelError(403, "flow_knowledge_forbidden", knowledgeStepDetail(node.label, wanted.length - reachable.length));
+            }
+        }
+        if (node?.kind === "tool") {
+            const missing = await deps.unavailableTools(actor, [node.configuration.toolName]);
+            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]));
+    }
     async function step(actor, run) {
-        await requireFlow(actor, run.flowId);
+        await requireRunnableFlow(actor, run.flowId);
         const version = await requireVersion(run.versionId, run.flowId);
-        return { run, node: nodeFor(version, run.currentNodeId) };
+        const node = nodeFor(version, run.currentNodeId);
+        await requireNodeAuthorized(actor, node);
+        return { run: await narrowed(actor, run, version), node, trail: await trailFor(run, version) };
+    }
+    // A failed run carries the text of the step that failed, and for a call that text came out of
+    // 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) {
+            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" && run.status !== "waiting") {
+            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) {
-            return { items: await deps.repository.listVisible(actor) };
+        async list(actor, input = {}) {
+            return { items: await deps.repository.listVisible(actor, input) };
         },
         async get(actor, flowId) {
             const flow = await requireFlow(actor, flowId);
@@ -128,14 +602,223 @@ export function createFlows(deps) {
                     : null,
             };
         },
+        // What accesses what, for one level of the shared tree (#19). Flows answers it because the edges
+        // live in flow graphs; Knowledge answers which nodes exist and who may see them, because the
+        // tree and its ACLs are Knowledge'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 knowledgeSeen = new Map();
+            const flowSeen = new Map();
+            // The level being drawn, what was actually read of it, and how much of it the bound left
+            // behind. `undefined` is the single-flow scope, which has no level and reads no list.
+            const levelFolderId = input.scope.of === "folder" ? input.scope.folderId : undefined;
+            const levelIds = new Set();
+            let unread = 0;
+            function place(node, parentId) {
+                const existing = nodes.get(node.id);
+                if (existing) {
+                    // A target that also lives in the level keeps the stronger of the two answers.
+                    if (node.inScope && !existing.inScope)
+                        nodes.set(node.id, node);
+                    return true;
+                }
+                if (nodes.size >= input.limit) {
+                    // ⚠️ A node filed in this level that the bound never read is already in `unread`. Counting
+                    // it a second time because a drawn flow happens to reach it would make the size the
+                    // picture reports differ from the number of nodes it actually left out.
+                    if (parentId !== levelFolderId || levelIds.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.
+            async function knowledgeNode(nodeId) {
+                if (!knowledgeSeen.has(nodeId)) {
+                    const found = await deps.visibleKnowledge(actor, nodeId);
+                    knowledgeSeen.set(nodeId, found && !found.archivedAt
+                        ? {
+                            node: { id: found.id, kind: found.kind, title: found.title, inScope: false },
+                            parentId: found.parentId,
+                        }
+                        : null);
+                }
+                return knowledgeSeen.get(nodeId) ?? null;
+            }
+            // The rows are already in hand — every callee of the level 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 level 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.
+            let scopeFlows;
+            if (input.scope.of === "flow") {
+                scopeFlows = [await requireFlow(actor, input.scope.flowId)];
+            }
+            else {
+                const children = await deps.knowledgeChildren(actor, input.scope.folderId, input.limit);
+                unread += children.total - children.items.length;
+                for (const item of children.items) {
+                    levelIds.add(item.id);
+                    place({ id: item.id, kind: item.kind, title: item.title, inScope: true }, item.parentId);
+                }
+                const filed = await deps.repository.listVisibleBounded(actor, input.scope.folderId, input.limit);
+                unread += filed.total - filed.items.length;
+                for (const flow of filed.items)
+                    levelIds.add(flow.id);
+                scopeFlows = filed.items;
+            }
+            const walkable = scopeFlows.filter((flow) => place({ id: flow.id, kind: "flow", title: flow.title, inScope: true }, flow.parentId));
+            // 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(walkable
+                    .map((flow) => flow.currentVersionId ?? flow.publishedVersionId)
+                    .filter((versionId) => versionId !== null)),
+            ])).map((version) => [version.id, version]));
+            const drawable = walkable.flatMap((flow) => {
+                const version = versions.get(flow.currentVersionId ?? flow.publishedVersionId ?? "");
+                return version ? [{ flow, version }] : [];
+            });
+            // One read for the versions of the level and one for everything it calls, instead of a pair
+            // per flow (#30). Both are bounded by the level, 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) {
+                // 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 knowledgeNodes(version.graph)) {
+                    for (const resourceId of node.configuration.resourceIds) {
+                        const target = await knowledgeNode(resourceId);
+                        if (!target || !place(target.node, target.parentId))
+                            continue;
+                        edges.push({
+                            id: `reads:${flow.id}:${node.id}:${resourceId}`,
+                            source: flow.id,
+                            target: resourceId,
+                            relation: "reads",
+                        });
+                    }
+                }
+                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 }, callee.parentId)) {
+                        continue;
+                    }
+                    edges.push({
+                        id: `calls:${flow.id}:${node.id}:${callee.id}`,
+                        source: flow.id,
+                        target: callee.id,
+                        relation: "calls",
+                    });
+                }
+            }
+            return {
+                scope: input.scope,
+                nodes: [...nodes.values()],
+                edges,
+                // 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: [] };
+            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);
+            }
+            return { 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.
+        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,
+                    knowledge: [],
+                    hiddenKnowledge: 0,
+                    tools: [],
+                };
+            }
+            const version = await requireVersion(versionId, flow.id);
+            const referenced = graphReferences(version.graph);
+            // ⚠️ The same lookup a Knowledge step passes through, not a second rule written for a list.
+            // What it hands back is named; the difference between what was asked for and what came back
+            // is a number, because 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 knowledge = await reachableKnowledge(actor, referenced.knowledge);
+            return {
+                flowId: flow.id,
+                versionId: version.id,
+                knowledge,
+                hiddenKnowledge: referenced.knowledge.length - knowledge.length,
+                tools: referenced.tools,
+            };
+        },
         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: {
                     id: deps.id(),
+                    parentId: input.parentId,
                     title: input.title,
                     description: input.description,
                     ownerId: actor.id,
@@ -150,6 +833,34 @@ export function createFlows(deps) {
                 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 ?? current.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;
+        },
         async save(actor, input) {
             const replayed = await deps.repository.findIdempotent(actor.id, "flows.save", input.idempotencyKey);
             if (replayed) {
@@ -185,6 +896,18 @@ export function createFlows(deps) {
             }
             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);
+            return {
+                flowId: flow.id,
+                versionId: version.id,
+                calls: await calls(actor, version.graph),
+            };
+        },
         async publish(actor, input) {
             const flow = await requireEdit(actor, input.flowId);
             const replayed = await deps.repository.findIdempotent(actor.id, "flows.publish", input.idempotencyKey);
@@ -194,8 +917,9 @@ export function createFlows(deps) {
             compileFlow(version.graph);
             for (const node of version.graph.nodes) {
                 if (node.kind === "knowledge") {
+                    const reachable = new Set((await reachableKnowledge(actor, node.configuration.resourceIds)).map((reference) => reference.id));
                     for (const resourceId of node.configuration.resourceIds) {
-                        if (!(await deps.knowledgeExists(actor, resourceId))) {
+                        if (!reachable.has(resourceId)) {
                             throw new IntelError(409, "flow_knowledge_unavailable", `Knowledge reference is unavailable: ${resourceId}`);
                         }
                     }
@@ -210,9 +934,57 @@ export function createFlows(deps) {
                     }
                 }
             }
+            // 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: version.id,
+                versionId: publishable.id,
                 actorId: actor.id,
                 idempotencyKey: input.idempotencyKey,
                 auditId: deps.id(),
@@ -224,6 +996,20 @@ export function createFlows(deps) {
         },
         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);
@@ -233,23 +1019,31 @@ export function createFlows(deps) {
                     return await step(actor, run);
                 }
             }
-            const flow = await requireFlow(actor, input.flowId);
+            const flow = await requireRunnableFlow(actor, input.flowId);
+            // Asked even for a frozen call: a flow whose publication was withdrawn is not something a
+            // pinned version may quietly keep running.
             if (!flow.publishedVersionId) {
                 throw new IntelError(409, "flow_not_published", "Flow has no published version");
             }
-            const version = await requireVersion(flow.publishedVersionId, flow.id);
+            // A frozen call runs its own version; everything else runs what is published now. Both land in
+            // `run.versionId` below, so a run always records which version actually ran (ADR-0004 §5).
+            const version = await requireVersion(call?.versionId ?? flow.publishedVersionId, flow.id);
             const compiled = compileFlow(version.graph);
-            const first = version.graph.edges.find((edge) => edge.source === compiled.triggerId)?.target;
+            // ⚠️ Flow edges only. A start carrying context would otherwise begin the run at the attached
+            // node, because that edge can come first in the list (#37).
+            const first = version.graph.edges.find((edge) => edge.kind === "flow" && edge.source === compiled.triggerId)?.target;
             if (!first)
                 invalid("The trigger requires an outgoing edge");
             // The flow may have been built by someone with wider portal access. Naming the missing tools
-            // before the first step beats failing halfway through with a portal error the user cannot place.
-            const missing = await deps.unavailableTools(actor, version.graph.nodes
-                .filter((node) => node.kind === "tool")
-                .map((node) => (node.kind === "tool" ? node.configuration.toolName : "")));
+            // before the first step beats failing halfway through with a portal error the user cannot
+            // place — and the portal is where they can do something about it.
+            const missing = await deps.unavailableTools(actor, graphReferences(version.graph).tools);
             if (missing.length) {
-                throw new IntelError(403, "flow_tools_unavailable", `You cannot reach these tools: ${missing.join(", ")}`);
+                throw new IntelError(403, "flow_tools_unavailable", toolStepDetail(missing));
             }
+            // The first step is authorized before a run row exists, so a refusal leaves nothing behind at
+            // all — not a run, not an idempotency key, not an audit event.
+            await requireNodeAuthorized(actor, nodeFor(version, first));
             const occurredAt = deps.now().toISOString();
             const run = {
                 id: deps.id(),
@@ -261,6 +1055,8 @@ export function createFlows(deps) {
                 output: null,
                 error: null,
                 initiatedBy: actor.id,
+                parentRunId: parent?.id ?? null,
+                parentNodeId: parent ? (input.parent?.nodeId ?? null) : null,
                 createdAt: occurredAt,
                 updatedAt: occurredAt,
                 completedAt: null,
@@ -280,6 +1076,137 @@ export function createFlows(deps) {
                 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 Knowledge and tools with the rights of whoever started it.
+         */
+        async listRuns(actor, input) {
+            const flow = await requireRunnableFlow(actor, input.flowId);
+            // 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: flow.id,
+                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),
+            };
+        },
         async completeStep(actor, input) {
             requireRun(actor);
             const replayed = await deps.repository.findIdempotent(actor.id, "flows.complete", input.idempotencyKey);
@@ -291,6 +1218,9 @@ export function createFlows(deps) {
             const current = await deps.repository.getRunVisible(actor, input.runId);
             if (!current)
                 throw new IntelError(404, "flow_run_not_found", "Flow run was not found");
+            // Rechecked here rather than trusted from the start: a grant revoked while a run waits for an
+            // approval must stop the next step, not only the next run.
+            await requireExecute(actor, current.flowId);
             if (current.status !== "running" && current.status !== "waiting") {
                 throw new IntelError(409, "flow_run_terminal", "Flow run is already terminal");
             }
@@ -305,24 +1235,55 @@ export function createFlows(deps) {
             if (node.kind === "approval" && !actor.canApprove) {
                 throw new IntelError(403, "flow_approval_forbidden", "Approval permission is required");
             }
+            // Asked again before the result is recorded, not only when the step was handed out: a grant
+            // revoked while the step was being carried out must stop it from landing.
+            await requireNodeAuthorized(actor, node);
+            // ⚠️ 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 (input.outcome === "failed") {
+            if (outcome === "failed") {
                 status = "failed";
-                error = input.error ?? "Flow step failed";
+                error = stepError ?? StepFailedDetail;
                 completedAt = occurredAt;
             }
             else if (node.kind === "output") {
                 status = "completed";
-                output = input.output;
+                output = stepOutput;
                 completedAt = occurredAt;
             }
             else {
-                const edges = version.graph.edges.filter((edge) => edge.source === node.id);
+                // ⚠️ Flow edges only, for the same reason as the start above: what a step works with is not
+                // where the run goes next (#37).
+                const edges = version.graph.edges.filter((edge) => edge.kind === "flow" && edge.source === node.id);
                 const edge = node.kind === "condition" || node.kind === "approval"
                     ? edges.find((candidate) => candidate.sourceHandle === input.branch)
                     : edges[0];
@@ -345,10 +1306,10 @@ export function createFlows(deps) {
                 expectedNodeId: input.nodeId,
                 actorId: actor.id,
                 stepId: deps.id(),
-                outcome: input.outcome,
+                outcome,
                 branch: input.branch,
-                output: input.output,
-                error: input.error,
+                output: stepOutput,
+                error: stepError,
                 idempotencyKey: input.idempotencyKey,
                 auditId: deps.id(),
             });
@@ -358,52 +1319,5 @@ export function createFlows(deps) {
             await deps.runtime.signal(next.id);
             return await step(actor, next);
         },
-        async listGrants(actor, flowId) {
-            await requireManage(actor, flowId);
-            return { items: await deps.repository.listGrants(flowId) };
-        },
-        async share(actor, input) {
-            await requireManage(actor, input.resourceId);
-            const replayedId = await deps.repository.findIdempotent(actor.id, "flows.share", input.idempotencyKey);
-            if (replayedId) {
-                const replayed = (await deps.repository.listGrants(input.resourceId)).find((grant) => grant.id === replayedId);
-                if (replayed)
-                    return replayed;
-            }
-            const principal = input.principal.type === "email"
-                ? { type: "email", email: input.principal.email.toLowerCase() }
-                : input.principal;
-            const createdAt = deps.now().toISOString();
-            return await deps.repository.setGrant({
-                grant: {
-                    id: deps.id(),
-                    resourceId: input.resourceId,
-                    principal,
-                    role: input.role,
-                    expiresAt: input.expiresAt,
-                    createdBy: actor.id,
-                    createdAt,
-                },
-                actorId: actor.id,
-                idempotencyKey: input.idempotencyKey,
-                auditId: deps.id(),
-            });
-        },
-        async revokeGrant(actor, input) {
-            await requireManage(actor, input.resourceId);
-            const replayed = await deps.repository.findIdempotentRevocation(actor.id, input.idempotencyKey);
-            if (replayed !== null)
-                return { revoked: replayed };
-            return {
-                revoked: await deps.repository.revokeGrant({
-                    flowId: input.resourceId,
-                    grantId: input.grantId,
-                    actorId: actor.id,
-                    idempotencyKey: input.idempotencyKey,
-                    auditId: deps.id(),
-                    occurredAt: deps.now().toISOString(),
-                }),
-            };
-        },
     };
 }