@anchrd/intel 0.59.0

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

@@ -0,0 +1,133 @@
+import type { ResourceGrant, ResourceVerb } from "../../contract/share.js";
+export interface GrantActor {
+    id: string;
+    email: string;
+    isAdmin?: boolean;
+}
+/**
+ * A grant row as every reader of one wants it: the subject column already aliased, so the same row
+ * shape comes back from `node_grants` and from `flow_grants`.
+ *
+ * ⚠️ The alias is what lets `mapGrant` stay one function. Two mappers would each carry the same
+ * `principal_type` switch, and the day a fourth principal shape arrives one of them gets it.
+ */
+export interface GrantRow {
+    id: string;
+    resource_id: string;
+    principal_type: "user" | "email" | "organization";
+    principal_id: string;
+    verb: ResourceVerb;
+    expires_at: string | null;
+    created_by: string;
+    created_at: string;
+}
+export declare const grantColumns: (subjectColumn: string) => string;
+export declare function mapGrant(row: GrantRow): ResourceGrant;
+export declare function principalColumns(principal: ResourceGrant["principal"]): {
+    type: ResourceGrant["principal"]["type"];
+    id: string;
+};
+/**
+ * Whether a grant row is in force at the moment bound after it. Takes one binding: that moment.
+ *
+ * ⚠️ The ONE place this repository decides what an expiry means, for both grant tables and for
+ * every statement that reads either — the point check, the subtree walk, and the two effective
+ * views alike. It is a fragment rather than part of `grantExists` because half the readers do not
+ * ask about a principal at all: `listEffectiveAccess` lists every grant along a path, and
+ * `callReach` asks only whether an organization-wide `execute` stands. Those had written the
+ * condition out by hand, which is exactly the second set of doors the header above warns about —
+ * a grace period, a different comparison, and the two spellings drift apart in silence.
+ *
+ * `git grep "expires_at IS NULL" -- packages/intel/src` must find this line and nothing else.
+ */
+export declare const grantInForce = "(grant_row.expires_at IS NULL OR grant_row.expires_at > ?)";
+export declare const subtreeCte: string;
+export declare function subtreeBindings(actor: GrantActor, verb: ResourceVerb, now: string): unknown[];
+/**
+ * One named folder and everything filed beneath it, appended to a statement that already carries
+ * `subtreeCte`. It answers "where", never "whether": a statement joins `descendants` *in addition
+ * to* `allowed`, so the scope can only take rows away from an answer the actor was already entitled
+ * to. Joining it instead of `allowed` would turn a search argument into a permission, which is
+ * exactly what ADR-0004 forbids — the caller supplies the id, and a caller is not a grant.
+ *
+ * ⚠️ `UNION`, never `UNION ALL`, for the reason `nodeVerbQuery` gives: a cycle in `parent_id` can
+ * reach the table and this walks downwards into it.
+ */
+export declare const descendantsCte = "descendants(id) AS (\n    SELECT scope.id FROM nodes scope WHERE scope.id = ?\n    UNION\n    SELECT child.id\n    FROM nodes child\n    JOIN descendants parent ON child.parent_id = parent.id\n  )";
+/**
+ * Both walks in one statement: what the actor may open, and what they may run. Its bindings are
+ * `subtreeBindings(actor, "read", now)` followed by `subtreeBindings(actor, "execute", now)`, in
+ * that order.
+ */
+export declare const readableOrRunnableCte: string;
+/**
+ * A flow the actor may open *or* may run, for a statement carrying `readableOrRunnableCte`. It is
+ * the callable rule of ADR-0004 §2/§3 — `execute` without `read` is the library, a building block
+ * anyone may run and few may open — asked of a whole list of flows at once instead of one flow at a
+ * time. Its bindings follow the two CTEs' and are `flowCallableBindings(actor, now)`.
+ *
+ * ⚠️ Both direct grants, and both are needed. A flow handed out on its own for `execute` alone is
+ * the library case shrunk to one flow — runnable by people who may not open it — and leaving `read`
+ * out here would hide a flow somebody was explicitly given to look at.
+ */
+export declare const flowCallable: string;
+export declare function flowCallableBindings(actor: GrantActor, now: string): unknown[];
+/**
+ * The point check for one node: the node itself and every ancestor above it. Cheaper than
+ * the subtree walk and the same answer, because a grant reaches down and never sideways.
+ *
+ * ⚠️ `UNION`, never `UNION ALL`. The service refuses to move a node into its own descendant, but a
+ * cycle in `parent_id` can still reach the table — a restore, a repair, a future writer. `UNION ALL`
+ * would walk such a ring without end, and this query runs on the authorization path of every
+ * request, so the damage lands in the database rather than in one tab. `UNION` folds the repeated
+ * row away and the recursion stops on its own.
+ */
+export declare const nodeVerbQuery: string;
+export declare function nodeVerbBindings(nodeId: string, actor: GrantActor, verb: ResourceVerb, now: string): unknown[];
+/**
+ * The same question for a flow. Three things reach it, and they are OR-ed rather than ranked: its
+ * owner, a grant on the folder it is filed in or any folder above that, and — since #530 — a grant
+ * that sits on the flow itself. Its owner keeps it the way a node's owner keeps theirs, otherwise a
+ * flow at the root of the tree would be unreachable by the person who created it. `UNION` for the
+ * same reason as above.
+ *
+ * ⚠️ The direct grant is asked BEFORE the ancestor walk, and only because it is cheaper: a point
+ * lookup on an indexed column against a recursive walk of the tree. It decides nothing the walk
+ * would have decided differently — both are the same OR.
+ */
+export declare const flowVerbQuery: string;
+export declare function flowVerbBindings(flowId: string, actor: GrantActor, verb: ResourceVerb, now: string): unknown[];
+/**
+ * The predicate a query over `flows` uses when it already carries `subtreeCte` for the same verb.
+ * Its bindings follow the CTE's.
+ *
+ * ⚠️ The verb is now a binding of its own, and it has to be the SAME verb the CTE was seeded with.
+ * The walk answers "which folders", the direct grant answers "this flow" — asking them for two
+ * different verbs would produce a predicate that is neither, and it is the kind of mismatch nothing
+ * fails on: the query still runs and quietly hands out the wrong list.
+ */
+/**
+ * ⚠️ The parent is a PARAMETER for exactly one caller, and giving it one was cheaper than the
+ * alternative. The feed reads events about flows that no longer exist: after `flows.purge` the row
+ * is gone, so `flow.parent_id`, `flow.owner_id` and every `flow_grants` row are gone with it, and
+ * the only anchor left is the `parentId` the purge wrote into its own metadata (#763, D73). A
+ * second, similar-looking predicate beside this one is the drift `destructive.md` warns about: two
+ * expressions with similar names are two different questions, and the one that goes stale is the
+ * copy.
+ */
+/**
+ * ⚠️ **The ALIAS is a parameter too, since #767, and leaving it hard-wired was a real fault rather
+ * than an inelegance.** The feed's third branch asks about a flow reached through its RUN, so the
+ * flow sits under a second join (`run_flow`) while `flow` is NULL on that row. Against the
+ * hard-wired name the owner branch and the direct-grant branch both compared NULL — so a flow
+ * somebody OWNS but that hangs at the top level, with no folder above it to carry a grant, answered
+ * "not visible" to its own owner.
+ *
+ * ⚠️ It fails in the safe direction, which is exactly what made it worth a test rather than a
+ * comment: nothing leaks, a row is only ever missing. A flow filed in a readable FOLDER answers
+ * correctly through the third branch, so every test with a folder is green either way — and the two
+ * tests that caught it are the ones that seed a flow at the root.
+ */
+export declare function flowInSubtreeOver(parentExpression: string, flowAlias?: string): string;
+export declare const flowInSubtree: string;
+export declare function flowInSubtreeBindings(actor: GrantActor, verb: ResourceVerb, now: string): unknown[];

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

@@ -0,0 +1,269 @@
+export const grantColumns = (subjectColumn) => `id, ${subjectColumn} AS resource_id, principal_type, principal_id, verb, expires_at,
+  created_by, created_at`;
+export function mapGrant(row) {
+    let principal;
+    switch (row.principal_type) {
+        case "user":
+            principal = { type: "user", id: row.principal_id };
+            break;
+        case "email":
+            principal = { type: "email", email: row.principal_id };
+            break;
+        case "organization":
+            principal = { type: "organization" };
+            break;
+        default:
+            throw new Error("Unsupported grant principal type");
+    }
+    return {
+        id: row.id,
+        resourceId: row.resource_id,
+        principal,
+        verb: row.verb,
+        expiresAt: row.expires_at,
+        createdBy: row.created_by,
+        createdAt: row.created_at,
+    };
+}
+// How a principal is written into the subject columns of both grant tables. An organization is the
+// literal `*` every reader above matches on; an email is folded to lower case on the way in so the
+// comparison there has one shape to worry about.
+export function principalColumns(principal) {
+    if (principal.type === "user")
+        return { type: "user", id: principal.id };
+    if (principal.type === "email")
+        return { type: "email", id: principal.email.toLowerCase() };
+    return { type: "organization", id: "*" };
+}
+const principalMatch = `(
+  (grant_row.principal_type = 'user' AND grant_row.principal_id = ?)
+  OR (grant_row.principal_type = 'email' AND lower(grant_row.principal_id) = lower(?))
+  OR (grant_row.principal_type = 'organization' AND grant_row.principal_id = '*')
+)`;
+/**
+ * Whether a grant row is in force at the moment bound after it. Takes one binding: that moment.
+ *
+ * ⚠️ The ONE place this repository decides what an expiry means, for both grant tables and for
+ * every statement that reads either — the point check, the subtree walk, and the two effective
+ * views alike. It is a fragment rather than part of `grantExists` because half the readers do not
+ * ask about a principal at all: `listEffectiveAccess` lists every grant along a path, and
+ * `callReach` asks only whether an organization-wide `execute` stands. Those had written the
+ * condition out by hand, which is exactly the second set of doors the header above warns about —
+ * a grace period, a different comparison, and the two spellings drift apart in silence.
+ *
+ * `git grep "expires_at IS NULL" -- packages/intel/src` must find this line and nothing else.
+ */
+export const grantInForce = "(grant_row.expires_at IS NULL OR grant_row.expires_at > ?)";
+/**
+ * One grant row that is in force, asked of one table.
+ *
+ * ⚠️ The table is a parameter and the rest is not, which is the whole reason #530 could give a flow
+ * its own grants without a second set of doors. `flow_grants` and `node_grants` differ in their
+ * subject column and in nothing else — same principal shapes, same verbs, same expiry — so a
+ * question asked of one is asked of the other by the same string. A hand-written copy for flows is
+ * how one of the two would eventually stop honouring `expires_at`.
+ */
+function grantExists(table, subjectColumn, targetColumn) {
+    return `EXISTS (
+    SELECT 1 FROM ${table} grant_row
+    WHERE grant_row.${subjectColumn} = ${targetColumn}
+      AND ${principalMatch}
+      AND grant_row.verb = ?
+      AND ${grantInForce}
+  )`;
+}
+const nodeGrantExists = (nodeColumn) => grantExists("node_grants", "node_id", nodeColumn);
+// A grant that sits on the flow itself (#530), beside whatever its folder already passes down. It
+// adds to the folder's reach and never replaces it, exactly as a grant on a document adds to its
+// folder's — the two are OR-ed everywhere this appears.
+const flowGrantExists = (flowColumn) => grantExists("flow_grants", "flow_id", flowColumn);
+// Bindings for one `grantExists`: principal (twice), verb, and the moment expiry is measured
+// against. Callers concatenate these in SQL order; the helpers below say which order that is.
+function grantBindings(actor, verb, now) {
+    return [actor.id, actor.email, verb, now];
+}
+/**
+ * Seeds every node the actor reaches for one verb and walks downwards, which is what "a grant
+ * applies to everything beneath it" means in SQL. The name is a parameter because one statement can
+ * need two of these — asking `read` and `execute` at once is what turns "one query per callee" into
+ * one query (#30) — and a second walk written out by hand would be a second copy of the rule.
+ */
+function subtreeWalk(name) {
+    return `${name}(id, parent_id) AS (
+    SELECT seed.id, seed.parent_id
+    FROM nodes seed
+    WHERE ? = 1
+       OR seed.owner_id = ?
+       OR ${nodeGrantExists("seed.id")}
+    UNION
+    SELECT child.id, child.parent_id
+    FROM nodes child
+    JOIN ${name} parent ON child.parent_id = parent.id
+  )`;
+}
+// The walk under the name every single-verb statement already uses. Callers append their own SELECT
+// and may append further CTEs with a comma.
+export const subtreeCte = `WITH RECURSIVE ${subtreeWalk("allowed")}`;
+export function subtreeBindings(actor, verb, now) {
+    return [actor.isAdmin ? 1 : 0, actor.id, ...grantBindings(actor, verb, now)];
+}
+/**
+ * One named folder and everything filed beneath it, appended to a statement that already carries
+ * `subtreeCte`. It answers "where", never "whether": a statement joins `descendants` *in addition
+ * to* `allowed`, so the scope can only take rows away from an answer the actor was already entitled
+ * to. Joining it instead of `allowed` would turn a search argument into a permission, which is
+ * exactly what ADR-0004 forbids — the caller supplies the id, and a caller is not a grant.
+ *
+ * ⚠️ `UNION`, never `UNION ALL`, for the reason `nodeVerbQuery` gives: a cycle in `parent_id` can
+ * reach the table and this walks downwards into it.
+ */
+export const descendantsCte = `descendants(id) AS (
+    SELECT scope.id FROM nodes scope WHERE scope.id = ?
+    UNION
+    SELECT child.id
+    FROM nodes child
+    JOIN descendants parent ON child.parent_id = parent.id
+  )`;
+/**
+ * Both walks in one statement: what the actor may open, and what they may run. Its bindings are
+ * `subtreeBindings(actor, "read", now)` followed by `subtreeBindings(actor, "execute", now)`, in
+ * that order.
+ */
+export const readableOrRunnableCte = `WITH RECURSIVE ${subtreeWalk("readable")},
+  ${subtreeWalk("runnable")}`;
+/**
+ * A flow the actor may open *or* may run, for a statement carrying `readableOrRunnableCte`. It is
+ * the callable rule of ADR-0004 §2/§3 — `execute` without `read` is the library, a building block
+ * anyone may run and few may open — asked of a whole list of flows at once instead of one flow at a
+ * time. Its bindings follow the two CTEs' and are `flowCallableBindings(actor, now)`.
+ *
+ * ⚠️ Both direct grants, and both are needed. A flow handed out on its own for `execute` alone is
+ * the library case shrunk to one flow — runnable by people who may not open it — and leaving `read`
+ * out here would hide a flow somebody was explicitly given to look at.
+ */
+export const flowCallable = `(
+  ? = 1
+  OR flow.owner_id = ?
+  OR flow.parent_id IN (SELECT id FROM readable)
+  OR flow.parent_id IN (SELECT id FROM runnable)
+  OR ${flowGrantExists("flow.id")}
+  OR ${flowGrantExists("flow.id")}
+)`;
+export function flowCallableBindings(actor, now) {
+    return [
+        actor.isAdmin ? 1 : 0,
+        actor.id,
+        ...grantBindings(actor, "read", now),
+        ...grantBindings(actor, "execute", now),
+    ];
+}
+/**
+ * The point check for one node: the node itself and every ancestor above it. Cheaper than
+ * the subtree walk and the same answer, because a grant reaches down and never sideways.
+ *
+ * ⚠️ `UNION`, never `UNION ALL`. The service refuses to move a node into its own descendant, but a
+ * cycle in `parent_id` can still reach the table — a restore, a repair, a future writer. `UNION ALL`
+ * would walk such a ring without end, and this query runs on the authorization path of every
+ * request, so the damage lands in the database rather than in one tab. `UNION` folds the repeated
+ * row away and the recursion stops on its own.
+ */
+export const nodeVerbQuery = `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 1 AS allowed
+  FROM ancestors
+  WHERE ? = 1
+     OR owner_id = ?
+     OR ${nodeGrantExists("ancestors.id")}
+  LIMIT 1`;
+export function nodeVerbBindings(nodeId, actor, verb, now) {
+    return [nodeId, actor.isAdmin ? 1 : 0, actor.id, ...grantBindings(actor, verb, now)];
+}
+/**
+ * The same question for a flow. Three things reach it, and they are OR-ed rather than ranked: its
+ * owner, a grant on the folder it is filed in or any folder above that, and — since #530 — a grant
+ * that sits on the flow itself. Its owner keeps it the way a node's owner keeps theirs, otherwise a
+ * flow at the root of the tree would be unreachable by the person who created it. `UNION` for the
+ * same reason as above.
+ *
+ * ⚠️ The direct grant is asked BEFORE the ancestor walk, and only because it is cheaper: a point
+ * lookup on an indexed column against a recursive walk of the tree. It decides nothing the walk
+ * would have decided differently — both are the same OR.
+ */
+export const flowVerbQuery = `WITH RECURSIVE ancestors(id, parent_id) AS (
+    SELECT folder.id, folder.parent_id
+    FROM nodes folder
+    JOIN flows flow ON flow.parent_id = folder.id
+    WHERE flow.id = ?
+    UNION
+    SELECT parent.id, parent.parent_id
+    FROM nodes parent
+    JOIN ancestors child ON child.parent_id = parent.id
+  )
+  SELECT 1 AS allowed
+  FROM flows flow
+  WHERE flow.id = ?
+    AND (
+      ? = 1
+      OR flow.owner_id = ?
+      OR ${flowGrantExists("flow.id")}
+      OR EXISTS (SELECT 1 FROM ancestors WHERE ${nodeGrantExists("ancestors.id")})
+    )
+  LIMIT 1`;
+export function flowVerbBindings(flowId, actor, verb, now) {
+    return [
+        flowId,
+        flowId,
+        actor.isAdmin ? 1 : 0,
+        actor.id,
+        ...grantBindings(actor, verb, now),
+        ...grantBindings(actor, verb, now),
+    ];
+}
+/**
+ * The predicate a query over `flows` uses when it already carries `subtreeCte` for the same verb.
+ * Its bindings follow the CTE's.
+ *
+ * ⚠️ The verb is now a binding of its own, and it has to be the SAME verb the CTE was seeded with.
+ * The walk answers "which folders", the direct grant answers "this flow" — asking them for two
+ * different verbs would produce a predicate that is neither, and it is the kind of mismatch nothing
+ * fails on: the query still runs and quietly hands out the wrong list.
+ */
+/**
+ * ⚠️ The parent is a PARAMETER for exactly one caller, and giving it one was cheaper than the
+ * alternative. The feed reads events about flows that no longer exist: after `flows.purge` the row
+ * is gone, so `flow.parent_id`, `flow.owner_id` and every `flow_grants` row are gone with it, and
+ * the only anchor left is the `parentId` the purge wrote into its own metadata (#763, D73). A
+ * second, similar-looking predicate beside this one is the drift `destructive.md` warns about: two
+ * expressions with similar names are two different questions, and the one that goes stale is the
+ * copy.
+ */
+/**
+ * ⚠️ **The ALIAS is a parameter too, since #767, and leaving it hard-wired was a real fault rather
+ * than an inelegance.** The feed's third branch asks about a flow reached through its RUN, so the
+ * flow sits under a second join (`run_flow`) while `flow` is NULL on that row. Against the
+ * hard-wired name the owner branch and the direct-grant branch both compared NULL — so a flow
+ * somebody OWNS but that hangs at the top level, with no folder above it to carry a grant, answered
+ * "not visible" to its own owner.
+ *
+ * ⚠️ It fails in the safe direction, which is exactly what made it worth a test rather than a
+ * comment: nothing leaks, a row is only ever missing. A flow filed in a readable FOLDER answers
+ * correctly through the third branch, so every test with a folder is green either way — and the two
+ * tests that caught it are the ones that seed a flow at the root.
+ */
+export function flowInSubtreeOver(parentExpression, flowAlias = "flow") {
+    return `(
+  ? = 1
+  OR ${flowAlias}.owner_id = ?
+  OR ${parentExpression} IN (SELECT id FROM allowed)
+  OR ${flowGrantExists(`${flowAlias}.id`)}
+)`;
+}
+export const flowInSubtree = flowInSubtreeOver("flow.parent_id");
+export function flowInSubtreeBindings(actor, verb, now) {
+    return [actor.isAdmin ? 1 : 0, actor.id, ...grantBindings(actor, verb, now)];
+}

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

@@ -0,0 +1,3 @@
+import type { NodeIndexRepository } from "../../nodes/nodes.types.js";
+import type { D1Database } from "./db.types.js";
+export declare function createNodeIndexRepository(db: D1Database): NodeIndexRepository;

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

@@ -0,0 +1,200 @@
+// How much of a chunk is kept as the passage a searcher is shown. The same 480 characters
+// `hydrateVisibleCitations` cuts out of the full-text row, so a citation reads the same length
+// whether it came from a card's own vector or from the fallback beside it.
+const maxPassageCharacters = 480;
+/**
+ * What goes into the `content` column beside the title (#816).
+ *
+ * The description is a sentence ABOUT the node, not a name, so it belongs on the side the query
+ * weights at 1.0 and draws its snippet from — `bm25(node_fts, 0.0, 0.0, 4.0, 1.0)` and
+ * `snippet(node_fts, 3, ...)` in `searchVisible`. In `title` it would let a sentence outrank a
+ * matching name at four times the weight, and a description-only match would then produce a snippet
+ * cut from a body the searcher's word never appears in.
+ *
+ * ⚠️ Applied to every chunk, and that is deliberately NOT the rule the title follows on the vector
+ * side. There a prefix lands in the fingerprint, so putting it on every chunk would cost one
+ * embedding per chunk each time the node is renamed (anchrd/intel#301); a full-text row has neither
+ * a fingerprint nor an embedding behind it, so the reason for the restriction does not exist here.
+ * Since #390 every kind brings exactly one chunk anyway.
+ */
+function indexedContent(description, text) {
+    const sentence = description?.trim() ?? "";
+    if (sentence === "")
+        return text;
+    return text === "" ? sentence : `${sentence}\n\n${text}`;
+}
+function mapTarget(row, contentKeys) {
+    return {
+        nodeId: row.node_id,
+        versionId: row.version_id,
+        title: row.title,
+        description: row.description,
+        contentKeys,
+        mediaType: row.media_type,
+        size: row.size,
+        kind: row.kind,
+        updatedAt: row.updated_at,
+    };
+}
+export function createNodeIndexRepository(db) {
+    return {
+        async getTarget(versionId) {
+            const row = await db
+                .prepare(`SELECT n.id AS node_id, v.id AS version_id, n.title, n.description, v.content_key,
+          v.media_type, v.size, n.kind, n.updated_at
+          FROM node_versions v
+          JOIN nodes n ON n.id = v.node_id
+          WHERE v.id = ? AND n.current_version_id = v.id AND n.archived_at IS NULL`)
+                .bind(versionId)
+                .first();
+            if (!row)
+                return null;
+            if (row.kind !== "table")
+                return mapTarget(row, [row.content_key]);
+            // A table's rows live in every segment since the newest snapshot, so indexing the newest one
+            // alone would make a search find only what the last append added (#40) — and indexing the
+            // segments before a snapshot would make it find rows a mutation removed (#135). The same
+            // reading rule as `listVersionContentKeys`, because the index must describe what a read sees.
+            const segments = await 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(row.node_id, row.node_id)
+                .all();
+            return mapTarget(row, (segments.results ?? []).map((segment) => segment.content_key));
+        },
+        /**
+         * Every passage of this node, replacing every passage it had.
+         *
+         * ⚠️ One row per chunk, in ONE batch with the delete in front of it. Most kinds bring exactly
+         * one chunk and this is the statement pair it always was; a board brings one per task (#285),
+         * and a search can then answer with the card that matched rather than with the whole board.
+         *
+         * ⚠️ A board with no tasks writes no row at all, and that is right: there is nothing to find in
+         * it. What must not happen is the delete landing without the inserts, which is why they share a
+         * batch — D1 runs it as one transaction.
+         */
+        async replace(target, chunks) {
+            await db.batch([
+                db
+                    .prepare(`DELETE FROM node_fts WHERE node_id = ? AND EXISTS (
+            SELECT 1 FROM nodes
+            WHERE id = ? AND current_version_id = ? AND archived_at IS NULL
+          )`)
+                    .bind(target.nodeId, target.nodeId, target.versionId),
+                ...chunks.map((chunk) => db
+                    .prepare(`INSERT INTO node_fts (version_id, node_id, title, content)
+              SELECT ?, ?, ?, ? WHERE EXISTS (
+                SELECT 1 FROM nodes
+                WHERE id = ? AND current_version_id = ? AND archived_at IS NULL
+              )`)
+                    .bind(target.versionId, target.nodeId, chunk.title, indexedContent(target.description, chunk.text), target.nodeId, target.versionId)),
+            ]);
+        },
+        /**
+         * ⚠️ `archived_at IS NOT NULL` carries this on its own, and it is the whole guard
+         * (anchrd/intel#348). `getTarget` above answers null for two reasons and only one of them means
+         * "purge": the other is a queue message for a version a later save superseded, and Cloudflare
+         * Queues deliver at least once, so those arrive as a matter of course. Acting on one would empty
+         * the vector index of a live board behind the back of the save that had just filled it — and
+         * nothing would report it, because a search that finds less is not an error.
+         *
+         * ⚠️ Deliberately NOT `current_version_id = v.id` as well, although that is what would make this
+         * the mirror image of `getTarget`. Symmetry is not a reason to write a condition: once the node
+         * IS archived, every version of it says the same thing about that node's vectors, so the extra
+         * clause could only ever refuse a purge that was right. A condition no test can turn red is a
+         * condition the next reader has to guess the purpose of.
+         */
+        async archivedNodeId(versionId) {
+            const row = await db
+                .prepare(`SELECT n.id AS node_id
+          FROM node_versions v
+          JOIN nodes n ON n.id = v.node_id
+          WHERE v.id = ? AND n.archived_at IS NOT NULL`)
+                .bind(versionId)
+                .first();
+            return row?.node_id ?? null;
+        },
+        async listVectors(nodeId) {
+            const result = await db
+                .prepare(`SELECT chunk_key, fingerprint, passage FROM node_vectors WHERE node_id = ?`)
+                .bind(nodeId)
+                .all();
+            return (result.results ?? []).map((row) => ({
+                chunkKey: row.chunk_key,
+                fingerprint: row.fingerprint,
+                passage: row.passage,
+            }));
+        },
+        /**
+         * The record of every vector this node has, replacing the record it had.
+         *
+         * ⚠️ The same delete-then-insert in ONE batch as `replace` above, and the same guard in front of
+         * every statement: a pass for a version that is no longer current, or for a node that has been
+         * archived meanwhile, writes nothing at all rather than half a record. What must not happen is
+         * the delete landing without the inserts — the next pass would then re-embed the whole board,
+         * which is exactly the cost anchrd/intel#301 exists to avoid.
+         */
+        async replaceVectors(target, records) {
+            await db.batch([
+                db
+                    .prepare(`DELETE FROM node_vectors WHERE node_id = ? AND EXISTS (
+            SELECT 1 FROM nodes
+            WHERE id = ? AND current_version_id = ? AND archived_at IS NULL
+          )`)
+                    .bind(target.nodeId, target.nodeId, target.versionId),
+                ...records.map((record) => db
+                    .prepare(`INSERT INTO node_vectors (node_id, chunk_key, version_id, fingerprint, passage)
+              SELECT ?, ?, ?, ?, ? WHERE EXISTS (
+                SELECT 1 FROM nodes
+                WHERE id = ? AND current_version_id = ? AND archived_at IS NULL
+              )`)
+                    .bind(target.nodeId, record.chunkKey, target.versionId, record.fingerprint, record.passage.slice(0, maxPassageCharacters), target.nodeId, target.versionId)),
+            ]);
+        },
+        /**
+         * The record of one node, gone — because its vectors are (anchrd/intel#348).
+         *
+         * ⚠️ No guard at all, and the absence is deliberate in both directions. There is no
+         * `archived_at IS NOT NULL`: the state this write exists to prevent is a row that outlives the
+         * vector it names, and a node restored between the deletion and this statement would keep
+         * exactly that — a record claiming vectors that are gone, which the next pass reads as "already
+         * embedded" and skips, leaving those cards silently unfindable. And there is no version
+         * condition: `archivedNodeId` has already established which node this is, from that same
+         * version, and a second reading of a moving row is a second answer rather than a safer one.
+         */
+        async deleteVectors(nodeId) {
+            await db.prepare("DELETE FROM node_vectors WHERE node_id = ?").bind(nodeId).run();
+        },
+        async markIndexed(versionId, occurredAt) {
+            await db
+                .prepare(`UPDATE node_index_state
+          SET status = 'indexed', attempt_count = attempt_count + 1,
+            last_error = NULL, updated_at = ?
+          WHERE version_id = ? AND EXISTS (
+            SELECT 1 FROM node_versions version
+            JOIN nodes node ON node.id = version.node_id
+            WHERE version.id = ? AND node.current_version_id = version.id
+              AND node.archived_at IS NULL
+          )`)
+                .bind(occurredAt, versionId, versionId)
+                .run();
+        },
+        async markError(versionId, message, occurredAt) {
+            await db
+                .prepare(`UPDATE node_index_state
+          SET status = 'error', attempt_count = attempt_count + 1,
+            last_error = ?, updated_at = ? WHERE version_id = ? AND EXISTS (
+              SELECT 1 FROM node_versions version
+              JOIN nodes node ON node.id = version.node_id
+              WHERE version.id = ? AND node.current_version_id = version.id
+                AND node.archived_at IS NULL
+            )`)
+                .bind(message.slice(0, 500), occurredAt, versionId, versionId)
+                .run();
+        },
+    };
+}

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

@@ -0,0 +1,3 @@
+import type { OAuthClientStore } from "../../auth/auth.types.js";
+import type { D1Database } from "./db.types.js";
+export declare function createOAuthClientStore(db: D1Database): OAuthClientStore;

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

@@ -0,0 +1,26 @@
+export function createOAuthClientStore(db) {
+    return {
+        async get(issuer, redirectUri) {
+            const row = await db
+                .prepare("SELECT client_id FROM oauth_clients WHERE issuer = ? AND redirect_uri = ?")
+                .bind(issuer, redirectUri)
+                .first();
+            return row?.client_id ?? null;
+        },
+        async put(input) {
+            await db
+                .prepare(`INSERT OR IGNORE INTO oauth_clients (
+          issuer, redirect_uri, client_id, created_at
+        ) VALUES (?, ?, ?, ?)`)
+                .bind(input.issuer, input.redirectUri, input.clientId, input.createdAt)
+                .run();
+            const stored = await db
+                .prepare("SELECT client_id FROM oauth_clients WHERE issuer = ? AND redirect_uri = ?")
+                .bind(input.issuer, input.redirectUri)
+                .first();
+            if (!stored)
+                throw new Error("OAuth client registration was not stored");
+            return stored.client_id;
+        },
+    };
+}