@anchrd/intel-api 0.3.1 → 0.3.3

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

@@ -1,6 +1,19 @@
 import { Flow, FlowGraph, FlowRun, FlowVersion, } from "@anchrd/intel-contract";
-const flowColumns = `id, parent_id, title, description, owner_id, current_version_id,
-  published_version_id, created_at, updated_at, archived_at`;
+import { calleeIds } from "../../flows/flows.js";
+import { flowCallable, flowInSubtree, flowInSubtreeBindings, flowVerbBindings, flowVerbQuery, readableOrRunnableCte, subtreeBindings, subtreeCte, } from "./db-grants.js";
+const flowColumnNames = [
+    "id",
+    "parent_id",
+    "title",
+    "description",
+    "owner_id",
+    "current_version_id",
+    "published_version_id",
+    "created_at",
+    "updated_at",
+    "archived_at",
+];
+const flowColumns = flowColumnNames.join(", ");
 const runColumnNames = [
     "id",
     "flow_id",
@@ -11,6 +24,8 @@ const runColumnNames = [
     "output_json",
     "error",
     "initiated_by",
+    "parent_run_id",
+    "parent_node_id",
     "created_at",
     "updated_at",
     "completed_at",
@@ -19,23 +34,7 @@ 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(", ");
-function accessPredicate(roles = []) {
-    const role = roles.length ? `AND grant_row.role IN (${roles.map(() => "?").join(", ")})` : "";
-    return `(flow.owner_id = ? OR EXISTS (
-    SELECT 1 FROM resource_grants grant_row
-    WHERE grant_row.resource_type = 'flow' AND grant_row.resource_id = flow.id
-      AND (
-        (grant_row.principal_type = 'user' AND grant_row.principal_id = ?)
-        OR (grant_row.principal_type = 'email' AND lower(grant_row.principal_id) = lower(?))
-        OR (grant_row.principal_type = 'organization' AND grant_row.principal_id = '*')
-      )
-      ${role}
-      AND (grant_row.expires_at IS NULL OR grant_row.expires_at > ?)
-  ))`;
-}
-function accessBindings(actor, now, roles = []) {
-    return [actor.id, actor.id, actor.email, ...roles, now];
-}
+const qualifiedFlowColumns = (alias) => flowColumnNames.map((column) => `${alias}.${column}`).join(", ");
 function mapFlow(row) {
     return Flow.parse({
         id: row.id,
@@ -60,6 +59,25 @@ function mapVersion(row) {
         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.
+const runVisible = `(run.initiated_by = ? OR ${flowInSubtree})`;
+const runVisibleBindings = (actor) => [actor.id, ...flowInSubtreeBindings(actor)];
+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,
@@ -71,78 +89,214 @@ function mapRun(row) {
         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,
     });
 }
-function mapGrant(row) {
-    let principal;
-    switch (row.principal_type) {
-        case "user":
-            principal = { type: "user", id: row.principal_id };
-            break;
-        case "email":
-            principal = { type: "email", email: row.principal_id };
-            break;
-        case "organization":
-            principal = { type: "organization" };
-            break;
-        default:
-            throw new Error("Unsupported flow grant principal type");
-    }
-    return {
-        id: row.id,
-        resourceId: row.resource_id,
-        principal,
-        role: row.role,
-        expiresAt: row.expires_at,
-        createdBy: row.created_by,
-        createdAt: row.created_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(?))";
 export function createFlowRepository(deps) {
-    const visible = accessPredicate();
+    // 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
+    // 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.
+    // `IS ?` would collapse the two, so the two cases are separate SQL rather than one binding that
+    // silently means both.
+    const scopeOf = (parentId) => parentId === undefined
+        ? { clause: "", bindings: [] }
+        : parentId === null
+            ? { clause: "AND flow.parent_id IS NULL", 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) => `${subtreeCte}
+    SELECT ${flowColumns}${bounded ? ", COUNT(*) OVER () AS total" : ""} FROM flows flow
+    WHERE ${flowInSubtree} AND flow.archived_at IS NULL ${scopeClause}
+    ORDER BY lower(flow.title), flow.id${bounded ? " LIMIT ?" : ""}`;
     return {
         async listVisible(actor, input = {}) {
-            // 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.
-            const scope = input.parentId === undefined
-                ? { clause: "", bindings: [] }
-                : input.parentId === null
-                    ? { clause: "AND flow.parent_id IS NULL", bindings: [] }
-                    : { clause: "AND flow.parent_id = ?", bindings: [input.parentId] };
+            const scope = scopeOf(input.parentId);
             const result = await deps.db
-                .prepare(`SELECT ${flowColumns} FROM flows flow
-          WHERE ${visible} AND flow.archived_at IS NULL ${scope.clause}
-          ORDER BY lower(flow.title), flow.id`)
-                .bind(...accessBindings(actor, deps.now().toISOString()), ...scope.bindings)
+                .prepare(visibleFlows(scope.clause, false))
+                .bind(...readableBindings(actor), ...flowInSubtreeBindings(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), ...flowInSubtreeBindings(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(`SELECT ${flowColumns} FROM flows flow WHERE flow.id = ? AND ${visible}`)
-                .bind(flowId, ...accessBindings(actor, deps.now().toISOString()))
+                .prepare(`${subtreeCte}
+          SELECT ${flowColumns} FROM flows flow
+          WHERE flow.id = ? AND ${flowInSubtree}`)
+                .bind(...readableBindings(actor), flowId, ...flowInSubtreeBindings(actor))
                 .first();
             return row ? mapFlow(row) : null;
         },
-        async canEdit(actor, flowId) {
+        async can(actor, flowId, verb) {
             const row = await deps.db
-                .prepare(`SELECT 1 AS allowed FROM flows flow
-          WHERE flow.id = ? AND ${accessPredicate(["editor", "manager"])}`)
-                .bind(flowId, ...accessBindings(actor, deps.now().toISOString(), ["editor", "manager"]))
+                .prepare(flowVerbQuery)
+                .bind(...flowVerbBindings(flowId, actor, verb, deps.now().toISOString()))
                 .first();
             return row?.allowed === 1;
         },
-        async canManage(actor, flowId) {
+        // 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), ...flowInSubtreeBindings(actor))
+                .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(`SELECT 1 AS allowed FROM flows flow
-          WHERE flow.id = ? AND ${accessPredicate(["manager"])}`)
-                .bind(flowId, ...accessBindings(actor, deps.now().toISOString(), ["manager"]))
+                .prepare(`WITH RECURSIVE ancestors(id, parent_id) AS (
+            SELECT id, parent_id FROM knowledge_nodes WHERE id = ?
+            UNION
+            SELECT parent.id, parent.parent_id
+            FROM knowledge_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 tree_grants grant_row
+              JOIN ancestors ON ancestors.id = grant_row.node_id
+              WHERE grant_row.principal_type = 'organization'
+                AND grant_row.verb = 'execute'
+                AND (grant_row.expires_at IS NULL OR grant_row.expires_at > ?)
+            ) AS library`)
+                .bind(calleeFolderId, callerFolderId, deps.now().toISOString())
                 .first();
-            return row?.allowed === 1;
+            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 knowledge_nodes WHERE id = ?
+            UNION
+            SELECT child.id FROM knowledge_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, ...flowInSubtreeBindings(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,
+            };
+        },
+        // The Knowledge 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
+        // 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) {
+            const result = await deps.db
+                .prepare(`${subtreeCte},
+          scope(id) AS (
+            SELECT id FROM knowledge_nodes WHERE id = ?
+            UNION
+            SELECT child.id FROM knowledge_nodes child JOIN scope ON child.parent_id = scope.id
+          ),
+          referencing(resource_ids) AS (
+            SELECT json_extract(node.value, '$.configuration.resourceIds')
+            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'
+              AND flow.archived_at IS NULL
+              AND flow.parent_id IN (SELECT id FROM scope)
+              AND ${flowInSubtree}
+          )
+          SELECT DISTINCT reference.value AS resource_id
+          FROM referencing
+          JOIN json_each(referencing.resource_ids) reference
+          ORDER BY reference.value`)
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), folderId, ...flowInSubtreeBindings(actor))
+                .all();
+            return (result.results ?? []).map((row) => row.resource_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
@@ -152,16 +306,6 @@ export function createFlowRepository(deps) {
                 .first();
             return row?.resource_id ?? null;
         },
-        async findIdempotentRevocation(actorId, key) {
-            const row = await deps.db
-                .prepare(`SELECT resource_id FROM idempotency_keys
-          WHERE actor_id = ? AND operation = 'flows.revoke' AND idempotency_key = ?`)
-                .bind(actorId, key)
-                .first();
-            if (!row)
-                return null;
-            return row.resource_id.startsWith("1:");
-        },
         async insertFlow(input) {
             const flow = input.flow;
             try {
@@ -244,13 +388,21 @@ export function createFlowRepository(deps) {
                 .first();
             return row ? mapFlow(row) : "conflict";
         },
-        async getVersion(versionId) {
-            const row = await deps.db
+        // 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 = ?`)
-                .bind(versionId)
-                .first();
-            return row ? mapVersion(row) : null;
+          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;
         },
         async insertVersion(input) {
             const version = input.version;
@@ -329,109 +481,6 @@ export function createFlowRepository(deps) {
             }
             return ((await this.findIdempotent(input.actorId, "flows.publish", input.idempotencyKey)) !== null);
         },
-        async listGrants(flowId) {
-            const result = await deps.db
-                .prepare(`SELECT id, resource_id, principal_type, principal_id, role, expires_at,
-          created_by, created_at FROM resource_grants
-          WHERE resource_type = 'flow' AND resource_id = ?
-          ORDER BY created_at, id`)
-                .bind(flowId)
-                .all();
-            return (result.results ?? []).map(mapGrant);
-        },
-        async setGrant(input) {
-            const grant = input.grant;
-            const principalType = grant.principal.type;
-            const principalId = grant.principal.type === "user"
-                ? grant.principal.id
-                : grant.principal.type === "email"
-                    ? grant.principal.email.toLowerCase()
-                    : "*";
-            try {
-                await deps.db.batch([
-                    deps.db
-                        .prepare(`INSERT INTO resource_grants (
-              id, resource_type, resource_id, principal_type, principal_id, role,
-              expires_at, created_by, created_at
-            ) VALUES (?, 'flow', ?, ?, ?, ?, ?, ?, ?)
-            ON CONFLICT (resource_type, resource_id, principal_type, principal_id)
-            DO UPDATE SET role = excluded.role, expires_at = excluded.expires_at`)
-                        .bind(grant.id, grant.resourceId, principalType, principalId, grant.role, 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 resource_grants
-              WHERE resource_type = 'flow' AND resource_id = ?
-                AND principal_type = ? AND principal_id = ?`)
-                        .bind(input.actorId, input.idempotencyKey, grant.createdAt, grant.resourceId, principalType, principalId),
-                    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, grant.resourceId, JSON.stringify({ principalType, role: grant.role }), grant.createdAt),
-                ]);
-                const stored = await deps.db
-                    .prepare(`SELECT id, resource_id, principal_type, principal_id, role, expires_at,
-            created_by, created_at FROM resource_grants
-            WHERE resource_type = 'flow' AND resource_id = ?
-              AND principal_type = ? AND principal_id = ?`)
-                    .bind(grant.resourceId, principalType, principalId)
-                    .first();
-                if (!stored)
-                    throw new Error("Flow grant disappeared after upsert");
-                return mapGrant(stored);
-            }
-            catch (error) {
-                const replayed = await this.findIdempotent(input.actorId, "flows.share", input.idempotencyKey);
-                const row = replayed
-                    ? await deps.db
-                        .prepare(`SELECT id, resource_id, principal_type, principal_id, role, expires_at,
-                created_by, created_at FROM resource_grants WHERE id = ?`)
-                        .bind(replayed)
-                        .first()
-                    : null;
-                if (row)
-                    return mapGrant(row);
-                throw error;
-            }
-        },
-        async revokeGrant(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 resource_grants
-                WHERE id = ? AND resource_type = 'flow' AND resource_id = ?
-              ) THEN '1:' ELSE '0:' END) || ?, ?`)
-                        .bind(input.actorId, input.idempotencyKey, input.grantId, input.flowId, input.grantId, input.occurredAt),
-                    deps.db
-                        .prepare(`DELETE FROM resource_grants
-              WHERE id = ? AND resource_type = 'flow' AND resource_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.findIdempotentRevocation(input.actorId, input.idempotencyKey);
-                if (replayed === null)
-                    throw error;
-                return replayed;
-            }
-            return (await this.findIdempotentRevocation(input.actorId, input.idempotencyKey)) ?? false;
-        },
         async insertRun(input) {
             const run = input.run;
             try {
@@ -439,9 +488,9 @@ export function createFlowRepository(deps) {
                     deps.db
                         .prepare(`INSERT INTO flow_runs (
               id, flow_id, version_id, status, current_node_id, input_json, output_json,
-              error, initiated_by, 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.createdAt, run.updatedAt, run.completedAt),
+              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
@@ -470,13 +519,138 @@ export function createFlowRepository(deps) {
         },
         async getRunVisible(actor, runId) {
             const row = await deps.db
-                .prepare(`SELECT ${qualifiedRunColumns("run")} FROM flow_runs run
+                .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 —
+        // and so `flow_runs_flow_idx (flow_id, created_at DESC)` is the index that serves it.
+        //
+        // ⚠️ `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.
+        async listRunsVisible(actor, input) {
+            const page = input.cursor
+                ? {
+                    clause: "AND (run.created_at < ? OR (run.created_at = ? AND run.id < ?))",
+                    bindings: [input.cursor.createdAt, input.cursor.createdAt, input.cursor.id],
+                }
+                : { clause: "", bindings: [] };
+            const result = await deps.db
+                .prepare(`${subtreeCte}
+          SELECT ${qualifiedRunColumns("run")} FROM flow_runs run
+          JOIN flows flow ON flow.id = run.flow_id
+          WHERE run.flow_id = ? AND ${runVisible}
+            ${input.failedOnly ? "AND run.status = 'failed'" : ""}
+            ${page.clause}
+          ORDER BY run.created_at DESC, run.id DESC
+          LIMIT ?`)
+                .bind(...readableBindings(actor), input.flowId, ...runVisibleBindings(actor), ...page.bindings, 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
-          WHERE run.id = ? AND ${visible}`)
-                .bind(runId, ...accessBindings(actor, deps.now().toISOString()))
+          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,
+            }));
+        },
         async advanceRun(input) {
             const run = input.run;
             try {