@anchrd/intel 0.59.0

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

@@ -0,0 +1,324 @@
+import { ARCHIVE_COLUMN_ID, BoardColumn } from "../../contract/board.js";
+import { grantInForce, subtreeBindings, subtreeCte } from "./db-grants.js";
+function parseList(raw, of) {
+    // The column is `NOT NULL DEFAULT '[]'`, but it is JSON written by this repository and read back
+    // by it — a value that cannot be parsed is a defect, not a caller's mistake. It must still not
+    // take the whole board down: one unreadable row would make the board unopenable, and there would
+    // be no way in to repair it.
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        void of;
+        return [];
+    }
+}
+function mapTask(row, boardId) {
+    return {
+        id: row.id,
+        title: row.title,
+        /**
+         * ⚠️ **An archived card reports the ARCHIVE column, not the one it came from** — that is what
+         * makes the column real instead of a label. `board_tasks.status` keeps naming the working
+         * column underneath, untouched, and that is what a card pulled back out returns to.
+         *
+         * A card archived over `node_archive`, without anybody dragging it, therefore appears here too.
+         * That is the test which tells this design apart from a second stored status (D68).
+         */
+        status: row.archived_at === null ? row.status : ARCHIVE_COLUMN_ID,
+        assigneeId: row.assignee_id,
+        labels: parseList(row.labels_json, "labels").filter((entry) => typeof entry === "string"),
+        startDate: row.start_date,
+        dueDate: row.due_date,
+        dependsOn: row.depends_on,
+        // ⚠️ The board itself is not a parent TASK. A card filed directly on the board has
+        // `parent_id = boardId`, and handing that back as `parentTaskId` would make every top-level
+        // card claim to be a subtask of the board — a tree one level too deep, in every view.
+        parentTaskId: row.parent_id === boardId ? null : row.parent_id,
+        position: row.position,
+        archivedAt: row.archived_at,
+    };
+}
+export function createBoardRepository(deps) {
+    /**
+     * ⚠️ **The VERB is a parameter, and every caller has to name it.** It was hard-wired to `"read"`
+     * once, and the consequence was not a missing check but the WRONG one: `columnsOf` and `taskRow`
+     * are the only gates the board service passes before it writes, so a board shared read-only could
+     * have its columns replaced and its cards moved. The refusal was there, it simply asked whether
+     * the actor may LOOK (ADR-0004 §2).
+     */
+    const walkBindings = (actor, verb) => subtreeBindings(actor, verb, deps.now().toISOString());
+    return {
+        /**
+         * The whole board in ONE answer: the node, its columns, and every card the actor may see.
+         *
+         * ⚠️ **`JOIN allowed` on the TASK, not only on the board.** Reaching the board is not the same
+         * question as reaching a card in it — a grant can sit on a single task, and one on the board
+         * does not make its tasks readable by a different rule than the tree uses. Asking once at the
+         * top would be a second authorization model beside `allowed`, and the two would drift.
+         *
+         * ⚠️ **Every filter is a WHERE, never a pass over the result.** A filter applied after reading
+         * has already carried the rows over the wire — which for `assigneeId` means titles of other
+         * people's cards in an answer that was supposed to exclude them.
+         */
+        async read(actor, input) {
+            const board = await deps.db
+                .prepare(`${subtreeCte}
+          SELECT n.id, n.title, COALESCE(b.statuses_json, '[]') AS statuses_json,
+                 COALESCE(b.archive_visible, 1) AS archive_visible
+          FROM nodes n
+          JOIN allowed ON allowed.id = n.id
+          LEFT JOIN boards b ON b.node_id = n.id
+          WHERE n.id = ? AND n.kind = 'board'`)
+                .bind(...walkBindings(actor, "read"), input.boardId)
+                .first();
+            if (board === null)
+                return null;
+            const conditions = ["t.board_id = ?"];
+            const bindings = [input.boardId];
+            if (input.status === ARCHIVE_COLUMN_ID) {
+                // ⚠️ The archive column is not a stored status — `board_tasks.status` keeps naming the
+                // working column underneath (D68). Matched against `t.status` the filter would answer
+                // "nothing here" on a board full of visibly archived cards, and the column would look
+                // broken rather than empty.
+                conditions.push("n.archived_at IS NOT NULL");
+            }
+            else if (input.status !== undefined) {
+                conditions.push("t.status = ?");
+                bindings.push(input.status);
+            }
+            if (input.assigneeId !== undefined) {
+                conditions.push("t.assignee_id = ?");
+                bindings.push(input.assigneeId);
+            }
+            if (input.dueBefore !== undefined) {
+                // ⚠️ `t.due_date IS NOT NULL` is not redundant beside `<`: in SQLite `NULL < 'x'` is NULL,
+                // which is not true, so the rows would be dropped anyway — but writing it out says that
+                // dropping them is the DECISION. A task with no due date is not "due before" anything.
+                conditions.push("t.due_date IS NOT NULL AND t.due_date < ?");
+                bindings.push(input.dueBefore);
+            }
+            if (input.dependsOn !== undefined) {
+                conditions.push("t.depends_on = ?");
+                bindings.push(input.dependsOn);
+            }
+            /**
+             * ⚠️ **The archive column IS the archived cards** (D68, #674). While it is drawn they belong
+             * in the answer, or the column would always be empty and nobody could pull anything back out
+             * of it. `includeArchived` stays for the other direction: a caller — an agent, a report —
+             * that wants them even on a board where the column is hidden.
+             */
+            const archiveVisible = board.archive_visible !== 0;
+            if (!input.includeArchived && !archiveVisible)
+                conditions.push("n.archived_at IS NULL");
+            const tasks = await deps.db
+                .prepare(`${subtreeCte}
+          SELECT n.id, n.title, n.parent_id, t.status, t.assignee_id, t.labels_json,
+                 t.start_date, t.due_date, t.depends_on, t.position, n.archived_at
+          FROM board_tasks t
+          JOIN nodes n ON n.id = t.node_id
+          JOIN allowed ON allowed.id = n.id
+          WHERE ${conditions.join(" AND ")}
+          ORDER BY t.status, t.position, n.id`)
+                .bind(...walkBindings(actor, "read"), ...bindings)
+                .all();
+            // ⚠️ The CONFIGURED columns only. The archive column is appended by the service, after the
+            // fallback for an unconfigured board has been applied — appended here it would make every
+            // board look configured, and a board with no columns of its own would answer with the
+            // archive and nothing else.
+            const columns = parseList(board.statuses_json, "columns")
+                .map((entry) => BoardColumn.safeParse(entry))
+                .filter((parsed) => parsed.success)
+                .map((parsed) => parsed.data);
+            return {
+                boardId: board.id,
+                title: board.title,
+                archiveVisible,
+                columns,
+                tasks: (tasks.results ?? []).map((row) => mapTask(row, board.id)),
+            };
+        },
+        async columnsOf(actor, boardId, verb) {
+            const row = await deps.db
+                .prepare(`${subtreeCte}
+          SELECT COALESCE(b.statuses_json, '[]') AS statuses_json
+          FROM nodes n
+          JOIN allowed ON allowed.id = n.id
+          LEFT JOIN boards b ON b.node_id = n.id
+          WHERE n.id = ? AND n.kind = 'board'`)
+                .bind(...walkBindings(actor, verb), boardId)
+                .first();
+            if (row === null)
+                return null;
+            return parseList(row.statuses_json, "columns")
+                .map((entry) => BoardColumn.safeParse(entry))
+                .filter((parsed) => parsed.success)
+                .map((parsed) => parsed.data.id);
+        },
+        async setColumns(boardId, columnsJson, occurredAt, archiveVisible) {
+            // ⚠️ `COALESCE(?, archive_visible)` rather than a second statement: an absent flag means
+            // "leave it", and writing a default here would un-hide an archive somebody put away every
+            // time the columns are reordered.
+            await deps.db
+                .prepare(`INSERT INTO boards (node_id, statuses_json, archive_visible, created_at, updated_at)
+          VALUES (?, ?, COALESCE(?, 1), ?, ?)
+          ON CONFLICT(node_id) DO UPDATE SET statuses_json = excluded.statuses_json,
+                                             archive_visible = COALESCE(?, boards.archive_visible),
+                                             updated_at = excluded.updated_at`)
+                .bind(boardId, columnsJson, archiveVisible === undefined ? null : Number(archiveVisible), occurredAt, occurredAt, archiveVisible === undefined ? null : Number(archiveVisible))
+                .run();
+        },
+        /**
+         * The row that makes a node a card.
+         *
+         * ⚠️ `INSERT … ON CONFLICT DO NOTHING`, because this runs on a path that may already have run:
+         * `nodes.create` under a board writes it, and so does `board_task_create`. Two rows are
+         * impossible (the primary key), and a second call must not overwrite a status somebody has
+         * since changed.
+         */
+        async attach(write) {
+            await deps.db
+                .prepare(`INSERT INTO board_tasks (
+            node_id, board_id, status, assignee_id, labels_json,
+            start_date, due_date, depends_on, position, created_at, updated_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          ON CONFLICT(node_id) DO NOTHING`)
+                .bind(write.nodeId, write.boardId, write.status, write.assigneeId, JSON.stringify(write.labels), write.startDate, write.dueDate, write.dependsOn, write.position, write.occurredAt, write.occurredAt)
+                .run();
+        },
+        async taskRow(actor, taskId, verb) {
+            const row = await deps.db
+                .prepare(`${subtreeCte}
+          SELECT t.node_id, t.board_id, t.status, t.position, n.archived_at, n.updated_at
+          FROM board_tasks t
+          JOIN nodes n ON n.id = t.node_id
+          JOIN allowed ON allowed.id = n.id
+          WHERE t.node_id = ?`)
+                .bind(...walkBindings(actor, verb), taskId)
+                .first();
+            if (row === null)
+                return null;
+            return {
+                nodeId: row.node_id,
+                boardId: row.board_id,
+                status: row.status,
+                position: row.position,
+                archivedAt: row.archived_at,
+                updatedAt: row.updated_at,
+            };
+        },
+        /**
+         * ⚠️ Only the named columns are written, and the statement is built from the fields that
+         * arrived. A full-row `UPDATE` would turn "move this card" into "write every field I happen to
+         * be holding" — and two people editing two different fields of one task would overwrite each
+         * other with values neither of them touched.
+         */
+        async updateTask(taskId, fields, occurredAt) {
+            const sets = ["updated_at = ?"];
+            const bindings = [occurredAt];
+            for (const [column, value] of Object.entries(fields)) {
+                sets.push(`${column} = ?`);
+                bindings.push(value);
+            }
+            await deps.db
+                .prepare(`UPDATE board_tasks SET ${sets.join(", ")} WHERE node_id = ?`)
+                .bind(...bindings, taskId)
+                .run();
+        },
+        async nextPosition(boardId, status) {
+            const row = await deps.db
+                .prepare("SELECT MAX(position) AS top FROM board_tasks WHERE board_id = ? AND status = ?")
+                .bind(boardId, status)
+                .first();
+            // A whole number apart, so the first drop between two cards has room for a midpoint without
+            // needing fractions immediately.
+            return (row?.top ?? 0) + 1;
+        },
+        /**
+         * Who reaches this board once inheritance is resolved (#700, D70).
+         *
+         * ⚠️ ONE statement, hence one D1 snapshot, for the reason `listEffectiveAccess` gives at the
+         * node repository: two parallel SELECTs are not atomic, and a grant mutation between their
+         * snapshots produces a set of people that never existed as a whole.
+         *
+         * ⚠️ It answers the THREE things the caller needs, not a list of grants. A service that
+         * received grant rows here would be one careless `return` away from handing a board's
+         * membership to anyone who can read it; what leaves this method cannot be turned back into who
+         * granted what to whom.
+         *
+         * ⚠️ **A grant can name an EMAIL instead of a user id, and both are real access** (#757). The
+         * first version of this counted only `principal_type = 'user'` and therefore showed nobody on a
+         * board shared by address. Measured on the installation on 2026-08-23: four of nine grants were
+         * `email` ones.
+         *
+         * ⚠️ **Not lowercased here, and that is measured rather than assumed.** The write path already
+         * normalises an address twice (`nodes.ts` before the write, `db-grants.ts` at the boundary), and
+         * the installation confirms it: every stored `email` grant is lowercase. A `lower()` here would
+         * be defence against data that cannot exist, and no test could tell it from a no-op. The side
+         * that DOES need folding is the directory hit, because gate stores what somebody typed at
+         * signup and its casing is not this repository's to decide.
+         *
+         * ⚠️ `verb = 'read'`, and that is not a detail. The verbs here are granted INDEPENDENTLY
+         * (ADR-0004 §2): `write` does not follow from `read` and `read` does not follow from `write`.
+         * Counting any verb would offer somebody who holds only `write` or `share` as an assignee for a
+         * board they cannot open — the exact opposite of what D70 decided, arrived at by asking a
+         * slightly different question than `columnsOrRefuse` asks two lines earlier.
+         *
+         * ⚠️ `UNION`, never `UNION ALL`: a ring in `parent_id` has to end the recursion rather than the
+         * database, the same reason every other walk of this tree gives.
+         */
+        async effectiveAccess(boardId) {
+            const row = await deps.db
+                .prepare(`WITH RECURSIVE ancestors(id, parent_id, owner_id) AS (
+            SELECT id, parent_id, owner_id FROM nodes WHERE 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 ancestors WHERE owner_id IS NOT NULL))
+              AS owner_ids_json,
+            (SELECT json_group_array(principal_id)
+             FROM (
+               SELECT DISTINCT grant_row.principal_id
+               FROM node_grants grant_row
+               JOIN ancestors ON ancestors.id = grant_row.node_id
+               WHERE grant_row.principal_type = 'user'
+                 AND grant_row.principal_id IS NOT NULL
+                 AND grant_row.verb = 'read'
+                 AND ${grantInForce}
+             )) AS principal_ids_json,
+            (SELECT json_group_array(principal_id)
+             FROM (
+               SELECT DISTINCT grant_row.principal_id
+               FROM node_grants grant_row
+               JOIN ancestors ON ancestors.id = grant_row.node_id
+               WHERE grant_row.principal_type = 'email'
+                 AND grant_row.principal_id IS NOT NULL
+                 AND grant_row.verb = 'read'
+                 AND ${grantInForce}
+             )) AS principal_emails_json,
+            (SELECT COUNT(*)
+             FROM node_grants grant_row
+             JOIN ancestors ON ancestors.id = grant_row.node_id
+             WHERE grant_row.principal_type = 'organization'
+               AND grant_row.verb = 'read'
+               AND ${grantInForce}) AS organization_grants`)
+                // ⚠️ ONE `now` per `grantInForce`, and there are three of them since #757: the user
+                // grants, the email grants and the organization count. A missing binding is not a wrong
+                // answer here, it is `D1_ERROR: Wrong number of parameter bindings` — loud, which is the
+                // good case. Read the count off the statement, never off memory.
+                .bind(boardId, deps.now().toISOString(), deps.now().toISOString(), deps.now().toISOString())
+                .first();
+            return {
+                ownerIds: JSON.parse(row?.owner_ids_json ?? "[]"),
+                principalIds: JSON.parse(row?.principal_ids_json ?? "[]"),
+                principalEmails: JSON.parse(row?.principal_emails_json ?? "[]"),
+                organizationWide: (row?.organization_grants ?? 0) > 0,
+            };
+        },
+    };
+}

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

@@ -0,0 +1,30 @@
+import type { FeedRepository } from "../../feed/feed.types.js";
+import type { D1Database } from "./db.types.js";
+export declare const feedPageQuery: string;
+/**
+ * The folders above each of a page's nodes, and only the ones the actor may open.
+ *
+ * ⚠️ **The walk upwards is filtered too, and leaving that out would be a leak.** Grants inherit
+ * DOWNWARDS: a grant handed out on a deep node says nothing about the folders above it. Without the
+ * join against `allowed`, a breadcrumb would spell out the names of folders the reader may not
+ * open — on a surface whose entire premise is that it shows nothing one is not entitled to. A
+ * segment that fails the check drops out, and the trail is simply shorter.
+ *
+ * ⚠️ `UNION` and not `UNION ALL`, and no depth column. A cycle in `parent_id` can reach this table,
+ * 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: {
+    db: D1Database;
+    now(): Date;
+}): FeedRepository;

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

@@ -0,0 +1,276 @@
+import { FeedAction, feedResourceTypeOf, } from "../../contract/feed.js";
+import { flowInSubtreeBindings, flowInSubtreeOver, subtreeBindings, subtreeCte, } from "./db-grants.js";
+// 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) => 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
+    // page down with it: the reader would be stuck at that position with no way past. An unreadable
+    // payload becomes `{}` and the event still arrives — that something happened is the part a feed
+    // cannot afford to lose.
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        return {};
+    }
+    return {};
+}
+/**
+ * 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.
+ *
+ * ⚠️ **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 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 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.
+ *
+ * ⚠️ **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; sorting the journal is not.
+ *
+ * ⚠️ **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. 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
+// gets a validation error instead of a feed. It is a real state and not a theoretical one (#763,
+// found against the running installation): an ADMIN passes `flowInSubtree` on its first branch
+// alone, so events about a flow whose row is gone reach this far, and only `flows.purge` carries a
+// title in its metadata. `flows.create` and `flows.archive` carry none, and there is nothing left
+// to read one from.
+//
+// ⚠️ 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, 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,
+           ${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'
+          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)}
+        )
+        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 = ?)
+      AND (
+        ? IS NULL
+        OR e.occurred_at < ?
+        OR (e.occurred_at = ? AND e.id < ?)
+      )
+    ORDER BY e.occurred_at DESC, e.id DESC
+    LIMIT ?`;
+/**
+ * The folders above each of a page's nodes, and only the ones the actor may open.
+ *
+ * ⚠️ **The walk upwards is filtered too, and leaving that out would be a leak.** Grants inherit
+ * DOWNWARDS: a grant handed out on a deep node says nothing about the folders above it. Without the
+ * join against `allowed`, a breadcrumb would spell out the names of folders the reader may not
+ * open — on a surface whose entire premise is that it shows nothing one is not entitled to. A
+ * segment that fails the check drops out, and the trail is simply shorter.
+ *
+ * ⚠️ `UNION` and not `UNION ALL`, and no depth column. A cycle in `parent_id` can reach this table,
+ * 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(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 grandparent.id, grandparent.parent_id, grandparent.title
+    FROM nodes grandparent
+    JOIN ancestry a ON a.parent_id = grandparent.id
+  )
+  SELECT a.id, a.parent_id, a.title
+  FROM ancestry a
+  JOIN allowed ON allowed.id = a.id`;
+/**
+ * The chain from the root down to (but not including) the node itself.
+ *
+ * Built here rather than in SQL because ordering it there would need a depth counter, and a depth
+ * counter is what turns a cycle into a hang. `seen` is the same guard on this side.
+ *
+ * ⚠️ It starts at the node's OWN `parent_id` and not at "some row with this seed": every ancestor
+ * of a node carries the same seed, and the order rows come back in is not promised. Picking the
+ * first one would put a random grandparent at the near end of the trail.
+ *
+ * ⚠️ The chain stops where visibility stops. If the actor may read a node but not the folder above
+ * it — grants inherit downwards, so a deep grant says nothing about the folders over it — that
+ * folder is absent from `rows`, the walk ends, and the trail is short. Short is the honest answer;
+ * skipping the gap and carrying on with the grandparent would spell out a place the reader cannot
+ * reach.
+ */
+function trailFor(parentId, rows) {
+    const byId = new Map(rows.map((row) => [row.id, row]));
+    const trail = [];
+    const seen = new Set();
+    let current = parentId === null ? undefined : byId.get(parentId);
+    while (current !== undefined && !seen.has(current.id)) {
+        seen.add(current.id);
+        trail.push({ id: current.id, title: current.title });
+        current = current.parent_id === null ? undefined : byId.get(current.parent_id);
+    }
+    return trail.reverse();
+}
+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", 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)
+                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. 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,
+                resourceId: row.resource_id,
+                resourceTitle: row.resource_title,
+                path: trails.get(row.id) ?? [],
+                metadata: parseMetadata(row.metadata_json),
+                occurredAt: row.occurred_at,
+            }));
+            return { events };
+        },
+    };
+}