@anchrd/intel-api 0.36.0 → 0.37.0

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

@@ -1,23 +1,5 @@
 import type { FeedRepository } from "../../feed/feed.types.js";
 import type { D1Database } from "./db.types.js";
-/**
- * One page of the journal, newest first, cut down to the rows this actor may see.
- *
- * ⚠️ **The visibility check is the same JOIN against `allowed` that `audit_list` uses**, which is
- * the same tree walk `nodes` reads through (`db-grants.ts`). An event about a node is visible
- * exactly when the node is. A second, similar-looking query beside the first is the drift that
- * `anchrd/intel#457` was built out of: two queries with similar names are two different questions.
- *
- * ⚠️ **`ORDER BY` and the cursor comparison name BOTH columns, in the same direction.** Two events
- * in the same millisecond are the normal case inside a batch, not the exception; on `occurred_at`
- * alone the second one is skipped in silence. SQLite has no row-value comparison here, so the
- * tuple comparison is written out: "earlier timestamp, OR same timestamp and smaller id".
- *
- * ⚠️ **Both columns descend, and that is what lets the index carry this.** `audit_events_feed_idx`
- * is `(resource_type, occurred_at, id)` ascending; SQLite reads an index backwards only when every
- * sort column is reversed together. Reversing one would cost a sort over the whole table, and that
- * is invisible on the first pages and only hurts far down.
- */
 export declare const feedPageQuery: string;
 /**
  * The folders above each of a page's nodes, and only the ones the actor may open.
@@ -32,6 +14,14 @@ export declare const feedPageQuery: string;
  * and `UNION` ends the walk because the row repeats — a depth counter would make every row unique
  * and turn the same cycle into a query that never returns. The order is rebuilt in TypeScript from
  * `parent_id`, where a visited-set makes the cycle harmless.
+ *
+ * ⚠️ **The seeds are the PARENTS, not the nodes** (#645). Starting at the node and stepping up to
+ * its parent works only while the node exists, and the one event that most needs a trail is the one
+ * whose node is gone. Starting a level higher costs nothing for the ordinary case — the parent is
+ * where the walk went anyway — and it is the only anchor a deletion has left.
+ *
+ * There is no `seed` column: ids are unique, so one flat set of visible ancestors serves every card
+ * on the page, and each trail is rebuilt from its own `parentId` through that set.
  */
 export declare const feedAncestorsQuery: (seeds: number) => string;
 export declare function createFeedRepository(deps: {

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

@@ -1,9 +1,12 @@
-import { FeedAction } from "@anchrd/intel-contract/feed";
-import { subtreeBindings, subtreeCte } from "./db-grants.js";
-// Built once from the contract enum rather than written out here: two lists of actions that have to
-// agree would eventually stop agreeing, and the one that silently wins is the SQL.
-const ACTIONS = FeedAction.options;
-const ACTION_PLACEHOLDERS = ACTIONS.map(() => "?").join(", ");
+import { FeedAction, feedKindOf, } 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
+// 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_PLACEHOLDERS = NODE_ACTIONS.map(() => "?").join(", ");
+const FLOW_PLACEHOLDERS = FLOW_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
@@ -29,24 +32,72 @@ function parseMetadata(raw) {
  * exactly when the node is. A second, similar-looking query beside the first is the drift that
  * `anchrd/intel#457` was built out of: two queries with similar names are two different questions.
  *
+ * ⚠️ **Two events have no row left to check, and that is why the join reads `COALESCE`** (#645 for
+ * `node.purge`, #763 for `flows.purge`).
+ * After `node.purge` the row is gone, so `JOIN nodes` dropped the event for everybody — creation,
+ * change and archiving arrived, final deletion never did. It now falls back to the `parentId` the
+ * purge wrote into its own metadata, and the check runs against that surviving FOLDER.
+ *
+ * The fallback is deliberately narrow: `COALESCE(n.id, …)` prefers the node whenever it exists, so
+ * for every other event nothing changes at all. It is not "or the parent is allowed" — that would
+ * hand out every event in a readable folder about nodes inside it that are NOT readable.
+ *
+ * ⚠️ **The title comes from the metadata for the same reason** — there is no row to read it from —
+ * and events written before #645 carry no `parentId`, so they stay unreachable. That cannot be
+ * repaired: at a deleted row there is nothing left to look up where it hung.
+ *
  * ⚠️ **`ORDER BY` and the cursor comparison name BOTH columns, in the same direction.** Two events
  * in the same millisecond are the normal case inside a batch, not the exception; on `occurred_at`
  * alone the second one is skipped in silence. SQLite has no row-value comparison here, so the
  * tuple comparison is written out: "earlier timestamp, OR same timestamp and smaller id".
  *
- * ⚠️ **Both columns descend, and that is what lets the index carry this.** `audit_events_feed_idx`
- * is `(resource_type, occurred_at, id)` ascending; SQLite reads an index backwards only when every
- * sort column is reversed together. Reversing one would cost a sort over the whole table, and that
- * is invisible on the first pages and only hurts far down.
+ * ⚠️ **Both columns descend, and that is what lets an index carry this.** SQLite reads an index
+ * backwards only when every sort column is reversed together. Reversing one would cost a sort over
+ * 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:
+ * `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.
+ *
+ * ⚠️ **The unary `+` in front of each `resource_type` is load-bearing, not a typo.** It tells SQLite
+ * 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.
+ *
+ * ⚠️ **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
+ * 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.
  */
+const FLOW_PARENT = "COALESCE(flow.parent_id, json_extract(e.metadata_json, '$.parentId'))";
+const NODE_PARENT = "COALESCE(n.id, json_extract(e.metadata_json, '$.parentId'))";
 export const feedPageQuery = `${subtreeCte}
-    SELECT e.id, e.actor_id, e.action, e.resource_id, n.title AS node_title,
-           n.parent_id AS node_parent_id, e.metadata_json, e.occurred_at
+    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'))
+             AS resource_parent_id,
+           e.metadata_json, e.occurred_at
     FROM audit_events e
-    JOIN allowed ON allowed.id = e.resource_id
-    JOIN nodes n ON n.id = e.resource_id
-    WHERE e.resource_type = 'node'
-      AND e.action IN (${ACTION_PLACEHOLDERS})
+    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'
+    WHERE (
+        (
+          +e.resource_type = 'node'
+          AND e.action IN (${NODE_PLACEHOLDERS})
+          AND ${NODE_PARENT} IN (SELECT id FROM allowed)
+        )
+        OR (
+          +e.resource_type = 'flow'
+          AND e.action IN (${FLOW_PLACEHOLDERS})
+          AND ${flowInSubtreeOver(FLOW_PARENT)}
+        )
+      )
       AND (? IS NULL OR e.actor_id = ?)
       AND (
         ? IS NULL
@@ -68,19 +119,26 @@ export const feedPageQuery = `${subtreeCte}
  * and `UNION` ends the walk because the row repeats — a depth counter would make every row unique
  * and turn the same cycle into a query that never returns. The order is rebuilt in TypeScript from
  * `parent_id`, where a visited-set makes the cycle harmless.
+ *
+ * ⚠️ **The seeds are the PARENTS, not the nodes** (#645). Starting at the node and stepping up to
+ * its parent works only while the node exists, and the one event that most needs a trail is the one
+ * whose node is gone. Starting a level higher costs nothing for the ordinary case — the parent is
+ * where the walk went anyway — and it is the only anchor a deletion has left.
+ *
+ * There is no `seed` column: ids are unique, so one flat set of visible ancestors serves every card
+ * on the page, and each trail is rebuilt from its own `parentId` through that set.
  */
 export const feedAncestorsQuery = (seeds) => `${subtreeCte},
-  ancestry(seed, id, parent_id, title) AS (
-    SELECT child.id, parent.id, parent.parent_id, parent.title
-    FROM nodes child
-    JOIN nodes parent ON parent.id = child.parent_id
-    WHERE child.id IN (${Array.from({ length: seeds }, () => "?").join(", ")})
+  ancestry(id, parent_id, title) AS (
+    SELECT parent.id, parent.parent_id, parent.title
+    FROM nodes parent
+    WHERE parent.id IN (${Array.from({ length: seeds }, () => "?").join(", ")})
     UNION
-    SELECT a.seed, grandparent.id, grandparent.parent_id, grandparent.title
+    SELECT grandparent.id, grandparent.parent_id, grandparent.title
     FROM nodes grandparent
     JOIN ancestry a ON a.parent_id = grandparent.id
   )
-  SELECT a.seed, a.id, a.parent_id, a.title
+  SELECT a.id, a.parent_id, a.title
   FROM ancestry a
   JOIN allowed ON allowed.id = a.id`;
 /**
@@ -115,36 +173,40 @@ export function createFeedRepository(deps) {
     return {
         async listEvents(actor, query) {
             const before = query.before ?? null;
+            // One reading of the clock for the whole call. Both guards measure grant expiry against it,
+            // and two `now()` calls could straddle the moment a grant runs out — a page whose flow half
+            // answers about a permission its node half no longer has.
+            const now = deps.now().toISOString();
             const page = await deps.db
                 .prepare(feedPageQuery)
-                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), ...ACTIONS, 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), 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)
                 return { events: [] };
             // One walk for the whole page rather than one per row. The set is at most the page size, and
             // it is deduplicated because a busy morning on one document is exactly the case the feed
-            // shows unsummarised today.
-            const nodeIds = [...new Set(rows.map((row) => row.resource_id))];
-            const ancestors = await deps.db
-                .prepare(feedAncestorsQuery(nodeIds.length))
-                .bind(...subtreeBindings(actor, "read", deps.now().toISOString()), ...nodeIds)
-                .all();
-            const ancestorRows = ancestors.results ?? [];
-            const parentOf = new Map(rows.map((row) => [row.resource_id, row.node_parent_id]));
-            const trails = new Map(nodeIds.map((id) => [
-                id,
-                trailFor(parentOf.get(id) ?? null, ancestorRows.filter((row) => row.seed === id)),
-            ]));
+            // shows unsummarised today. The trail is keyed by EVENT rather than by node: two events about
+            // one node share a trail, but a deleted node and a live one can carry the same parent.
+            const parentIds = [
+                ...new Set(rows.map((row) => row.resource_parent_id).filter((id) => id !== null)),
+            ];
+            const ancestorRows = parentIds.length === 0
+                ? []
+                : ((await deps.db
+                    .prepare(feedAncestorsQuery(parentIds.length))
+                    .bind(...subtreeBindings(actor, "read", now), ...parentIds)
+                    .all()).results ?? []);
+            const trails = new Map(rows.map((row) => [row.id, trailFor(row.resource_parent_id, ancestorRows)]));
             const events = rows.map((row) => ({
                 id: row.id,
                 actorId: row.actor_id,
                 // Narrowed at the door by the SQL `IN`, so the cast names what the query already
                 // guarantees rather than trusting the column.
                 action: row.action,
-                nodeId: row.resource_id,
-                nodeTitle: row.node_title,
-                path: trails.get(row.resource_id) ?? [],
+                resourceId: row.resource_id,
+                resourceTitle: row.resource_title,
+                path: trails.get(row.id) ?? [],
                 metadata: parseMetadata(row.metadata_json),
                 occurredAt: row.occurred_at,
             }));

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

@@ -532,7 +532,8 @@ export function createFlowRepository(deps) {
                 deps.db
                     .prepare(`INSERT INTO audit_events (
             id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
-          ) SELECT ?, ?, 'flows.purge', 'flow', f.id, json_object('title', f.title), ?
+          ) SELECT ?, ?, 'flows.purge', 'flow', f.id,
+              json_object('title', f.title, 'parentId', f.parent_id), ?
             FROM flows f WHERE f.id = ? AND f.archived_at IS NOT NULL`)
                     .bind(input.auditId, input.actorId, input.occurredAt, input.flowId),
                 // The runs are this flow's history: the steps hang off the runs, the runs off the flow.

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

@@ -106,5 +106,15 @@ export declare function flowVerbBindings(flowId: string, actor: GrantActor, verb
  * 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.
  */
+/**
+ * ⚠️ The parent is a PARAMETER for exactly one caller, and giving it one was cheaper than the
+ * alternative. The feed reads events about flows that no longer exist: after `flows.purge` the row
+ * is gone, so `flow.parent_id`, `flow.owner_id` and every `flow_grants` row are gone with it, and
+ * the only anchor left is the `parentId` the purge wrote into its own metadata (#763, D73). A
+ * second, similar-looking predicate beside this one is the drift `destructive.md` warns about: two
+ * expressions with similar names are two different questions, and the one that goes stale is the
+ * copy.
+ */
+export declare function flowInSubtreeOver(parentExpression: 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

@@ -233,12 +233,24 @@ export function flowVerbBindings(flowId, actor, verb, now) {
  * 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 const flowInSubtree = `(
+/**
+ * ⚠️ The parent is a PARAMETER for exactly one caller, and giving it one was cheaper than the
+ * alternative. The feed reads events about flows that no longer exist: after `flows.purge` the row
+ * is gone, so `flow.parent_id`, `flow.owner_id` and every `flow_grants` row are gone with it, and
+ * the only anchor left is the `parentId` the purge wrote into its own metadata (#763, D73). A
+ * second, similar-looking predicate beside this one is the drift `destructive.md` warns about: two
+ * expressions with similar names are two different questions, and the one that goes stale is the
+ * copy.
+ */
+export function flowInSubtreeOver(parentExpression) {
+    return `(
   ? = 1
   OR flow.owner_id = ?
-  OR flow.parent_id IN (SELECT id FROM allowed)
+  OR ${parentExpression} IN (SELECT id FROM allowed)
   OR ${flowGrantExists("flow.id")}
 )`;
+}
+export const flowInSubtree = flowInSubtreeOver("flow.parent_id");
 export function flowInSubtreeBindings(actor, verb, now) {
     return [actor.isAdmin ? 1 : 0, actor.id, ...grantBindings(actor, verb, now)];
 }

package/dist/adapters/db/db.js

@@ -904,11 +904,18 @@ export function createNodeRepository(deps) {
                 // ⚠️ FIRST, and reading the title out of the row that falls at the end of this batch. Its
                 // `WHERE EXISTS` is what makes it honest: no row, no entry — a purge that hit nothing does
                 // not book one.
+                //
+                // ⚠️ **`parentId` travels beside the title, and it is what makes this row READABLE
+                // afterwards** (#645). Visibility everywhere else walks `nodes` from the row itself, and
+                // after this batch that row is gone — so until now the event was unreachable for everybody,
+                // admin included. The surviving FOLDER answers instead. It is written here rather than
+                // derived later for the same reason the title is: after the delete there is nothing left to
+                // look either of them up from (`destructive.md`).
                 deps.db
                     .prepare(`INSERT INTO audit_events (
             id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
           ) SELECT ?, ?, 'node.purge', 'node', n.id,
-              json_patch(?, json_object('title', n.title, 'kind', n.kind)), ?
+              json_patch(?, json_object('title', n.title, 'kind', n.kind, 'parentId', n.parent_id)), ?
             FROM nodes n WHERE n.id = ? AND n.archived_at IS NOT NULL`)
                     .bind(input.auditId, input.actorId, JSON.stringify(input.metadata), input.occurredAt, input.nodeId),
                 deps.db

package/migrations/0026_one_feed_over_two_kinds.sql

@@ -0,0 +1,23 @@
+-- The feed reads both kinds at once — nodes and flows — and `audit_events_feed_idx` cannot serve
+-- that. It leads with `resource_type` because every reader until now named exactly one kind, so for
+-- a query saying `resource_type IN ('node', 'flow')` that column is no longer an equality prefix but
+-- an ordinary filter, and the ordering falls off the index.
+--
+-- ⚠️ Measured against the real `feedPageQuery` before this file existed, not assumed
+-- (anchrd/intel#763):
+--
+--     SEARCH e USING INDEX audit_events_feed_idx (resource_type=?)
+--     … | USE TEMP B-TREE FOR ORDER BY
+--
+-- That last line is a sorting pass over the whole table. It costs nothing on the first page and
+-- everything far down — which is exactly where an endless scroll goes.
+--
+-- ⚠️ Both columns, in the order the cursor compares them, for the reason `0022` gives: two events
+-- written in the same millisecond are the normal case inside one batch, and without the tie-break
+-- on `id` a reader skips the second one with no error and no log.
+--
+-- ⚠️ This does NOT replace `audit_events_feed_idx`. That one still serves `audit_list`, which names
+-- one kind and is the contract `anchrd/signals` builds on; dropping it would put a sorting pass into
+-- the reader that has none today. Two readers, two shapes, two indexes.
+CREATE INDEX audit_events_time_idx
+  ON audit_events(occurred_at, id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@anchrd/gate-sdk": "^0.25.0",
-    "@anchrd/intel-contract": "^0.28.0",
+    "@anchrd/intel-contract": "^0.29.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",