@anchrd/intel-api 0.39.0 → 0.40.0

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

@@ -28,6 +28,34 @@ import type { D1Database } from "./db.types.js";
  * row-value comparison here: "later timestamp, OR same timestamp and larger id".
  */
 export declare const auditFeedQuery: string;
+/**
+ * The same journal about FLOWS (#774).
+ *
+ * ⚠️ **A separate statement rather than a widened one, and that is the decision.** The three kinds
+ * do not differ in a value but in the QUESTION they ask: a node is visible when the node is in
+ * `allowed`, a flow when its folder is or it carries a grant of its own, a run one join further on.
+ * Written as one query with three branches, every caller would pay all three joins to read one
+ * kind — and `audit_list` names exactly one kind per call, so there is nothing to gain from it.
+ * The feed is the opposite case and rightly written the opposite way: it reads all three at once.
+ *
+ * ⚠️ **`INNER JOIN flows`, so an event about a purged flow is unreachable** — the same shape the
+ * node half has carried since #620, and for the same reason: at a deleted row there is nothing left
+ * against which a claim to have been allowed to read it could be tested. Hiding is the safe
+ * direction. The feed differs deliberately (it falls back on the purge's own metadata) because a
+ * card that says "deleted" is the whole point there; a journal consumer gets the deletion through
+ * the parent folder's events instead.
+ */
+export declare const auditFlowFeedQuery: string;
+/**
+ * And about RUNS, which is the walk one join further: run → flow → folder (#774).
+ *
+ * ⚠️ The alias is `run_flow` and it is handed to `flowInSubtreeOver` explicitly. Until #767 that
+ * guard had `flow` hard-wired, and against a flow reached through a second join every branch but
+ * the folder one compared NULL — a flow somebody OWNS but that hangs at the top level answered "not
+ * visible" to its own owner. It fails in the safe direction, which is exactly why it needs a test
+ * that seeds a run of a flow at the ROOT rather than in a folder.
+ */
+export declare const auditRunFeedQuery: string;
 export declare function createAuditRepository(deps: {
     db: D1Database;
     now(): Date;

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

@@ -1,5 +1,5 @@
-import { subtreeBindings, subtreeCte } from "./db-grants.js";
-function mapEvent(row) {
+import { flowInSubtree, flowInSubtreeBindings, flowInSubtreeOver, subtreeBindings, subtreeCte, } from "./db-grants.js";
+function mapEvent(row, resourceType) {
     let metadata = {};
     // The column is `NOT NULL DEFAULT '{}'`, but it is written by 11 call sites over
     // `JSON.stringify` on whatever each one had at hand. A row that cannot be parsed, or that parses
@@ -20,7 +20,10 @@ function mapEvent(row) {
         id: row.id,
         actorId: row.actor_id,
         action: row.action,
-        resourceType: "node",
+        // ⚠️ Taken from the QUESTION, not from the row. Each statement names exactly one
+        // `resource_type` in its `WHERE`, so the answer cannot carry another — and reading the column
+        // back would add a second truth about the same thing (#774).
+        resourceType,
         resourceId: row.resource_id,
         metadata,
         occurredAt: row.occurred_at,
@@ -65,25 +68,83 @@ export const auditFeedQuery = `${subtreeCte}
       )
     ORDER BY e.occurred_at ASC, e.id ASC
     LIMIT ?`;
+/**
+ * The same journal about FLOWS (#774).
+ *
+ * ⚠️ **A separate statement rather than a widened one, and that is the decision.** The three kinds
+ * do not differ in a value but in the QUESTION they ask: a node is visible when the node is in
+ * `allowed`, a flow when its folder is or it carries a grant of its own, a run one join further on.
+ * Written as one query with three branches, every caller would pay all three joins to read one
+ * kind — and `audit_list` names exactly one kind per call, so there is nothing to gain from it.
+ * The feed is the opposite case and rightly written the opposite way: it reads all three at once.
+ *
+ * ⚠️ **`INNER JOIN flows`, so an event about a purged flow is unreachable** — the same shape the
+ * node half has carried since #620, and for the same reason: at a deleted row there is nothing left
+ * against which a claim to have been allowed to read it could be tested. Hiding is the safe
+ * direction. The feed differs deliberately (it falls back on the purge's own metadata) because a
+ * card that says "deleted" is the whole point there; a journal consumer gets the deletion through
+ * the parent folder's events instead.
+ */
+export const auditFlowFeedQuery = `${subtreeCte}
+    SELECT e.id, e.actor_id, e.action, e.resource_id, e.metadata_json, e.occurred_at
+    FROM audit_events e
+    JOIN flows flow ON flow.id = e.resource_id
+    WHERE e.resource_type = 'flow'
+      AND ${flowInSubtree}
+      AND (
+        ? IS NULL
+        OR e.occurred_at > ?
+        OR (e.occurred_at = ? AND e.id > ?)
+      )
+    ORDER BY e.occurred_at ASC, e.id ASC
+    LIMIT ?`;
+/**
+ * And about RUNS, which is the walk one join further: run → flow → folder (#774).
+ *
+ * ⚠️ The alias is `run_flow` and it is handed to `flowInSubtreeOver` explicitly. Until #767 that
+ * guard had `flow` hard-wired, and against a flow reached through a second join every branch but
+ * the folder one compared NULL — a flow somebody OWNS but that hangs at the top level answered "not
+ * visible" to its own owner. It fails in the safe direction, which is exactly why it needs a test
+ * that seeds a run of a flow at the ROOT rather than in a folder.
+ */
+export const auditRunFeedQuery = `${subtreeCte}
+    SELECT e.id, e.actor_id, e.action, e.resource_id, e.metadata_json, e.occurred_at
+    FROM audit_events e
+    JOIN flow_runs run ON run.id = e.resource_id
+    JOIN flows run_flow ON run_flow.id = run.flow_id
+    WHERE e.resource_type = 'flow-run'
+      AND ${flowInSubtreeOver("run_flow.parent_id", "run_flow")}
+      AND (
+        ? IS NULL
+        OR e.occurred_at > ?
+        OR (e.occurred_at = ? AND e.id > ?)
+      )
+    ORDER BY e.occurred_at ASC, e.id ASC
+    LIMIT ?`;
 export function createAuditRepository(deps) {
-    const page = auditFeedQuery;
     return {
-        async listNodeEvents(actor, query) {
+        async listEvents(actor, query) {
             const after = query.after ?? null;
-            const bindings = [
-                ...subtreeBindings(actor, "read", deps.now().toISOString()),
-                after === null ? null : after.occurredAt,
-                after === null ? null : after.occurredAt,
-                after === null ? null : after.occurredAt,
-                after === null ? null : after.id,
-                query.limit,
-            ];
+            const now = deps.now().toISOString();
+            // ⚠️ One reading of the clock for the whole call. Both guards measure grant expiry against
+            // it, and two `now()` readings could straddle the moment a grant runs out.
+            const guard = query.resourceType === "node"
+                ? { page: auditFeedQuery, bindings: subtreeBindings(actor, "read", now) }
+                : {
+                    page: query.resourceType === "flow" ? auditFlowFeedQuery : auditRunFeedQuery,
+                    // The flow walks need the CTE's bindings and the guard's, in that order — the guard
+                    // is written into the statement after the CTE.
+                    bindings: [
+                        ...subtreeBindings(actor, "read", now),
+                        ...flowInSubtreeBindings(actor, "read", now),
+                    ],
+                };
             const result = await deps.db
-                .prepare(page)
-                .bind(...bindings)
+                .prepare(guard.page)
+                .bind(...guard.bindings, after === null ? null : after.occurredAt, after === null ? null : after.occurredAt, after === null ? null : after.occurredAt, after === null ? null : after.id, query.limit)
                 .all();
             const rows = result.results ?? [];
-            return { events: rows.map(mapEvent) };
+            return { events: rows.map((row) => mapEvent(row, query.resourceType)) };
         },
     };
 }

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

@@ -1,12 +1,19 @@
-import { FeedAction, feedKindOf, } from "@anchrd/intel-contract/feed";
+import { FeedAction, feedResourceTypeOf, } from "@anchrd/intel-contract/feed";
 import { flowInSubtreeBindings, flowInSubtreeOver, subtreeBindings, subtreeCte, } from "./db-grants.js";
-// The two kinds of resource the feed reads, split out of the one action list so the SQL can name
+// The three kinds of resource the feed reads, split out of the one action list so the SQL can name
 // each side by itself. Derived from the contract rather than written again here: one list that has
 // to agree with another is one list too many.
-const NODE_ACTIONS = FeedAction.options.filter((action) => feedKindOf(action) === "node");
-const FLOW_ACTIONS = FeedAction.options.filter((action) => feedKindOf(action) === "flow");
+const NODE_ACTIONS = FeedAction.options.filter((action) => feedResourceTypeOf(action) === "node");
+const FLOW_ACTIONS = FeedAction.options.filter((action) => feedResourceTypeOf(action) === "flow");
+// ⚠️ The third kind (#767). These are cards ABOUT a flow — `feedKindOf` says `flow` — written as
+// rows about a RUN, so they are found under their own `resource_type` and nowhere near the two
+// lists above. Splitting on `feedResourceTypeOf` rather than on `feedKindOf` is what keeps them out
+// of the flow branch, where `flow.id = e.resource_id` would never match a run id and every one of
+// them would vanish without a word.
+const RUN_ACTIONS = FeedAction.options.filter((action) => feedResourceTypeOf(action) === "flow-run");
 const NODE_PLACEHOLDERS = NODE_ACTIONS.map(() => "?").join(", ");
 const FLOW_PLACEHOLDERS = FLOW_ACTIONS.map(() => "?").join(", ");
+const RUN_PLACEHOLDERS = RUN_ACTIONS.map(() => "?").join(", ");
 function parseMetadata(raw) {
     // The column is `NOT NULL DEFAULT '{}'` but it is written by eleven call sites over
     // `JSON.stringify` on whatever each had at hand. A row that cannot be parsed must not take the
@@ -56,9 +63,10 @@ function parseMetadata(raw) {
  * the whole table, and that is invisible on the first pages and only hurts far down.
  *
  * ⚠️ **The index that carries it is `audit_events_time_idx`, NOT `audit_events_feed_idx`** (#763).
- * The feed reads two kinds at once, and the older index leads with `resource_type`; under
- * `IN ('node', 'flow')` — or, as written here, under two branches joined by `OR` — that column
- * stops being an equality prefix, and the ordering falls off it. Measured before `0026` existed:
+ * The feed reads all three kinds at once (#767), and the older index leads with `resource_type`;
+ * under `IN ('node', 'flow', 'flow-run')` — or, as written here, under three branches joined by
+ * `OR` — that column stops being an equality prefix, and the ordering falls off it. Measured before
+ * `0026` existed:
  * `SEARCH e USING INDEX audit_events_feed_idx (resource_type=?)` followed by
  * `USE TEMP B-TREE FOR ORDER BY`. The older index stays for `audit_list`, which names one kind.
  *
@@ -66,14 +74,15 @@ function parseMetadata(raw) {
  * the term may not drive an index. Without it the planner sees two indexable `OR` branches, picks
  * `MULTI-INDEX OR` over the OLD index — one search per branch, both on `resource_type=?` — and buys
  * the filtering back at the price of the ordering: `USE TEMP B-TREE FOR ORDER BY` returns, over the
- * whole table. Measured both ways. Filtering on kind is cheap here (two values out of three);
- * sorting the journal is not.
+ * whole table. Measured both ways. Filtering on kind is cheap here; sorting the journal is not.
  *
- * ⚠️ **The two halves ask two DIFFERENT authorization questions, and neither may stand in for the
- * other.** A node is visible when the node itself is in `allowed`; a flow when its FOLDER is, or
+ * ⚠️ **The three branches ask three DIFFERENT authorization questions, and none may stand in for
+ * another.** A node is visible when the node itself is in `allowed`; a flow when its FOLDER is, or
  * when it carries a grant of its own — flows hang in the tree but have nothing beneath them, so
  * `flowInSubtree` is the rule and `allowed.id = flow.id` would answer about a node that does not
- * exist. Both halves fall back on the metadata `parentId` for the one event whose row is gone.
+ * exist. A RUN is visible when the flow it belongs to is, which takes one join more to reach
+ * (#767). The first two fall back on the metadata `parentId` for the one event whose row is gone;
+ * the third deliberately does not — see `RUN_PARENT`.
  */
 const FLOW_PARENT = "COALESCE(flow.parent_id, json_extract(e.metadata_json, '$.parentId'))";
 // ⚠️ A card whose title is NULL names nothing, and `FeedEvent.resourceTitle` refuses it — the reader
@@ -86,17 +95,46 @@ const FLOW_PARENT = "COALESCE(flow.parent_id, json_extract(e.metadata_json, '$.p
 // ⚠️ The node half cannot reach this state, and that asymmetry is the whole reason it was missed:
 // there the check is `COALESCE(n.id, …) IN (SELECT id FROM allowed)`, a join against real rows with
 // no admin short-circuit in front of it, so a deleted node's events drop out on their own.
-const HAS_TITLE = "COALESCE(n.title, flow.title, json_extract(e.metadata_json, '$.title')) IS NOT NULL";
+const HAS_TITLE = "COALESCE(n.title, flow.title, run_flow.title, json_extract(e.metadata_json, '$.title')) IS NOT NULL";
 const NODE_PARENT = "COALESCE(n.id, json_extract(e.metadata_json, '$.parentId'))";
+/**
+ * The third walk (#767): the run's flow, and that flow's folder.
+ *
+ * ⚠️ There is **no metadata fallback here**, and that is the decision rather than an omission. The
+ * other two kinds fall back on a `parentId` the purge wrote, because a purged node or flow still
+ * has events worth reading. A run has no purge of its own — it disappears when its flow is purged,
+ * and `flows.purge` already carries that news as its own card. An event whose run row is gone
+ * therefore drops out on `HAS_TITLE`, which is the safe direction: the alternative is a card naming
+ * a flow nobody can check the reader was allowed to see.
+ */
+const RUN_PARENT = "run_flow.parent_id";
+/**
+ * What a run card POINTS at: the flow, never the run (#767).
+ *
+ * Everything else about such a card already names the flow — its title, its path — and the surface
+ * turns `resourceId` into a link through `feedKindOf`, which answers `flow` for these two actions.
+ * Left as the run id it would navigate to `/flows?select=<run id>`, where nothing matches: an empty
+ * pane with no error, which `feed.tsx` names the worst of the three possible outcomes. There is no
+ * route onto a single run, so the flow is the honest target rather than a second-best one.
+ *
+ * ⚠️ `COALESCE` and not a `CASE` on the resource type: `run` is only joined for `flow-run` rows, so
+ * it is NULL everywhere else and every other card keeps its own id untouched.
+ */
+const RUN_TARGET = "COALESCE(run.flow_id, e.resource_id)";
 export const feedPageQuery = `${subtreeCte}
-    SELECT e.id, e.actor_id, e.action, e.resource_id,
-           COALESCE(n.title, flow.title, json_extract(e.metadata_json, '$.title')) AS resource_title,
-           COALESCE(n.parent_id, flow.parent_id, json_extract(e.metadata_json, '$.parentId'))
+    SELECT e.id, e.actor_id, e.action,
+           ${RUN_TARGET} AS resource_id,
+           COALESCE(n.title, flow.title, run_flow.title,
+                    json_extract(e.metadata_json, '$.title')) AS resource_title,
+           COALESCE(n.parent_id, flow.parent_id, run_flow.parent_id,
+                    json_extract(e.metadata_json, '$.parentId'))
              AS resource_parent_id,
            e.metadata_json, e.occurred_at
     FROM audit_events e
     LEFT JOIN nodes n ON n.id = e.resource_id AND e.resource_type = 'node'
     LEFT JOIN flows flow ON flow.id = e.resource_id AND e.resource_type = 'flow'
+    LEFT JOIN flow_runs run ON run.id = e.resource_id AND e.resource_type = 'flow-run'
+    LEFT JOIN flows run_flow ON run_flow.id = run.flow_id
     WHERE (
         (
           +e.resource_type = 'node'
@@ -108,6 +146,11 @@ export const feedPageQuery = `${subtreeCte}
           AND e.action IN (${FLOW_PLACEHOLDERS})
           AND ${flowInSubtreeOver(FLOW_PARENT)}
         )
+        OR (
+          +e.resource_type = 'flow-run'
+          AND e.action IN (${RUN_PLACEHOLDERS})
+          AND ${flowInSubtreeOver(RUN_PARENT, "run_flow")}
+        )
       )
       AND ${HAS_TITLE}
       AND (? IS NULL OR e.actor_id = ?)
@@ -191,7 +234,12 @@ export function createFeedRepository(deps) {
             const now = deps.now().toISOString();
             const page = await deps.db
                 .prepare(feedPageQuery)
-                .bind(...subtreeBindings(actor, "read", now), ...NODE_ACTIONS, ...FLOW_ACTIONS, ...flowInSubtreeBindings(actor, "read", now), query.actor, query.actor, before === null ? null : before.occurredAt, before === null ? null : before.occurredAt, before === null ? null : before.occurredAt, before === null ? null : before.id, query.limit)
+                .bind(...subtreeBindings(actor, "read", now), ...NODE_ACTIONS, ...FLOW_ACTIONS, ...flowInSubtreeBindings(actor, "read", now), ...RUN_ACTIONS, 
+            // ⚠️ A SECOND set of bindings for the same guard: `flowInSubtreeOver` writes its
+            // placeholders out again for the run branch, and positional binding counts every one of
+            // them. Reusing the first set would shift every parameter after it by the width of the
+            // guard — which is not a type error and not a syntax error, only wrong answers.
+            ...flowInSubtreeBindings(actor, "read", now), query.actor, query.actor, before === null ? null : before.occurredAt, before === null ? null : before.occurredAt, before === null ? null : before.occurredAt, before === null ? null : before.id, query.limit)
                 .all();
             const rows = page.results ?? [];
             if (rows.length === 0)

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

@@ -1,5 +1,41 @@
 import type { FlowRepository } from "../../flows/flows.types.js";
 import type { D1Database } from "./db.types.js";
+/**
+ * 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 declare function flowRunsPageQuery(shape: {
+    scoped: boolean;
+    failedOnly: boolean;
+    paged: boolean;
+}): string;
 export declare function createFlowRepository(deps: {
     db: D1Database;
     now(): Date;

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

@@ -74,6 +74,47 @@ function mapVersion(row) {
 // 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,
@@ -983,29 +1024,28 @@ export function createFlowRepository(deps) {
                 .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.
+        // 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 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 scoped = input.flowId !== null;
             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)
+                .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);
         },

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

@@ -115,6 +115,19 @@ export declare function flowVerbBindings(flowId: string, actor: GrantActor, verb
  * expressions with similar names are two different questions, and the one that goes stale is the
  * copy.
  */
-export declare function flowInSubtreeOver(parentExpression: string): string;
+/**
+ * ⚠️ **The ALIAS is a parameter too, since #767, and leaving it hard-wired was a real fault rather
+ * than an inelegance.** The feed's third branch asks about a flow reached through its RUN, so the
+ * flow sits under a second join (`run_flow`) while `flow` is NULL on that row. Against the
+ * hard-wired name the owner branch and the direct-grant branch both compared NULL — so a flow
+ * somebody OWNS but that hangs at the top level, with no folder above it to carry a grant, answered
+ * "not visible" to its own owner.
+ *
+ * ⚠️ It fails in the safe direction, which is exactly what made it worth a test rather than a
+ * comment: nothing leaks, a row is only ever missing. A flow filed in a readable FOLDER answers
+ * correctly through the third branch, so every test with a folder is green either way — and the two
+ * tests that caught it are the ones that seed a flow at the root.
+ */
+export declare function flowInSubtreeOver(parentExpression: string, flowAlias?: string): string;
 export declare const flowInSubtree: string;
 export declare function flowInSubtreeBindings(actor: GrantActor, verb: ResourceVerb, now: string): unknown[];

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

@@ -242,12 +242,25 @@ export function flowVerbBindings(flowId, actor, verb, now) {
  * expressions with similar names are two different questions, and the one that goes stale is the
  * copy.
  */
-export function flowInSubtreeOver(parentExpression) {
+/**
+ * ⚠️ **The ALIAS is a parameter too, since #767, and leaving it hard-wired was a real fault rather
+ * than an inelegance.** The feed's third branch asks about a flow reached through its RUN, so the
+ * flow sits under a second join (`run_flow`) while `flow` is NULL on that row. Against the
+ * hard-wired name the owner branch and the direct-grant branch both compared NULL — so a flow
+ * somebody OWNS but that hangs at the top level, with no folder above it to carry a grant, answered
+ * "not visible" to its own owner.
+ *
+ * ⚠️ It fails in the safe direction, which is exactly what made it worth a test rather than a
+ * comment: nothing leaks, a row is only ever missing. A flow filed in a readable FOLDER answers
+ * correctly through the third branch, so every test with a folder is green either way — and the two
+ * tests that caught it are the ones that seed a flow at the root.
+ */
+export function flowInSubtreeOver(parentExpression, flowAlias = "flow") {
     return `(
   ? = 1
-  OR flow.owner_id = ?
+  OR ${flowAlias}.owner_id = ?
   OR ${parentExpression} IN (SELECT id FROM allowed)
-  OR ${flowGrantExists("flow.id")}
+  OR ${flowGrantExists(`${flowAlias}.id`)}
 )`;
 }
 export const flowInSubtree = flowInSubtreeOver("flow.parent_id");

package/dist/audit/audit.js

@@ -47,25 +47,40 @@ function decodeCursor(cursor) {
 export function createAudit(deps) {
     return {
         async list(actor, input) {
-            // `resourceType` is validated by the contract enum before it reaches here; the value is
-            // named again rather than assumed, so adding `flow` to the enum later cannot silently route
-            // flow events through the node visibility walk.
-            if (input.resourceType !== "node") {
-                throw new IntelError(400, "unsupported_resource_type", "Only node events can be listed today. Flow and flow-run events need their own visibility check and are refused rather than omitted, so that an empty answer never has to mean two different things.");
-            }
             const after = input.after === undefined ? null : decodeCursor(input.after);
-            // One more than asked for, so "is there another page" is answered by the same authorized
+            // ⚠️ The refusal that stood here until #774 is GONE, and it was doing real work: it named
+            // `node` explicitly so that widening the contract enum could not silently route flow events
+            // through the node visibility walk. What replaces it is not trust but a repository that takes
+            // the kind as an argument and picks a statement per kind — each with its own walk, none able
+            // to answer for another. Adding a fourth kind to the enum is now a type error there rather
+            // than a wrong answer here, which is the stronger version of the same guard.
+            //
+            // One more row than asked for, so "is there another page" is answered by the same authorized
             // query instead of a second one that could disagree with it.
-            const page = await deps.audit.listNodeEvents(actor, { after, limit: input.limit + 1 });
+            const page = await deps.audit.listEvents(actor, {
+                after,
+                resourceType: input.resourceType,
+                limit: input.limit + 1,
+            });
             const hasMore = page.events.length > input.limit;
             const events = hasMore ? page.events.slice(0, input.limit) : page.events;
             const last = events.at(-1);
             return {
                 events,
-                // ⚠️ The cursor is the LAST DELIVERED row, never the probe row that was dropped. Taking it
-                // from the probe would skip exactly one event per page — the classic off-by-one that shows
-                // up as a lead nobody contacted, not as an error.
-                nextCursor: hasMore && last !== undefined ? encodeCursor(last) : null,
+                /**
+                 * ⚠️ The cursor is the LAST DELIVERED row, never the probe row that was dropped. Taking it
+                 * from the probe would skip exactly one event per page — the classic off-by-one that shows
+                 * up as a lead nobody contacted, not as an error.
+                 *
+                 * ⚠️ **And it is returned whenever rows were delivered, not only when more follows.** It
+                 * used to carry `hasMore &&`, which meant a reader catching up received fifty events and no
+                 * position: it started over on its next run and would have delivered the same fifty for
+                 * ever. A reader paging through never sees it, because it always asks for a full page —
+                 * which is why this survived until `anchrd/signals` read the journal for real (`#793`).
+                 */
+                nextCursor: last === undefined ? null : encodeCursor(last),
+                // Whether another page may follow. Its own field, because it is its own question.
+                hasMore,
             };
         },
     };

package/dist/audit/audit.types.d.ts

@@ -1,4 +1,4 @@
-import type { AuditEvent, AuditListRequest, AuditListResponse } from "@anchrd/intel-contract/audit";
+import type { AuditEvent, AuditListRequest, AuditListResponse, AuditResourceType } from "@anchrd/intel-contract/audit";
 import type { Actor } from "../nodes/nodes.types.js";
 export interface AuditPosition {
     occurredAt: string;
@@ -6,13 +6,14 @@ export interface AuditPosition {
 }
 export interface AuditQuery {
     after: AuditPosition | null;
+    resourceType: AuditResourceType;
     limit: number;
 }
 export interface AuditPage {
     events: AuditEvent[];
 }
 export interface AuditRepository {
-    listNodeEvents(actor: Actor, query: AuditQuery): Promise<AuditPage>;
+    listEvents(actor: Actor, query: AuditQuery): Promise<AuditPage>;
 }
 export interface AuditDeps {
     audit: AuditRepository;

package/dist/flows/flows.js

@@ -1776,11 +1776,16 @@ export function createFlows(deps) {
         async listRuns(actor, input) {
             // The history of a flow that has since been archived stays readable — the runs happened, and
             // archiving is about what may start next (#112).
-            const flow = await requireStartedFlow(actor, input.flowId);
+            //
+            // ⚠️ Without a flow there is nothing to require, and skipping the check does NOT widen the
+            // answer (#774): `requireStartedFlow` decides whether one named flow exists FOR this actor,
+            // while which runs appear is decided per row in the repository — their own, plus every run of
+            // a flow they may read. Asking it for a flow nobody named would mean inventing one.
+            const flowId = input.flowId === null ? null : (await requireStartedFlow(actor, input.flowId)).id;
             // One row beyond the page: it answers "is there more" and is dropped rather than shown, so a
             // count over the whole table is never needed to draw a "next" affordance.
             const rows = await deps.repository.listRunsVisible(actor, {
-                flowId: flow.id,
+                flowId,
                 failedOnly: input.failedOnly,
                 limit: input.limit + 1,
                 cursor: decodeCursor(input.cursor),

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

@@ -13,7 +13,7 @@ export interface FlowRunChainEntry {
     currentNodeId: string | null;
 }
 export interface ListRunsQuery {
-    flowId: string;
+    flowId: string | null;
     failedOnly: boolean;
     limit: number;
     cursor: {

package/dist/http/http.js

@@ -207,16 +207,25 @@ export function createHttp(deps) {
         const input = GetNodeInput.parse({ nodeId: context.req.param("nodeId") });
         return zipResponse(await deps.bundle.exportSubtree(asBundleActor(auth), input.nodeId));
     });
-    // The change journal, read forward from a stable position (#620). `nodes/read` and nothing new:
-    // an audit row about a node says the same thing the node says, so a second capability would be a
-    // second answer to one question. The per-row check is the service's, and it is the same tree walk
-    // the node reads go through.
+    // The change journal, read forward from a stable position (#620).
+    //
+    // ⚠️ **The capability follows the KIND asked for** (#774). An audit row says the same thing its
+    // resource says, so the journal asks what reading that resource asks: `nodes/read` for `node`,
+    // `flows/read` for `flow` and `flow-run` — which is what every other flow-delivering route in
+    // this file requires. Until the enum was widened one capability covered the one kind there was;
+    // leaving it at `nodes/read` afterwards would have dropped the first of the three checks for
+    // exactly the two kinds this ticket opened, and left the Intel ACL as the only filter.
+    //
+    // ⚠️ The parse therefore runs BEFORE the capability check, which is the one place in this file
+    // where it does. That is not a loosening of "capability first, so a refusal costs no storage
+    // read": parsing touches the query string and nothing else, and the kind cannot be known any
+    // earlier than this. What it costs is that a malformed `resourceType` answers 400 rather than
+    // 403 — a sentence about the caller's own parameter, which names nothing of Intel's.
     //
     // ⚠️ GET with the cursor in the query string, because the verb is one of the four in the grammar
     // and the method carries it. `limit` arrives as a string and is coerced here — the contract
     // wants a number, and a query string has none.
     app.get("/audit", async (context) => {
-        const auth = requireCapability(context, "nodes", "read");
         const limit = context.req.query("limit");
         const after = context.req.query("after");
         const input = AuditListRequest.parse({
@@ -224,10 +233,19 @@ export function createHttp(deps) {
             ...(after === undefined ? {} : { after }),
             ...(limit === undefined ? {} : { limit: Number(limit) }),
         });
+        const auth = requireCapability(context, input.resourceType === "node" ? "nodes" : "flows", "read");
         return context.json(await deps.audit.list(asActor(auth), input));
     });
     // The same journal read the other way round: newest first, for a person rather than for a
-    // consumer catching up (#740). `nodes/read` and nothing new, for the reason `/audit` gives.
+    // consumer catching up (#740).
+    //
+    // ⚠️ `nodes/read` for the whole answer, and here that CANNOT follow the kind the way `/audit`
+    // above does: one page mixes node and flow cards on purpose, so there is no single kind to pick a
+    // capability from. It has been that way since flow cards existed and #767 only added two actions
+    // to them, so nothing about it is new — but it does mean somebody holding `nodes/read` without
+    // `flows/read` still sees flow activity here, filtered by the Intel ACL alone. Narrowing it means
+    // filtering cards by capability inside the feed service, which is a change to the answer rather
+    // than to the door: #790.
     //
     // ⚠️ A SECOND door and not an option on `/audit`. That one is the contract `anchrd/signals` will
     // build on, cursor and direction included; a shared signature would put both readers on one
@@ -736,6 +754,28 @@ export function createHttp(deps) {
         });
         return context.json(await deps.flows.listRuns(asFlowActor(auth), input));
     });
+    /**
+     * The same list across every flow (#774) — "did anything run", which used to take one call per
+     * flow and therefore went unasked.
+     *
+     * ⚠️ It sits at the root beside the other three run routes rather than under a flow, and the
+     * reason is the one already written for them in `packages/api/CLAUDE.md`: reading, cancelling and
+     * completing a run do not need the flow, and a run outlives it. Naming no flow is exactly that
+     * case. One tool answers both addresses — `flow_run_list` with `flowId: null` — which is the same
+     * many-to-one the attachment routes have.
+     */
+    app.get("/flow-runs", async (context) => {
+        const auth = requireCapability(context, "flows", "read");
+        const url = new URL(context.req.url);
+        requireKnownQuery(url, ["failedOnly", "limit", "cursor"]);
+        const input = ListFlowRunsInput.parse({
+            flowId: null,
+            ...(url.searchParams.has("failedOnly") ? { failedOnly: true } : {}),
+            ...(url.searchParams.has("limit") ? { limit: Number(url.searchParams.get("limit")) } : {}),
+            ...(url.searchParams.has("cursor") ? { cursor: url.searchParams.get("cursor") } : {}),
+        });
+        return context.json(await deps.flows.listRuns(asFlowActor(auth), input));
+    });
     app.get("/flow-runs/:runId", async (context) => {
         const auth = requireCapability(context, "flows", "read");
         const input = GetFlowRunInput.parse({ runId: context.req.param("runId") });

package/dist/mcp/mcp.js

@@ -158,15 +158,46 @@ export async function handleMcp(request, deps) {
         email: deps.authorization.identity.email,
         name: deps.authorization.identity.name ?? null,
     }));
+    // The change journal, read forward from a stable position (#620). It is what makes Intel the
+    // simplest of all signal sources: a consumer keeps its own cursor and asks what happened since,
+    // and Intel never learns that the consumer exists. That is the D24 test passed rather than
+    // argued — remove every reader and nothing piles up here.
+    //
+    // ⚠️ **The capability follows the KIND asked for** (#774), which is why this tool stands outside
+    // both capability blocks rather than inside one. An audit row says the same thing its resource
+    // says, so the journal asks what reading that resource asks — `nodes/read` for `node`,
+    // `flows/read` for `flow` and `flow-run`. A capability of its own would be a second answer to one
+    // question and the two would drift; `nodes/read` for all three would drop the first of the three
+    // checks for exactly the two kinds #774 opened.
+    //
+    // ⚠️ **Offered on EITHER capability, decided per call.** Registration is per connection and the
+    // kind arrives per call, so the two cannot be the same gate. Holding one of the two is what makes
+    // the tool worth listing at all; which of the three journals it then answers is the handler's
+    // question. Same shape, same order, same refusal as `GET /audit` — one business layer, three thin
+    // surfaces.
+    if (permits(deps.authorization, "nodes", "read") ||
+        permits(deps.authorization, "flows", "read")) {
+        server.registerTool("audit_list", {
+            title: "List change events",
+            description: "Read the change journal forward from a stable position: what happened to the resources you may read, oldest first. `resourceType` picks which of the three journals to read — `node`, `flow` or `flow-run` — and each has its own cursor; do not carry one over to another. Pass `nextCursor` back as `after` to continue where you stopped — it says WHERE YOU GOT TO and comes back on the last page as well. Whether another page may follow is `hasMore`; a null `nextCursor` means nothing was returned, not that you have caught up. Events about permanently deleted nodes and flows are never returned, to anybody.",
+            inputSchema: AuditListRequest,
+            annotations: {
+                title: "List change events",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => {
+            // ⚠️ Before the service, so a refusal costs no journal read. A 403 that arrived after the
+            // rows were read is a 403 that already read them.
+            if (!permits(deps.authorization, input.resourceType === "node" ? "nodes" : "flows", "read")) {
+                throw new IntelError(403, "permission_required", "Permission required");
+            }
+            return text(await deps.audit.list(actor, input));
+        });
+    }
     if (permits(deps.authorization, "nodes", "read")) {
-        // The change journal, read forward from a stable position (#620). It is what makes Intel the
-        // simplest of all signal sources: a consumer keeps its own cursor and asks what happened since,
-        // and Intel never learns that the consumer exists. That is the D24 test passed rather than
-        // argued — remove every reader and nothing piles up here.
-        //
-        // ⚠️ `nodes/read`, not a capability of its own. An audit row about a node says the same thing
-        // the node says; a second capability would be a second answer to one question, and the two
-        // would drift.
         // The board as one answer (#648). Four tools, not five: a move is an update of `status` and
         // `position`, and deleting a task is `node_archive` — nothing here removes a `nodes` row.
         server.registerTool("board_get", {
@@ -252,18 +283,6 @@ export async function handleMcp(request, deps) {
                 openWorldHint: false,
             },
         }, async (input) => text(await deps.boards.update(actor, input)));
-        server.registerTool("audit_list", {
-            title: "List change events",
-            description: "Read the change journal forward from a stable position: what happened to the nodes you may read, oldest first. Pass `nextCursor` back as `after` to continue where you stopped; a null `nextCursor` means you have caught up. Only node events can be listed — flow events need their own visibility check and are refused rather than left out. Events about permanently deleted nodes are never returned, to anybody.",
-            inputSchema: AuditListRequest,
-            annotations: {
-                title: "List change events",
-                readOnlyHint: true,
-                destructiveHint: false,
-                idempotentHint: true,
-                openWorldHint: false,
-            },
-        }, async (input) => text(await deps.audit.list(actor, input)));
         server.registerTool("feed_list", {
             title: "List recent activity",
             description: "Read the change journal backwards: what most recently happened to the nodes you may read, newest first, one entry per event. Each entry carries the node's current title and the folders above it, and only the folders you may open. Pass `nextCursor` back as `before` to keep going further into the past; a null `nextCursor` means you have reached the beginning. Pass `actor` to see one person's or one agent's work alone. This is the human-facing view — for catching up on everything in order, use audit_list, and do not mix the two cursors.",
@@ -929,7 +948,7 @@ export async function handleMcp(request, deps) {
         // whoever started it, and only their own runs are the calling user's to read out that way.
         server.registerTool("flow_run_list", {
             title: "List flow runs",
-            description: "List the runs of one flow, newest first, with status, start, duration, what triggered them, and for a failed run the step that ended it. Optionally only the failed ones. Runs the calling user may not see are absent, and a failure inside a called flow they may not see is named by the calling step alone.",
+            description: 'List flow runs, newest first, with status, start, duration, what triggered them, and for a failed run the step that ended it. Name a `flowId` for one flow, or leave it out for the runs of every flow you may read — which is the way to answer "did anything run at all" without knowing a flow first. Optionally only the failed ones. Runs the calling user may not see are absent, and a failure inside a called flow they may not see is named by the calling step alone.',
             inputSchema: ListFlowRunsInput,
             annotations: {
                 title: "List flow runs",

package/migrations/0027_the_runs_of_every_flow.sql

@@ -0,0 +1,27 @@
+-- `flow_run_list` may now be asked without a flow (#774): "did anything run at all", over every
+-- flow the caller may read. `flow_runs_flow_idx (flow_id, created_at DESC)` cannot serve that — it
+-- leads with `flow_id`, and without an equality on that column the ordering falls off the index and
+-- SQLite sorts the whole table instead.
+--
+-- ⚠️ Measured against the real `flowRunsPageQuery({ scoped: false })` before this file existed, on
+-- the same engine and the same schema:
+--
+--     SCAN run
+--     … | USE TEMP B-TREE FOR ORDER BY
+--
+-- That last line is a sorting pass over every run in the installation. It costs nothing while a
+-- customer has fifty runs and everything once an agent has been running for a month.
+--
+-- ⚠️ Both columns, in the order the cursor compares them, for the reason `0022` and `0026` give:
+-- two runs created in the same millisecond are not exotic, and without the tie-break on `id` a
+-- reader continuing on `created_at` alone skips the second one with no error and no log.
+--
+-- ⚠️ `DESC` on both, because this page is newest-first. An ASC index can be walked backwards by
+-- SQLite, but only as long as EVERY term agrees on the direction — matching the `ORDER BY` exactly
+-- is the one shape that keeps that true when a third term is added later.
+--
+-- ⚠️ This does NOT replace `flow_runs_flow_idx`. That one still serves the scoped page — the runs
+-- of ONE flow — which is the older and by far the more frequent question; dropping it would put a
+-- full scan into the call that has none today. Two questions, two shapes, two indexes.
+CREATE INDEX flow_runs_time_idx
+  ON flow_runs(created_at DESC, id DESC);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@anchrd/gate-sdk": "^0.26.0",
-    "@anchrd/intel-contract": "^0.31.0",
+    "@anchrd/intel-contract": "^0.32.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",