@anchrd/intel 0.59.0

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

@@ -0,0 +1,46 @@
+import type { Actor } from "../../nodes/nodes.types.js";
+import type { PromptNameHolder, PromptRepository } from "../../prompts/prompts.types.js";
+import type { D1Database } from "./db.types.js";
+/**
+ * The documents this actor may read that are offered as a slash command (#775).
+ *
+ * ⚠️ **Two statements rather than one `UNION`, and the reason is the visibility walk.** A document
+ * is visible through `allowed`; a flow is visible through `flowInSubtree`, which is a different
+ * predicate over different tables and needs its own bindings in its own order. Welded into one
+ * statement the two would share a placeholder sequence that nobody can read back — and the failure
+ * that produces is a shifted binding, which does not throw: it answers the wrong list.
+ *
+ * ⚠️ **`archived_at IS NULL` is part of being offered.** Archiving is what "delete" means here, and
+ * a command that starts an archived document is a command onto something the tree no longer shows.
+ * The name stays taken while it is archived — a restore brings the command back rather than finding
+ * its name given away in the meantime.
+ *
+ * ⚠️ The `kind = 'document'` is redundant against the CHECK in `0028` and stays anyway: it is the
+ * one line that keeps this query honest if that CHECK is ever loosened, and it costs nothing on a
+ * partial index that only holds the offered rows.
+ */
+export declare const offeredDocumentsQuery: string;
+/**
+ * The published flows this actor may read that are offered as a slash command.
+ *
+ * ⚠️ **`published_version_id IS NOT NULL` is the switch, and it is the whole of it** (#775).
+ * Publishing is already the decision that a flow is for other people, so `flow_publish` sets the
+ * name and nothing else asks again. A flow that is withdrawn KEEPS its name and leaves this list:
+ * the name is what makes republishing it the same command rather than a new one, and a client that
+ * stored it is not left pointing at a command that has since become somebody else's.
+ *
+ * ⚠️ `read`, not `execute`, and that is not the obvious choice. A flow in the library — runnable by
+ * people who may not open it (ADR-0004 §2/§3) — is deliberately NOT listed: a catalogue entry
+ * carries a title and a description, and those are the readable half. Somebody who may only run it
+ * still can, through `flow_run_start` with the id they were given; what they do not get is a
+ * listing that names it.
+ */
+export declare const offeredFlowsQuery: string;
+export declare function promptNameHolder(deps: {
+    db: D1Database;
+    now(): Date;
+}, actor: Actor, name: string): Promise<PromptNameHolder | null>;
+export declare function createPromptRepository(deps: {
+    db: D1Database;
+    now(): Date;
+}): PromptRepository;

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

@@ -0,0 +1,144 @@
+import { flowInSubtree, flowInSubtreeBindings, subtreeBindings, subtreeCte } from "./db-grants.js";
+/**
+ * The documents this actor may read that are offered as a slash command (#775).
+ *
+ * ⚠️ **Two statements rather than one `UNION`, and the reason is the visibility walk.** A document
+ * is visible through `allowed`; a flow is visible through `flowInSubtree`, which is a different
+ * predicate over different tables and needs its own bindings in its own order. Welded into one
+ * statement the two would share a placeholder sequence that nobody can read back — and the failure
+ * that produces is a shifted binding, which does not throw: it answers the wrong list.
+ *
+ * ⚠️ **`archived_at IS NULL` is part of being offered.** Archiving is what "delete" means here, and
+ * a command that starts an archived document is a command onto something the tree no longer shows.
+ * The name stays taken while it is archived — a restore brings the command back rather than finding
+ * its name given away in the meantime.
+ *
+ * ⚠️ The `kind = 'document'` is redundant against the CHECK in `0028` and stays anyway: it is the
+ * one line that keeps this query honest if that CHECK is ever loosened, and it costs nothing on a
+ * partial index that only holds the offered rows.
+ */
+export const offeredDocumentsQuery = `${subtreeCte}
+    SELECT n.prompt_name, n.id, n.title, n.description
+    FROM nodes n
+    JOIN allowed ON allowed.id = n.id
+    WHERE n.prompt_name IS NOT NULL
+      AND n.kind = 'document'
+      AND n.archived_at IS NULL
+    ORDER BY n.prompt_name`;
+/**
+ * The published flows this actor may read that are offered as a slash command.
+ *
+ * ⚠️ **`published_version_id IS NOT NULL` is the switch, and it is the whole of it** (#775).
+ * Publishing is already the decision that a flow is for other people, so `flow_publish` sets the
+ * name and nothing else asks again. A flow that is withdrawn KEEPS its name and leaves this list:
+ * the name is what makes republishing it the same command rather than a new one, and a client that
+ * stored it is not left pointing at a command that has since become somebody else's.
+ *
+ * ⚠️ `read`, not `execute`, and that is not the obvious choice. A flow in the library — runnable by
+ * people who may not open it (ADR-0004 §2/§3) — is deliberately NOT listed: a catalogue entry
+ * carries a title and a description, and those are the readable half. Somebody who may only run it
+ * still can, through `flow_run_start` with the id they were given; what they do not get is a
+ * listing that names it.
+ */
+export const offeredFlowsQuery = `${subtreeCte}
+    SELECT flow.prompt_name, flow.id, flow.title, flow.description
+    FROM flows flow
+    WHERE flow.prompt_name IS NOT NULL
+      AND flow.published_version_id IS NOT NULL
+      AND flow.archived_at IS NULL
+      AND ${flowInSubtree}
+    ORDER BY flow.prompt_name`;
+/**
+ * Who holds one name, asked of both tables at once, for the refusal a taken name gets.
+ *
+ * ⚠️ **Existence is answered to everybody; the TITLE only to those entitled to it.** The question
+ * "is this name free" has to be answered truthfully or the caller can do nothing — they are refused
+ * by an index they cannot see and told the node was changed by another editor. What must not travel
+ * is the title: naming the document that holds `payroll` tells somebody without access that a
+ * document by that title exists, and ADR-0004 §3 is explicit that a refusal must not become a way
+ * of reading the tree. The `CASE` below is where the two halves part.
+ *
+ * ⚠️ **One function, called from both repositories, rather than one query per repository.** A node
+ * write and a flow publish refuse for the same reason and have to say the same sentence; two
+ * spellings of this would drift, and the one that drifts is the one whose surface is used less.
+ * `destructive.md` calls it by name: two queries with similar names are two different questions.
+ */
+const holderQuery = `${subtreeCte}
+    SELECT 'document' AS kind, CASE WHEN allowed.id IS NULL THEN NULL ELSE n.title END AS title
+    FROM nodes n
+    LEFT JOIN allowed ON allowed.id = n.id
+    WHERE n.prompt_name = ?
+    UNION ALL
+    SELECT 'flow' AS kind, CASE WHEN ${flowInSubtree} THEN flow.title ELSE NULL END AS title
+    FROM flows flow
+    WHERE flow.prompt_name = ?`;
+export async function promptNameHolder(deps, actor, name) {
+    const now = deps.now().toISOString();
+    const row = await deps.db
+        .prepare(holderQuery)
+        .bind(...subtreeBindings(actor, "read", now), name, ...flowInSubtreeBindings(actor, "read", now), name)
+        .first();
+    return row === null ? null : { kind: row.kind, title: row.title };
+}
+function mapEntry(row, kind) {
+    return {
+        name: row.prompt_name,
+        kind,
+        targetId: row.id,
+        title: row.title,
+        description: row.description,
+    };
+}
+export function createPromptRepository(deps) {
+    return {
+        async listOffered(actor) {
+            const now = deps.now().toISOString();
+            /**
+             * ⚠️ **A half the actor has no capability for is not asked for at all** (#775, following
+             * #774). Running the statement and discarding its rows would be the same answer at the cost
+             * of a walk over the tree — and worse, it would put the decision in the mapping step, where
+             * the next reader of this function cannot see it.
+             *
+             * ⚠️ **Each statement carries its own kind, rather than the two being read back out of fixed
+             * positions.** With only `flows/read` the flow query is the ONLY element, so it arrives as
+             * result zero: a `const [documents, flows]` here puts the flows in a variable called
+             * `documents`, and the name is then a lie in one of the four branches. It answers correctly
+             * today and mis-binds the moment somebody adds a third conditional query — which is exactly
+             * the kind of edit this list invites.
+             */
+            const asked = [];
+            if (actor.canReadNodes) {
+                asked.push({
+                    kind: "document",
+                    statement: deps.db
+                        .prepare(offeredDocumentsQuery)
+                        .bind(...subtreeBindings(actor, "read", now)),
+                });
+            }
+            if (actor.canReadFlows) {
+                asked.push({
+                    kind: "flow",
+                    statement: deps.db
+                        .prepare(offeredFlowsQuery)
+                        .bind(...subtreeBindings(actor, "read", now), ...flowInSubtreeBindings(actor, "read", now)),
+                });
+            }
+            const results = await deps.db.batch(asked.map((each) => each.statement));
+            return (asked
+                .flatMap((each, index) => (results[index]?.results ?? []).map((row) => mapEntry(row, each.kind)))
+                // ⚠️ Sorted over the MERGED list rather than relying on the two `ORDER BY` clauses. Each
+                // statement orders its own half, and concatenating two ordered halves gives an unordered
+                // whole — `prompts/list` would then be alphabetical within documents and again within
+                // flows, which reads as "unsorted with a pattern" to anybody scrolling it.
+                .sort((left, right) => left.name.localeCompare(right.name)));
+        },
+        async findOffered(actor, name) {
+            // The catalogue is the list this actor may see, so looking one entry up is looking in that
+            // list. A separate statement with its own `WHERE prompt_name = ?` would be a second walk to
+            // keep in step with the first, for a set that is small by construction: the offered rows are
+            // a curated handful, not the tree.
+            const offered = await this.listOffered(actor);
+            return offered.find((entry) => entry.name === name) ?? null;
+        },
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { NodeRepository } from "../../nodes/nodes.types.js";
+import type { D1Database } from "./db.types.js";
+export declare function createNodeRepository(deps: {
+    db: D1Database;
+    now(): Date;
+}): NodeRepository;