@anchrd/intel-api 0.6.6 → 0.7.0

package/dist/bundle/bundle.types.d.ts

@@ -0,0 +1,33 @@
+import type { BundleImportResult, BundleManifest } from "@anchrd/intel-contract";
+import type { FlowRepository } from "../flows/flows.types.js";
+import type { Actor, ContentStore, NodeRepository } from "../nodes/nodes.types.js";
+export interface BundleActor extends Actor {
+    canReadFlows: boolean;
+    canCreateFlows?: boolean;
+}
+export interface BundleDeps {
+    repository: Pick<NodeRepository, "getVisible" | "listVisibleSubtree" | "listVersionContentKeys" | "can" | "importTree" | "findImportReplay" | "resolveVisibleTitles">;
+    flows: Pick<FlowRepository, "listVisible" | "getVisible" | "getVersions">;
+    content: Pick<ContentStore, "get" | "getStream" | "put" | "putBytes" | "delete">;
+    id(): string;
+    now(): Date;
+    hash(content: string | Uint8Array): Promise<string>;
+    indexing: {
+        enqueue(versionId: string): Promise<void>;
+    };
+}
+export interface BundleExport {
+    filename: string;
+    stream: ReadableStream<Uint8Array>;
+}
+export interface BundleImportInput {
+    targetNodeId: string | null;
+    zip: ReadableStream<Uint8Array> | Uint8Array;
+    idempotencyKey: string;
+}
+export interface BundleService {
+    exportSubtree(actor: BundleActor, rootId: string | null): Promise<BundleExport>;
+    exportFlow(actor: BundleActor, flowId: string): Promise<BundleExport>;
+    manifest(actor: BundleActor, rootId: string | null): Promise<BundleManifest>;
+    importBundle(actor: BundleActor, input: BundleImportInput): Promise<BundleImportResult>;
+}

package/dist/bundle/bundle.types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/cli.js

@@ -12,6 +12,15 @@ const interfaces = [
         functions: ["read", "create", "write", "publish", "run", "share"],
     },
     { handle: "tools", functions: ["read", "test", "execute", "admin"] },
+    // Declared here, and not by a service of its own, because Gate scopes the rules it returns to the
+    // service whose key asked (least privilege). The agent runtime authorizes its callers with this
+    // installation's Gate service key against the same audience Intel uses, so a handle registered
+    // anywhere else would never appear in the rules that `can("agents", "run")` reads.
+    //
+    // Without it there is no state between "administrator" and "not at all": the runtime falls back to
+    // `intel:admin`, which is the first-grant exit in the same sense as everywhere else, not the way a
+    // team lets a colleague talk to an agent.
+    { handle: "agents", functions: ["run"] },
     // `mcp:connect` means the same thing at every MCP service of this installation. A separate name
     // for the same thing forces the operator to check, service by service, which permission carries
     // portal access.
@@ -72,7 +81,7 @@ export function createCli(deps) {
             failures.push("GATE_SERVICE_KEY is missing");
         if (!toolSourceOrigins)
             failures.push("TOOL_SOURCE_ORIGINS is missing");
-        // Tools are optional for a deployment that only uses Knowledge and Flows, so a missing portal
+        // Tools are optional for a deployment that only uses nodes and Flows, so a missing portal
         // is reported as a warning rather than a failure.
         if (!portalUrl) {
             deps.log("Note: MCP_PORTAL_URL is unset, so the Tools area stays empty.");

package/dist/flows/flows.d.ts

@@ -3,14 +3,14 @@ import type { CompiledFlow, FlowDeps, FlowService } from "./flows.types.js";
 type SubflowNode = Extract<FlowNode, {
     kind: "subflow";
 }>;
-type KnowledgeStepNode = Extract<FlowNode, {
-    kind: KnowledgeLinkKind;
+type TreeLinkNode = Extract<FlowNode, {
+    kind: TreeLinkKind;
 }>;
 type ToolStepNode = Extract<FlowNode, {
     kind: "tool";
 }>;
-declare const knowledgeLinkKinds: readonly ["folder", "document", "upload", "table"];
-type KnowledgeLinkKind = (typeof knowledgeLinkKinds)[number];
+export declare const treeLinkKinds: readonly ["folder", "document", "upload", "table"];
+type TreeLinkKind = (typeof treeLinkKinds)[number];
 /**
  * One place reads a graph for each kind of step it contains, and everything else is derived from
  * these three. The publish-time rule, the freeze, the sidebar, the relation graph, the requirements
@@ -18,18 +18,18 @@ type KnowledgeLinkKind = (typeof knowledgeLinkKinds)[number];
  * beside them would drift quietly, because both would keep returning something plausible.
  */
 export declare function subflowNodes(graph: FlowGraph): SubflowNode[];
-export declare function knowledgeNodes(graph: FlowGraph): KnowledgeStepNode[];
+export declare function treeLinkNodes(graph: FlowGraph): TreeLinkNode[];
 export declare function toolNodes(graph: FlowGraph): ToolStepNode[];
-export declare function resourceIdOf(node: KnowledgeStepNode): string;
+export declare function resourceIdOf(node: TreeLinkNode): string;
 export declare function calleeIds(graph: FlowGraph): string[];
 /**
- * The Knowledge documents a graph names and the tools it calls, flattened and without repetition.
+ * The 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 declare function graphReferences(graph: FlowGraph): {
-    knowledge: string[];
+    nodes: string[];
     tools: string[];
 };
 export declare function compileFlow(graph: FlowGraph): CompiledFlow;

package/dist/flows/flows.js

@@ -9,7 +9,7 @@ const MaxCallDepth = 20;
 // The four link kinds that name something in the shared tree (D25). `tool` is a link too, but it
 // names a portal tool rather than a resource, and every rule about reachability applies to these
 // four and not to it.
-const knowledgeLinkKinds = ["folder", "document", "upload", "table"];
+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
@@ -22,8 +22,8 @@ export function subflowNodes(graph) {
 // ⚠️ Kept as one list although it is now four kinds: every caller asks "what does this graph read
 // from the tree", never "which of the four". Splitting the callers to match the split in the schema
 // would multiply four ways at each of the six call sites for no answer anyone wants.
-export function knowledgeNodes(graph) {
-    return graph.nodes.filter((node) => knowledgeLinkKinds.includes(node.kind));
+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");
@@ -45,29 +45,29 @@ export function calleeIds(graph) {
     return ids;
 }
 /**
- * The Knowledge documents a graph names and the tools it calls, flattened and without repetition.
+ * The 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 nodes = [];
     const tools = [];
-    for (const node of knowledgeNodes(graph)) {
-        if (!knowledge.includes(node.configuration.resourceId)) {
-            knowledge.push(node.configuration.resourceId);
+    for (const node of treeLinkNodes(graph)) {
+        if (!nodes.includes(node.configuration.resourceId)) {
+            nodes.push(node.configuration.resourceId);
         }
     }
     for (const node of toolNodes(graph)) {
         if (!tools.includes(node.configuration.toolName))
             tools.push(node.configuration.toolName);
     }
-    return { knowledge, tools };
+    return { nodes, 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) {
+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}`;
@@ -454,7 +454,7 @@ export function createFlows(deps) {
         }
         return { problems, version, first };
     }
-    // A flow's parent is a Knowledge folder, so the answer comes from Knowledge rather than from a
+    // 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) {
@@ -468,7 +468,7 @@ export function createFlows(deps) {
             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");
+            throw new IntelError(403, "node_forbidden", "Destination folder cannot be edited");
         }
     }
     async function requireVersion(versionId, flowId) {
@@ -520,26 +520,26 @@ export function createFlows(deps) {
     // 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,
+    // ⚠️ 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 reachableKnowledge(actor, resourceIds) {
+    async function reachableNodes(actor, resourceIds) {
         const reachable = [];
         for (const resourceId of new Set(resourceIds)) {
-            const node = await deps.visibleKnowledge(actor, resourceId);
+            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 Knowledge or
+    // ⚠️ 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 knowledge step"
+    // `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) {
         if (!node)
@@ -547,11 +547,11 @@ export function createFlows(deps) {
         const attached = graph.edges
             .filter((edge) => edge.kind === "context" && edge.source === node.id)
             .flatMap((edge) => graph.nodes.filter((candidate) => candidate.id === edge.target));
-        const wanted = [...new Set(knowledgeNodes({ ...graph, nodes: attached }).map(resourceIdOf))];
+        const wanted = [...new Set(treeLinkNodes({ ...graph, nodes: attached }).map(resourceIdOf))];
         if (wanted.length) {
-            const reachable = await reachableKnowledge(actor, wanted);
+            const reachable = await reachableNodes(actor, wanted);
             if (reachable.length !== wanted.length) {
-                throw new IntelError(403, "flow_knowledge_forbidden", knowledgeStepDetail(node.label, wanted.length - reachable.length));
+                throw new IntelError(403, "flow_node_forbidden", treeLinkStepDetail(node.label, wanted.length - reachable.length));
             }
         }
         const toolNames = attached
@@ -809,9 +809,32 @@ export function createFlows(deps) {
                     : 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 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).
+        // 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
@@ -821,7 +844,7 @@ export function createFlows(deps) {
             const nodes = new Map();
             const edges = [];
             const dropped = new Set();
-            const knowledgeSeen = new Map();
+            const nodesSeen = 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.
@@ -852,17 +875,17 @@ export function createFlows(deps) {
             // 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
+            async function seenNode(nodeId) {
+                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: found.parentId,
                         }
                         : null);
                 }
-                return knowledgeSeen.get(nodeId) ?? null;
+                return nodesSeen.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.
@@ -884,7 +907,7 @@ export function createFlows(deps) {
                 scopeFlows = [await requireFlow(actor, input.scope.flowId)];
             }
             else {
-                const children = await deps.knowledgeChildren(actor, input.scope.folderId, input.limit);
+                const children = await deps.nodeChildren(actor, input.scope.folderId, input.limit);
                 unread += children.total - children.items.length;
                 for (const item of children.items) {
                     levelIds.add(item.id);
@@ -921,9 +944,9 @@ export function createFlows(deps) {
                 // 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 node of treeLinkNodes(version.graph)) {
                     const resourceId = resourceIdOf(node);
-                    const target = await knowledgeNode(resourceId);
+                    const target = await seenNode(resourceId);
                     if (!target || !place(target.node, target.parentId))
                         continue;
                     edges.push({
@@ -979,7 +1002,7 @@ export function createFlows(deps) {
                 if (callee && !callee.archivedAt)
                     items.push(callee);
             }
-            // Ein aufgerufener Flow ruft selbst welche: dieselbe Frage, eine Ebene tiefer (#59).
+            // 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,
@@ -1017,24 +1040,24 @@ export function createFlows(deps) {
                 return {
                     flowId: flow.id,
                     versionId: null,
-                    knowledge: [],
-                    hiddenKnowledge: 0,
+                    nodes: [],
+                    hiddenNodes: 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.
+            // ⚠️ The same lookup a tree link 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);
+            const reachable = await reachableNodes(actor, referenced.nodes);
             return {
                 flowId: flow.id,
                 versionId: version.id,
-                knowledge,
-                hiddenKnowledge: referenced.knowledge.length - knowledge.length,
+                nodes: reachable,
+                hiddenNodes: referenced.nodes.length - reachable.length,
                 tools: referenced.tools,
             };
         },
@@ -1194,11 +1217,11 @@ export function createFlows(deps) {
                 return await requireFlow(actor, flow.id);
             const version = await requireVersion(input.versionId, flow.id);
             compileFlow(version.graph);
-            const wanted = [...new Set(knowledgeNodes(version.graph).map(resourceIdOf))];
-            const reachable = new Set((await reachableKnowledge(actor, wanted)).map((reference) => reference.id));
+            const wanted = [...new Set(treeLinkNodes(version.graph).map(resourceIdOf))];
+            const reachable = new Set((await reachableNodes(actor, wanted)).map((reference) => reference.id));
             for (const resourceId of wanted) {
                 if (!reachable.has(resourceId)) {
-                    throw new IntelError(409, "flow_knowledge_unavailable", `Knowledge reference is unavailable: ${resourceId}`);
+                    throw new IntelError(409, "flow_node_unavailable", `Node reference is unavailable: ${resourceId}`);
                 }
             }
             for (const node of version.graph.nodes) {
@@ -1272,6 +1295,41 @@ export function createFlows(deps) {
                 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
@@ -1362,7 +1420,7 @@ export function createFlows(deps) {
          * 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.
+         * 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
@@ -1482,6 +1540,64 @@ export function createFlows(deps) {
                 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);

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

@@ -1,4 +1,4 @@
-import type { ArchiveFlowInput, CompleteFlowRunStepInput, CreateFlowInput, Flow, FlowDocument, FlowGraph, FlowPublishPreview, FlowRequirements, FlowRun, FlowRunHistory, FlowRunList, FlowRunStep, FlowValidation, FlowVersion, KnowledgeNode, ListFlowRunsInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, RelationGraph, RelationGraphInput, ResourceVerb, SaveFlowVersionInput, StartFlowRunInput, UpdateFlowInput } from "@anchrd/intel-contract";
+import type { ArchiveFlowInput, CancelFlowRunInput, CompleteFlowRunStepInput, CreateFlowInput, Flow, FlowDocument, FlowGraph, FlowPublishPreview, FlowRequirements, FlowRun, FlowRunHistory, FlowRunList, FlowRunStep, FlowValidation, FlowVersion, FlowVersionList, FlowVersionSummary, GetFlowVersionInput, ListFlowRunsInput, ListFlowsInput, Node, PreviewFlowPublishInput, PublishFlowInput, RelationGraph, RelationGraphInput, ResourceVerb, SaveFlowVersionInput, StartFlowRunInput, UnpublishFlowInput, UpdateFlowInput } from "@anchrd/intel-contract";
 export type FlowPrincipal = Pick<FlowActor, "id" | "email" | "isAdmin">;
 export type FlowCallReach = "subtree" | "library" | "out-of-reach";
 export interface FlowRunChainEntry {
@@ -40,7 +40,7 @@ export interface FlowActor {
     isAdmin?: boolean;
 }
 export type FlowVerb = Extract<ResourceVerb, "read" | "write" | "execute">;
-export type FlowOperation = "flows.create" | "flows.update" | "flows.archive" | "flows.save" | "flows.publish" | "flows.run" | "flows.complete";
+export type FlowOperation = "flows.create" | "flows.update" | "flows.archive" | "flows.save" | "flows.publish" | "flows.run" | "flows.complete" | "flows.cancel" | "flows.unpublish";
 export interface BoundedLevel<T> {
     items: T[];
     total: number;
@@ -57,7 +57,7 @@ export interface FlowRepository {
         visible: string[];
         hidden: number;
     }>;
-    knowledgeReferences(actor: FlowPrincipal, folderId: string): Promise<string[]>;
+    nodeReferences(actor: FlowPrincipal, folderId: string): Promise<string[]>;
     publishedCallees(flowId: string): Promise<{
         title: string;
         calleeIds: string[];
@@ -86,6 +86,7 @@ export interface FlowRepository {
         auditId: string;
     }): Promise<"conflict" | Flow>;
     getVersion(versionId: string): Promise<FlowVersion | null>;
+    listVersions(flowId: string): Promise<Omit<FlowVersionSummary, "published">[]>;
     getVersions(versionIds: string[]): Promise<FlowVersion[]>;
     insertVersion(input: {
         version: FlowVersion;
@@ -102,6 +103,14 @@ export interface FlowRepository {
         auditId: string;
         occurredAt: string;
     }): Promise<boolean>;
+    unpublish(input: {
+        flowId: string;
+        versionId: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+        occurredAt: string;
+    }): Promise<boolean>;
     insertRun(input: {
         run: FlowRun;
         actorId: string;
@@ -115,6 +124,26 @@ export interface FlowRepository {
     visibleCallRuns(actor: FlowActor, sites: FlowCallSite[]): Promise<FlowVisibleCall[]>;
     findChildRun(parentRunId: string, parentNodeId: string): Promise<FlowRun | null>;
     runChain(runId: string): Promise<FlowRunChainEntry[]>;
+    /**
+     * End a run and every non-terminal run below it in one write (#145). The recursion follows
+     * `parent_run_id`, so cancelling a caller cannot leave a called run working for a result nobody
+     * will ever read. No step row is written for any of them: cancelling is not a step outcome, and
+     * inventing a failed step is exactly what this operation exists to replace.
+     *
+     * `"conflict"` means the run was already terminal when the write arrived — the caller's status
+     * check raced another writer — and nothing was changed. `cancelled` names every run this write
+     * ended, so the service can wake each of their durable waits.
+     */
+    cancelRun(input: {
+        runId: string;
+        flowId: string;
+        actorId: string;
+        occurredAt: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"conflict" | {
+        cancelled: string[];
+    }>;
     advanceRun(input: {
         run: FlowRun;
         expectedNodeId: string;
@@ -140,25 +169,25 @@ export interface FlowDeps {
     folderAccess(actor: FlowActor, folderId: string): Promise<FolderAccess>;
     /**
      * The children of one folder of the shared tree as this actor may see them, without their bodies.
-     * `null` is the root. Knowledge answers, for the same reason `folderAccess` does.
+     * `null` is the root. The node service answers, for the same reason `folderAccess` does.
      *
      * ⚠️ `limit` bounds the read, not its result: its one caller draws a bounded picture, and a folder
      * of a thousand documents must not be loaded whole for it (#30). What the bound left behind comes
      * back as `total`, counted among the nodes this actor may see and no others — a number that
      * included the rest would say that the rest is there.
      */
-    knowledgeChildren(actor: FlowActor, folderId: string | null, limit: number): Promise<BoundedLevel<KnowledgeNode>>;
+    nodeChildren(actor: FlowActor, folderId: string | null, limit: number): Promise<BoundedLevel<Node>>;
     /**
      * One node as this actor may see it. `null` means "this actor cannot reach it", never "it is
      * gone" — the relation graph must then leave it out altogether rather than draw a placeholder,
      * because the edge alone would already give away that it exists (#19).
      *
      * ⚠️ Three jobs, one door, on purpose. The relation graph draws what comes back here; the
-     * requirements list names it; and every Knowledge step of every run is authorized by it, nested
+     * requirements list names it; and every tree link of every run is authorized by it, nested
      * calls included (ADR-0004 §4). A second lookup beside it is how a drawing or a message ends up
      * kinder than the door it describes — which is what #17 and #19 were sent back for.
      */
-    visibleKnowledge(actor: FlowActor, nodeId: string): Promise<KnowledgeNode | null>;
+    visibleNodes(actor: FlowActor, nodeId: string): Promise<Node | null>;
     toolFingerprint(actor: FlowActor, toolName: string): Promise<string | null>;
     unavailableTools(actor: FlowActor, toolNames: string[]): Promise<string[]>;
 }
@@ -169,6 +198,8 @@ export interface FlowService {
         withCalls: string[];
     }>;
     get(actor: FlowActor, flowId: string): Promise<FlowDocument>;
+    listVersions(actor: FlowActor, flowId: string): Promise<FlowVersionList>;
+    getVersion(actor: FlowActor, input: GetFlowVersionInput): Promise<FlowVersion>;
     listCalls(actor: FlowActor, flowId: string): Promise<{
         items: Flow[];
         withCalls: string[];
@@ -182,11 +213,13 @@ export interface FlowService {
     save(actor: FlowActor, input: SaveFlowVersionInput): Promise<FlowDocument>;
     previewPublish(actor: FlowActor, input: PreviewFlowPublishInput): Promise<FlowPublishPreview>;
     publish(actor: FlowActor, input: PublishFlowInput): Promise<Flow>;
+    unpublish(actor: FlowActor, input: UnpublishFlowInput): Promise<Flow>;
     start(actor: FlowActor, input: StartFlowRunInput): Promise<FlowRunStep>;
     getRun(actor: FlowActor, runId: string): Promise<FlowRunStep>;
     listRuns(actor: FlowActor, input: ListFlowRunsInput): Promise<FlowRunList>;
     listRunSteps(actor: FlowActor, runId: string): Promise<FlowRunHistory>;
     completeStep(actor: FlowActor, input: CompleteFlowRunStepInput): Promise<FlowRunStep>;
+    cancelRun(actor: FlowActor, input: CancelFlowRunInput): Promise<FlowRunStep>;
 }
 export interface CompiledFlow {
     graph: FlowGraph;

package/dist/http/http.d.ts

@@ -4,5 +4,6 @@ import type { HttpDeps } from "./http.types.js";
 export declare function createHttp(deps: HttpDeps): Hono<{
     Variables: {
         authorization: Authorized;
+        token: string;
     };
 }, import("hono/types").BlankSchema, "/">;