@anchrd/intel-api 0.6.7 → 0.9.0

package/README.md

@@ -1,10 +1,10 @@
 # @anchrd/intel-api
 
-Intel is a customer-deployed, model-agnostic operating layer for company knowledge and processes. It
+Intel is a customer-deployed, model-agnostic operating layer for company intelligence and processes. It
 gives people and MCP-capable AI clients the same governed access to three surfaces:
 
-- **Knowledge** — company content with sharing, immutable versions, retrieval, citations and a graph
-- **Flows** — versioned, durable processes that reference Knowledge and Tools
+- **Intelligence** — company content as nodes, with sharing, immutable versions, retrieval, citations and a graph
+- **Flows** — versioned, durable processes that reference nodes and Tools
 - **Tools** — MCP capabilities discovered through a Cloudflare MCP Portal
 
 The UI, the HTTP API and the Intel MCP surface call the same application services, so authorization,
@@ -88,6 +88,66 @@ derived from `INTEL_SESSION_SECRET` and kept in the `portal_tokens` table of you
 credentials stay with the portal and never reach Intel. The Intel audience token is never forwarded
 to another OAuth resource.
 
+Where agents are deployed, bind the agent runtime Worker as the service `AGENT` — the reference
+deployment does, as `{ "binding": "AGENT", "service": "intel-agent" }`. The browser never talks to
+that Worker: it asks Intel under `/api/v1/agents/:agentId/*`, and Intel forwards the call over the
+binding with the Gate token of the person who asked, after checking `agents/run` and the agent's own
+resource ACL. So the runtime needs no second hostname, no CORS and no token in the browser bundle,
+and the page stays on one origin with one session cookie. The binding is optional: without it those
+routes answer `503 agent_runtime_not_configured` and nothing else changes. Deploy `@anchrd/intel-agent`
+before an Intel deployment that declares it — Wrangler refuses a binding to a service that does not
+exist yet.
+
+### Creating an agent creates its Gate application
+
+An agent acts as its own machine principal, so creating an agent node also creates the Gate
+Application it runs as, and archiving the node switches that Application off (`disabledAt`) rather
+than deleting it. Restoring the node switches it back on — the same principal, with the same ID and
+the same grants, which is the whole reason it is disabled rather than deleted.
+
+Both calls are made with **the bearer of the person asking**, not with `GATE_SERVICE_KEY`. Creating
+and switching a machine principal is administrative work in Gate: the caller needs the applications
+permission there on top of `knowledge:create` in Intel, and Gate audits the act under their name. A
+caller without it is refused with `agent_application_forbidden`, and a Gate that does not answer
+with `agent_application_unavailable` — in which case **no agent node is created at all**. There is
+deliberately no half-created agent to repair later; the request is simply repeated.
+
+**No response in Intel carries a credential.** The Application key Gate issues once, in plain text,
+is handed to the agent runtime over the `AGENT` service binding inside the same request, and the
+runtime encrypts it into that agent's Durable Object. Intel writes it to no table, no R2 object, no
+audit event, no log and no response body; the browser never sees it, and neither does an MCP client.
+The agent can run the moment it exists — there is no secret to set and no terminal to open.
+
+The handover carries the caller's own bearer plus `AGENT_HANDOVER_SECRET`, the one value Intel and
+the agent runtime share. The runtime cannot check Intel's resource ACLs, so that secret is what says
+the key came through Intel rather than off the open internet; without it on both Workers, creating an
+agent refuses by name.
+
+The handover happens **before** the node row, for the same reason the Gate call does: a runtime that
+will not take the key leaves no agent behind, and the freshly minted Application is switched off
+again. There is deliberately no half-created agent to repair later; the request is simply repeated.
+
+What still stays manual is the reach: grant the application its Gate roles and the resource grants
+on the Intel nodes it works with. That is what makes the agent's reach its own.
+
+`POST /api/v1/nodes/agents/<id>/rotate-key` (and the `agent_rotate_key` MCP tool) replaces the key:
+Intel asks Gate for a new one and hands it to the runtime the same way, the previous key stops
+working at once, and the answer names the principal and the moment rather than the key. It needs
+`knowledge:write` in Intel plus write access to the agent node, and the applications permission in
+Gate. It is the repair for a run that fails with `agent_key_missing`.
+
+**A written schedule is an armed one.** The agent runtime sets its alarm only when something tells
+it to look, so Intel calls `POST /agents/<id>/schedules/sync` over the same service binding after
+every definition write — creating an agent with schedules, and every save. That call goes down the
+handover route with the caller's own bearer beside `AGENT_HANDOVER_SECRET`, because arming an agent
+belongs to editing one and not to driving one. A save whose arming fails keeps the definition it
+wrote and answers `agent_schedules_not_armed`: the version is current, and saving again arms it.
+
+Intel keeps `applicationId` beside the node and returns it on every agent read. It names the
+principal without authenticating it, which is why it may be stored and shown while the key may not.
+An agent whose `applicationId` is `null` has no principal — imported, restored from a bundle, or
+created before this was automatic — and archiving it touches Gate not at all.
+
 The reference Wrangler deployment binds `DB`, `CONTENT`, `INDEXING`, `AI`, `SEARCH`, `FLOWS`, and
 `ASSETS`. Create `SEARCH` as a 1024-dimension cosine Vectorize index for the default multilingual
 Workers AI `@cf/baai/bge-m3` embedding adapter. `FLOWS` targets the exported

package/dist/adapters/cloudflare/cloudflare.js

@@ -1,20 +1,23 @@
 import { createGateClient } from "@anchrd/gate-sdk";
 import { ulid } from "ulid";
+import { createAgentRuntimeService } from "../../agent-runtime/agent-runtime.js";
 import { createBrowserAuth } from "../../auth/auth.js";
+import { createBundle } from "../../bundle/bundle.js";
 import { createFlows } from "../../flows/flows.js";
 import { createIndexing, PermanentIndexingError } from "../../indexing/indexing.js";
 import { createIntel } from "../../intel/intel.js";
-import { createKnowledge } from "../../knowledge/knowledge.js";
+import { createNodes } from "../../nodes/nodes.js";
 import { IntelError } from "../../shared/intel-error/intel-error.js";
 import { sha256Hex } from "../../shared/sha256/sha256.js";
 import { createTools } from "../../tools/tools.js";
 import { createContentStore } from "../content/content.js";
-import { createKnowledgeRepository } from "../db/db.js";
+import { createNodeRepository } from "../db/db.js";
 import { createFlowRepository } from "../db/db-flows.js";
-import { createKnowledgeIndexRepository } from "../db/db-indexing.js";
+import { createNodeIndexRepository } from "../db/db-indexing.js";
 import { createOAuthClientStore } from "../db/db-oauth.js";
 import { createDocumentConverter } from "../document-converter/document-converter.js";
 import { createFlowRuntime } from "../flow-runtime/flow-runtime.js";
+import { createGateApplications } from "../gate-applications/gate-applications.js";
 import { createIndexQueue, IndexMessage } from "../index-queue/index-queue.js";
 import { createJsonSchemaValidator } from "../json-schema/json-schema.js";
 import { createOpenId } from "../openid/openid.js";
@@ -22,6 +25,7 @@ import { createPortalTokenStore } from "../portal-tokens/portal-tokens.js";
 import { createRemoteTools } from "../remote-tools/remote-tools.js";
 import { createSemanticIndex } from "../semantic-index/semantic-index.js";
 import { createSessionCodec } from "../session-cookie/session-cookie.js";
+import { createToolDelegation } from "../tool-delegation/tool-delegation.js";
 import { createToolSourcePolicy } from "../tool-source-policy/tool-source-policy.js";
 // biome-ignore lint/performance/noBarrelFile: The package entry must expose Wrangler's named Workflow class.
 export { IntelFlowWorkflow } from "./cloudflare-flow-workflow.js";
@@ -57,25 +61,11 @@ export default {
         assertConfigured(env);
         const now = () => new Date();
         const semantic = env.AI && env.SEARCH ? createSemanticIndex({ ai: env.AI, index: env.SEARCH }) : undefined;
-        // Built before Knowledge because Knowledge has to ask it one question: who calls into a folder
+        // Built before the tree because the tree has to ask it one question: who calls into a folder
         // from outside it. The repository knows no service, so this stays one direction of dependency.
         const flowRepository = createFlowRepository({ db: env.DB, now });
-        const knowledge = createKnowledge({
-            repository: createKnowledgeRepository({ db: env.DB, now }),
-            content: createContentStore(env.CONTENT),
-            id: ulid,
-            now,
-            indexing: createIndexQueue(env.INDEXING),
-            semantic,
-            externalFlowCallers: async (who, folderId) => await flowRepository.externalCallers(who, folderId),
-            flowKnowledgeReferences: async (who, folderId) => await flowRepository.knowledgeReferences(who, folderId),
-            hash: async (content) => {
-                const source = typeof content === "string"
-                    ? new TextEncoder().encode(content)
-                    : Uint8Array.from(content).buffer;
-                return await sha256Hex(crypto, source);
-            },
-        });
+        const nodeRepository = createNodeRepository({ db: env.DB, now });
+        const contentStore = createContentStore(env.CONTENT);
         const gate = createGateClient({ url: env.GATE_URL, serviceKey: env.GATE_SERVICE_KEY });
         const oauth = createOpenId({
             fetch: globalThis.fetch.bind(globalThis),
@@ -89,21 +79,22 @@ export default {
             crypto,
             now,
         });
-        const auth = createBrowserAuth({
-            baseUrl: env.INTEL_URL,
-            gateUrl: env.GATE_URL,
-            resource: intelResource,
-            oauth,
-            clients: createOAuthClientStore(env.DB),
-            sessions: createSessionCodec({ secret: env.INTEL_SESSION_SECRET, crypto }),
-            portalUrl,
-            portalTokens,
+        // Built before the tree since D30: saving an agent has to ask the portal, live, whether the
+        // person saving reaches every server they are delegating. The dependency runs one way — the
+        // tool service knows nothing about the tree, and the delegation lookup below reads D1 directly
+        // rather than through the node service.
+        const toolDelegation = createToolDelegation({
+            db: env.DB,
+            content: contentStore,
+            id: ulid,
             now,
         });
         const tools = createTools({
             portalUrl,
             remote: createRemoteTools({ fetch: globalThis.fetch.bind(globalThis) }),
             tokens: portalTokens,
+            delegation: toolDelegation.resolve,
+            audit: toolDelegation.audit,
             refresh: async (token) => {
                 try {
                     const refreshed = await oauth.refresh({
@@ -132,17 +123,76 @@ export default {
                 return await sha256Hex(crypto, JSON.stringify(value));
             },
         });
+        // ⚠️ Built before `nodes` and not after, because creating an agent has to be able to hand the
+        // runtime its key inside the same call (D29). Its `visibleNode` closes over `nodes` and is only
+        // ever called later, which is what keeps the two from being a cycle.
+        const agents = createAgentRuntimeService({
+            ...(env.AGENT ? { runtime: env.AGENT } : {}),
+            ...(env.AGENT_HANDOVER_SECRET ? { handoverSecret: env.AGENT_HANDOVER_SECRET } : {}),
+            // The tree's own visibility lookup, unchanged: whether somebody may reach an agent is the
+            // same question as whether they may see the node, and no second answer is invented here.
+            visibleNode: async (actor, nodeId) => await nodes.visibleNode(actor, nodeId),
+        });
+        const nodes = createNodes({
+            repository: nodeRepository,
+            content: contentStore,
+            // ⚠️ Built from `GATE_URL` alone — no service key is handed to it, and none would help. The
+            // Applications surface is admin-gated on a real principal, so every call carries the bearer
+            // of the person making it, which the tree passes in per operation (#182).
+            applications: createGateApplications({
+                fetch: globalThis.fetch.bind(globalThis),
+                gateUrl: env.GATE_URL,
+            }),
+            // The binding's presence IS the signal (#190) — no separate configuration option exists.
+            agentRuntimeAvailable: () => env.AGENT !== undefined,
+            // Where the Application key goes, and the only place it goes (D29). The same service the
+            // browser paths are proxied through, so there is one door to the runtime and not two.
+            agentKeys: { store: async (input) => await agents.storeKey(input) },
+            // The same door again (#214): a definition that was written is a schedule that has to be
+            // armed, and the runtime only looks when it is told to.
+            agentSchedules: { sync: async (input) => await agents.syncSchedules(input) },
+            id: ulid,
+            now,
+            indexing: createIndexQueue(env.INDEXING),
+            semantic,
+            externalFlowCallers: async (who, folderId) => await flowRepository.externalCallers(who, folderId),
+            flowNodeReferences: async (who, folderId) => await flowRepository.nodeReferences(who, folderId),
+            // ⚠️ `canExecute: true` is not a permission being granted here — the servers list touches
+            // nothing and executes nothing. It exists because `ToolActor` carries the flag for the one
+            // method that needs it, and a `false` would read as if listing were gated on execution.
+            toolServers: async (who) => {
+                const catalog = await tools.servers({ id: who.id, email: who.email, canExecute: true });
+                return catalog.items.map((server) => server.handle);
+            },
+            hash: async (content) => {
+                const source = typeof content === "string"
+                    ? new TextEncoder().encode(content)
+                    : Uint8Array.from(content).buffer;
+                return await sha256Hex(crypto, source);
+            },
+        });
+        const auth = createBrowserAuth({
+            baseUrl: env.INTEL_URL,
+            gateUrl: env.GATE_URL,
+            resource: intelResource,
+            oauth,
+            clients: createOAuthClientStore(env.DB),
+            sessions: createSessionCodec({ secret: env.INTEL_SESSION_SECRET, crypto }),
+            portalUrl,
+            portalTokens,
+            now,
+        });
         const flows = createFlows({
             repository: flowRepository,
             runtime: createFlowRuntime(env.FLOWS),
             id: ulid,
             now,
-            folderAccess: async (actor, folderId) => await knowledge.folderAccess(actor, folderId),
-            knowledgeChildren: async (actor, folderId, limit) => await knowledge.childrenBounded(actor, { parentId: folderId, limit }),
-            // Knowledge's own visibility lookup, unchanged on the way through: the relation graph, the
-            // requirements list and every Knowledge step of every run read this one answer, so none of
+            folderAccess: async (actor, folderId) => await nodes.folderAccess(actor, folderId),
+            nodeChildren: async (actor, folderId, limit) => await nodes.childrenBounded(actor, { parentId: folderId, limit }),
+            // The tree's own visibility lookup, unchanged on the way through: the relation graph, the
+            // requirements list and every tree link of every run read this one answer, so none of
             // them can be kinder than the others.
-            visibleKnowledge: async (actor, nodeId) => await knowledge.visibleNode(actor, nodeId),
+            visibleNodes: async (actor, nodeId) => await nodes.visibleNode(actor, nodeId),
             toolFingerprint: async (actor, toolName) => {
                 const catalog = await tools
                     .catalog({ id: actor.id, email: actor.email, canExecute: true })
@@ -155,15 +205,30 @@ export default {
             baseUrl: env.INTEL_URL,
             gateUrl: env.GATE_URL,
             gate,
-            knowledge,
+            nodes,
             flows,
             tools,
+            bundle: createBundle({
+                repository: nodeRepository,
+                flows: flowRepository,
+                content: contentStore,
+                id: ulid,
+                now,
+                hash: async (content) => {
+                    const source = typeof content === "string"
+                        ? new TextEncoder().encode(content)
+                        : Uint8Array.from(content).buffer;
+                    return await sha256Hex(crypto, source);
+                },
+                indexing: createIndexQueue(env.INDEXING),
+            }),
+            agents,
             auth,
         }).fetch(request);
     },
     async queue(batch, env) {
         const indexing = createIndexing({
-            repository: createKnowledgeIndexRepository(env.DB),
+            repository: createNodeIndexRepository(env.DB),
             content: createContentStore(env.CONTENT),
             semantic: env.AI && env.SEARCH ? createSemanticIndex({ ai: env.AI, index: env.SEARCH }) : undefined,
             converter: env.AI ? createDocumentConverter(env.AI) : undefined,
@@ -182,7 +247,7 @@ export default {
             }
             catch (error) {
                 if (error instanceof PermanentIndexingError) {
-                    console.warn("Intel discarded a permanently unindexable Knowledge version", {
+                    console.warn("Intel discarded a permanently unindexable node version", {
                         versionId: parsed.data.versionId,
                         error: error.message,
                     });

package/dist/adapters/cloudflare/cloudflare.types.d.ts

@@ -9,6 +9,17 @@ export interface CloudflareEnv {
     ASSETS?: {
         fetch(request: Request): Promise<Response>;
     };
+    /**
+     * The agent runtime Worker, bound as a service.
+     *
+     * ⚠️ Optional, and it has to be: a deployment may run Intel without agents, and a hard requirement
+     * here would make the whole installation fail to start over a feature nobody uses. Where it is
+     * absent the agent routes answer 503 by name; where it is present the browser reaches the runtime
+     * through Intel and never across a second origin (#178).
+     */
+    AGENT?: {
+        fetch(request: Request): Promise<Response>;
+    };
     DB: D1Database;
     CONTENT: R2Bucket;
     INDEXING: QueueProducer<IndexMessage>;
@@ -19,6 +30,15 @@ export interface CloudflareEnv {
     GATE_SERVICE_KEY: string;
     INTEL_URL: string;
     INTEL_SESSION_SECRET: string;
+    /**
+     * The shared secret that proves a key handover reached the agent runtime through this Worker
+     * (D29, #207). The SAME value the agent Worker holds as `AGENT_HANDOVER_SECRET`.
+     *
+     * ⚠️ Optional exactly like `AGENT`: a deployment may run Intel without agents, and a hard
+     * requirement would make the whole installation fail to start over a feature nobody uses. Where
+     * it is absent, creating an agent refuses by name instead of leaving one without a key.
+     */
+    AGENT_HANDOVER_SECRET?: string;
     TOOL_SOURCE_ORIGINS: string;
     MCP_PORTAL_URL?: string;
     ALLOW_INSECURE_OAUTH?: string;

package/dist/adapters/content/content.d.ts

@@ -1,3 +1,3 @@
-import type { ContentStore } from "../../knowledge/knowledge.types.js";
+import type { ContentStore } from "../../nodes/nodes.types.js";
 import type { R2Bucket } from "./content.types.js";
 export declare function createContentStore(bucket: R2Bucket): ContentStore;

package/dist/adapters/db/db-flows.js

@@ -1,5 +1,5 @@
 import { Flow, FlowGraph, FlowRun, FlowVersion, } from "@anchrd/intel-contract";
-import { calleeIds } from "../../flows/flows.js";
+import { calleeIds, treeLinkKinds } from "../../flows/flows.js";
 import { flowCallable, flowInSubtree, flowInSubtreeBindings, flowVerbBindings, flowVerbQuery, readableOrRunnableCte, subtreeBindings, subtreeCte, } from "./db-grants.js";
 const flowColumnNames = [
     "id",
@@ -35,6 +35,11 @@ const runColumns = runColumnNames.join(", ");
 // splitting the rendered string would break the moment it is reformatted.
 const qualifiedRunColumns = (alias) => runColumnNames.map((column) => `${alias}.${column}`).join(", ");
 const qualifiedFlowColumns = (alias) => flowColumnNames.map((column) => `${alias}.${column}`).join(", ");
+// The same four kinds `treeLinkNodes` filters on, rendered for SQL. Derived rather than written out
+// a second time: a fifth link kind added to the contract would otherwise reach every reader of a
+// graph except this one, and the miss would look like an empty result rather than an error — which
+// is precisely how the pre-0008 `knowledge` matcher survived unnoticed (#153).
+const treeLinkKindList = treeLinkKinds.map((kind) => `'${kind}'`).join(", ");
 function mapFlow(row) {
     return Flow.parse({
         id: row.id,
@@ -102,7 +107,7 @@ function mapRun(row) {
 const idList = "(SELECT value FROM json_each(?))";
 export function createFlowRepository(deps) {
     // A flow holds no grant of its own any more (ADR-0004 §2). What reaches it is the folder it is
-    // filed in, read through the same walk Knowledge uses, so the two can never drift apart. The CTE
+    // filed in, read through the same walk the tree uses, so the two can never drift apart. The CTE
     // stands in front of the statement, so its bindings come before every other one.
     const readableBindings = (actor) => subtreeBindings(actor, "read", deps.now().toISOString());
     // An absent `parentId` asks for every visible flow; `null` asks for the root of the shared tree.
@@ -205,10 +210,10 @@ export function createFlowRepository(deps) {
                 return "out-of-reach";
             const row = await deps.db
                 .prepare(`WITH RECURSIVE ancestors(id, parent_id) AS (
-            SELECT id, parent_id FROM knowledge_nodes WHERE id = ?
+            SELECT id, parent_id FROM nodes WHERE id = ?
             UNION
             SELECT parent.id, parent.parent_id
-            FROM knowledge_nodes parent
+            FROM nodes parent
             JOIN ancestors child ON child.parent_id = parent.id
           )
           SELECT
@@ -237,9 +242,9 @@ export function createFlowRepository(deps) {
             const result = await deps.db
                 .prepare(`${subtreeCte},
           scope(id) AS (
-            SELECT id FROM knowledge_nodes WHERE id = ?
+            SELECT id FROM nodes WHERE id = ?
             UNION
-            SELECT child.id FROM knowledge_nodes child JOIN scope ON child.parent_id = scope.id
+            SELECT child.id FROM nodes child JOIN scope ON child.parent_id = scope.id
           )
           SELECT DISTINCT ${qualifiedFlowColumns("flow")},
             CASE WHEN ${flowInSubtree} THEN 1 ELSE 0 END AS visible
@@ -260,38 +265,42 @@ export function createFlowRepository(deps) {
                 hidden: rows.filter((row) => row.visible !== 1).length,
             };
         },
-        // The Knowledge documents the flows in this folder's subtree read, so whoever shares the folder
+        // The documents the flows in this folder's subtree read, so whoever shares the folder
         // can be told what the grant does not cover (ADR-0004 §4).
         //
         // ⚠️ `flowInSubtree` again, the very predicate `listVisible` uses: a flow this actor may not see
         // must not reach the answer even as a number, because what it reads would then be attributed to
-        // a folder they administer. Whether any of the returned IDs may be *named* is Knowledge's
+        // a folder they administer. Whether any of the returned IDs may be *named* is the tree's
         // question — this one hands back IDs and no titles.
         //
-        // The knowledge nodes are collected first and expanded afterwards, so `json_each` is only ever
-        // handed the `resourceIds` array of a node that has one.
-        async knowledgeReferences(actor, folderId) {
+        // ⚠️ The link kinds, one `resourceId` each — the shape migration 0008 left behind. Before #153
+        // this asked for a `knowledge` node with a `resourceIds` array, and both had been rewritten away:
+        // the query matched nothing, and the warning it feeds went quiet without ever failing. A stored
+        // graph from before 0008 still cannot break it — its kind is not in the list, so it is not read
+        // at all — and a node whose configuration carries no `resourceId` is dropped rather than passed
+        // on as a null the caller would look up.
+        async nodeReferences(actor, folderId) {
             const result = await deps.db
                 .prepare(`${subtreeCte},
           scope(id) AS (
-            SELECT id FROM knowledge_nodes WHERE id = ?
+            SELECT id FROM nodes WHERE id = ?
             UNION
-            SELECT child.id FROM knowledge_nodes child JOIN scope ON child.parent_id = scope.id
+            SELECT child.id FROM nodes child JOIN scope ON child.parent_id = scope.id
           ),
-          referencing(resource_ids) AS (
-            SELECT json_extract(node.value, '$.configuration.resourceIds')
+          referencing(resource_id) AS (
+            SELECT json_extract(node.value, '$.configuration.resourceId')
             FROM flows flow
             JOIN flow_versions version ON version.id = flow.published_version_id
             JOIN json_each(version.graph_json, '$.nodes') node
-            WHERE json_extract(node.value, '$.kind') = 'knowledge'
+            WHERE json_extract(node.value, '$.kind') IN (${treeLinkKindList})
               AND flow.archived_at IS NULL
               AND flow.parent_id IN (SELECT id FROM scope)
               AND ${flowInSubtree}
           )
-          SELECT DISTINCT reference.value AS resource_id
+          SELECT DISTINCT resource_id
           FROM referencing
-          JOIN json_each(referencing.resource_ids) reference
-          ORDER BY reference.value`)
+          WHERE resource_id IS NOT NULL
+          ORDER BY resource_id`)
                 .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), folderId, ...flowInSubtreeBindings(actor))
                 .all();
             return (result.results ?? []).map((row) => row.resource_id);
@@ -407,7 +416,7 @@ export function createFlowRepository(deps) {
         // flow that went in.
         //
         // ⚠️ The idempotency row is written only if the UPDATE actually matched — same guard as
-        // `knowledge.archive` — so a stale `baseUpdatedAt` leaves no key behind that would make the
+        // `node.archive` — so a stale `baseUpdatedAt` leaves no key behind that would make the
         // retry of a *lost* write look like a replay of a successful one.
         async archiveFlow(input) {
             try {
@@ -466,6 +475,22 @@ export function createFlowRepository(deps) {
         async getVersion(versionId) {
             return (await this.getVersions([versionId]))[0] ?? null;
         },
+        // `graph_json` is deliberately absent from the SELECT: the history is metadata, and reading
+        // every graph of a much-edited flow to draw a table would grow with the number of edits.
+        async listVersions(flowId) {
+            const result = await deps.db
+                .prepare(`SELECT id, flow_id, sequence, created_by, created_at
+          FROM flow_versions WHERE flow_id = ? ORDER BY sequence`)
+                .bind(flowId)
+                .all();
+            return (result.results ?? []).map((row) => ({
+                id: row.id,
+                flowId: row.flow_id,
+                sequence: row.sequence,
+                createdBy: row.created_by,
+                createdAt: row.created_at,
+            }));
+        },
         async insertVersion(input) {
             const version = input.version;
             try {
@@ -543,6 +568,45 @@ export function createFlowRepository(deps) {
             }
             return ((await this.findIdempotent(input.actorId, "flows.publish", input.idempotencyKey)) !== null);
         },
+        // The mirror of `publish`, with the same shape of guards: the idempotency row is written only
+        // if the UPDATE actually withdrew something, so revoking what was never published leaves no key
+        // behind that would make a later retry look like a success.
+        async unpublish(input) {
+            try {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`UPDATE flows SET published_version_id = NULL, updated_at = ?
+              WHERE id = ? AND published_version_id IS NOT NULL`)
+                        .bind(input.occurredAt, input.flowId),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'flows.unpublish', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM flows
+              WHERE id = ? AND published_version_id IS NULL AND updated_at = ?
+            )`)
+                        .bind(input.actorId, input.idempotencyKey, input.flowId, input.occurredAt, input.flowId, input.occurredAt),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'flows.unpublish', 'flow', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM idempotency_keys
+              WHERE actor_id = ? AND operation = 'flows.unpublish' AND idempotency_key = ?
+            )`)
+                        .bind(input.auditId, input.actorId, input.flowId, 
+                    // What was withdrawn, so the trail can say which version was live until here.
+                    JSON.stringify({ versionId: input.versionId }), input.occurredAt, input.actorId, input.idempotencyKey),
+                ]);
+            }
+            catch (error) {
+                if (!(await this.findIdempotent(input.actorId, "flows.unpublish", input.idempotencyKey))) {
+                    throw error;
+                }
+            }
+            return ((await this.findIdempotent(input.actorId, "flows.unpublish", input.idempotencyKey)) !== null);
+        },
         async insertRun(input) {
             const run = input.run;
             try {
@@ -713,6 +777,70 @@ export function createFlowRepository(deps) {
                 currentNodeId: row.current_node_id,
             }));
         },
+        // One write for the run and everything below it. The recursion gathers only non-terminal
+        // descendants, and the root joins the set only while it is itself non-terminal — so a run that
+        // turned terminal between the caller's check and this write cancels nothing at all, and the
+        // missing idempotency row reports the conflict. `flow_run_steps` is deliberately untouched:
+        // cancelling is not a step outcome (#145).
+        async cancelRun(input) {
+            const nonTerminal = "status NOT IN ('completed', 'failed', 'cancelled')";
+            const affected = `WITH RECURSIVE affected(id) AS (
+          SELECT id FROM flow_runs WHERE id = ? AND ${nonTerminal}
+          UNION
+          SELECT child.id FROM flow_runs child
+          JOIN affected ON child.parent_run_id = affected.id
+          WHERE child.${nonTerminal}
+        )`;
+            try {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`${affected}
+              UPDATE flow_runs SET status = 'cancelled', current_node_id = NULL,
+                updated_at = ?, completed_at = ?
+              WHERE id IN (SELECT id FROM affected)`)
+                        .bind(input.runId, input.occurredAt, input.occurredAt),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'flows.cancel', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM flow_runs WHERE id = ? AND status = 'cancelled' AND updated_at = ?
+            )`)
+                        .bind(input.actorId, input.idempotencyKey, input.runId, input.occurredAt, input.runId, input.occurredAt),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'flows.cancel', 'flow-run', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM idempotency_keys
+              WHERE actor_id = ? AND operation = 'flows.cancel' AND idempotency_key = ?
+            )`)
+                        .bind(input.auditId, input.actorId, input.runId, JSON.stringify({ flowId: input.flowId }), input.occurredAt, input.actorId, input.idempotencyKey),
+                ]);
+            }
+            catch (error) {
+                if (!(await this.findIdempotent(input.actorId, "flows.cancel", input.idempotencyKey))) {
+                    throw error;
+                }
+            }
+            const replayed = await this.findIdempotent(input.actorId, "flows.cancel", input.idempotencyKey);
+            if (replayed !== input.runId)
+                return "conflict";
+            // What this write ended, read back by the timestamp it stamped: the root and its descendants,
+            // narrowed to the rows this very write turned. A child cancelled by an earlier call keeps its
+            // earlier timestamp and stays out, so nothing is signalled twice.
+            const result = await deps.db
+                .prepare(`WITH RECURSIVE affected(id) AS (
+            SELECT id FROM flow_runs WHERE id = ?
+            UNION
+            SELECT child.id FROM flow_runs child JOIN affected ON child.parent_run_id = affected.id
+          )
+          SELECT id FROM flow_runs
+          WHERE id IN (SELECT id FROM affected) AND status = 'cancelled' AND updated_at = ?`)
+                .bind(input.runId, input.occurredAt)
+                .all();
+            return { cancelled: (result.results ?? []).map((row) => row.id) };
+        },
         async advanceRun(input) {
             const run = input.run;
             try {

package/dist/adapters/db/db-grants.d.ts

@@ -6,6 +6,17 @@ export interface GrantActor {
 }
 export declare const subtreeCte: string;
 export declare function subtreeBindings(actor: GrantActor, verb: ResourceVerb, now: string): unknown[];
+/**
+ * One named folder and everything filed beneath it, appended to a statement that already carries
+ * `subtreeCte`. It answers "where", never "whether": a statement joins `descendants` *in addition
+ * to* `allowed`, so the scope can only take rows away from an answer the actor was already entitled
+ * to. Joining it instead of `allowed` would turn a search argument into a permission, which is
+ * exactly what ADR-0004 forbids — the caller supplies the id, and a caller is not a grant.
+ *
+ * ⚠️ `UNION`, never `UNION ALL`, for the reason `nodeVerbQuery` gives: a cycle in `parent_id` can
+ * reach the table and this walks downwards into it.
+ */
+export declare const descendantsCte = "descendants(id) AS (\n    SELECT scope.id FROM nodes scope WHERE scope.id = ?\n    UNION\n    SELECT child.id\n    FROM nodes child\n    JOIN descendants parent ON child.parent_id = parent.id\n  )";
 /**
  * Both walks in one statement: what the actor may open, and what they may run. Its bindings are
  * `subtreeBindings(actor, "read", now)` followed by `subtreeBindings(actor, "execute", now)`, in
@@ -20,7 +31,7 @@ export declare const readableOrRunnableCte: string;
  */
 export declare const flowCallable = "(\n  ? = 1\n  OR flow.owner_id = ?\n  OR flow.parent_id IN (SELECT id FROM readable)\n  OR flow.parent_id IN (SELECT id FROM runnable)\n)";
 /**
- * The point check for one Knowledge node: the node itself and every ancestor above it. Cheaper than
+ * The point check for one node: the node itself and every ancestor above it. Cheaper than
  * the subtree walk and the same answer, because a grant reaches down and never sideways.
  *
  * ⚠️ `UNION`, never `UNION ALL`. The service refuses to move a node into its own descendant, but a
@@ -33,7 +44,7 @@ export declare const nodeVerbQuery: string;
 export declare function nodeVerbBindings(nodeId: string, actor: GrantActor, verb: ResourceVerb, now: string): unknown[];
 /**
  * The same question for a flow. A flow carries no grant of its own any more: what reaches it is the
- * folder it is filed in and that folder's ancestors. Its owner keeps it, the way a Knowledge node's
+ * folder it is filed in and that folder's ancestors. Its owner keeps it, the way a node's
  * owner keeps theirs — otherwise a flow at the root of the tree would be unreachable by the person
  * who created it. `UNION` for the same reason as above.
  */