@anchrd/intel 0.59.0

package/dist/adapters/db/db.js

@@ -0,0 +1,1687 @@
+import { descendantsCte, flowInSubtree, flowInSubtreeBindings, grantColumns as grantColumnsFor, grantInForce, mapGrant, nodeVerbBindings, nodeVerbQuery, principalColumns, subtreeBindings, subtreeCte, } from "./db-grants.js";
+import { promptNameHolder } from "./db-prompts.js";
+const versionColumns = `id, node_id, sequence, content_key, media_type, content_hash,
+  size, segment, created_by, created_at`;
+const grantColumns = grantColumnsFor("node_id");
+const linkColumns = `link.id, link.source_node_id, link.target_node_id, link.relation,
+  link.origin, link.label, link.created_by, link.created_at`;
+// The first row of each node, in the order they arrive. A chunked kind — one whose index holds
+// one row per task (#285) — answers a query once per matching card; a citation names a node, so the
+// best of them is the one that gets to speak for it.
+function dedupedByNode(rows) {
+    const seen = new Set();
+    return rows.filter((row) => {
+        if (seen.has(row.node_id))
+            return false;
+        seen.add(row.node_id);
+        return true;
+    });
+}
+const nodeColumns = `n.id, n.parent_id, n.kind, n.title, n.description,
+  n.owner_id, n.current_version_id, n.created_at, n.updated_at, n.archived_at, n.prompt_name`;
+function mapNode(row) {
+    return {
+        id: row.id,
+        parentId: row.parent_id,
+        kind: row.kind,
+        title: row.title,
+        description: row.description,
+        ownerId: row.owner_id,
+        currentVersionId: row.current_version_id,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        archivedAt: row.archived_at,
+        promptName: row.prompt_name,
+    };
+}
+function mapVersion(row) {
+    return {
+        id: row.id,
+        nodeId: row.node_id,
+        sequence: row.sequence,
+        contentKey: row.content_key,
+        mediaType: row.media_type,
+        contentHash: row.content_hash,
+        size: row.size,
+        segment: row.segment,
+        createdBy: row.created_by,
+        createdAt: row.created_at,
+    };
+}
+function mapLink(row) {
+    return {
+        id: row.id,
+        sourceNodeId: row.source_node_id,
+        targetNodeId: row.target_node_id,
+        relation: row.relation,
+        origin: row.origin,
+        label: row.label,
+        createdBy: row.created_by,
+        createdAt: row.created_at,
+    };
+}
+function toFtsQuery(query) {
+    return query
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((token) => `"${token.replaceAll('"', '""')}"`)
+        .join(" AND ");
+}
+export function createNodeRepository(deps) {
+    // Reading is one verb among four; the tree walk itself lives in db-grants.ts so Flows asks the
+    // same question of the same table.
+    const visibleCte = subtreeCte;
+    const readBindings = (actor) => subtreeBindings(actor, "read", deps.now().toISOString());
+    /**
+     * What a LEVEL query binds: the walk over `nodes`, then the flow half of `has_children`, in the
+     * order the two appear in the statement.
+     *
+     * ⚠️ One clock reading for both halves. Two calls to `deps.now()` inside one statement would
+     * measure the same `expires_at` against two different moments, and a grant that expires between
+     * them would be honoured on one side of the OR and refused on the other.
+     */
+    const levelBindings = (actor) => {
+        const now = deps.now().toISOString();
+        return [...subtreeBindings(actor, "read", now), ...flowInSubtreeBindings(actor, "read", now)];
+    };
+    /**
+     * The optional folder cut a search carries (#126), in the three places one statement needs it:
+     * the extra CTE, the extra join, and the one binding between the actor's and the query's. All
+     * three are absent together when there is no scope, so an unscoped search runs the exact
+     * statement it ran before.
+     *
+     * ⚠️ The join is added *beside* `allowed`, never instead of it. `descendants` is seeded from a
+     * caller-supplied id and knows nothing about grants; on its own it would answer "everything under
+     * this folder" to anyone who names the folder.
+     */
+    const scopeCte = (scopeId) => scopeId === undefined ? "" : `,\n${descendantsCte}`;
+    const scopeJoin = (scopeId) => scopeId === undefined ? "" : "\n          JOIN descendants ON descendants.id = n.id";
+    const scopeBindings = (scopeId) => (scopeId === undefined ? [] : [scopeId]);
+    /**
+     * Which rows belong to the level being asked for.
+     *
+     * ⚠️ At the ROOT this is not `parent_id IS NULL` but "the top of every region this actor may
+     * read" (#429). A grant on a nested folder has no entry point otherwise: the way to it leads
+     * through a folder the recipient may not see, so the level it would appear in can never be
+     * opened, and the share stays usable only for whoever passes the URL around by hand. It is the
+     * same seed `listVisibleSubtree` already starts a whole-installation export from — written once
+     * more rather than differently.
+     *
+     * ⚠️ It says nothing about the way there. A row carries its own id and its own title, both of
+     * which `getVisible` already answers to this actor; the ancestors it hangs under are never read,
+     * named or counted, so the title of an unreadable parent folder stays where it was.
+     *
+     * ⚠️ Both `?` take the SAME value, and the second is not redundant: SQLite binds by position, so
+     * asking "was the root asked for" needs its own placeholder rather than a second reading of the
+     * first.
+     */
+    const levelPredicate = `(
+      n.parent_id IS ?
+      OR (? IS NULL AND n.parent_id NOT IN (SELECT id FROM allowed))
+    )`;
+    /**
+     * One statement for the level the tree reads and for the bounded read the relation graph makes,
+     * so the visibility predicate cannot drift between them.
+     *
+     * ⚠️ In the bounded form `LIMIT` follows the `WHERE`, so the cut falls among the rows this actor
+     * may see and never before them, and `COUNT(*) OVER ()` counts those same rows alone (#30).
+     */
+    /**
+     * The kinds the FOLDER TREE does not show. A task belongs to its board and is reached there
+     * (D66, #376); the tree would otherwise flood with three hundred cards, which is the objection
+     * that sank the node-per-task idea the first time it was proposed.
+     *
+     * ⚠️ It is a cut in the STATEMENT, not a filter in the interface. Filtered later, the rows have
+     * already crossed the wire — titles of other people's tasks inside an answer that was not
+     * supposed to carry them.
+     *
+     * ⚠️ It says nothing about reachability. A task keeps its own address, its own grants and its own
+     * place in search and in the relation graph; only this one level query looks away. Hiding it
+     * everywhere would make a link to a task a dead end.
+     */
+    const notInTree = (alias) => `${alias}.kind <> 'task'`;
+    /**
+     * The chevron column, and it is drawn ONLY for the tree (#777). The bounded read the relation
+     * graph makes discards it, and since #777 it is no longer free: computing it costs a second
+     * correlated `EXISTS` per row and six bindings that statement has no other use for. Leaving it
+     * out there is not a divergence in the visibility predicate, which is what the two forms share;
+     * it is one column the caller never reads.
+     */
+    const chevronColumn = `
+      -- Whether this row has children THIS actor may see (#59), asked of the same allowed set one
+      -- level down. A second rule written here would drift from the one above it, and the drift
+      -- would show as a chevron that opens onto nothing.
+      --
+      -- ⚠️ The same cut here as below, and it is the SAME rule read twice rather
+      -- than a second one: a board's children are all tasks, so with them hidden it has none this
+      -- actor can see, and the chevron falls away by itself (D66, #376). Leaving it out here would
+      -- draw a chevron that opens onto an empty level — exactly the drift the comment above warns
+      -- about, arriving through the door it was written for.
+      --
+      -- ⚠️ And the SECOND half of the level, because the tree is shared: a folder holds nodes and
+      -- flows side by side (ADR-0004 §1), and a flow is not a node. Asking only the nodes table
+      -- left a folder whose only children are flows answering "empty": no chevron, no way down,
+      -- while clicking the folder listed both kinds perfectly well (#777). It is the same root as
+      -- #457, where a count over nodes alone held such a folder for empty on the delete path; that
+      -- one was fixed, this one was not.
+      --
+      -- ⚠️ flowInSubtree rather than a hand-written condition, for the reason stated above it: it
+      -- is the very predicate db-flows.ts draws the level with, so the chevron and the level it
+      -- opens onto cannot answer differently. Its folder clause is already satisfied here (the
+      -- flow's parent is n, and n is joined to allowed), so today it can only widen the answer,
+      -- never narrow it, which is the only direction a chevron may drift in at all.
+      (EXISTS (
+        SELECT 1 FROM nodes child
+        JOIN allowed AS allowed_child ON allowed_child.id = child.id
+        WHERE child.parent_id = n.id AND child.archived_at IS NULL AND ${notInTree("child")}
+      ) OR EXISTS (
+        SELECT 1 FROM flows flow
+        WHERE flow.parent_id = n.id AND flow.archived_at IS NULL AND ${flowInSubtree}
+      )) AS has_children`;
+    const visibleChildren = (bounded) => `${visibleCte}
+    SELECT ${nodeColumns}${bounded ? ", COUNT(*) OVER () AS total" : `,${chevronColumn}`}
+    FROM nodes n
+    JOIN allowed ON allowed.id = n.id
+    WHERE ${levelPredicate} AND (? = 1 OR n.archived_at IS NULL) AND ${notInTree("n")}
+    ORDER BY CASE n.kind WHEN 'folder' THEN 0 ELSE 1 END, lower(n.title), n.id${bounded ? " LIMIT ?" : ""}`;
+    /**
+     * Everything archived that this actor may see, wherever it sits (#113).
+     *
+     * ⚠️ No `parent_id` at all, and that is the point rather than an omission: somebody looking for
+     * what they archived does not know which folder it was in. The visibility predicate is the same
+     * `allowed` set every other read uses, so the archive shows no more than the tree would have.
+     *
+     * `has_children` is answered as 0 without asking: an archived row is not expandable — its
+     * children are reached by restoring it, not by opening it here.
+     */
+    const archivedEverywhere = `${visibleCte}
+    SELECT ${nodeColumns}, 0 AS has_children
+    FROM nodes n
+    JOIN allowed ON allowed.id = n.id
+    WHERE n.archived_at IS NOT NULL
+    ORDER BY n.archived_at DESC, lower(n.title), n.id`;
+    return {
+        async listVisible(actor, input) {
+            const result = await deps.db
+                .prepare(input.archivedOnly ? archivedEverywhere : visibleChildren(false))
+                .bind(
+            // ⚠️ The archive statement answers `has_children` as a literal 0, so it carries no flow
+            // bindings; the level statement carries both halves. Same branch, two bind lists.
+            ...(input.archivedOnly
+                ? readBindings(actor)
+                : [
+                    ...levelBindings(actor),
+                    input.parentId,
+                    input.parentId,
+                    input.includeArchived ? 1 : 0,
+                ]))
+                .all();
+            const rows = result.results ?? [];
+            return {
+                items: rows.map(mapNode),
+                withChildren: rows.filter((row) => row.has_children === 1).map((row) => row.id),
+            };
+        },
+        async listVisibleBounded(actor, input) {
+            const result = await deps.db
+                .prepare(visibleChildren(true))
+                // ⚠️ `readBindings`, not `levelBindings`: this form carries no chevron column, so the
+                // flow half's six bindings have no placeholder to land in. D1 answers a miscount with
+                // `Wrong number of parameter bindings`, so the two cannot silently go out of step.
+                .bind(...readBindings(actor), input.parentId, input.parentId, 0, input.limit)
+                .all();
+            const rows = result.results ?? [];
+            return { items: rows.map(mapNode), total: rows[0]?.total ?? 0 };
+        },
+        async getVisible(actor, nodeId) {
+            const row = await deps.db
+                .prepare(`${visibleCte}
+          SELECT ${nodeColumns}
+          FROM nodes n
+          JOIN allowed ON allowed.id = n.id
+          WHERE n.id = ?`)
+                .bind(...readBindings(actor), nodeId)
+                .first();
+            return row ? mapNode(row) : null;
+        },
+        /**
+         * The readable subtree as one statement (#136): the `allowed` walk says what the actor may
+         * read, and `walk` says what hangs together under the chosen root. Both joins apply at every
+         * step, so the walk neither descends into an archived node nor through an unreadable one — a
+         * child the actor may read under a folder they may not stays out, because the bundle would have
+         * no path to file it under.
+         *
+         * ⚠️ `UNION`, never `UNION ALL`, for the reason `nodeVerbQuery` gives: a cycle in `parent_id`
+         * can reach the table and this walks downwards into it.
+         */
+        async listVisibleSubtree(actor, rootId) {
+            const seed = rootId === null
+                ? // "Everything this actor may read": the top of every readable region, not only the top
+                    // of the tree. A reader who holds a grant on one nested folder has that folder as the
+                    // top of what they see, and their whole-installation export starts there.
+                    "(seed.parent_id IS NULL OR seed.parent_id NOT IN (SELECT id FROM allowed))"
+                : // The root node itself is the seed; whether it is a folder is the service's question.
+                    "seed.id = ?";
+            const result = await deps.db
+                .prepare(`${visibleCte},
+          walk(id) AS (
+            SELECT seed.id FROM nodes seed
+            JOIN allowed ON allowed.id = seed.id
+            WHERE ${seed} AND seed.archived_at IS NULL
+            UNION
+            SELECT child.id FROM nodes child
+            JOIN walk ON child.parent_id = walk.id
+            JOIN allowed AS allowed_child ON allowed_child.id = child.id
+            WHERE child.archived_at IS NULL
+          )
+          SELECT ${nodeColumns},
+            version.id AS version_id, version.media_type, version.content_key
+          FROM nodes n
+          JOIN walk ON walk.id = n.id
+          LEFT JOIN node_versions version ON version.id = n.current_version_id`)
+                .bind(...readBindings(actor), ...(rootId === null ? [] : [rootId]))
+                .all();
+            return (result.results ?? []).map((row) => ({
+                node: mapNode(row),
+                version: row.version_id === null || row.media_type === null || row.content_key === null
+                    ? null
+                    : { id: row.version_id, mediaType: row.media_type, contentKey: row.content_key },
+            }));
+        },
+        /**
+         * One bundle import as one transaction (#137). Every table takes its rows from a single JSON
+         * parameter through `json_each`, so the statement count stays constant however large the
+         * bundle is — the same reason `idList` exists in db-flows — and `db.batch` makes the whole
+         * import land or refuse as one.
+         *
+         * ⚠️ `nodes` arrive parents before children: `parent_id REFERENCES nodes(id)` is checked as
+         * each row lands, and a child before its parent would abort the batch that is otherwise valid.
+         * The service owns that order; this only writes what it is handed.
+         */
+        async importTree(input) {
+            const statements = [
+                deps.db
+                    .prepare(`INSERT INTO nodes (
+            id, parent_id, kind, title, description, owner_id,
+            current_version_id, created_at, updated_at, archived_at
+          ) SELECT
+            json_extract(value, '$.id'), json_extract(value, '$.parentId'),
+            json_extract(value, '$.kind'), json_extract(value, '$.title'),
+            json_extract(value, '$.description'),
+            json_extract(value, '$.ownerId'), json_extract(value, '$.currentVersionId'),
+            json_extract(value, '$.createdAt'), json_extract(value, '$.updatedAt'), NULL
+          FROM json_each(?)`)
+                    .bind(JSON.stringify(input.nodes)),
+                deps.db
+                    .prepare(`INSERT INTO node_versions (
+            id, node_id, sequence, content_key, media_type, content_hash, size, segment,
+            created_by, created_at
+          ) SELECT
+            json_extract(value, '$.id'), json_extract(value, '$.nodeId'),
+            json_extract(value, '$.sequence'), json_extract(value, '$.contentKey'),
+            json_extract(value, '$.mediaType'), json_extract(value, '$.contentHash'),
+            json_extract(value, '$.size'), json_extract(value, '$.segment'),
+            json_extract(value, '$.createdBy'), json_extract(value, '$.createdAt')
+          FROM json_each(?)`)
+                    .bind(JSON.stringify(input.versions)),
+                deps.db
+                    .prepare(`INSERT INTO node_links (
+            id, source_node_id, target_node_id, relation, origin, label, created_by, created_at
+          ) SELECT
+            json_extract(value, '$.id'), json_extract(value, '$.sourceNodeId'),
+            json_extract(value, '$.targetNodeId'), 'references', 'text', NULL, ?, ?
+          FROM json_each(?)`)
+                    .bind(input.actorId, input.occurredAt, JSON.stringify(input.links)),
+                deps.db
+                    .prepare(`INSERT INTO flows (
+            id, parent_id, title, description, owner_id, current_version_id,
+            published_version_id, created_at, updated_at, archived_at
+          ) SELECT
+            json_extract(value, '$.id'), json_extract(value, '$.parentId'),
+            json_extract(value, '$.title'), json_extract(value, '$.description'),
+            json_extract(value, '$.ownerId'), json_extract(value, '$.currentVersionId'),
+            json_extract(value, '$.publishedVersionId'), json_extract(value, '$.createdAt'),
+            json_extract(value, '$.updatedAt'), NULL
+          FROM json_each(?)`)
+                    .bind(JSON.stringify(input.flows)),
+                deps.db
+                    .prepare(`INSERT INTO flow_versions (
+            id, flow_id, sequence, graph_json, created_by, created_at
+          ) SELECT
+            json_extract(value, '$.id'), json_extract(value, '$.flowId'),
+            -- json_extract of an object answers with its JSON text, which is exactly what the
+            -- graph_json column stores.
+            json_extract(value, '$.sequence'), json_extract(value, '$.graph'),
+            json_extract(value, '$.createdBy'), json_extract(value, '$.createdAt')
+          FROM json_each(?)`)
+                    .bind(JSON.stringify(input.flowVersions)),
+                // ⚠️ The idempotency row stores the AUDIT id, unlike its siblings that store the resource:
+                // one import creates many resources, and the collective audit event is where the summary a
+                // replay answers with is kept.
+                deps.db
+                    .prepare(`INSERT INTO idempotency_keys (
+            actor_id, operation, idempotency_key, resource_id, created_at
+          ) VALUES (?, 'node.import', ?, ?, ?)`)
+                    .bind(input.actorId, input.idempotencyKey, input.auditId, input.occurredAt),
+                deps.db
+                    .prepare(`INSERT INTO audit_events (
+            id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+          ) VALUES (?, ?, 'node.import', 'node', ?, ?, ?)`)
+                    .bind(input.auditId, input.actorId, input.auditResourceId, JSON.stringify(input.metadata), input.occurredAt),
+            ];
+            try {
+                await deps.db.batch(statements);
+                return "created";
+            }
+            catch (error) {
+                const replayed = await this.findImportReplay(input.actorId, input.idempotencyKey);
+                if (replayed !== null)
+                    return "replayed";
+                throw error;
+            }
+        },
+        /**
+         * What an earlier write with this key recorded about itself (#285).
+         *
+         * ⚠️ The idempotency row points at the VERSION, and the audit event points at the node, so the
+         * two are joined through the version id the snapshot writer puts into the metadata. That
+         * metadata is where a snapshot says which positions it touched and how many it removed —
+         * facts a replay cannot recompute from the stored document, because the document is the state
+         * AFTER the write. Without this, repeating a delete would answer with a count nobody measured.
+         */
+        async findSnapshotMetadata(actorId, operation, idempotencyKey) {
+            const row = await deps.db
+                .prepare(`SELECT audit.metadata_json AS metadata_json
+          FROM idempotency_keys keys
+          JOIN audit_events audit
+            ON audit.action = keys.operation
+            AND json_extract(audit.metadata_json, '$.versionId') = keys.resource_id
+          WHERE keys.actor_id = ? AND keys.operation = ? AND keys.idempotency_key = ?`)
+                .bind(actorId, operation, idempotencyKey)
+                .first();
+            if (!row)
+                return null;
+            const parsed = JSON.parse(row.metadata_json);
+            return typeof parsed === "object" && parsed !== null
+                ? parsed
+                : null;
+        },
+        async findImportReplay(actorId, idempotencyKey) {
+            const row = await deps.db
+                .prepare(`SELECT audit.metadata_json AS metadata_json
+          FROM idempotency_keys keys
+          JOIN audit_events audit ON audit.id = keys.resource_id
+          WHERE keys.actor_id = ? AND keys.operation = 'node.import'
+            AND keys.idempotency_key = ?`)
+                .bind(actorId, idempotencyKey)
+                .first();
+            if (!row)
+                return null;
+            const parsed = JSON.parse(row.metadata_json);
+            return typeof parsed === "object" && parsed !== null
+                ? parsed
+                : null;
+        },
+        async can(actor, nodeId, verb) {
+            const row = await deps.db
+                .prepare(nodeVerbQuery)
+                .bind(...nodeVerbBindings(nodeId, actor, verb, deps.now().toISOString()))
+                .first();
+            return row?.allowed === 1;
+        },
+        async findIdempotentNode(actorId, operation, idempotencyKey) {
+            const row = await deps.db
+                .prepare(`SELECT resource_id FROM idempotency_keys
+          WHERE actor_id = ? AND operation = ? AND idempotency_key = ?`)
+                .bind(actorId, operation, idempotencyKey)
+                .first();
+            return row?.resource_id ?? null;
+        },
+        async findIdempotentRevocation(actorId, idempotencyKey) {
+            const row = await deps.db
+                .prepare(`SELECT resource_id FROM idempotency_keys
+          WHERE actor_id = ? AND operation = 'node.revoke' AND idempotency_key = ?`)
+                .bind(actorId, idempotencyKey)
+                .first();
+            if (!row)
+                return null;
+            return row.resource_id.startsWith("1:");
+        },
+        async insertNode(input) {
+            const node = input.node;
+            try {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`INSERT INTO nodes (
+            id, parent_id, kind, title, description, owner_id,
+            current_version_id, created_at, updated_at, archived_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                        .bind(node.id, node.parentId, node.kind, node.title, node.description, node.ownerId, node.currentVersionId, node.createdAt, node.updatedAt, node.archivedAt),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+            actor_id, operation, idempotency_key, resource_id, created_at
+          ) VALUES (?, 'node.create', ?, ?, ?)`)
+                        .bind(input.actorId, input.idempotencyKey, node.id, node.createdAt),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+            id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+          ) VALUES (?, ?, 'node.create', 'node', ?, ?, ?)`)
+                        .bind(input.auditId, input.actorId, node.id, JSON.stringify({ kind: node.kind, parentId: node.parentId }), node.createdAt),
+                ]);
+            }
+            catch (error) {
+                const replayedKey = await deps.db
+                    .prepare(`SELECT resource_id FROM idempotency_keys
+            WHERE actor_id = ? AND operation = 'node.create' AND idempotency_key = ?`)
+                    .bind(input.actorId, input.idempotencyKey)
+                    .first();
+                if (replayedKey) {
+                    const replayed = await deps.db
+                        .prepare(`${visibleCte}
+              SELECT ${nodeColumns}
+              FROM nodes n
+              JOIN allowed ON allowed.id = n.id
+              WHERE n.id = ?`)
+                        .bind(...readBindings({ id: input.actorId, email: "" }), replayedKey.resource_id)
+                        .first();
+                    if (replayed)
+                        return mapNode(replayed);
+                }
+                throw error;
+            }
+            return node;
+        },
+        async getVersion(versionId) {
+            const row = await deps.db
+                .prepare(`SELECT ${versionColumns} FROM node_versions WHERE id = ?`)
+                .bind(versionId)
+                .first();
+            return row ? mapVersion(row) : null;
+        },
+        // From the newest snapshot on (#135). `COALESCE(..., 0)` keeps a table from before snapshots
+        // readable in full: without any snapshot row every segment still counts.
+        async listVersionContentKeys(nodeId) {
+            const result = await deps.db
+                .prepare(`SELECT content_key FROM node_versions
+          WHERE node_id = ? AND sequence >= COALESCE((
+            SELECT MAX(sequence) FROM node_versions
+            WHERE node_id = ? AND segment = 'snapshot'
+          ), 0)
+          ORDER BY sequence`)
+                .bind(nodeId, nodeId)
+                .all();
+            return (result.results ?? []).map((row) => row.content_key);
+        },
+        async tableHeaderContentKey(nodeId) {
+            const row = await deps.db
+                .prepare(`SELECT content_key FROM node_versions
+          WHERE node_id = ? AND segment = 'snapshot'
+          ORDER BY sequence DESC LIMIT 1`)
+                .bind(nodeId)
+                .first();
+            return row?.content_key ?? null;
+        },
+        async listVersions(nodeId) {
+            const result = await deps.db
+                .prepare(`SELECT ${versionColumns}
+          FROM node_versions
+          WHERE node_id = ?
+          ORDER BY sequence DESC`)
+                .bind(nodeId)
+                .all();
+            return (result.results ?? []).map(mapVersion);
+        },
+        /**
+         * ⚠️ **The prompt name is the one field here whose write can fail for a reason that is not a
+         * conflict, and its guard sits ON the statement rather than in front of it** (#775). A
+         * `SELECT` beforehand decides on a state that may be gone by the time the `UPDATE` lands; the
+         * condition below is evaluated inside the same transaction as the write it guards.
+         *
+         * ⚠️ **And it is on every statement of the batch, not only the first** — `destructive.md`,
+         * `anchrd/intel#457`. A statement matching zero rows is not an error and the batch commits
+         * anyway, so the idempotency row and the audit row carry the same `prompt_name IS ?` the
+         * `UPDATE` carries. Without it a refused rename would still be booked as done, and the replay
+         * path would hand the caller back a node it never wrote.
+         *
+         * ⚠️ `other.id <> ?` is what lets a node keep its OWN name. Writing the name it already holds
+         * is the everyday case — every `node_update` that changes a title sends the current prompt
+         * name along — and without the exclusion the node would be refused for colliding with itself.
+         */
+        async updateNode(input) {
+            const node = input.node;
+            try {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`WITH RECURSIVE descendants(id) AS (
+              SELECT id FROM nodes WHERE id = ?
+              UNION ALL
+              SELECT child.id
+              FROM nodes child
+              JOIN descendants parent ON child.parent_id = parent.id
+            )
+            UPDATE nodes
+            SET parent_id = ?, title = ?, description = ?, prompt_name = ?, updated_at = ?
+            WHERE id = ? AND updated_at = ?
+              AND (? IS NULL OR ? NOT IN (SELECT id FROM descendants))
+              AND (
+                ? IS NULL
+                OR (
+                  NOT EXISTS (
+                    SELECT 1 FROM nodes other WHERE other.prompt_name = ? AND other.id <> ?
+                  )
+                  AND NOT EXISTS (SELECT 1 FROM flows holder WHERE holder.prompt_name = ?)
+                )
+              )`)
+                        .bind(node.id, node.parentId, node.title, node.description, node.promptName, node.updatedAt, node.id, input.baseUpdatedAt, node.parentId, node.parentId, node.promptName, node.promptName, node.id, node.promptName),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'node.update', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM nodes
+              WHERE id = ? AND parent_id IS ? AND title = ? AND description IS ?
+                AND prompt_name IS ? AND updated_at = ?
+            )`)
+                        .bind(input.actorId, input.idempotencyKey, node.id, node.updatedAt, node.id, node.parentId, node.title, node.description, node.promptName, node.updatedAt),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'node.update', 'node', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM idempotency_keys
+              WHERE actor_id = ? AND operation = 'node.update'
+                AND idempotency_key = ? AND resource_id = ?
+            )`)
+                        .bind(input.auditId, input.actorId, node.id, JSON.stringify({
+                        parentId: node.parentId,
+                        title: node.title,
+                    }), node.updatedAt, input.actorId, input.idempotencyKey, node.id),
+                ]);
+            }
+            catch (error) {
+                const replayed = await deps.db
+                    .prepare(`SELECT resource_id FROM idempotency_keys
+            WHERE actor_id = ? AND operation = 'node.update' AND idempotency_key = ?`)
+                    .bind(input.actorId, input.idempotencyKey)
+                    .first();
+                if (!replayed)
+                    throw error;
+            }
+            const replayed = await deps.db
+                .prepare(`SELECT resource_id FROM idempotency_keys
+          WHERE actor_id = ? AND operation = 'node.update' AND idempotency_key = ?`)
+                .bind(input.actorId, input.idempotencyKey)
+                .first();
+            if (replayed) {
+                const row = await deps.db
+                    .prepare(`SELECT ${nodeColumns} FROM nodes n WHERE n.id = ?`)
+                    .bind(replayed.resource_id)
+                    .first();
+                if (row)
+                    return mapNode(row);
+            }
+            if (node.parentId !== null) {
+                const cycle = await deps.db
+                    .prepare(`WITH RECURSIVE descendants(id) AS (
+            SELECT id FROM nodes WHERE id = ?
+            UNION ALL
+            SELECT child.id
+            FROM nodes child
+            JOIN descendants parent ON child.parent_id = parent.id
+          )
+          SELECT 1 AS found FROM descendants WHERE id = ? LIMIT 1`)
+                    .bind(node.id, node.parentId)
+                    .first();
+                if (cycle?.found === 1)
+                    return "cycle";
+            }
+            /**
+             * ⚠️ **Which of the two refusals it was, asked only once the write has already failed.** The
+             * condition on the statement is what makes the guard hold; this read is what makes the answer
+             * sayable. Doing it the other way round — deciding here and writing unguarded — is the shape
+             * that loses the race it was written for.
+             *
+             * ⚠️ It is asked of BOTH tables, because the name is one catalogue across the two (#775). A
+             * check against `nodes` alone answers "free" for a name a published flow holds, and the write
+             * would then keep failing with a message that says the node was changed by another editor.
+             */
+            if (node.promptName !== null) {
+                const taken = await deps.db
+                    .prepare(`SELECT 1 AS found FROM nodes WHERE prompt_name = ? AND id <> ?
+            UNION ALL
+            SELECT 1 AS found FROM flows WHERE prompt_name = ?
+            LIMIT 1`)
+                    .bind(node.promptName, node.id, node.promptName)
+                    .first();
+                if (taken?.found === 1)
+                    return "prompt_name_taken";
+            }
+            return "conflict";
+        },
+        async promptNameHolder(actor, name) {
+            // One question, one implementation, shared with the flow repository — see `db-prompts.ts`.
+            return await promptNameHolder(deps, actor, name);
+        },
+        async archiveNode(input) {
+            const archiving = input.archivedAt !== null;
+            /**
+             * ⚠️ **The operation a node falls with, read BEFORE anything moves** (D71, #733).
+             *
+             * Archiving takes the whole subtree, so a restore needs to know which nodes fell TOGETHER —
+             * anything already archived before keeps its own older operation and stays archived. On the
+             * way in that is the new id; on the way back it is the one the root already carries, and it
+             * has to be read here because the first statement below clears it.
+             *
+             * ⚠️ `NULL` is not a group. A node archived before this migration carries `NULL`, and
+             * restoring it must bring back that node alone — matching on `NULL` would revive every node
+             * ever archived before the migration ran.
+             */
+            const group = archiving
+                ? input.operationId
+                : ((await deps.db
+                    .prepare("SELECT archived_with FROM nodes WHERE id = ?")
+                    .bind(input.nodeId)
+                    .first())?.archived_with ?? null);
+            const subtree = `WITH RECURSIVE tree(id) AS (
+        SELECT id FROM nodes WHERE id = ?
+        UNION SELECT child.id FROM nodes child JOIN tree parent ON child.parent_id = parent.id
+      )`;
+            /**
+             * ⚠️ **Every cascading statement carries the same guard, not just the first** (#457). A
+             * `D1.batch` is one transaction, but a statement matching zero rows is not an error — so
+             * without `EXISTS` on the root the children would fall while the root stayed put, taken out
+             * by the `updated_at` guard on statement one, and the caller would be told about a conflict
+             * that had already half happened.
+             */
+            const rootMoved = archiving
+                ? "EXISTS (SELECT 1 FROM nodes WHERE id = ? AND archived_at = ? AND archived_with = ?)"
+                : "EXISTS (SELECT 1 FROM nodes WHERE id = ? AND archived_at IS NULL)";
+            const cascade = archiving
+                ? [
+                    // The subtree, minus what was already archived: those keep their own operation.
+                    deps.db
+                        .prepare(`${subtree}
+                UPDATE nodes SET archived_at = ?, archived_with = ?, updated_at = ?
+                WHERE id IN (SELECT id FROM tree) AND id != ? AND archived_at IS NULL
+                  AND ${rootMoved}`)
+                        .bind(input.nodeId, input.archivedAt, input.operationId, input.updatedAt, input.nodeId, input.nodeId, input.archivedAt, input.operationId),
+                    // Flows hang in the same tree by `parent_id` and carry their own `archived_at`.
+                    deps.db
+                        .prepare(`${subtree}
+                UPDATE flows SET archived_at = ?, archived_with = ?, updated_at = ?
+                WHERE parent_id IN (SELECT id FROM tree) AND archived_at IS NULL
+                  AND ${rootMoved}`)
+                        .bind(input.nodeId, input.archivedAt, input.operationId, input.updatedAt, input.nodeId, input.archivedAt, input.operationId),
+                ]
+                : group === null
+                    ? []
+                    : [
+                        /**
+                         * ⚠️ **The group AND the subtree, not the group alone** (found in review of #738).
+                         * Matching on the operation by itself made restoring a leaf bring back its former
+                         * parent and every sibling that fell with it: one card pulled out of a board's
+                         * archive column put the whole card tree back. The walk starts at the node being
+                         * restored, so a leaf restores itself and a folder restores what hangs under it.
+                         */
+                        deps.db
+                            .prepare(`${subtree}
+                  UPDATE nodes SET archived_at = NULL, archived_with = NULL, updated_at = ?
+                  WHERE id IN (SELECT id FROM tree) AND id != ? AND archived_with = ?
+                    AND ${rootMoved}`)
+                            .bind(input.nodeId, input.updatedAt, input.nodeId, group, input.nodeId),
+                        deps.db
+                            .prepare(`${subtree}
+                  UPDATE flows SET archived_at = NULL, archived_with = NULL, updated_at = ?
+                  WHERE parent_id IN (SELECT id FROM tree) AND archived_with = ?
+                    AND ${rootMoved}`)
+                            .bind(input.nodeId, input.updatedAt, group, input.nodeId),
+                    ];
+            // How many rows this operation moves besides the root, read before it moves them: the journal
+            // line is written inside the same batch and cannot count what it is doing.
+            const cascadeSize = archiving
+                ? ((await deps.db
+                    .prepare(`WITH RECURSIVE tree(id) AS (
+                SELECT id FROM nodes WHERE id = ?
+                UNION SELECT child.id FROM nodes child JOIN tree parent ON child.parent_id = parent.id
+              )
+              SELECT (SELECT COUNT(*) FROM nodes WHERE id IN (SELECT id FROM tree) AND id != ?
+                        AND archived_at IS NULL)
+                   + (SELECT COUNT(*) FROM flows WHERE parent_id IN (SELECT id FROM tree)
+                        AND archived_at IS NULL) AS total`)
+                    .bind(input.nodeId, input.nodeId)
+                    .first())?.total ?? 0)
+                : group === null
+                    ? 0
+                    : ((await deps.db
+                        .prepare(`WITH RECURSIVE tree(id) AS (
+                  SELECT id FROM nodes WHERE id = ?
+                  UNION SELECT child.id FROM nodes child JOIN tree parent ON child.parent_id = parent.id
+                )
+                SELECT (SELECT COUNT(*) FROM nodes WHERE id IN (SELECT id FROM tree) AND id != ?
+                          AND archived_with = ?)
+                     + (SELECT COUNT(*) FROM flows WHERE parent_id IN (SELECT id FROM tree)
+                          AND archived_with = ?) AS total`)
+                        .bind(input.nodeId, input.nodeId, group, group)
+                        .first())?.total ?? 0);
+            try {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`UPDATE nodes
+              SET archived_at = ?, archived_with = ?, updated_at = ?
+              WHERE id = ? AND updated_at = ?`)
+                        .bind(input.archivedAt, archiving ? input.operationId : null, input.updatedAt, input.nodeId, input.baseUpdatedAt),
+                    ...cascade,
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'node.archive', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM nodes
+              WHERE id = ? AND archived_at IS ? AND updated_at = ?
+            )`)
+                        .bind(input.actorId, input.idempotencyKey, input.nodeId, input.updatedAt, input.nodeId, input.archivedAt, input.updatedAt),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'node.archive', 'node', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM idempotency_keys
+              WHERE actor_id = ? AND operation = 'node.archive'
+                AND idempotency_key = ? AND resource_id = ?
+            )`)
+                        .bind(input.auditId, input.actorId, input.nodeId, 
+                    /**
+                     * ⚠️ **The operation and the SIZE of what moved** (D71, #733). One `node.archive` now
+                     * moves a whole subtree, and the change journal (#747) reads this table: without the
+                     * count, archiving a folder makes N documents disappear from every list behind a
+                     * single line that names only the folder.
+                     *
+                     * ⚠️ What this row does NOT carry is WHICH nodes fell. After a restore the column is
+                     * cleared, so that list is gone; if it is ever needed, it needs its own row per node
+                     * and that is a decision, not a detail.
+                     */
+                    JSON.stringify({
+                        archived: input.archivedAt !== null,
+                        operation: group,
+                        cascaded: cascadeSize,
+                    }), input.updatedAt, input.actorId, input.idempotencyKey, input.nodeId),
+                ]);
+            }
+            catch (error) {
+                const replayed = await deps.db
+                    .prepare(`SELECT resource_id FROM idempotency_keys
+            WHERE actor_id = ? AND operation = 'node.archive' AND idempotency_key = ?`)
+                    .bind(input.actorId, input.idempotencyKey)
+                    .first();
+                if (!replayed)
+                    throw error;
+            }
+            const replayed = await deps.db
+                .prepare(`SELECT resource_id FROM idempotency_keys
+          WHERE actor_id = ? AND operation = 'node.archive' AND idempotency_key = ?`)
+                .bind(input.actorId, input.idempotencyKey)
+                .first();
+            if (!replayed)
+                return "conflict";
+            const row = await deps.db
+                .prepare(`SELECT ${nodeColumns} FROM nodes n WHERE n.id = ?`)
+                .bind(replayed.resource_id)
+                .first();
+            return row ? mapNode(row) : "conflict";
+        },
+        async parentArchivedAt(nodeId) {
+            // ⚠️ **No visibility predicate, and that is the whole point of this query** (found in review
+            // of #738). A grant can sit on a single node (ADR-0004 §2), so whoever may restore a child may
+            // well not see the folder above it. Asked through `getVisible`, that folder answers `null`,
+            // the guard reads "not archived", and a live node ends up under an archived one — where the
+            // purge takes it unnamed. It is the same lesson `countLiveChildren` carried before D71
+            // replaced it, and the same mistake was made again in its place.
+            //
+            // It leaks one timestamp about a node the caller cannot open. The alternative leaks the node
+            // itself, permanently.
+            const row = await deps.db
+                .prepare("SELECT archived_at, kind FROM nodes WHERE id = ?")
+                .bind(nodeId)
+                .first();
+            return row ? { archivedAt: row.archived_at, kind: row.kind } : null;
+        },
+        async versionIdsInSubtree(nodeId) {
+            // ⚠️ No visibility predicate and no archived filter, for the reason `hasAnyChild` gives: this
+            // answers what the INDEX has to be told about, not what somebody may look at. A node whose
+            // vectors stay behind pays for itself out of everybody else's search results (#348).
+            const rows = await deps.db
+                .prepare(`WITH RECURSIVE tree(id) AS (
+          SELECT id FROM nodes WHERE id = ?
+          UNION SELECT child.id FROM nodes child JOIN tree parent ON child.parent_id = parent.id
+        )
+        SELECT n.current_version_id AS version_id FROM nodes n
+        JOIN tree ON tree.id = n.id
+        WHERE n.current_version_id IS NOT NULL`)
+                .bind(nodeId)
+                .all();
+            return (rows.results ?? []).map((row) => row.version_id);
+        },
+        async hasAnyChild(nodeId) {
+            // ⚠️ Without a visibility predicate and without an archived filter, both on purpose: this
+            // answers whether the row can be deleted at all, not what somebody may look at (#457).
+            //
+            // ⚠️ BOTH tables, and that is not defensive breadth: knowledge and flows share ONE tree
+            // (ADR-0004), `flows.parent_id` references `nodes(id)` since migration 0002, and a folder whose
+            // only content is a flow answered "empty" while it was not. Purging it left the flow with a
+            // parent that no longer exists — invisible in the tree, unreachable, unmovable.
+            const row = await deps.db
+                .prepare(`SELECT 1 AS found FROM nodes WHERE parent_id = ?
+          UNION ALL
+          SELECT 1 AS found FROM flows WHERE parent_id = ?
+          LIMIT 1`)
+                .bind(nodeId, nodeId)
+                .first();
+            return row !== null;
+        },
+        // The names this node's vectors carry in the external index. They are read BEFORE the row falls,
+        // because `node_vectors` is the only thing that knows them — and once it is gone, an orphan in
+        // Vectorize can never be named again (#457).
+        async listVectorKeys(nodeId) {
+            const rows = await deps.db
+                .prepare("SELECT chunk_key FROM node_vectors WHERE node_id = ?")
+                .bind(nodeId)
+                .all();
+            return (rows.results ?? []).map((row) => row.chunk_key);
+        },
+        async countInboundLinks(nodeId) {
+            const row = await deps.db
+                .prepare(`WITH RECURSIVE tree(id) AS (
+          SELECT id FROM nodes WHERE id = ?
+          UNION ALL SELECT child.id FROM nodes child JOIN tree parent ON child.parent_id = parent.id
+        ) SELECT COUNT(*) AS n FROM node_links
+          WHERE target_node_id IN (SELECT id FROM tree)
+            AND source_node_id NOT IN (SELECT id FROM tree)`)
+                .bind(nodeId)
+                .first();
+            return row?.n ?? 0;
+        },
+        async inspectPurgeTree(nodeId) {
+            const tree = `WITH RECURSIVE tree(id) AS (
+        SELECT id FROM nodes WHERE id = ?
+        UNION ALL SELECT child.id FROM nodes child JOIN tree parent ON child.parent_id = parent.id
+      )`;
+            const nodes = await deps.db
+                .prepare(`${tree} SELECT n.id, n.kind, n.title FROM nodes n JOIN tree ON tree.id = n.id`)
+                .bind(nodeId)
+                .all();
+            const nodeIds = (nodes.results ?? []).map((row) => row.id);
+            const flows = await deps.db
+                .prepare(`${tree} SELECT f.id, f.title FROM flows f WHERE f.parent_id IN (SELECT id FROM tree)`)
+                .bind(nodeId)
+                .all();
+            const keys = await deps.db
+                .prepare(`${tree} SELECT v.content_key FROM node_versions v WHERE v.node_id IN (SELECT id FROM tree)`)
+                .bind(nodeId)
+                .all();
+            const vectors = await deps.db
+                .prepare(`${tree} SELECT v.node_id, v.chunk_key FROM node_vectors v WHERE v.node_id IN (SELECT id FROM tree)`)
+                .bind(nodeId)
+                .all();
+            const grouped = new Map();
+            for (const row of vectors.results ?? []) {
+                const current = grouped.get(row.node_id) ?? [];
+                current.push(row.chunk_key);
+                grouped.set(row.node_id, current);
+            }
+            const counts = { flow: flows.results?.length ?? 0 };
+            for (const row of nodes.results ?? [])
+                counts[row.kind] = (counts[row.kind] ?? 0) + 1;
+            return {
+                nodeIds,
+                // The names the preview shows, capped there rather than here: a caller that wants the whole
+                // tree has `nodeIds`, and the cap belongs where the sentence is written (#733).
+                /**
+                 * ⚠️ **Flows FIRST, and the order is the finding rather than a preference** (second review
+                 * of #738). The preview names the first fifty, so with flows appended a folder holding
+                 * fifty documents and one flow named every document and hid the flow — the one thing the
+                 * cascade had to be widened for, and the one a reader is least likely to expect in there.
+                 */
+                named: [
+                    ...(flows.results ?? []).map((row) => ({
+                        id: row.id,
+                        kind: "flow",
+                        title: row.title,
+                    })),
+                    ...(nodes.results ?? []).map((row) => ({
+                        id: row.id,
+                        kind: row.kind,
+                        title: row.title,
+                    })),
+                ],
+                flowIds: (flows.results ?? []).map((row) => row.id),
+                contentKeys: [...new Set((keys.results ?? []).map((row) => row.content_key))],
+                vectorKeys: nodeIds.map((id) => ({ nodeId: id, keys: grouped.get(id) ?? [] })),
+                counts,
+            };
+        },
+        async findPurgeReplay(actorId, idempotencyKey) {
+            const row = await deps.db
+                .prepare(`SELECT title, content_keys_json FROM node_purge_receipts
+          WHERE actor_id = ? AND idempotency_key = ?`)
+                .bind(actorId, idempotencyKey)
+                .first();
+            return row ? { title: row.title, contentKeys: JSON.parse(row.content_keys_json) } : null;
+        },
+        async completePurgeReplay(actorId, idempotencyKey, completedAt) {
+            await deps.db
+                .prepare(`UPDATE node_purge_receipts SET completed_at = ?
+          WHERE actor_id = ? AND idempotency_key = ?`)
+                .bind(completedAt, actorId, idempotencyKey)
+                .run();
+        },
+        async purgeNode(input) {
+            // The keys BEFORE anything falls: after the batch there is no version row left to read them
+            // from, and an object nobody can name is an object nobody can delete.
+            const keys = await deps.db
+                .prepare(`WITH RECURSIVE tree(id) AS (
+          SELECT id FROM nodes WHERE id = ?
+          UNION ALL SELECT child.id FROM nodes child JOIN tree parent ON child.parent_id = parent.id
+        ) SELECT content_key FROM node_versions WHERE node_id IN (SELECT id FROM tree)`)
+                .bind(input.nodeId)
+                .all();
+            // ⚠️ The guard belongs on EVERY statement, not only on the last one (found in review). A
+            // `D1.batch` is one implicit transaction, but a final statement that changes ZERO rows is not
+            // an error — the transaction commits. With the condition only at the end, a restore between
+            // the service's check and this batch deleted every version, grant, link and index row of a
+            // node that was alive again, left its row standing, and answered `409 update_conflict`: the
+            // reader was told nothing had happened while the content was already gone. The audit row
+            // carried the same condition, so it was not even booked.
+            const alive = "EXISTS (SELECT 1 FROM nodes n WHERE n.id = ? AND n.archived_at IS NOT NULL)";
+            const tree = `WITH RECURSIVE tree(id) AS (
+        SELECT id FROM nodes WHERE id = ?
+        UNION ALL SELECT child.id FROM nodes child JOIN tree parent ON child.parent_id = parent.id
+      )`;
+            const treeFlows = `${tree}, tree_flows(id) AS (
+        SELECT id FROM flows WHERE parent_id IN (SELECT id FROM tree)
+      )`;
+            const deleted = await deps.db.batch([
+                // ⚠️ 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, '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
+                    .prepare(`INSERT INTO node_purge_receipts (
+            actor_id, idempotency_key, node_id, title, content_keys_json, completed_at
+          ) SELECT ?, ?, n.id, n.title, ?, NULL FROM nodes n
+            WHERE n.id = ? AND n.archived_at IS NOT NULL`)
+                    .bind(input.actorId, input.idempotencyKey, JSON.stringify([...new Set((keys.results ?? []).map((row) => row.content_key))]), input.nodeId),
+                // The derived indexes go with their source. ⚠️ A hit on a deleted document is not a blemish
+                // but a leak: the title stands in the result and the content is gone.
+                deps.db
+                    .prepare(`${tree} DELETE FROM node_fts WHERE node_id IN (SELECT id FROM tree) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`${tree} DELETE FROM node_vectors WHERE node_id IN (SELECT id FROM tree) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`${tree} DELETE FROM node_index_state
+            WHERE version_id IN (SELECT id FROM node_versions WHERE node_id IN (SELECT id FROM tree)) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                // Both directions. Outgoing links belong to this node; incoming ones would otherwise point
+                // at a row that is gone, and a foreign key would refuse the delete anyway.
+                deps.db
+                    .prepare(`${tree} DELETE FROM node_links
+            WHERE (source_node_id IN (SELECT id FROM tree) OR target_node_id IN (SELECT id FROM tree)) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                // A permission on a node that does not exist is a dangling permission.
+                deps.db
+                    .prepare(`${tree} DELETE FROM node_grants WHERE node_id IN (SELECT id FROM tree) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`${treeFlows} UPDATE flows SET published_version_id = NULL
+            WHERE id NOT IN (SELECT id FROM tree_flows) AND EXISTS (
+              SELECT 1 FROM flow_versions fv, json_tree(fv.graph_json) graph
+              WHERE fv.id IN (flows.current_version_id, flows.published_version_id)
+                AND ((graph.key = 'resourceId' AND graph.value IN (SELECT id FROM tree))
+                  OR (graph.key = 'flowId' AND graph.value IN (SELECT id FROM tree_flows)))
+            ) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`${treeFlows} DELETE FROM flow_run_steps
+            WHERE run_id IN (SELECT id FROM flow_runs WHERE flow_id IN (SELECT id FROM tree_flows)) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`${treeFlows} DELETE FROM flow_runs WHERE flow_id IN (SELECT id FROM tree_flows) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`${treeFlows} DELETE FROM flow_versions WHERE flow_id IN (SELECT id FROM tree_flows) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`${treeFlows} DELETE FROM idempotency_keys WHERE resource_id IN (SELECT id FROM tree_flows) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`${treeFlows} DELETE FROM flows WHERE id IN (SELECT id FROM tree_flows) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                deps.db
+                    .prepare(`${tree} DELETE FROM node_versions WHERE node_id IN (SELECT id FROM tree) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                // ⚠️ The replay keys of every earlier write to this node. Left behind, a later write reusing
+                // one of them would be answered with a resource id that no longer resolves.
+                deps.db
+                    .prepare(`${tree} DELETE FROM idempotency_keys WHERE resource_id IN (SELECT id FROM tree) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+                // LAST — and its count is what the caller reads as the verdict.
+                deps.db
+                    .prepare(`${tree} DELETE FROM nodes WHERE id IN (SELECT id FROM tree) AND ${alive}`)
+                    .bind(input.nodeId, input.nodeId),
+            ]);
+            const removed = deleted.at(-1)?.meta?.changes ?? 0;
+            if (removed === 0)
+                return "missing";
+            return { contentKeys: [...new Set((keys.results ?? []).map((row) => row.content_key))] };
+        },
+        async appendVersion(input) {
+            const version = input.version;
+            await deps.db.batch([
+                deps.db
+                    .prepare(`INSERT INTO node_versions (
+            id, node_id, sequence, content_key, media_type, content_hash, size, segment,
+            created_by, created_at
+          ) SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
+          FROM nodes
+          WHERE id = ? AND current_version_id IS ?`)
+                    .bind(version.id, version.nodeId, version.sequence, version.contentKey, version.mediaType, version.contentHash, version.size, version.segment, version.createdBy, version.createdAt, version.nodeId, input.baseVersionId),
+                deps.db
+                    .prepare(`UPDATE nodes
+            SET current_version_id = ?, updated_at = ?
+            WHERE id = ? AND EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
+                    .bind(version.id, version.createdAt, version.nodeId, version.id),
+                deps.db
+                    .prepare(`INSERT INTO idempotency_keys (
+            actor_id, operation, idempotency_key, resource_id, created_at
+          ) SELECT ?, 'node.save', ?, ?, ?
+          WHERE EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
+                    .bind(input.actorId, input.idempotencyKey, version.id, version.createdAt, version.id),
+                deps.db
+                    .prepare(`INSERT INTO node_index_state (
+            version_id, status, attempt_count, last_error, updated_at
+          ) SELECT ?, 'pending', 0, NULL, ?
+          WHERE EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
+                    .bind(version.id, version.createdAt, version.id),
+                deps.db
+                    .prepare(`INSERT INTO audit_events (
+            id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+          ) SELECT ?, ?, 'node.save', 'node', ?, ?, ?
+          WHERE EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
+                    .bind(input.auditId, input.actorId, version.nodeId, JSON.stringify({ versionId: version.id, sequence: version.sequence }), version.createdAt, version.id),
+            ]);
+            const row = await deps.db
+                .prepare("SELECT current_version_id FROM nodes WHERE id = ?")
+                .bind(version.nodeId)
+                .first();
+            return row?.current_version_id === version.id ? "saved" : "conflict";
+        },
+        /**
+         * One appended segment of a table (#40).
+         *
+         * ⚠️ The sequence is computed inside the INSERT, never read out and sent back in. Two appends
+         * that arrive together would otherwise both read the same `MAX(sequence)` and the second would
+         * lose to `UNIQUE (node_id, sequence)` — the very loss the ticket forbids.
+         *
+         * ⚠️ `current_version_id` only ever moves forward. It names the newest segment, and indexing
+         * keys off it; letting a slower append pull it back would leave the index describing a table
+         * that is missing its last rows.
+         */
+        async appendTableVersion(input) {
+            const version = input.version;
+            const stored = async () => await deps.db
+                .prepare(`SELECT ${versionColumns} FROM node_versions WHERE id = ?`)
+                .bind(version.id)
+                .first();
+            try {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`INSERT INTO node_versions (
+              id, node_id, sequence, content_key, media_type, content_hash, size, segment,
+              created_by, created_at
+            ) SELECT ?, ?, COALESCE(MAX(sequence), 0) + 1, ?, ?, ?, ?, ?, ?, ?
+            FROM node_versions WHERE node_id = ?`)
+                        .bind(version.id, version.nodeId, version.contentKey, version.mediaType, version.contentHash, version.size, version.segment, version.createdBy, version.createdAt, version.nodeId),
+                    deps.db
+                        .prepare(`UPDATE nodes
+              SET current_version_id = ?, updated_at = ?
+              WHERE id = ?
+                AND EXISTS (SELECT 1 FROM node_versions WHERE id = ?)
+                AND (
+                  current_version_id IS NULL
+                  OR COALESCE((
+                    SELECT sequence FROM node_versions
+                    WHERE id = nodes.current_version_id
+                  ), 0) < (SELECT sequence FROM node_versions WHERE id = ?)
+                )`)
+                        .bind(version.id, version.createdAt, version.nodeId, version.id, version.id),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'node.append', ?, ?, ?
+            WHERE EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
+                        .bind(input.actorId, input.idempotencyKey, version.id, version.createdAt, version.id),
+                    deps.db
+                        .prepare(`INSERT INTO node_index_state (
+              version_id, status, attempt_count, last_error, updated_at
+            ) SELECT ?, 'pending', 0, NULL, ?
+            WHERE EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
+                        .bind(version.id, version.createdAt, version.id),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'node.append', 'node', ?, json_object(
+              'versionId', ?, 'size', ?
+            ), ?
+            WHERE EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
+                        .bind(input.auditId, input.actorId, version.nodeId, version.id, version.size, version.createdAt, version.id),
+                ]);
+            }
+            catch (error) {
+                // The same key twice at the same moment: the first write owns the row, and this call
+                // answers with it rather than with a failure the caller cannot act on.
+                const replayed = await deps.db
+                    .prepare(`SELECT resource_id FROM idempotency_keys
+            WHERE actor_id = ? AND operation = 'node.append' AND idempotency_key = ?`)
+                    .bind(input.actorId, input.idempotencyKey)
+                    .first();
+                const row = replayed
+                    ? await deps.db
+                        .prepare(`SELECT ${versionColumns} FROM node_versions WHERE id = ?`)
+                        .bind(replayed.resource_id)
+                        .first()
+                    : null;
+                if (row)
+                    return mapVersion(row);
+                throw error;
+            }
+            const row = await stored();
+            if (!row)
+                throw new Error("Node table append did not store a version");
+            return mapVersion(row);
+        },
+        /**
+         * One snapshot — the whole readable state after a mutation — written only against the state it
+         * replaces (#135, #285).
+         *
+         * ⚠️ The shape of `appendVersion`, not of the append above it: the base check sits inside the
+         * INSERT's own WHERE, so a segment that landed between the service's read and this batch makes
+         * the INSERT store nothing and every guarded statement after it a no-op. The service reads the
+         * answer the same way `save` does — by asking whether the node now stands on the new version.
+         *
+         * The idempotency row carries the mutation's own operation, so a replayed update can never be
+         * confused with a delete that reused the key, and the audit trail names what was done.
+         */
+        async appendSnapshotVersion(input) {
+            const version = input.version;
+            await deps.db.batch([
+                deps.db
+                    .prepare(`INSERT INTO node_versions (
+            id, node_id, sequence, content_key, media_type, content_hash, size, segment,
+            created_by, created_at
+          ) SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
+          FROM nodes
+          WHERE id = ? AND current_version_id IS ?`)
+                    .bind(version.id, version.nodeId, version.sequence, version.contentKey, version.mediaType, version.contentHash, version.size, 
+                // ⚠️ Taken from the version rather than written in as `'snapshot'`. A table's mutation
+                // marks a snapshot, because reading a table starts at the newest one and everything
+                // before it is history (#135). A snapshot version carries the whole document by
+                // construction, so it marks nothing — the same `null` a document's version carries, and
+                // for the same reason (#285).
+                version.segment, version.createdBy, version.createdAt, version.nodeId, input.baseVersionId),
+                deps.db
+                    .prepare(`UPDATE nodes
+            SET current_version_id = ?, updated_at = ?
+            WHERE id = ? AND EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
+                    .bind(version.id, version.createdAt, version.nodeId, version.id),
+                deps.db
+                    .prepare(`INSERT INTO idempotency_keys (
+            actor_id, operation, idempotency_key, resource_id, created_at
+          ) SELECT ?, ?, ?, ?, ?
+          WHERE EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
+                    .bind(input.actorId, input.operation, input.idempotencyKey, version.id, version.createdAt, version.id),
+                deps.db
+                    .prepare(`INSERT INTO node_index_state (
+            version_id, status, attempt_count, last_error, updated_at
+          ) SELECT ?, 'pending', 0, NULL, ?
+          WHERE EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
+                    .bind(version.id, version.createdAt, version.id),
+                deps.db
+                    .prepare(`INSERT INTO audit_events (
+            id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+          ) SELECT ?, ?, ?, 'node', ?, ?, ?
+          WHERE EXISTS (SELECT 1 FROM node_versions WHERE id = ?)`)
+                    .bind(input.auditId, input.actorId, input.operation, version.nodeId, JSON.stringify({ versionId: version.id, ...input.metadata }), version.createdAt, version.id),
+            ]);
+            const row = await deps.db
+                .prepare("SELECT current_version_id FROM nodes WHERE id = ?")
+                .bind(version.nodeId)
+                .first();
+            return row?.current_version_id === version.id ? "saved" : "conflict";
+        },
+        async listGrants(resourceId) {
+            const result = await deps.db
+                .prepare(`SELECT ${grantColumns} FROM node_grants
+          WHERE node_id = ?
+          ORDER BY principal_type, principal_id, verb`)
+                .bind(resourceId)
+                .all();
+            return (result.results ?? []).map(mapGrant);
+        },
+        async listEffectiveAccess(resourceId) {
+            // Owners and grants come from ONE statement, hence one D1 snapshot. Two parallel SELECTs are
+            // not atomic: a grant mutation between their snapshots can produce a principal list that
+            // never existed as a whole.
+            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 ORDER BY owner_id)) AS owner_ids_json,
+            (SELECT json_group_array(json_object(
+               'id', id, 'resource_id', node_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.node_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 grant_row.principal_type, grant_row.principal_id, grant_row.verb
+             )) AS grants_json`)
+                .bind(resourceId, deps.now().toISOString())
+                .first();
+            return {
+                ownerIds: JSON.parse(row?.owner_ids_json ?? "[]"),
+                items: JSON.parse(row?.grants_json ?? "[]").map(mapGrant),
+            };
+        },
+        // ⚠️ `UNION`, never `UNION ALL`: a ring in `parent_id` must end the recursion rather than the
+        // database, the same reason every other walk of this tree gives.
+        async organizationExecuteReaches(nodeId, exceptGrantId) {
+            const row = await deps.db
+                .prepare(`WITH RECURSIVE ancestors(id, parent_id) AS (
+            SELECT id, parent_id FROM nodes WHERE id = ?
+            UNION
+            SELECT parent.id, parent.parent_id
+            FROM nodes parent
+            JOIN ancestors child ON child.parent_id = parent.id
+          )
+          SELECT 1 AS reaches
+          FROM node_grants grant_row
+          JOIN ancestors ON ancestors.id = grant_row.node_id
+          WHERE grant_row.id <> ?
+            AND grant_row.principal_type = 'organization'
+            AND grant_row.verb = 'execute'
+            AND ${grantInForce}
+          LIMIT 1`)
+                .bind(nodeId, exceptGrantId, deps.now().toISOString())
+                .first();
+            return row?.reaches === 1;
+        },
+        async listLinksVisible(actor, nodeId) {
+            const result = await deps.db
+                .prepare(`${visibleCte}
+          SELECT ${linkColumns}
+          FROM node_links link
+          JOIN allowed source_access ON source_access.id = link.source_node_id
+          JOIN allowed target_access ON target_access.id = link.target_node_id
+          WHERE link.source_node_id = ? OR link.target_node_id = ?
+          ORDER BY link.created_at, link.id`)
+                .bind(...readBindings(actor), nodeId, nodeId)
+                .all();
+            return (result.results ?? []).map(mapLink);
+        },
+        /**
+         * The titles of the nodes among these that this actor may see (#41).
+         *
+         * ⚠️ The same `allowed` walk as every other read, joined rather than filtered afterwards, and
+         * archived nodes are out. An unreachable or deleted target contributes no row at all — no
+         * placeholder, no id echoed back — because a row is already the statement "something is here".
+         */
+        async resolveVisibleTitles(actor, nodeIds) {
+            const uniqueIds = [...new Set(nodeIds)].slice(0, 200);
+            if (uniqueIds.length === 0)
+                return [];
+            const rows = [];
+            for (let offset = 0; offset < uniqueIds.length; offset += 96) {
+                const ids = uniqueIds.slice(offset, offset + 96);
+                const placeholders = ids.map(() => "?").join(", ");
+                const result = await deps.db
+                    .prepare(`${visibleCte}
+            SELECT n.id, n.title
+            FROM nodes n
+            JOIN allowed ON allowed.id = n.id
+            WHERE n.id IN (${placeholders}) AND n.archived_at IS NULL`)
+                    .bind(...readBindings(actor), ...ids)
+                    .all();
+                rows.push(...(result.results ?? []));
+            }
+            return rows.map((row) => ({ nodeId: row.id, title: row.title }));
+        },
+        /**
+         * The `text` links of one document, replaced wholesale by what the saved text says (#41).
+         *
+         * ⚠️ `origin = 'text'` in the delete, and nowhere else. Links made in the removed dialog are
+         * `manual`; saving a document must not take away a relationship somebody entered before the
+         * text became the place to write one.
+         *
+         * The whole set is written in one batch, so a save never leaves the graph half-rewritten. There
+         * is no idempotency row: the operation is a replacement, and replaying it writes the same set.
+         */
+        async replaceTextLinks(input) {
+            await deps.db.batch([
+                deps.db
+                    .prepare("DELETE FROM node_links WHERE source_node_id = ? AND origin = 'text'")
+                    .bind(input.sourceNodeId),
+                ...input.links.map((link) => deps.db
+                    .prepare(`INSERT INTO node_links (
+              id, source_node_id, target_node_id, relation, origin, label, created_by, created_at
+            ) VALUES (?, ?, ?, 'references', 'text', NULL, ?, ?)
+            ON CONFLICT (source_node_id, target_node_id, relation) DO NOTHING`)
+                    .bind(link.id, input.sourceNodeId, link.targetNodeId, input.actorId, input.occurredAt)),
+                deps.db
+                    .prepare(`INSERT INTO audit_events (
+            id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+          ) VALUES (?, ?, 'node.link', 'node', ?, ?, ?)`)
+                    .bind(input.auditId, input.actorId, input.sourceNodeId, JSON.stringify({ targetNodeIds: input.links.map((link) => link.targetNodeId) }), input.occurredAt),
+            ]);
+        },
+        async graphVisible(actor, input) {
+            const nodeResult = await deps.db
+                .prepare(`${visibleCte}
+          SELECT ${nodeColumns}
+          FROM nodes n
+          JOIN allowed ON allowed.id = n.id
+          WHERE n.archived_at IS NULL
+          ORDER BY lower(n.title), n.id
+          LIMIT ?`)
+                .bind(...readBindings(actor), input.limit)
+                .all();
+            const nodes = (nodeResult.results ?? []).map(mapNode);
+            if (nodes.length === 0)
+                return { nodes, links: [] };
+            const linkResult = await deps.db
+                .prepare(`${visibleCte}, graph_nodes(id) AS (
+          SELECT n.id FROM nodes n
+          JOIN allowed ON allowed.id = n.id
+          WHERE n.archived_at IS NULL
+          ORDER BY lower(n.title), n.id
+          LIMIT ?
+        )
+          SELECT ${linkColumns}
+          FROM node_links link
+          JOIN graph_nodes source_node ON source_node.id = link.source_node_id
+          JOIN graph_nodes target_node ON target_node.id = link.target_node_id
+          ORDER BY link.created_at, link.id`)
+                .bind(...readBindings(actor), input.limit)
+                .all();
+            return { nodes, links: (linkResult.results ?? []).map(mapLink) };
+        },
+        /**
+         * The same `allowed` set every other read joins against, narrowed to attachments (#773).
+         *
+         * ⚠️ Ordered and paged by `n.id` rather than by title: the id is the cursor, and a cursor has to
+         * be unique or a page boundary falling between two identical titles silently drops one of them.
+         * `graphVisible` above orders by title because it draws a picture and takes the whole set.
+         */
+        async listVisibleAttachments(actor, input) {
+            const result = await deps.db
+                .prepare(`${visibleCte}
+          SELECT ${nodeColumns}
+          FROM nodes n
+          JOIN allowed ON allowed.id = n.id
+          WHERE n.archived_at IS NULL
+            AND n.kind = 'attachment'
+            AND (? IS NULL OR n.id > ?)
+          ORDER BY n.id
+          LIMIT ?`)
+                // ⚠️ Positional throughout, and the cursor is bound TWICE. Numbered parameters (?1, ?2)
+                // would count from the first placeholder of the whole statement — and `visibleCte` above
+                // has already spent several of them.
+                .bind(...readBindings(actor), input.after, input.after, input.limit)
+                .all();
+            return (result.results ?? []).map(mapNode);
+        },
+        async setGrant(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 node_grants (
+              id, node_id, principal_type, principal_id, verb,
+              expires_at, created_by, created_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT (node_id, principal_type, principal_id, verb)
+            DO UPDATE SET expires_at = excluded.expires_at`)
+                        .bind(grant.id, grant.resourceId, 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 ?, 'node.share', ?, id, ? FROM node_grants
+              WHERE node_id = ? AND principal_type = ? AND principal_id = ? AND verb = ?`)
+                        .bind(input.actorId, input.idempotencyKey, grant.createdAt, grant.resourceId, principalType, principalId, grant.verb),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) VALUES (?, ?, 'node.share', 'node', ?, ?, ?)`)
+                        .bind(input.auditId, input.actorId, grant.resourceId, JSON.stringify({ principalType, verb: grant.verb }), grant.createdAt),
+                ]);
+                const stored = await deps.db
+                    .prepare(`SELECT ${grantColumns} FROM node_grants
+            WHERE node_id = ? AND principal_type = ? AND principal_id = ? AND verb = ?`)
+                    .bind(grant.resourceId, principalType, principalId, grant.verb)
+                    .first();
+                if (!stored)
+                    throw new Error("Node 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 = 'node.share' AND idempotency_key = ?`)
+                    .bind(input.actorId, input.idempotencyKey)
+                    .first();
+                if (replayed) {
+                    const row = await deps.db
+                        .prepare(`SELECT ${grantColumns} FROM node_grants WHERE id = ?`)
+                        .bind(replayed.resource_id)
+                        .first();
+                    if (row)
+                        return mapGrant(row);
+                }
+                throw error;
+            }
+        },
+        async revokeGrant(input) {
+            try {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'node.revoke', ?,
+              (CASE WHEN EXISTS (
+                SELECT 1 FROM node_grants WHERE id = ? AND node_id = ?
+              ) THEN '1:' ELSE '0:' END) || ?, ?`)
+                        .bind(input.actorId, input.idempotencyKey, input.grantId, input.resourceId, input.grantId, input.occurredAt),
+                    deps.db
+                        .prepare("DELETE FROM node_grants WHERE id = ? AND node_id = ?")
+                        .bind(input.grantId, input.resourceId),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'node.revoke', 'node', ?,
+              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 = 'node.revoke' AND idempotency_key = ?`)
+                        .bind(input.auditId, input.actorId, input.resourceId, input.grantId, input.occurredAt, input.actorId, input.idempotencyKey),
+                ]);
+            }
+            catch (error) {
+                const replayed = await this.findIdempotentRevocation(input.actorId, input.idempotencyKey);
+                if (replayed === null)
+                    throw error;
+                return replayed;
+            }
+            return (await this.findIdempotentRevocation(input.actorId, input.idempotencyKey)) ?? false;
+        },
+        async searchVisible(actor, input) {
+            const query = toFtsQuery(input.query);
+            if (!query)
+                return [];
+            const result = await deps.db
+                .prepare(`${visibleCte}${scopeCte(input.scopeId)}
+          SELECT n.id AS node_id, v.id AS version_id, n.title,
+            snippet(node_fts, 3, '', '', ' … ', 32) AS passage,
+            n.updated_at AS freshness, bm25(node_fts, 0.0, 0.0, 4.0, 1.0) AS rank
+          FROM node_fts
+          JOIN nodes n ON n.id = node_fts.node_id
+          JOIN node_versions v ON v.id = node_fts.version_id
+          JOIN allowed ON allowed.id = n.id${scopeJoin(input.scopeId)}
+          WHERE node_fts MATCH ?
+            AND n.current_version_id = v.id
+            AND n.archived_at IS NULL
+          ORDER BY rank, n.updated_at DESC
+          LIMIT ?`)
+                .bind(...readBindings(actor), ...scopeBindings(input.scopeId), query, input.limit)
+                .all();
+            // ⚠️ One citation per node, and the FIRST is the one kept. The index is CHUNKED — a node
+            // may hold several rows (#285) — so a query matching three of them arrives here three times;
+            // the rows come back in rank order, so the survivor is the best-matching card and its own
+            // passage is what the reader is shown. Without this, one busy node could fill a whole page
+            // of results and push every other node off it.
+            return dedupedByNode(result.results ?? []).map((row) => ({
+                nodeId: row.node_id,
+                versionId: row.version_id,
+                title: row.title,
+                passage: row.passage,
+                source: `intel://nodes/${encodeURIComponent(row.node_id)}?version=${encodeURIComponent(row.version_id)}`,
+                freshness: row.freshness,
+                score: 1 / (1 + Math.abs(row.rank)),
+                match: "lexical",
+            }));
+        },
+        async hydrateVisibleCitations(actor, hits, scopeId) {
+            // One entry per node: the caller has already picked the best-scoring chunk of each, so a
+            // node that answered with four passages arrives as the one passage that answered best.
+            const unique = [...new Map(hits.map((hit) => [hit.nodeId, hit])).values()].slice(0, 100);
+            if (unique.length === 0)
+                return [];
+            const rows = [];
+            // Two bindings per hit now instead of one, so the batch is halved and then some: the actor's
+            // predicate and the optional scope are bound in front of them, and D1 counts every one of
+            // them against the same per-statement ceiling.
+            for (let offset = 0; offset < unique.length; offset += 40) {
+                const batch = unique.slice(offset, offset + 40);
+                const pairs = batch.map(() => "(?, ?)").join(", ");
+                const result = await deps.db
+                    .prepare(`${visibleCte}${scopeCte(scopeId)},
+            hits(node_id, chunk_key) AS (VALUES ${pairs})
+            SELECT n.id AS node_id, v.id AS version_id, n.title,
+              -- ⚠️ The card that answered, and only otherwise the first passage of the node
+              -- (anchrd/intel#301). Every vector written before #301 is named by the bare node id
+              -- and has no row here, so the fallback is not defensive coding but the exact
+              -- behaviour those vectors had — a board found through one of them still answers,
+              -- with the passage it always answered with, until the next indexing pass.
+              COALESCE(vector.passage, substr(node_fts.content, 1, 480)) AS passage,
+              n.updated_at AS freshness
+            FROM hits
+            JOIN nodes n ON n.id = hits.node_id
+            JOIN node_versions v ON v.id = n.current_version_id
+            JOIN node_fts ON node_fts.version_id = v.id
+            LEFT JOIN node_vectors vector
+              ON vector.node_id = hits.node_id AND vector.chunk_key = hits.chunk_key
+            JOIN allowed ON allowed.id = n.id${scopeJoin(scopeId)}
+            WHERE n.archived_at IS NULL`)
+                    .bind(...readBindings(actor), ...scopeBindings(scopeId), ...batch.flatMap((hit) => [hit.nodeId, hit.chunkKey]))
+                    .all();
+                rows.push(...(result.results ?? []));
+            }
+            const order = new Map(unique.map((hit, index) => [hit.nodeId, index]));
+            // The same one-per-node rule as the lexical half above, for the same reason: a citation names
+            // a NODE, and a board holds one full-text row per task (#285), so the join above still
+            // produces one row per card even though only one of them was asked about.
+            const deduped = dedupedByNode(rows);
+            deduped.sort((left, right) => (order.get(left.node_id) ?? 0) - (order.get(right.node_id) ?? 0));
+            return deduped.map((row) => ({
+                nodeId: row.node_id,
+                versionId: row.version_id,
+                title: row.title,
+                passage: row.passage,
+                source: `intel://nodes/${encodeURIComponent(row.node_id)}?version=${encodeURIComponent(row.version_id)}`,
+                freshness: row.freshness,
+                score: 0,
+                match: "semantic",
+            }));
+        },
+        async invalidateVectors() {
+            /**
+             * ⚠️ The fingerprints are cleared and the ROWS are kept, which is not a detail. A record row
+             * says two things at once: "this chunk was embedded from this text" and "this vector exists".
+             * Only the first is stale after a rebuild is asked for; deleting the row would throw the
+             * second away, and then a card removed between this call and that board's pass would leave a
+             * vector nothing could ever name again — matching questions and answering with a card that is
+             * not on the board.
+             *
+             * The empty string is a value no digest produces, so every chunk compares as changed and the
+             * next pass embeds all of them. `node_fts` is deliberately not touched: its rows are
+             * overwritten by the pass that rewrites them, and emptying it would take the lexical half of
+             * the installation offline for as long as the queue needs to work through the tree.
+             */
+            await deps.db.prepare("UPDATE node_vectors SET fingerprint = ''").run();
+        },
+        /**
+         * ⚠️ Archived nodes are IN this walk since anchrd/intel#348, and the omission of
+         * `archived_at IS NULL` is the point. The pass an archived node gets is a purge, not an index —
+         * `getTarget` refuses it and `archivedNodeId` says why — so including them is what makes
+         * `reindex` the way back for a vector that is in the index with nothing left to name it.
+         *
+         * Three of those exist and none of them has another repair: everything archived before #348,
+         * which nothing ever swept; a node whose `archive` wrote its row and then failed to reach the
+         * queue; and a pass that upserted vectors in the moment somebody archived the node underneath
+         * it. Without this line an administrator's rebuild walked straight past all three, and the only
+         * remaining answer would have been to delete the whole Vectorize index by hand.
+         *
+         * It does mean `queued` counts them. That is still what the number says — versions handed to the
+         * queue — and a rebuild that silently skipped part of the tree is the failure `reindex` exists
+         * to prevent.
+         */
+        async listCurrentVersionIds(input) {
+            const result = await deps.db
+                .prepare(`SELECT current_version_id AS id FROM nodes
+          WHERE current_version_id IS NOT NULL
+            AND (? IS NULL OR current_version_id > ?)
+          ORDER BY id LIMIT ?`)
+                .bind(input.after, input.after, input.limit)
+                .all();
+            return (result.results ?? []).map((row) => row.id);
+        },
+    };
+}