@anchrd/intel-api 0.6.6 → 0.7.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,47 @@ 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.
+
+The response to `POST /api/v1/nodes/agents` (and to the `agent_create` MCP tool) is the only place
+in Intel where a credential appears:
+
+1. It carries `applicationKey.key` **once**, in plain text. Gate issues an Application key a single
+   time and stores only its hash, and Intel writes it to no table, no R2 object, no audit event and
+   no log. Nothing can hand it out a second time — `application_rotate_key` in Gate issues a new one.
+2. Put it into the agent runtime's `AGENT_APPLICATION_KEYS` secret, keyed by the **agent node ID**
+   that comes back as `applicationKey.agentId`, and store it nowhere else. That secret carries the
+   whole list, so `wrangler secret put` is given every entry, not only the new one.
+3. Grant the application what this agent may reach — its Gate roles, and the resource grants on the
+   Intel nodes it works with. That step is what makes the agent's reach its own and stays manual.
+
+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";
@@ -57,18 +60,29 @@ 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),
+        const nodeRepository = createNodeRepository({ db: env.DB, now });
+        const contentStore = createContentStore(env.CONTENT);
+        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,
             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),
+            flowNodeReferences: async (who, folderId) => await flowRepository.nodeReferences(who, folderId),
             hash: async (content) => {
                 const source = typeof content === "string"
                     ? new TextEncoder().encode(content)
@@ -137,12 +151,12 @@ export default {
             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 +169,35 @@ 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: createAgentRuntimeService({
+                ...(env.AGENT ? { runtime: env.AGENT } : {}),
+                // 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),
+            }),
             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 +216,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>;

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.
@@ -128,6 +133,19 @@ export function createFlowRepository(deps) {
     ORDER BY lower(flow.title), flow.id${bounded ? " LIMIT ?" : ""}`;
     return {
         async listVisible(actor, input = {}) {
+            // ⚠️ `archivedOnly` overrides the folder rather than narrowing within it: somebody looking
+            // for what they archived does not know where it was filed (#113). The visibility predicate
+            // is unchanged, so the archive shows no flow the tree would have hidden.
+            if (input.archivedOnly === true) {
+                const result = await deps.db
+                    .prepare(`${subtreeCte}
+            SELECT ${flowColumns} FROM flows flow
+            WHERE ${flowInSubtree} AND flow.archived_at IS NOT NULL
+            ORDER BY flow.archived_at DESC, lower(flow.title), flow.id`)
+                    .bind(...readableBindings(actor), ...flowInSubtreeBindings(actor))
+                    .all();
+                return (result.results ?? []).map(mapFlow);
+            }
             const scope = scopeOf(input.parentId);
             const result = await deps.db
                 .prepare(visibleFlows(scope.clause, false, input.includeArchived === true))
@@ -192,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
@@ -224,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
@@ -247,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);
@@ -394,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 {
@@ -453,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 {
@@ -530,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 {
@@ -700,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.
  */

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

@@ -26,13 +26,13 @@ function grantBindings(actor, verb, now) {
 function subtreeWalk(name) {
     return `${name}(id, parent_id) AS (
     SELECT seed.id, seed.parent_id
-    FROM knowledge_nodes seed
+    FROM nodes seed
     WHERE ? = 1
        OR seed.owner_id = ?
        OR ${grantExists("seed.id")}
     UNION
     SELECT child.id, child.parent_id
-    FROM knowledge_nodes child
+    FROM nodes child
     JOIN ${name} parent ON child.parent_id = parent.id
   )`;
 }
@@ -42,6 +42,23 @@ export const subtreeCte = `WITH RECURSIVE ${subtreeWalk("allowed")}`;
 export function subtreeBindings(actor, verb, now) {
     return [actor.isAdmin ? 1 : 0, actor.id, ...grantBindings(actor, verb, now)];
 }
+/**
+ * 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 const descendantsCte = `descendants(id) AS (
+    SELECT scope.id FROM nodes scope WHERE scope.id = ?
+    UNION
+    SELECT child.id
+    FROM nodes child
+    JOIN descendants parent ON child.parent_id = parent.id
+  )`;
 /**
  * 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
@@ -62,7 +79,7 @@ export const flowCallable = `(
   OR flow.parent_id IN (SELECT id FROM runnable)
 )`;
 /**
- * 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
@@ -72,10 +89,10 @@ export const flowCallable = `(
  * row away and the recursion stops on its own.
  */
 export const nodeVerbQuery = `WITH RECURSIVE ancestors(id, parent_id, owner_id) AS (
-    SELECT id, parent_id, owner_id FROM knowledge_nodes WHERE id = ?
+    SELECT id, parent_id, owner_id FROM nodes WHERE id = ?
     UNION
     SELECT parent.id, parent.parent_id, parent.owner_id
-    FROM knowledge_nodes parent
+    FROM nodes parent
     JOIN ancestors child ON child.parent_id = parent.id
   )
   SELECT 1 AS allowed
@@ -89,18 +106,18 @@ export function nodeVerbBindings(nodeId, actor, verb, now) {
 }
 /**
  * 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.
  */
 export const flowVerbQuery = `WITH RECURSIVE ancestors(id, parent_id) AS (
     SELECT folder.id, folder.parent_id
-    FROM knowledge_nodes folder
+    FROM nodes folder
     JOIN flows flow ON flow.parent_id = folder.id
     WHERE flow.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 1 AS allowed

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

@@ -1,3 +1,3 @@
-import type { KnowledgeIndexRepository } from "../../knowledge/knowledge.types.js";
+import type { NodeIndexRepository } from "../../nodes/nodes.types.js";
 import type { D1Database } from "./db.types.js";
-export declare function createKnowledgeIndexRepository(db: D1Database): KnowledgeIndexRepository;
+export declare function createNodeIndexRepository(db: D1Database): NodeIndexRepository;