@anchrd/intel-api 0.39.0 → 0.41.0

package/dist/adapters/cloudflare/cloudflare.js

@@ -10,6 +10,7 @@ import { createFlows } from "../../flows/flows.js";
 import { createIndexing, PermanentIndexingError } from "../../indexing/indexing.js";
 import { createIntel } from "../../intel/intel.js";
 import { createNodes } from "../../nodes/nodes.js";
+import { createPrompts } from "../../prompts/prompts.js";
 import { bearer } from "../../shared/gate-authorization/gate-authorization.js";
 import { IntelError } from "../../shared/intel-error/intel-error.js";
 import { sha256Hex } from "../../shared/sha256/sha256.js";
@@ -22,6 +23,7 @@ import { createFeedRepository } from "../db/db-feed.js";
 import { createFlowRepository } from "../db/db-flows.js";
 import { createNodeIndexRepository } from "../db/db-indexing.js";
 import { createOAuthClientStore } from "../db/db-oauth.js";
+import { createPromptRepository } from "../db/db-prompts.js";
 import { createDocumentConverter } from "../document-converter/document-converter.js";
 import { createFlowRuntime } from "../flow-runtime/flow-runtime.js";
 import { createIndexQueue, IndexMessage } from "../index-queue/index-queue.js";
@@ -265,6 +267,20 @@ export default {
             tools,
             audit: createAudit({ audit: auditRepository }),
             feed: createFeed({ feed: feedRepository }),
+            /**
+             * The slash-command catalogue (#775). It reads its own rows through its own repository and
+             * borrows exactly one thing from the node service: reading one document, with the
+             * authorization walk that service already performs. A second reader into R2 here would be a
+             * second place for that ACL to be applied, and the one that gets it wrong is the one nobody
+             * looks at.
+             */
+            prompts: createPrompts({
+                repository: createPromptRepository({ db: env.DB, now }),
+                // ⚠️ Handed on whole, and nothing is decided here. Turning a stored version into readable
+                // text is business behaviour, and this shell maps bindings — it does not get to know what a
+                // BlockNote payload is.
+                readDocument: async (actor, nodeId) => await nodes.get(actor, nodeId),
+            }),
             boards: createBoards({
                 boards: boardRepository,
                 nodes,

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

@@ -2,6 +2,7 @@ import { Flow, FlowGraph, FlowVersion, } from "@anchrd/intel-contract/flow";
 import { FlowRun } from "@anchrd/intel-contract/flow-run";
 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",
@@ -13,6 +14,7 @@ const flowColumnNames = [
     "created_at",
     "updated_at",
     "archived_at",
+    "prompt_name",
 ];
 const flowColumns = flowColumnNames.join(", ");
 const runColumnNames = [
@@ -53,6 +55,7 @@ function mapFlow(row) {
         createdAt: row.created_at,
         updatedAt: row.updated_at,
         archivedAt: row.archived_at,
+        promptName: row.prompt_name,
     });
 }
 function mapVersion(row) {
@@ -74,6 +77,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,
@@ -863,23 +907,61 @@ export function createFlowRepository(deps) {
                 .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 = ?, updated_at = ?
+                        .prepare(`UPDATE flows SET published_version_id = ?${nameAssignment}, updated_at = ?
               WHERE id = ? AND EXISTS (
                 SELECT 1 FROM flow_versions WHERE id = ? AND flow_id = ?
-              )`)
-                        .bind(input.versionId, input.occurredAt, input.flowId, input.versionId, input.flowId),
+              )
+              ${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 = ?
+              SELECT 1 FROM flows WHERE id = ? AND published_version_id = ? ${nameEcho}
             )`)
-                        .bind(input.actorId, input.idempotencyKey, input.versionId, input.occurredAt, input.flowId, input.versionId),
+                        .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
@@ -896,7 +978,22 @@ export function createFlowRepository(deps) {
                 if (!replayed)
                     throw error;
             }
-            return ((await this.findIdempotent(input.actorId, "flows.publish", input.idempotencyKey)) !== null);
+            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
@@ -983,29 +1080,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");