@anchrd/intel-api 0.23.0 → 0.25.0

package/README.md

@@ -75,12 +75,29 @@ values it stops with `Error: GATE_URL and GATE_SERVICE_KEY must be set.` before
 It declares five interfaces — `intel`, `nodes`, `flows`, `tools`, `mcp` — with the functions listed
 under *Permission, layer one* below. It is idempotent and safe to repeat after an upgrade.
 
-⚠️ **`bootstrap` declares interfaces and changes no grant.** It creates the permissions an
-administrator can hand out; it hands out none of them. This is step 8, and it is why a fresh
-installation shows an empty screen to everybody including the person who installed it.
+⚠️ **`bootstrap` hands out no grant, and it takes none away as long as the declared list does not
+change.** It creates the permissions an administrator can hand out; it hands out none of them. This
+is step 8, and it is why a fresh installation shows an empty screen to everybody including the
+person who installed it.
 
-⚠️ It also never revokes. An interface an older version declared stays declared in Gate; that is
-harmless, and removing one is an act in Gate, by hand.
+⚠️ **But a function that falls out of a still-declared interface takes its grants with it.**
+Declaring is an upsert that REPLACES an interface's function list, and Gate deletes every grant on a
+function the new list no longer names. So an upgrade that retires a function also retires every role
+assignment on it — against a running installation that is a change to who may do what, not a
+read. `bootstrap` reads the catalog before it writes and names each one as it goes:
+
+```text
+Removed flows:approve from Gate; every grant on it was deleted with it.
+Declared 5 Intel interfaces in Gate.
+```
+
+A run that dropped nothing says so instead: `No declared function was dropped, so Gate deleted no
+grant.` And if the catalog cannot be read, `bootstrap` writes nothing at all rather than delete
+grants it would then be unable to name.
+
+⚠️ It never revokes a whole **interface**. One an older version declared stays declared in Gate:
+`bootstrap` writes only the handles it names, so an interface outside that list keeps its functions
+and its grants. That is harmless, and removing one is an act in Gate, by hand.
 
 ### 4. Copy the migrations out of `node_modules`
 
@@ -135,6 +152,19 @@ FAIL TOOL_SOURCE_ORIGINS is missing
 FAIL INTEL_SESSION_SECRET must contain at least 32 bytes
 ```
 
+It also compares the Gate interfaces **in both directions**. A function or a whole interface Gate
+carries that this version of Intel no longer declares is reported as a `NOTE`, never as a `FAIL`:
+nothing is broken by it, and a check one knows red stops being read. Each note names the surplus,
+why it went, and what to do about it:
+
+```text
+NOTE Gate carries flows:approve, which Intel does not declare — the approval node is gone (#73).
+NOTE Gate carries the interface knowledge (read, write), which Intel does not declare — the whole interface became `nodes` (#152, after #125).
+NOTE The next `intel bootstrap` removes a surplus function and every grant on it (#474). Take the grant away in Gate first if anybody should keep it.
+NOTE `bootstrap` never touches an interface Intel does not declare, so a surplus one stays until somebody removes it in Gate by hand — which takes its grants with it.
+OK Intel packages, configuration, and Gate interfaces are ready.
+```
+
 ⚠️ **`doctor` cannot see the Worker's secrets.** It answers about the shell it runs in, so it says
 nothing about whether the deployed Worker is configured. `GET /health` on the deployed Worker
 answers `{"status":"ok"}`; a Worker missing one of the five required variables answers
@@ -255,10 +285,10 @@ grants them.
 
 | Interface | Functions |
 |---|---|
-| `intel` | `use`, `admin` |
+| `intel` | `admin` |
 | `nodes` | `read`, `create`, `write`, `share` |
 | `flows` | `read`, `create`, `write`, `publish`, `run`, `share` |
-| `tools` | `read`, `test`, `execute`, `admin` |
+| `tools` | `read`, `test`, `execute` |
 | `mcp` | `connect` |
 
 A missing capability answers **`403`**, and the screen says a permission is missing.
@@ -303,8 +333,10 @@ the titles of the folders above it. Nobody has to be sent a link.
 
 ### Three things about grants that surprise people
 
-- **A flow is not a node.** It carries no grants of its own; it inherits those of the folder it
-  lives in. Move a flow and you have changed who can reach it.
+- **A flow is not a node, and is reached by two things at once.** The folder it is filed in passes
+  its grants down, and since #530 a grant may sit on the flow itself; they add up. Move a flow and
+  you have changed the first half of that. A grant on one flow does not reach the flows it calls —
+  the answer names them, and `flow_validate` tells the person about to run what is still missing.
 - **`organization` + `execute` on a folder makes that folder a library**: flows from anywhere in the
   tree may then call into it. The share dialog warns before the click, because the way back is
   narrow — revoking is refused with `409 folder_execute_in_use` for as long as one of those callers

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

@@ -1,7 +1,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, flowInSubtree, flowInSubtreeBindings, flowVerbBindings, flowVerbQuery, readableOrRunnableCte, subtreeBindings, subtreeCte, } from "./db-grants.js";
+import { flowCallable, flowCallableBindings, flowInSubtree, flowInSubtreeBindings, flowVerbBindings, flowVerbQuery, grantColumns, grantInForce, mapGrant, principalColumns, readableOrRunnableCte, subtreeBindings, subtreeCte, } from "./db-grants.js";
 const flowColumnNames = [
     "id",
     "parent_id",
@@ -71,9 +71,9 @@ function mapVersion(row) {
 // 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.
+// 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})`;
-const runVisibleBindings = (actor) => [actor.id, ...flowInSubtreeBindings(actor)];
 function mapStep(row) {
     return {
         runId: row.run_id,
@@ -106,11 +106,17 @@ function mapRun(row) {
 // statement may carry, and the lists here are as long as a graph, a call chain or a drawn level —
 // so an `IN (?, ?, …)` built from the input would be a limit waiting to be hit by real data (#30).
 const idList = "(SELECT value FROM json_each(?))";
+const flowGrantColumns = grantColumns("flow_id");
 export function createFlowRepository(deps) {
-    // 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 the tree uses, so the two can never drift apart. The CTE
-    // stands in front of the statement, so its bindings come before every other one.
+    // The folders this actor may open, read through the same walk the tree uses, so the two can never
+    // drift apart. The CTE stands in front of the statement, so its bindings come before every other
+    // one.
     const readableBindings = (actor) => subtreeBindings(actor, "read", deps.now().toISOString());
+    // The other half of the same question since #530: the folders this actor reads come from the walk
+    // above, the flows handed to them directly come from `flow_grants`. Always `read` here, because
+    // every statement these two appear in together is seeded with `read`.
+    const inSubtreeBindings = (actor) => flowInSubtreeBindings(actor, "read", deps.now().toISOString());
+    const runVisibleBindings = (actor) => [actor.id, ...inSubtreeBindings(actor)];
     // An absent `parentId` asks for every visible flow; `null` asks for the root of the shared tree.
     // `IS ?` would collapse the two, so the two cases are separate SQL rather than one binding that
     // silently means both.
@@ -152,14 +158,14 @@ export function createFlowRepository(deps) {
             SELECT ${flowColumns} FROM flows flow
             WHERE ${flowInSubtree} AND flow.archived_at IS NOT NULL
             ORDER BY flow.archived_at DESC, lower(flow.title), flow.id`)
-                    .bind(...readableBindings(actor), ...flowInSubtreeBindings(actor))
+                    .bind(...readableBindings(actor), ...inSubtreeBindings(actor))
                     .all();
                 return (result.results ?? []).map(mapFlow);
             }
             const scope = scopeOf(input.parentId);
             const result = await deps.db
                 .prepare(visibleFlows(scope.clause, false, input.includeArchived === true))
-                .bind(...readableBindings(actor), ...flowInSubtreeBindings(actor), ...scope.bindings)
+                .bind(...readableBindings(actor), ...inSubtreeBindings(actor), ...scope.bindings)
                 .all();
             return (result.results ?? []).map(mapFlow);
         },
@@ -167,7 +173,7 @@ export function createFlowRepository(deps) {
             const scope = scopeOf(folderId);
             const result = await deps.db
                 .prepare(visibleFlows(scope.clause, true))
-                .bind(...readableBindings(actor), ...flowInSubtreeBindings(actor), ...scope.bindings, limit)
+                .bind(...readableBindings(actor), ...inSubtreeBindings(actor), ...scope.bindings, limit)
                 .all();
             const rows = result.results ?? [];
             return { items: rows.map(mapFlow), total: rows[0]?.total ?? 0 };
@@ -177,10 +183,175 @@ export function createFlowRepository(deps) {
                 .prepare(`${subtreeCte}
           SELECT ${flowColumns} FROM flows flow
           WHERE flow.id = ? AND ${flowInSubtree}`)
-                .bind(...readableBindings(actor), flowId, ...flowInSubtreeBindings(actor))
+                .bind(...readableBindings(actor), flowId, ...inSubtreeBindings(actor))
                 .first();
             return row ? mapFlow(row) : null;
         },
+        async listFlowGrants(flowId) {
+            const result = await deps.db
+                .prepare(`SELECT ${flowGrantColumns} FROM flow_grants
+          WHERE flow_id = ?
+          ORDER BY principal_type, principal_id, verb`)
+                .bind(flowId)
+                .all();
+            return (result.results ?? []).map(mapGrant);
+        },
+        // ⚠️ Owners and grants out of ONE statement, hence one D1 snapshot, for the reason the node side
+        // gives: two parallel SELECTs are not atomic, and a grant written between their snapshots
+        // produces a principal list that never existed as a whole.
+        //
+        // ⚠️ The grants come from BOTH tables. Reading only `flow_grants` here would draw a flow as
+        // though the folder above it granted nothing — which is the everyday case, not the exception.
+        async listEffectiveFlowAccess(flowId) {
+            const row = await deps.db
+                .prepare(`WITH RECURSIVE ancestors(id, parent_id, owner_id) AS (
+            SELECT folder.id, folder.parent_id, folder.owner_id
+            FROM nodes folder
+            JOIN flows flow ON flow.parent_id = folder.id
+            WHERE flow.id = ?
+            UNION
+            SELECT parent.id, parent.parent_id, parent.owner_id
+            FROM nodes parent
+            JOIN ancestors child ON child.parent_id = parent.id
+          )
+          SELECT
+            (SELECT json_group_array(owner_id) FROM (
+               SELECT DISTINCT owner_id FROM (
+                 SELECT owner_id FROM flows WHERE id = ?
+                 UNION
+                 SELECT owner_id FROM ancestors
+               ) ORDER BY owner_id
+             )) AS owner_ids_json,
+            (SELECT json_group_array(json_object(
+               'id', id, 'resource_id', resource_id, 'principal_type', principal_type,
+               'principal_id', principal_id, 'verb', verb, 'expires_at', expires_at,
+               'created_by', created_by, 'created_at', created_at
+             ))
+             FROM (
+               SELECT grant_row.id, grant_row.flow_id AS resource_id, grant_row.principal_type,
+                 grant_row.principal_id, grant_row.verb, grant_row.expires_at,
+                 grant_row.created_by, grant_row.created_at
+               FROM flow_grants grant_row
+               WHERE grant_row.flow_id = ?
+                 AND ${grantInForce}
+               UNION ALL
+               SELECT grant_row.id, grant_row.node_id AS resource_id, grant_row.principal_type,
+                 grant_row.principal_id, grant_row.verb, grant_row.expires_at,
+                 grant_row.created_by, grant_row.created_at
+               FROM node_grants grant_row
+               JOIN ancestors ON ancestors.id = grant_row.node_id
+               WHERE ${grantInForce}
+               ORDER BY principal_type, principal_id, verb
+             )) AS grants_json`)
+                .bind(flowId, flowId, flowId, deps.now().toISOString(), deps.now().toISOString())
+                .first();
+            return {
+                ownerIds: JSON.parse(row?.owner_ids_json ?? "[]"),
+                items: JSON.parse(row?.grants_json ?? "[]").map(mapGrant),
+            };
+        },
+        async setFlowGrant(input) {
+            const grant = input.grant;
+            const { type: principalType, id: principalId } = principalColumns(grant.principal);
+            try {
+                await deps.db.batch([
+                    deps.db
+                        // The verb is part of the key, so re-granting the same verb only refreshes its expiry
+                        // and never turns one verb into another.
+                        .prepare(`INSERT INTO flow_grants (
+              id, flow_id, principal_type, principal_id, verb,
+              expires_at, created_by, created_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT (flow_id, principal_type, principal_id, verb)
+            DO UPDATE SET expires_at = excluded.expires_at`)
+                        .bind(grant.id, input.flowId, principalType, principalId, grant.verb, grant.expiresAt, grant.createdBy, grant.createdAt),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'flows.share', ?, id, ? FROM flow_grants
+              WHERE flow_id = ? AND principal_type = ? AND principal_id = ? AND verb = ?`)
+                        .bind(input.actorId, input.idempotencyKey, grant.createdAt, input.flowId, principalType, principalId, grant.verb),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) VALUES (?, ?, 'flows.share', 'flow', ?, ?, ?)`)
+                        .bind(input.auditId, input.actorId, input.flowId, JSON.stringify({ principalType, verb: grant.verb }), grant.createdAt),
+                ]);
+                const stored = await deps.db
+                    .prepare(`SELECT ${flowGrantColumns} FROM flow_grants
+            WHERE flow_id = ? AND principal_type = ? AND principal_id = ? AND verb = ?`)
+                    .bind(input.flowId, principalType, principalId, grant.verb)
+                    .first();
+                if (!stored)
+                    throw new Error("Flow grant disappeared after upsert");
+                return mapGrant(stored);
+            }
+            catch (error) {
+                const replayed = await deps.db
+                    .prepare(`SELECT resource_id FROM idempotency_keys
+            WHERE actor_id = ? AND operation = 'flows.share' AND idempotency_key = ?`)
+                    .bind(input.actorId, input.idempotencyKey)
+                    .first();
+                if (replayed) {
+                    const row = await deps.db
+                        .prepare(`SELECT ${flowGrantColumns} FROM flow_grants WHERE id = ?`)
+                        .bind(replayed.resource_id)
+                        .first();
+                    if (row)
+                        return mapGrant(row);
+                }
+                throw error;
+            }
+        },
+        // ⚠️ Whether the row was there is decided BEFORE it is deleted and remembered in the
+        // idempotency key's own value, because afterwards nothing can tell "I removed it" from "it was
+        // never here" — and a replay that answered `true` to the second would claim a deletion that did
+        // not happen. The `1:`/`0:` prefix is the node side's device, and it is the same device here.
+        async revokeFlowGrant(input) {
+            try {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'flows.revoke', ?,
+              (CASE WHEN EXISTS (
+                SELECT 1 FROM flow_grants WHERE id = ? AND flow_id = ?
+              ) THEN '1:' ELSE '0:' END) || ?, ?`)
+                        .bind(input.actorId, input.idempotencyKey, input.grantId, input.flowId, input.grantId, input.occurredAt),
+                    deps.db
+                        .prepare("DELETE FROM flow_grants WHERE id = ? AND flow_id = ?")
+                        .bind(input.grantId, input.flowId),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'flows.revoke', 'flow', ?,
+              json_object(
+                'grantId', ?,
+                'revoked', json(CASE WHEN substr(resource_id, 1, 2) = '1:' THEN 'true' ELSE 'false' END)
+              ), ?
+              FROM idempotency_keys
+              WHERE actor_id = ? AND operation = 'flows.revoke' AND idempotency_key = ?`)
+                        .bind(input.auditId, input.actorId, input.flowId, input.grantId, input.occurredAt, input.actorId, input.idempotencyKey),
+                ]);
+            }
+            catch (error) {
+                const replayed = await this.findIdempotentFlowRevocation(input.actorId, input.idempotencyKey);
+                if (replayed === null)
+                    throw error;
+                return replayed;
+            }
+            return ((await this.findIdempotentFlowRevocation(input.actorId, input.idempotencyKey)) ?? false);
+        },
+        async findIdempotentFlowRevocation(actorId, idempotencyKey) {
+            const row = await deps.db
+                .prepare(`SELECT resource_id FROM idempotency_keys
+          WHERE actor_id = ? AND operation = 'flows.revoke' AND idempotency_key = ?`)
+                .bind(actorId, idempotencyKey)
+                .first();
+            if (!row)
+                return null;
+            return row.resource_id.startsWith("1:");
+        },
         async can(actor, flowId, verb) {
             const row = await deps.db
                 .prepare(flowVerbQuery)
@@ -202,7 +373,7 @@ export function createFlowRepository(deps) {
           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))
+                .bind(...subtreeBindings(actor, "read", occurredAt), ...subtreeBindings(actor, "execute", occurredAt), JSON.stringify(flowIds), ...flowCallableBindings(actor, occurredAt))
                 .all();
             return (result.results ?? []).map(mapFlow);
         },
@@ -233,7 +404,7 @@ export function createFlowRepository(deps) {
               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 > ?)
+                AND ${grantInForce}
             ) AS library`)
                 .bind(calleeFolderId, callerFolderId, deps.now().toISOString())
                 .first();
@@ -267,7 +438,7 @@ export function createFlowRepository(deps) {
             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))
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), folderId, ...inSubtreeBindings(actor))
                 .all();
             const rows = result.results ?? [];
             return {
@@ -291,7 +462,7 @@ export function createFlowRepository(deps) {
             AND flow.archived_at IS NULL
             AND flow.id <> ?
           ORDER BY lower(flow.title), flow.id`)
-                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), ...flowInSubtreeBindings(actor), flowId, flowId)
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), ...inSubtreeBindings(actor), flowId, flowId)
                 .all();
             const rows = result.results ?? [];
             return {
@@ -315,7 +486,7 @@ export function createFlowRepository(deps) {
             AND json_extract(node.value, '$.configuration.resourceId') = ?
             AND flow.archived_at IS NULL
           ORDER BY lower(flow.title), flow.id`)
-                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), ...flowInSubtreeBindings(actor), nodeId)
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), ...inSubtreeBindings(actor), nodeId)
                 .all();
             const rows = result.results ?? [];
             return {
@@ -381,6 +552,13 @@ export function createFlowRepository(deps) {
                 deps.db
                     .prepare(`DELETE FROM idempotency_keys WHERE resource_id = ? AND ${aliveFlow}`)
                     .bind(input.flowId, input.flowId),
+                // The grants that sat on the flow itself (#530). They point at `flows(id)`, so they have to
+                // go before the row does — and they carry the same guard as everything above for the same
+                // reason: a batch whose last statement matches nothing still commits, and a restore in
+                // between would leave a living flow stripped of every grant somebody set on it.
+                deps.db
+                    .prepare(`DELETE FROM flow_grants WHERE flow_id = ? AND ${aliveFlow}`)
+                    .bind(input.flowId, input.flowId),
                 // ⚠️ LAST, and still guarded — a restore between the service's check and this statement
                 // would otherwise cost a living flow.
                 deps.db
@@ -425,10 +603,26 @@ export function createFlowRepository(deps) {
           FROM referencing
           WHERE resource_id IS NOT NULL
           ORDER BY resource_id`)
-                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), folderId, ...flowInSubtreeBindings(actor))
+                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), folderId, ...inSubtreeBindings(actor))
                 .all();
             return (result.results ?? []).map((row) => row.resource_id);
         },
+        // ⚠️ No actor and no `archived_at` condition, both on purpose (#509). The question is whether
+        // the row is still there at all, and archiving keeps it — a reference to something archived is
+        // not broken, it is waiting for a restore. The caller has already asked the visibility door for
+        // every one of these ids and reaches this only for the ones it answered nothing for.
+        //
+        // ⚠️ An empty list short-circuits rather than building `IN ()`, which SQLite refuses to parse.
+        async existingNodes(nodeIds) {
+            const wanted = [...new Set(nodeIds)];
+            if (wanted.length === 0)
+                return [];
+            const result = await deps.db
+                .prepare(`SELECT id FROM nodes WHERE id IN (${wanted.map(() => "?").join(", ")}) ORDER BY id`)
+                .bind(...wanted)
+                .all();
+            return (result.results ?? []).map((row) => row.id);
+        },
         async publishedCallees(flowId) {
             const row = await deps.db
                 .prepare(`SELECT flow.title AS title, version.graph_json AS graph_json

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

@@ -1,9 +1,46 @@
-import type { ResourceVerb } from "@anchrd/intel-contract/share";
+import type { ResourceGrant, ResourceVerb } from "@anchrd/intel-contract/share";
 export interface GrantActor {
     id: string;
     email: string;
     isAdmin?: boolean;
 }
+/**
+ * A grant row as every reader of one wants it: the subject column already aliased, so the same row
+ * shape comes back from `node_grants` and from `flow_grants`.
+ *
+ * ⚠️ The alias is what lets `mapGrant` stay one function. Two mappers would each carry the same
+ * `principal_type` switch, and the day a fourth principal shape arrives one of them gets it.
+ */
+export interface GrantRow {
+    id: string;
+    resource_id: string;
+    principal_type: "user" | "email" | "organization";
+    principal_id: string;
+    verb: ResourceVerb;
+    expires_at: string | null;
+    created_by: string;
+    created_at: string;
+}
+export declare const grantColumns: (subjectColumn: string) => string;
+export declare function mapGrant(row: GrantRow): ResourceGrant;
+export declare function principalColumns(principal: ResourceGrant["principal"]): {
+    type: ResourceGrant["principal"]["type"];
+    id: string;
+};
+/**
+ * Whether a grant row is in force at the moment bound after it. Takes one binding: that moment.
+ *
+ * ⚠️ The ONE place this repository decides what an expiry means, for both grant tables and for
+ * every statement that reads either — the point check, the subtree walk, and the two effective
+ * views alike. It is a fragment rather than part of `grantExists` because half the readers do not
+ * ask about a principal at all: `listEffectiveAccess` lists every grant along a path, and
+ * `callReach` asks only whether an organization-wide `execute` stands. Those had written the
+ * condition out by hand, which is exactly the second set of doors the header above warns about —
+ * a grace period, a different comparison, and the two spellings drift apart in silence.
+ *
+ * `git grep "expires_at IS NULL" -- packages/api/src` must find this line and nothing else.
+ */
+export declare const grantInForce = "(grant_row.expires_at IS NULL OR grant_row.expires_at > ?)";
 export declare const subtreeCte: string;
 export declare function subtreeBindings(actor: GrantActor, verb: ResourceVerb, now: string): unknown[];
 /**
@@ -27,9 +64,14 @@ export declare const readableOrRunnableCte: string;
  * A flow the actor may open *or* may run, for a statement carrying `readableOrRunnableCte`. It is
  * the callable rule of ADR-0004 §2/§3 — `execute` without `read` is the library, a building block
  * anyone may run and few may open — asked of a whole list of flows at once instead of one flow at a
- * time. Its bindings follow the two CTEs' and are `flowInSubtreeBindings(actor)`.
+ * time. Its bindings follow the two CTEs' and are `flowCallableBindings(actor, now)`.
+ *
+ * ⚠️ Both direct grants, and both are needed. A flow handed out on its own for `execute` alone is
+ * the library case shrunk to one flow — runnable by people who may not open it — and leaving `read`
+ * out here would hide a flow somebody was explicitly given to look at.
  */
-export declare const flowCallable = "(\n  ? = 1\n  OR flow.owner_id = ?\n  OR flow.parent_id IN (SELECT id FROM readable)\n  OR flow.parent_id IN (SELECT id FROM runnable)\n)";
+export declare const flowCallable: string;
+export declare function flowCallableBindings(actor: GrantActor, now: string): unknown[];
 /**
  * The point check for one node: the node itself and every ancestor above it. Cheaper than
  * the subtree walk and the same answer, because a grant reaches down and never sideways.
@@ -43,16 +85,26 @@ export declare const flowCallable = "(\n  ? = 1\n  OR flow.owner_id = ?\n  OR fl
 export declare const nodeVerbQuery: string;
 export declare function nodeVerbBindings(nodeId: string, actor: GrantActor, verb: ResourceVerb, now: string): unknown[];
 /**
- * The same question for a flow. A flow carries no grant of its own any more: what reaches it is the
- * folder it is filed in and that folder's ancestors. Its owner keeps it, the way a node's
- * owner keeps theirs — otherwise a flow at the root of the tree would be unreachable by the person
- * who created it. `UNION` for the same reason as above.
+ * The same question for a flow. Three things reach it, and they are OR-ed rather than ranked: its
+ * owner, a grant on the folder it is filed in or any folder above that, and — since #530 — a grant
+ * that sits on the flow itself. Its owner keeps it the way a node's owner keeps theirs, otherwise a
+ * flow at the root of the tree would be unreachable by the person who created it. `UNION` for the
+ * same reason as above.
+ *
+ * ⚠️ The direct grant is asked BEFORE the ancestor walk, and only because it is cheaper: a point
+ * lookup on an indexed column against a recursive walk of the tree. It decides nothing the walk
+ * would have decided differently — both are the same OR.
  */
 export declare const flowVerbQuery: string;
 export declare function flowVerbBindings(flowId: string, actor: GrantActor, verb: ResourceVerb, now: string): unknown[];
 /**
  * The predicate a query over `flows` uses when it already carries `subtreeCte` for the same verb.
  * Its bindings follow the CTE's.
+ *
+ * ⚠️ The verb is now a binding of its own, and it has to be the SAME verb the CTE was seeded with.
+ * The walk answers "which folders", the direct grant answers "this flow" — asking them for two
+ * different verbs would produce a predicate that is neither, and it is the kind of mismatch nothing
+ * fails on: the query still runs and quietly hands out the wrong list.
  */
-export declare const flowInSubtree = "(? = 1 OR flow.owner_id = ? OR flow.parent_id IN (SELECT id FROM allowed))";
-export declare function flowInSubtreeBindings(actor: GrantActor): unknown[];
+export declare const flowInSubtree: string;
+export declare function flowInSubtreeBindings(actor: GrantActor, verb: ResourceVerb, now: string): unknown[];