@anchrd/intel 0.59.0

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

@@ -0,0 +1,1311 @@
+import { Flow, FlowGraph, FlowVersion, } from "../../contract/flow.js";
+import { FlowRun } from "../../contract/flow-run.js";
+import { calleeIds, treeLinkKinds } from "../../flows/flows.js";
+import { flowCallable, flowCallableBindings, flowInSubtree, flowInSubtreeBindings, flowVerbBindings, flowVerbQuery, grantColumns, grantInForce, mapGrant, principalColumns, readableOrRunnableCte, subtreeBindings, subtreeCte, } from "./db-grants.js";
+import { promptNameHolder } from "./db-prompts.js";
+const flowColumnNames = [
+    "id",
+    "parent_id",
+    "title",
+    "description",
+    "owner_id",
+    "current_version_id",
+    "published_version_id",
+    "created_at",
+    "updated_at",
+    "archived_at",
+    "prompt_name",
+];
+const flowColumns = flowColumnNames.join(", ");
+const runColumnNames = [
+    "id",
+    "flow_id",
+    "version_id",
+    "status",
+    "current_node_id",
+    "input_json",
+    "output_json",
+    "error",
+    "initiated_by",
+    "parent_run_id",
+    "parent_node_id",
+    "created_at",
+    "updated_at",
+    "completed_at",
+];
+const runColumns = runColumnNames.join(", ");
+// Joined queries need the columns qualified. Deriving them from the array keeps both forms in step;
+// 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,
+        parentId: row.parent_id,
+        title: row.title,
+        description: row.description,
+        ownerId: row.owner_id,
+        currentVersionId: row.current_version_id,
+        publishedVersionId: row.published_version_id,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        archivedAt: row.archived_at,
+        promptName: row.prompt_name,
+    });
+}
+function mapVersion(row) {
+    return FlowVersion.parse({
+        id: row.id,
+        flowId: row.flow_id,
+        sequence: row.sequence,
+        graph: FlowGraph.parse(JSON.parse(row.graph_json)),
+        createdBy: row.created_by,
+        createdAt: row.created_at,
+    });
+}
+// ⚠️ The one answer to "may this actor see this run", so a single run and a list of them cannot
+// start disagreeing. A run you started is yours to follow — without that, a run of a library flow,
+// shared with `execute` for everyone and readable by nobody (ADR-0004 §3), would vanish the moment
+// it was started. Everything else is the folder the flow is filed in, read through `flowInSubtree`,
+// the very predicate the flow list itself uses.
+//
+// It expects `flow_runs run` joined to `flows flow`, and its bindings follow the CTE's. The bindings
+// live in the factory below because `flowInSubtree` now needs the moment expiry is measured against.
+const runVisible = `(run.initiated_by = ? OR ${flowInSubtree})`;
+/**
+ * One page of runs, newest first — and the flow is part of the STATEMENT rather than a bound value
+ * (#774, found in the review of #787).
+ *
+ * ⚠️ **`WHERE (? IS NULL OR run.flow_id = ?)` is the shape that must not be used here**, however
+ * naturally it reads. SQLite picks its plan when the statement is prepared, from the text alone —
+ * it never sees the value — so an `OR` on the leading index column drops that column as an equality
+ * prefix **in both cases**, including the one where a real flow id was passed. Measured on the same
+ * engine and schema, `flow_runs_flow_idx (flow_id, created_at DESC)`:
+ *
+ *     -- WHERE run.flow_id = ?
+ *     SEARCH run USING INDEX flow_runs_flow_idx (flow_id=?)
+ *
+ *     -- WHERE (? IS NULL OR run.flow_id = ?)   — identical for a real id AND for null
+ *     SCAN run | USE TEMP B-TREE FOR ORDER BY
+ *
+ * The damage is not on the new door but on the old one: `GET /flows/:flowId/runs` has existed all
+ * along and is the frequent call, and it would have started scanning every run in the installation
+ * without a single test going red. `db-audit.ts` had the same choice one file over and split its
+ * statements per kind; this is that decision, applied where the review found it missing.
+ *
+ * ⚠️ The two shapes lean on two different indexes, and both are needed. Scoped: `flow_runs_flow_idx`,
+ * whose `flow_id` prefix an equality serves. Unscoped: `flow_runs_time_idx (created_at DESC,
+ * id DESC)` from `0027`, because "every readable flow" has no one `flow_id` to match on and the
+ * ordering has to come from somewhere.
+ *
+ * ⚠️ `failedOnly` and the cursor are shape too, not bindings, and that is not the same decision —
+ * they were already written this way. An absent clause binds nothing, so every caller of this
+ * function has to build its bindings from the SAME three flags, in this order: the CTE's, the flow
+ * id when scoped, `runVisible`'s, the cursor's three when paged, and the limit.
+ */
+export function flowRunsPageQuery(shape) {
+    return `${subtreeCte}
+          SELECT ${qualifiedRunColumns("run")} FROM flow_runs run
+          JOIN flows flow ON flow.id = run.flow_id
+          WHERE ${shape.scoped ? "run.flow_id = ? AND " : ""}${runVisible}
+            ${shape.failedOnly ? "AND run.status = 'failed'" : ""}
+            ${shape.paged ? "AND (run.created_at < ? OR (run.created_at = ? AND run.id < ?))" : ""}
+          ORDER BY run.created_at DESC, run.id DESC
+          LIMIT ?`;
+}
+function mapStep(row) {
+    return {
+        runId: row.run_id,
+        nodeId: row.node_id,
+        outcome: row.outcome,
+        branch: row.branch,
+        error: row.error,
+        completedAt: row.completed_at,
+    };
+}
+function mapRun(row) {
+    return FlowRun.parse({
+        id: row.id,
+        flowId: row.flow_id,
+        versionId: row.version_id,
+        status: row.status,
+        currentNodeId: row.current_node_id,
+        input: JSON.parse(row.input_json),
+        output: row.output_json === null ? null : JSON.parse(row.output_json),
+        error: row.error,
+        initiatedBy: row.initiated_by,
+        parentRunId: row.parent_run_id,
+        parentNodeId: row.parent_node_id,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        completedAt: row.completed_at,
+    });
+}
+// A list of IDs as one bound value rather than one placeholder each. D1 caps how many parameters a
+// statement may carry, and the lists here are as long as a graph, a call chain or a drawn level —
+// so an `IN (?, ?, …)` built from the input would be a limit waiting to be hit by real data (#30).
+const idList = "(SELECT value FROM json_each(?))";
+const flowGrantColumns = grantColumns("flow_id");
+export function createFlowRepository(deps) {
+    // The folders this actor may open, 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());
+    // The other half of the same question since #530: the folders this actor reads come from the walk
+    // above, the flows handed to them directly come from `flow_grants`. Always `read` here, because
+    // every statement these two appear in together is seeded with `read`.
+    const inSubtreeBindings = (actor) => flowInSubtreeBindings(actor, "read", deps.now().toISOString());
+    const runVisibleBindings = (actor) => [actor.id, ...inSubtreeBindings(actor)];
+    // An absent `parentId` asks for every visible flow; `null` asks for the root of the shared tree.
+    // `IS ?` would collapse the two, so the two cases are separate SQL rather than one binding that
+    // silently means both.
+    //
+    // ⚠️ The root is "the top of every region this actor may read", exactly as it is for nodes in
+    // `db.ts` (#429) — a flow whose folder the reader may not open would otherwise sit in a level
+    // nothing can ever open. `flowInSubtree` is what puts such a row in reach at all (its owner, or
+    // `intel/admin`), and this only decides which level it appears in; it can add no flow that
+    // predicate has not already allowed.
+    const scopeOf = (parentId) => parentId === undefined
+        ? { clause: "", bindings: [] }
+        : parentId === null
+            ? {
+                clause: "AND (flow.parent_id IS NULL OR flow.parent_id NOT IN (SELECT id FROM allowed))",
+                bindings: [],
+            }
+            : { clause: "AND flow.parent_id = ?", bindings: [parentId] };
+    /**
+     * One statement for the list the sidebar reads and for the bounded read the relation graph makes,
+     * so the visibility predicate cannot drift between them.
+     *
+     * ⚠️ The order of the two is the whole point of the bounded form (#30): `LIMIT` follows the
+     * `WHERE`, so the cut is made among the rows this actor may see and never before them. For the
+     * same reason `COUNT(*) OVER ()` is a count of those rows alone — the number the graph reports
+     * about its own size would otherwise disclose that something else is there.
+     */
+    const visibleFlows = (scopeClause, bounded, includeArchived = false) => `${subtreeCte}
+    SELECT ${flowColumns}${bounded ? ", COUNT(*) OVER () AS total" : ""} FROM flows flow
+    WHERE ${flowInSubtree} ${includeArchived ? "" : "AND flow.archived_at IS NULL"} ${scopeClause}
+    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), ...inSubtreeBindings(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))
+                .bind(...readableBindings(actor), ...inSubtreeBindings(actor), ...scope.bindings)
+                .all();
+            return (result.results ?? []).map(mapFlow);
+        },
+        async listVisibleBounded(actor, folderId, limit) {
+            const scope = scopeOf(folderId);
+            const result = await deps.db
+                .prepare(visibleFlows(scope.clause, true))
+                .bind(...readableBindings(actor), ...inSubtreeBindings(actor), ...scope.bindings, limit)
+                .all();
+            const rows = result.results ?? [];
+            return { items: rows.map(mapFlow), total: rows[0]?.total ?? 0 };
+        },
+        async getVisible(actor, flowId) {
+            const row = await deps.db
+                .prepare(`${subtreeCte}
+          SELECT ${flowColumns} FROM flows flow
+          WHERE flow.id = ? AND ${flowInSubtree}`)
+                .bind(...readableBindings(actor), flowId, ...inSubtreeBindings(actor))
+                .first();
+            return row ? mapFlow(row) : null;
+        },
+        async listFlowGrants(flowId) {
+            const result = await deps.db
+                .prepare(`SELECT ${flowGrantColumns} FROM flow_grants
+          WHERE flow_id = ?
+          ORDER BY principal_type, principal_id, verb`)
+                .bind(flowId)
+                .all();
+            return (result.results ?? []).map(mapGrant);
+        },
+        // ⚠️ Owners and grants out of ONE statement, hence one D1 snapshot, for the reason the node side
+        // gives: two parallel SELECTs are not atomic, and a grant written between their snapshots
+        // produces a principal list that never existed as a whole.
+        //
+        // ⚠️ The grants come from BOTH tables. Reading only `flow_grants` here would draw a flow as
+        // though the folder above it granted nothing — which is the everyday case, not the exception.
+        async listEffectiveFlowAccess(flowId) {
+            const row = await deps.db
+                .prepare(`WITH RECURSIVE ancestors(id, parent_id, owner_id) AS (
+            SELECT folder.id, folder.parent_id, folder.owner_id
+            FROM nodes folder
+            JOIN flows flow ON flow.parent_id = folder.id
+            WHERE flow.id = ?
+            UNION
+            SELECT parent.id, parent.parent_id, parent.owner_id
+            FROM nodes parent
+            JOIN ancestors child ON child.parent_id = parent.id
+          )
+          SELECT
+            (SELECT json_group_array(owner_id) FROM (
+               SELECT DISTINCT owner_id FROM (
+                 SELECT owner_id FROM flows WHERE id = ?
+                 UNION
+                 SELECT owner_id FROM ancestors
+               ) ORDER BY owner_id
+             )) AS owner_ids_json,
+            (SELECT json_group_array(json_object(
+               'id', id, 'resource_id', resource_id, 'principal_type', principal_type,
+               'principal_id', principal_id, 'verb', verb, 'expires_at', expires_at,
+               'created_by', created_by, 'created_at', created_at
+             ))
+             FROM (
+               SELECT grant_row.id, grant_row.flow_id AS resource_id, grant_row.principal_type,
+                 grant_row.principal_id, grant_row.verb, grant_row.expires_at,
+                 grant_row.created_by, grant_row.created_at
+               FROM flow_grants grant_row
+               WHERE grant_row.flow_id = ?
+                 AND ${grantInForce}
+               UNION ALL
+               SELECT grant_row.id, grant_row.node_id AS resource_id, grant_row.principal_type,
+                 grant_row.principal_id, grant_row.verb, grant_row.expires_at,
+                 grant_row.created_by, grant_row.created_at
+               FROM node_grants grant_row
+               JOIN ancestors ON ancestors.id = grant_row.node_id
+               WHERE ${grantInForce}
+               ORDER BY principal_type, principal_id, verb
+             )) AS grants_json`)
+                .bind(flowId, flowId, flowId, deps.now().toISOString(), deps.now().toISOString())
+                .first();
+            return {
+                ownerIds: JSON.parse(row?.owner_ids_json ?? "[]"),
+                items: JSON.parse(row?.grants_json ?? "[]").map(mapGrant),
+            };
+        },
+        async setFlowGrant(input) {
+            const grant = input.grant;
+            const { type: principalType, id: principalId } = principalColumns(grant.principal);
+            try {
+                await deps.db.batch([
+                    deps.db
+                        // The verb is part of the key, so re-granting the same verb only refreshes its expiry
+                        // and never turns one verb into another.
+                        .prepare(`INSERT INTO flow_grants (
+              id, flow_id, principal_type, principal_id, verb,
+              expires_at, created_by, created_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT (flow_id, principal_type, principal_id, verb)
+            DO UPDATE SET expires_at = excluded.expires_at`)
+                        .bind(grant.id, input.flowId, principalType, principalId, grant.verb, grant.expiresAt, grant.createdBy, grant.createdAt),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'flows.share', ?, id, ? FROM flow_grants
+              WHERE flow_id = ? AND principal_type = ? AND principal_id = ? AND verb = ?`)
+                        .bind(input.actorId, input.idempotencyKey, grant.createdAt, input.flowId, principalType, principalId, grant.verb),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) VALUES (?, ?, 'flows.share', 'flow', ?, ?, ?)`)
+                        .bind(input.auditId, input.actorId, input.flowId, JSON.stringify({ principalType, verb: grant.verb }), grant.createdAt),
+                ]);
+                const stored = await deps.db
+                    .prepare(`SELECT ${flowGrantColumns} FROM flow_grants
+            WHERE flow_id = ? AND principal_type = ? AND principal_id = ? AND verb = ?`)
+                    .bind(input.flowId, principalType, principalId, grant.verb)
+                    .first();
+                if (!stored)
+                    throw new Error("Flow grant disappeared after upsert");
+                return mapGrant(stored);
+            }
+            catch (error) {
+                const replayed = await deps.db
+                    .prepare(`SELECT resource_id FROM idempotency_keys
+            WHERE actor_id = ? AND operation = 'flows.share' AND idempotency_key = ?`)
+                    .bind(input.actorId, input.idempotencyKey)
+                    .first();
+                if (replayed) {
+                    const row = await deps.db
+                        .prepare(`SELECT ${flowGrantColumns} FROM flow_grants WHERE id = ?`)
+                        .bind(replayed.resource_id)
+                        .first();
+                    if (row)
+                        return mapGrant(row);
+                }
+                throw error;
+            }
+        },
+        // ⚠️ Whether the row was there is decided BEFORE it is deleted and remembered in the
+        // idempotency key's own value, because afterwards nothing can tell "I removed it" from "it was
+        // never here" — and a replay that answered `true` to the second would claim a deletion that did
+        // not happen. The `1:`/`0:` prefix is the node side's device, and it is the same device here.
+        async revokeFlowGrant(input) {
+            try {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'flows.revoke', ?,
+              (CASE WHEN EXISTS (
+                SELECT 1 FROM flow_grants WHERE id = ? AND flow_id = ?
+              ) THEN '1:' ELSE '0:' END) || ?, ?`)
+                        .bind(input.actorId, input.idempotencyKey, input.grantId, input.flowId, input.grantId, input.occurredAt),
+                    deps.db
+                        .prepare("DELETE FROM flow_grants WHERE id = ? AND flow_id = ?")
+                        .bind(input.grantId, input.flowId),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'flows.revoke', 'flow', ?,
+              json_object(
+                'grantId', ?,
+                'revoked', json(CASE WHEN substr(resource_id, 1, 2) = '1:' THEN 'true' ELSE 'false' END)
+              ), ?
+              FROM idempotency_keys
+              WHERE actor_id = ? AND operation = 'flows.revoke' AND idempotency_key = ?`)
+                        .bind(input.auditId, input.actorId, input.flowId, input.grantId, input.occurredAt, input.actorId, input.idempotencyKey),
+                ]);
+            }
+            catch (error) {
+                const replayed = await this.findIdempotentFlowRevocation(input.actorId, input.idempotencyKey);
+                if (replayed === null)
+                    throw error;
+                return replayed;
+            }
+            return ((await this.findIdempotentFlowRevocation(input.actorId, input.idempotencyKey)) ?? false);
+        },
+        async findIdempotentFlowRevocation(actorId, idempotencyKey) {
+            const row = await deps.db
+                .prepare(`SELECT resource_id FROM idempotency_keys
+          WHERE actor_id = ? AND operation = 'flows.revoke' AND idempotency_key = ?`)
+                .bind(actorId, idempotencyKey)
+                .first();
+            if (!row)
+                return null;
+            return row.resource_id.startsWith("1:");
+        },
+        async can(actor, flowId, verb) {
+            const row = await deps.db
+                .prepare(flowVerbQuery)
+                .bind(...flowVerbBindings(flowId, actor, verb, deps.now().toISOString()))
+                .first();
+            return row?.allowed === 1;
+        },
+        // A library flow is run by people who may not open the folder it lives in, so `read` alone would
+        // make the library unwirable. The two grants stay independent (ADR-0004 §2) — they are two
+        // walks of the tree — but they are asked in one breath rather than one after the other, because
+        // a graph names as many callees as it likes and each of them used to cost its own round trip
+        // (#30). Order is the graph's, restored by the caller: SQL sorts, a call list does not.
+        async listCallable(actor, flowIds) {
+            if (flowIds.length === 0)
+                return [];
+            const occurredAt = deps.now().toISOString();
+            const result = await deps.db
+                .prepare(`${readableOrRunnableCte}
+          SELECT ${flowColumns} FROM flows flow
+          WHERE flow.id IN ${idList} AND ${flowCallable}
+          ORDER BY lower(flow.title), flow.id`)
+                .bind(...subtreeBindings(actor, "read", occurredAt), ...subtreeBindings(actor, "execute", occurredAt), JSON.stringify(flowIds), ...flowCallableBindings(actor, occurredAt))
+                .all();
+            return (result.results ?? []).map(mapFlow);
+        },
+        async getCallable(actor, flowId) {
+            return (await this.listCallable(actor, [flowId]))[0] ?? null;
+        },
+        // ⚠️ `UNION`, never `UNION ALL`, for the same reason as every other walk of this tree: a ring in
+        // `parent_id` must end the recursion rather than the database.
+        async callReach(callerFolderId, calleeFolderId) {
+            // A flow at the root of the tree stands in the root folder, whose subtree is the whole tree.
+            if (callerFolderId === null)
+                return "subtree";
+            // A callee at the root has no folder, so nothing can carry an `execute` for it: not a library.
+            if (calleeFolderId === null)
+                return "out-of-reach";
+            const row = await deps.db
+                .prepare(`WITH RECURSIVE ancestors(id, parent_id) AS (
+            SELECT id, parent_id FROM nodes WHERE id = ?
+            UNION
+            SELECT parent.id, parent.parent_id
+            FROM nodes parent
+            JOIN ancestors child ON child.parent_id = parent.id
+          )
+          SELECT
+            EXISTS (SELECT 1 FROM ancestors WHERE id = ?) AS in_subtree,
+            EXISTS (
+              SELECT 1 FROM node_grants grant_row
+              JOIN ancestors ON ancestors.id = grant_row.node_id
+              WHERE grant_row.principal_type = 'organization'
+                AND grant_row.verb = 'execute'
+                AND ${grantInForce}
+            ) AS library`)
+                .bind(calleeFolderId, callerFolderId, deps.now().toISOString())
+                .first();
+            if (row?.in_subtree === 1)
+                return "subtree";
+            // The ADR allows a folder whose `execute` reaches at least as far as the caller's own. The
+            // only such folder that can be answered without comparing two principal sets is the one whose
+            // `execute` reaches everyone, and the ADR names that as the case in practice.
+            return row?.library === 1 ? "library" : "out-of-reach";
+        },
+        // ⚠️ Two answers out of one statement: the callers this actor may see, by title, and how many
+        // more there are. The predicate is `flowInSubtree` — the very one `listVisible` uses — so a
+        // caller is named here exactly when it would be listed anywhere else. A second, kinder rule for
+        // error messages is how a refusal turns into a way of reading the tree.
+        async externalCallers(actor, folderId) {
+            const result = await deps.db
+                .prepare(`${subtreeCte},
+          scope(id) AS (
+            SELECT id FROM nodes WHERE id = ?
+            UNION
+            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
+          FROM flows flow
+          JOIN flow_versions version ON version.id = flow.published_version_id
+          JOIN json_each(version.graph_json, '$.nodes') node
+          JOIN flows callee ON callee.id = json_extract(node.value, '$.configuration.flowId')
+          WHERE json_extract(node.value, '$.kind') = 'subflow'
+            AND flow.archived_at IS NULL
+            AND callee.parent_id IN (SELECT id FROM scope)
+            AND (flow.parent_id IS NULL OR flow.parent_id NOT IN (SELECT id FROM scope))
+          ORDER BY lower(flow.title), flow.id`)
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), folderId, ...inSubtreeBindings(actor))
+                .all();
+            const rows = result.results ?? [];
+            return {
+                visible: rows.filter((row) => row.visible === 1).map((row) => mapFlow(row).title),
+                hidden: rows.filter((row) => row.visible !== 1).length,
+            };
+        },
+        // Who calls THIS flow — the sibling of `externalCallers`, which asks the same question about a
+        // whole folder (#457). Same shape: what the actor may see by name, the rest as a number, because
+        // a refusal must not become a way of learning that a flow one cannot see exists.
+        async flowCallers(actor, flowId) {
+            const result = await deps.db
+                .prepare(`${subtreeCte}
+          SELECT DISTINCT ${qualifiedFlowColumns("flow")},
+            CASE WHEN ${flowInSubtree} THEN 1 ELSE 0 END AS visible
+          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') = 'subflow'
+            AND json_extract(node.value, '$.configuration.flowId') = ?
+            AND flow.archived_at IS NULL
+            AND flow.id <> ?
+          ORDER BY lower(flow.title), flow.id`)
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), ...inSubtreeBindings(actor), flowId, flowId)
+                .all();
+            const rows = result.results ?? [];
+            return {
+                visible: rows.filter((row) => row.visible === 1).map((row) => mapFlow(row).title),
+                hidden: rows.filter((row) => row.visible !== 1).length,
+            };
+        },
+        // Published flows whose graph reads THIS node as a step (#457) — the mirror of `nodeReferences`,
+        // which asks the same graph the other way round ("which documents do the flows in this folder
+        // read"). Same visible/hidden shape as every other refusal: a title only where the actor may see
+        // it, the rest counted, so a refusal never becomes a directory of the tree (ADR-0004 §3).
+        async flowsUsingNode(actor, nodeId) {
+            const result = await deps.db
+                .prepare(`${subtreeCte}
+          SELECT DISTINCT ${qualifiedFlowColumns("flow")},
+            CASE WHEN ${flowInSubtree} THEN 1 ELSE 0 END AS visible
+          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') IN (${treeLinkKindList})
+            AND json_extract(node.value, '$.configuration.resourceId') = ?
+            AND flow.archived_at IS NULL
+          ORDER BY lower(flow.title), flow.id`)
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), ...inSubtreeBindings(actor), nodeId)
+                .all();
+            const rows = result.results ?? [];
+            return {
+                visible: rows.filter((row) => row.visible === 1).map((row) => mapFlow(row).title),
+                hidden: rows.filter((row) => row.visible !== 1).length,
+            };
+        },
+        // ⚠️ BOTH directions, and the second one was missing (found in review). A run of this flow can be
+        // the PARENT of somebody else's run — deleting it takes the record of what started theirs. It can
+        // just as well be the CHILD of somebody else's run, and deleting that leaves the caller standing
+        // on a sub-flow node whose callee is gone: it can never be completed, and migration 0010's stall
+        // rule then sweeps the caller to `failed`. A history with a hole is not a history, in either
+        // direction.
+        async hasEntangledRuns(flowId) {
+            const row = await deps.db
+                .prepare(`SELECT 1 AS found
+          FROM flow_runs mine
+          JOIN flow_runs other
+            ON other.parent_run_id = mine.id OR other.id = mine.parent_run_id
+          WHERE mine.flow_id = ? AND other.flow_id <> ?
+          LIMIT 1`)
+                .bind(flowId, flowId)
+                .first();
+            return row !== null;
+        },
+        // ⚠️ Archiving deliberately leaves runs in flight alone — restoring the flow is what makes them
+        // readable again (`flows.ts`). A purge takes that way back with it, so a run that has not
+        // finished refuses the deletion rather than being deleted mid-execution.
+        async hasUnfinishedRuns(flowId) {
+            const row = await deps.db
+                .prepare(`SELECT 1 AS found FROM flow_runs
+          WHERE flow_id = ? AND status IN ('queued', 'running', 'waiting') LIMIT 1`)
+                .bind(flowId)
+                .first();
+            return row !== null;
+        },
+        async purgeFlow(input) {
+            const aliveFlow = "EXISTS (SELECT 1 FROM flows f WHERE f.id = ? AND f.archived_at IS NOT NULL)";
+            const deleted = await deps.db.batch([
+                // ⚠️ FIRST, reading the title out of the row that falls at the end of this batch. Afterwards
+                // nothing can look a name up, and an entry carrying only an id names something nobody can
+                // find again (`anchrd/gate#146`).
+                deps.db
+                    .prepare(`INSERT INTO audit_events (
+            id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+          ) SELECT ?, ?, 'flows.purge', 'flow', f.id,
+              json_object('title', f.title, 'parentId', f.parent_id), ?
+            FROM flows f WHERE f.id = ? AND f.archived_at IS NOT NULL`)
+                    .bind(input.auditId, input.actorId, input.occurredAt, input.flowId),
+                // The runs are this flow's history: the steps hang off the runs, the runs off the flow.
+                // ⚠️ The guard belongs on EVERY statement, not only the last: a batch whose final statement
+                // matches nothing still COMMITS, so a restore in between would empty a living flow's history
+                // and answer `409` as if nothing had happened.
+                deps.db
+                    .prepare(`DELETE FROM flow_run_steps
+            WHERE run_id IN (SELECT id FROM flow_runs WHERE flow_id = ?) AND ${aliveFlow}`)
+                    .bind(input.flowId, input.flowId),
+                deps.db
+                    .prepare(`DELETE FROM flow_runs WHERE flow_id = ? AND ${aliveFlow}`)
+                    .bind(input.flowId, input.flowId),
+                deps.db
+                    .prepare(`DELETE FROM flow_versions WHERE flow_id = ? AND ${aliveFlow}`)
+                    .bind(input.flowId, input.flowId),
+                deps.db
+                    .prepare(`DELETE FROM idempotency_keys WHERE resource_id = ? AND ${aliveFlow}`)
+                    .bind(input.flowId, input.flowId),
+                // The grants that sat on the flow itself (#530). They point at `flows(id)`, so they have to
+                // go before the row does — and they carry the same guard as everything above for the same
+                // reason: a batch whose last statement matches nothing still commits, and a restore in
+                // between would leave a living flow stripped of every grant somebody set on it.
+                deps.db
+                    .prepare(`DELETE FROM flow_grants WHERE flow_id = ? AND ${aliveFlow}`)
+                    .bind(input.flowId, input.flowId),
+                // ⚠️ LAST, and still guarded — a restore between the service's check and this statement
+                // would otherwise cost a living flow.
+                deps.db
+                    .prepare("DELETE FROM flows WHERE id = ? AND archived_at IS NOT NULL")
+                    .bind(input.flowId),
+            ]);
+            return (deleted.at(-1)?.meta?.changes ?? 0) === 0 ? "missing" : { purged: true };
+        },
+        // 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 the tree's
+        // question — this one hands back IDs and no titles.
+        //
+        // ⚠️ 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 nodes WHERE id = ?
+            UNION
+            SELECT child.id FROM nodes child JOIN scope ON child.parent_id = scope.id
+          ),
+          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') IN (${treeLinkKindList})
+              AND flow.archived_at IS NULL
+              AND flow.parent_id IN (SELECT id FROM scope)
+              AND ${flowInSubtree}
+          )
+          SELECT DISTINCT resource_id
+          FROM referencing
+          WHERE resource_id IS NOT NULL
+          ORDER BY resource_id`)
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), folderId, ...inSubtreeBindings(actor))
+                .all();
+            return (result.results ?? []).map((row) => row.resource_id);
+        },
+        // ⚠️ No actor and no `archived_at` condition, both on purpose (#509). The question is whether
+        // the row is still there at all, and archiving keeps it — a reference to something archived is
+        // not broken, it is waiting for a restore. The caller has already asked the visibility door for
+        // every one of these ids and reaches this only for the ones it answered nothing for.
+        //
+        // ⚠️ An empty list short-circuits rather than building `IN ()`, which SQLite refuses to parse.
+        async existingNodes(nodeIds) {
+            const wanted = [...new Set(nodeIds)];
+            if (wanted.length === 0)
+                return [];
+            const result = await deps.db
+                .prepare(`SELECT id FROM nodes WHERE id IN (${wanted.map(() => "?").join(", ")}) ORDER BY id`)
+                .bind(...wanted)
+                .all();
+            return (result.results ?? []).map((row) => row.id);
+        },
+        async publishedCallees(flowId) {
+            const row = await deps.db
+                .prepare(`SELECT flow.title AS title, version.graph_json AS graph_json
+          FROM flows flow
+          JOIN flow_versions version ON version.id = flow.published_version_id
+          WHERE flow.id = ? AND flow.archived_at IS NULL`)
+                .bind(flowId)
+                .first();
+            if (!row)
+                return null;
+            return {
+                title: row.title,
+                calleeIds: calleeIds(FlowGraph.parse(JSON.parse(row.graph_json))),
+            };
+        },
+        async findIdempotent(actorId, operation, key) {
+            const row = await deps.db
+                .prepare(`SELECT resource_id FROM idempotency_keys
+          WHERE actor_id = ? AND operation = ? AND idempotency_key = ?`)
+                .bind(actorId, operation, key)
+                .first();
+            return row?.resource_id ?? null;
+        },
+        async insertFlow(input) {
+            const flow = input.flow;
+            try {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`INSERT INTO flows (
+              id, parent_id, title, description, owner_id, current_version_id, published_version_id,
+              created_at, updated_at, archived_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                        .bind(flow.id, flow.parentId, flow.title, flow.description, flow.ownerId, flow.currentVersionId, flow.publishedVersionId, flow.createdAt, flow.updatedAt, flow.archivedAt),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) VALUES (?, 'flows.create', ?, ?, ?)`)
+                        .bind(input.actorId, input.idempotencyKey, flow.id, flow.createdAt),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) VALUES (?, ?, 'flows.create', 'flow', ?, '{}', ?)`)
+                        .bind(input.auditId, input.actorId, flow.id, flow.createdAt),
+                ]);
+                return flow;
+            }
+            catch (error) {
+                const replayedId = await this.findIdempotent(input.actorId, "flows.create", input.idempotencyKey);
+                const replayed = replayedId
+                    ? await deps.db
+                        .prepare(`SELECT ${flowColumns} FROM flows WHERE id = ?`)
+                        .bind(replayedId)
+                        .first()
+                    : null;
+                if (replayed)
+                    return mapFlow(replayed);
+                throw error;
+            }
+        },
+        // Renaming and moving touch the flow row and nothing else. `current_version_id` and
+        // `published_version_id` are deliberately absent from the SET list: organization must not be
+        // able to change what a flow does (ADR-0004).
+        async updateFlow(input) {
+            const flow = input.flow;
+            try {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`UPDATE flows SET parent_id = ?, title = ?, description = ?, updated_at = ?
+              WHERE id = ? AND updated_at = ?`)
+                        .bind(flow.parentId, flow.title, flow.description, flow.updatedAt, flow.id, input.baseUpdatedAt),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'flows.update', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM flows
+              WHERE id = ? AND parent_id IS ? AND title = ? AND description IS ? AND updated_at = ?
+            )`)
+                        .bind(input.actorId, input.idempotencyKey, flow.id, flow.updatedAt, flow.id, flow.parentId, flow.title, flow.description, flow.updatedAt),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'flows.update', 'flow', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM idempotency_keys
+              WHERE actor_id = ? AND operation = 'flows.update'
+                AND idempotency_key = ? AND resource_id = ?
+            )`)
+                        .bind(input.auditId, input.actorId, flow.id, JSON.stringify({ parentId: flow.parentId, title: flow.title }), flow.updatedAt, input.actorId, input.idempotencyKey, flow.id),
+                ]);
+            }
+            catch (error) {
+                if (!(await this.findIdempotent(input.actorId, "flows.update", input.idempotencyKey))) {
+                    throw error;
+                }
+            }
+            const replayed = await this.findIdempotent(input.actorId, "flows.update", input.idempotencyKey);
+            if (!replayed)
+                return "conflict";
+            const row = await deps.db
+                .prepare(`SELECT ${flowColumns} FROM flows WHERE id = ?`)
+                .bind(replayed)
+                .first();
+            return row ? mapFlow(row) : "conflict";
+        },
+        // Archiving and restoring are one statement, told apart only by whether `archived_at` is a
+        // timestamp or null. Like `updateFlow` it writes the flow row alone: an archived flow keeps its
+        // versions and its published version, because coming back out of the archive has to return the
+        // flow that went in.
+        //
+        // ⚠️ The idempotency row is written only if the UPDATE actually matched — same guard as
+        // `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 {
+                await deps.db.batch([
+                    /**
+                     * ⚠️ **`archived_with` is CLEARED here, in both directions** (D71, #733, found in review
+                     * of #738). A flow that travels through this door travels alone, so it belongs to no
+                     * group: archiving it on its own must not leave it looking like part of one, and a row
+                     * that still pointed at a group it no longer belongs to would come back with that group's
+                     * next restore.
+                     *
+                     * The group itself is written by ONE place, the cascade in `archiveNode`. Minting an
+                     * operation here as well would be a second writer for one column, and it would have no
+                     * reader: for a restore, "no group" and "somebody else's group" are the same answer.
+                     */
+                    deps.db
+                        .prepare(`UPDATE flows SET archived_at = ?, archived_with = NULL, updated_at = ?
+              WHERE id = ? AND updated_at = ?`)
+                        .bind(input.archivedAt, input.updatedAt, input.flowId, input.baseUpdatedAt),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'flows.archive', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM flows WHERE id = ? AND archived_at IS ? AND updated_at = ?
+            )`)
+                        .bind(input.actorId, input.idempotencyKey, input.flowId, input.updatedAt, input.flowId, input.archivedAt, input.updatedAt),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'flows.archive', 'flow', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM idempotency_keys
+              WHERE actor_id = ? AND operation = 'flows.archive'
+                AND idempotency_key = ? AND resource_id = ?
+            )`)
+                        .bind(input.auditId, input.actorId, input.flowId, JSON.stringify({ archived: input.archivedAt !== null }), input.updatedAt, input.actorId, input.idempotencyKey, input.flowId),
+                ]);
+            }
+            catch (error) {
+                if (!(await this.findIdempotent(input.actorId, "flows.archive", input.idempotencyKey))) {
+                    throw error;
+                }
+            }
+            const replayed = await this.findIdempotent(input.actorId, "flows.archive", input.idempotencyKey);
+            if (!replayed)
+                return "conflict";
+            const row = await deps.db
+                .prepare(`SELECT ${flowColumns} FROM flows WHERE id = ?`)
+                .bind(replayed)
+                .first();
+            return row ? mapFlow(row) : "conflict";
+        },
+        // Versions are immutable, so a set of them is a single read by definition: the trail of a nested
+        // run needs one per level and the relation graph one per flow it draws, and both used to ask
+        // level by level (#30). Missing IDs are simply absent from the answer.
+        async getVersions(versionIds) {
+            if (versionIds.length === 0)
+                return [];
+            const result = await deps.db
+                .prepare(`SELECT id, flow_id, sequence, graph_json, created_by, created_at
+          FROM flow_versions WHERE id IN ${idList}`)
+                .bind(JSON.stringify(versionIds))
+                .all();
+            return (result.results ?? []).map(mapVersion);
+        },
+        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 {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`INSERT INTO flow_versions (
+              id, flow_id, sequence, graph_json, created_by, created_at
+            ) SELECT ?, ?, ?, ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM flows WHERE id = ? AND current_version_id IS ?
+            )`)
+                        .bind(version.id, version.flowId, version.sequence, JSON.stringify(version.graph), version.createdBy, version.createdAt, version.flowId, input.baseVersionId),
+                    deps.db
+                        .prepare(`UPDATE flows SET current_version_id = ?, updated_at = ?
+              WHERE id = ? AND current_version_id IS ?
+                AND EXISTS (SELECT 1 FROM flow_versions WHERE id = ?)`)
+                        .bind(version.id, version.createdAt, version.flowId, input.baseVersionId, version.id),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'flows.save', ?, ?, ?
+            WHERE EXISTS (SELECT 1 FROM flow_versions WHERE id = ?)`)
+                        .bind(input.actorId, input.idempotencyKey, version.id, version.createdAt, version.id),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'flows.save', 'flow', ?, ?, ?
+            WHERE EXISTS (SELECT 1 FROM flow_versions WHERE id = ?)`)
+                        .bind(input.auditId, input.actorId, version.flowId, JSON.stringify({ versionId: version.id, sequence: version.sequence }), version.createdAt, version.id),
+                ]);
+            }
+            catch (error) {
+                const replayed = await this.findIdempotent(input.actorId, "flows.save", input.idempotencyKey);
+                if (!replayed)
+                    throw error;
+            }
+            const stored = await deps.db
+                .prepare("SELECT 1 AS saved FROM flow_versions WHERE id = ?")
+                .bind(version.id)
+                .first();
+            return stored ? "saved" : "conflict";
+        },
+        async promptNameHolder(actor, name) {
+            // One question, one implementation, shared with the node repository — see `db-prompts.ts`.
+            return await promptNameHolder(deps, actor, name);
+        },
+        /**
+         * ⚠️ **Two statement forms, not one with a conditional value** (#775). Publishing without
+         * mentioning a prompt name must leave the name alone; `SET prompt_name = ?` with the current
+         * value read back beforehand would work until two publishes race, and then the second one
+         * writes a name the first had just replaced. The form that does not mention the column cannot
+         * do that, and the form that does carries its guard.
+         *
+         * ⚠️ **The guard is on all three statements** (`destructive.md`, `anchrd/intel#457`). A
+         * statement matching zero rows is not an error, so an idempotency row and an audit row written
+         * without the same condition would book a publication that never happened — and the caller's
+         * retry would then be answered out of the replay table.
+         */
+        async publish(input) {
+            const setsName = input.promptName !== undefined;
+            const nameAssignment = setsName ? ", prompt_name = ?" : "";
+            const nameBinding = setsName ? [input.promptName] : [];
+            // ⚠️ `other.id <> ?` lets a flow keep the name it already holds: republishing an offered flow
+            // sends the same name again, and without the exclusion it would collide with itself.
+            const nameGuard = setsName
+                ? `AND (
+                ? IS NULL
+                OR (
+                  NOT EXISTS (SELECT 1 FROM nodes holder WHERE holder.prompt_name = ?)
+                  AND NOT EXISTS (
+                    SELECT 1 FROM flows other WHERE other.prompt_name = ? AND other.id <> ?
+                  )
+                )
+              )`
+                : "";
+            const nameGuardBindings = setsName
+                ? [input.promptName, input.promptName, input.promptName, input.flowId]
+                : [];
+            const nameEcho = setsName ? "AND prompt_name IS ?" : "";
+            const nameEchoBinding = setsName ? [input.promptName] : [];
+            try {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`UPDATE flows SET published_version_id = ?${nameAssignment}, updated_at = ?
+              WHERE id = ? AND EXISTS (
+                SELECT 1 FROM flow_versions WHERE id = ? AND flow_id = ?
+              )
+              ${nameGuard}`)
+                        .bind(input.versionId, ...nameBinding, input.occurredAt, input.flowId, input.versionId, input.flowId, ...nameGuardBindings),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'flows.publish', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM flows WHERE id = ? AND published_version_id = ? ${nameEcho}
+            )`)
+                        .bind(input.actorId, input.idempotencyKey, input.versionId, input.occurredAt, input.flowId, input.versionId, ...nameEchoBinding),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'flows.publish', 'flow', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM idempotency_keys
+              WHERE actor_id = ? AND operation = 'flows.publish' AND idempotency_key = ?
+            )`)
+                        .bind(input.auditId, input.actorId, input.flowId, JSON.stringify({ versionId: input.versionId }), input.occurredAt, input.actorId, input.idempotencyKey),
+                ]);
+            }
+            catch (error) {
+                const replayed = await this.findIdempotent(input.actorId, "flows.publish", input.idempotencyKey);
+                if (!replayed)
+                    throw error;
+            }
+            const published = (await this.findIdempotent(input.actorId, "flows.publish", input.idempotencyKey)) !== null;
+            // ⚠️ Which of the two refusals it was, asked only after the write has failed — the same order
+            // `updateNode` uses, and for the same reason: deciding first and writing unguarded is the
+            // shape that loses the race the guard exists for.
+            if (!published && setsName && input.promptName !== null) {
+                const taken = await deps.db
+                    .prepare(`SELECT 1 AS found FROM nodes WHERE prompt_name = ?
+            UNION ALL
+            SELECT 1 AS found FROM flows WHERE prompt_name = ? AND id <> ?
+            LIMIT 1`)
+                    .bind(input.promptName, input.promptName, input.flowId)
+                    .first();
+                if (taken?.found === 1)
+                    return "prompt_name_taken";
+            }
+            return published;
+        },
+        // 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 {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`INSERT INTO flow_runs (
+              id, flow_id, version_id, status, current_node_id, input_json, output_json,
+              error, initiated_by, parent_run_id, parent_node_id, created_at, updated_at, completed_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                        .bind(run.id, run.flowId, run.versionId, run.status, run.currentNodeId, JSON.stringify(run.input), null, run.error, run.initiatedBy, run.parentRunId, run.parentNodeId, run.createdAt, run.updatedAt, run.completedAt),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) VALUES (?, 'flows.run', ?, ?, ?)`)
+                        .bind(input.actorId, input.idempotencyKey, run.id, run.createdAt),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) VALUES (?, ?, 'flows.run', 'flow-run', ?, ?, ?)`)
+                        .bind(input.auditId, input.actorId, run.id, JSON.stringify({ flowId: run.flowId, versionId: run.versionId }), run.createdAt),
+                ]);
+                return run;
+            }
+            catch (error) {
+                const replayedId = await this.findIdempotent(input.actorId, "flows.run", input.idempotencyKey);
+                const replayed = replayedId
+                    ? await deps.db
+                        .prepare(`SELECT ${runColumns} FROM flow_runs WHERE id = ?`)
+                        .bind(replayedId)
+                        .first()
+                    : null;
+                if (replayed)
+                    return mapRun(replayed);
+                throw error;
+            }
+        },
+        async getRunVisible(actor, runId) {
+            const row = await deps.db
+                .prepare(`${subtreeCte}
+          SELECT ${qualifiedRunColumns("run")} FROM flow_runs run
+          JOIN flows flow ON flow.id = run.flow_id
+          WHERE run.id = ? AND ${runVisible}`)
+                .bind(...readableBindings(actor), runId, ...runVisibleBindings(actor))
+                .first();
+            return row ? mapRun(row) : null;
+        },
+        // Newest first, keyed on `(created_at, id)` so a page holds still while runs keep arriving.
+        //
+        // ⚠️ `runVisible`, the same predicate `getRunVisible` uses one function up. Seeing the flow is
+        // not the same as seeing its runs: a library flow is executable for everyone and readable by
+        // nobody, and the people running it must still find their own runs back.
+        //
+        // ⚠️ A null flow means EVERY flow this actor may read, not "no flow" (#774). The row filter is
+        // untouched by it — `runVisible` decides per row either way — so the wider question cannot
+        // answer with a run the narrow one would have hidden. Which SHAPE of statement asks it is
+        // `flowRunsPageQuery`'s business, and the reason it is a shape rather than a binding is written
+        // there.
+        async listRunsVisible(actor, input) {
+            const scoped = input.flowId !== null;
+            const result = await deps.db
+                .prepare(flowRunsPageQuery({
+                scoped,
+                failedOnly: input.failedOnly,
+                paged: input.cursor !== null && input.cursor !== undefined,
+            }))
+                .bind(...readableBindings(actor), ...(scoped ? [input.flowId] : []), ...runVisibleBindings(actor), ...(input.cursor
+                ? [input.cursor.createdAt, input.cursor.createdAt, input.cursor.id]
+                : []), input.limit)
+                .all();
+            return (result.results ?? []).map(mapRun);
+        },
+        // `idList` rather than a placeholder per run: a page of runs is as long as the page size, and
+        // a statement built from the input would carry its length into D1's parameter cap (#30).
+        async failedSteps(runIds) {
+            if (runIds.length === 0)
+                return [];
+            const result = await deps.db
+                .prepare(`SELECT run_id, node_id, outcome, branch, error, completed_at
+          FROM flow_run_steps
+          WHERE outcome = 'failed' AND run_id IN ${idList}`)
+                .bind(JSON.stringify(runIds))
+                .all();
+            return (result.results ?? []).map(mapStep);
+        },
+        async runSteps(runId) {
+            const result = await deps.db
+                .prepare(`SELECT run_id, node_id, outcome, branch, error, completed_at
+          FROM flow_run_steps WHERE run_id = ?
+          ORDER BY completed_at, id`)
+                .bind(runId)
+                .all();
+            return (result.results ?? []).map(mapStep);
+        },
+        // ⚠️ `runVisible` once more, for many call sites at once. The reason a call failed lives in the
+        // called run, and whether it may be repeated is that run's own question — asking it per row is
+        // what would put a query on every line of the list, and answering it with a second, cheaper rule
+        // is what #17, #19 and #20 were each sent back for.
+        //
+        // The pairs travel as one JSON value, like every other list here: a call site is two columns, so
+        // `IN` cannot express it and a placeholder pair per row would carry the page size into D1's
+        // parameter cap.
+        async visibleCallRuns(actor, sites) {
+            if (sites.length === 0)
+                return [];
+            const result = await deps.db
+                .prepare(`${subtreeCte},
+          sites(caller_id, caller_node) AS (
+            SELECT json_extract(site.value, '$.r'), json_extract(site.value, '$.n')
+            FROM json_each(?) site
+          )
+          SELECT run.parent_run_id AS caller_id, run.parent_node_id AS caller_node,
+                 run.id AS called_id
+          FROM flow_runs run
+          JOIN flows flow ON flow.id = run.flow_id
+          JOIN sites ON sites.caller_id = run.parent_run_id
+            AND sites.caller_node = run.parent_node_id
+          WHERE ${runVisible}`)
+                .bind(...readableBindings(actor), JSON.stringify(sites.map((site) => ({ r: site.runId, n: site.nodeId }))), ...runVisibleBindings(actor))
+                .all();
+            return (result.results ?? []).map((row) => ({
+                runId: row.caller_id,
+                nodeId: row.caller_node,
+                calledRunId: row.called_id,
+            }));
+        },
+        // No ACL here on purpose: the caller has already been answered for the outer run, and the result
+        // of a call belongs to the step that made it. What it is used for is the step's output, never a
+        // route into the called flow — that goes through `getRunVisible` like everything else.
+        async findChildRun(parentRunId, parentNodeId) {
+            const row = await deps.db
+                .prepare(`SELECT ${runColumns} FROM flow_runs
+          WHERE parent_run_id = ? AND parent_node_id = ?`)
+                .bind(parentRunId, parentNodeId)
+                .first();
+            return row ? mapRun(row) : null;
+        },
+        // Both directions in one statement: every caller above the run, and the run each active subflow
+        // step below it started. `UNION` ends both walks even if a repair ever wrote a ring.
+        async runChain(runId) {
+            const result = await deps.db
+                .prepare(`WITH RECURSIVE up(id, parent_run_id) AS (
+            SELECT id, parent_run_id FROM flow_runs WHERE id = ?
+            UNION
+            SELECT parent.id, parent.parent_run_id
+            FROM flow_runs parent JOIN up ON up.parent_run_id = parent.id
+          ),
+          down(id, current_node_id) AS (
+            SELECT id, current_node_id FROM flow_runs WHERE id = ?
+            UNION
+            SELECT child.id, child.current_node_id
+            FROM flow_runs child
+            JOIN down ON child.parent_run_id = down.id AND child.parent_node_id = down.current_node_id
+          )
+          SELECT run.id AS run_id, run.flow_id, flow.title AS flow_title, run.version_id,
+                 run.parent_run_id, run.current_node_id
+          FROM flow_runs run
+          JOIN flows flow ON flow.id = run.flow_id
+          WHERE run.id IN (SELECT id FROM up) OR run.id IN (SELECT id FROM down)`)
+                .bind(runId, runId)
+                .all();
+            return (result.results ?? []).map((row) => ({
+                runId: row.run_id,
+                flowId: row.flow_id,
+                flowTitle: row.flow_title,
+                versionId: row.version_id,
+                parentRunId: row.parent_run_id,
+                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 {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`UPDATE flow_runs SET
+              status = ?, current_node_id = ?, output_json = ?, error = ?,
+              updated_at = ?, completed_at = ?, transition_id = ?
+              WHERE id = ? AND current_node_id = ? AND status IN ('running', 'waiting')`)
+                        .bind(run.status, run.currentNodeId, run.output === null ? null : JSON.stringify(run.output), run.error, run.updatedAt, run.completedAt, input.stepId, run.id, input.expectedNodeId),
+                    deps.db
+                        .prepare(`INSERT INTO flow_run_steps (
+              id, run_id, node_id, outcome, branch, output_json, error, completed_by, completed_at
+            ) SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM flow_runs WHERE id = ? AND transition_id = ?
+            )`)
+                        .bind(input.stepId, run.id, input.expectedNodeId, input.outcome, input.branch, JSON.stringify(input.output), input.error, input.actorId, run.updatedAt, run.id, input.stepId),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'flows.complete', ?, ?, ?
+            WHERE EXISTS (SELECT 1 FROM flow_run_steps WHERE id = ?)`)
+                        .bind(input.actorId, input.idempotencyKey, run.id, run.updatedAt, input.stepId),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'flows.complete', 'flow-run', ?, ?, ?
+            WHERE EXISTS (SELECT 1 FROM flow_run_steps WHERE id = ?)`)
+                        .bind(input.auditId, input.actorId, run.id, JSON.stringify({ nodeId: input.expectedNodeId, outcome: input.outcome }), run.updatedAt, input.stepId),
+                ]);
+            }
+            catch (error) {
+                const replayed = await this.findIdempotent(input.actorId, "flows.complete", input.idempotencyKey);
+                if (!replayed)
+                    throw error;
+            }
+            const replayed = await this.findIdempotent(input.actorId, "flows.complete", input.idempotencyKey);
+            return replayed === run.id ? "advanced" : "conflict";
+        },
+    };
+}