@anchrd/intel-api 0.13.0 → 0.14.0

package/dist/adapters/cloudflare/cloudflare.js

@@ -259,6 +259,7 @@ export default {
             content: createContentStore(env.CONTENT),
             semantic: env.AI && env.SEARCH ? createSemanticIndex({ ai: env.AI, index: env.SEARCH }) : undefined,
             converter: env.AI ? createDocumentConverter(env.AI) : undefined,
+            hash: async (content) => await sha256Hex(crypto, content),
             now: () => new Date(),
         });
         for (const message of batch.messages) {

package/dist/adapters/cloudflare-api/cloudflare-api.js

@@ -36,6 +36,16 @@ const PerPage = 50;
  * yet (anchrd/intel#330).
  */
 const ModelPerPage = 100;
+/**
+ * How many pages of the model catalog are read before the reader gives up.
+ *
+ * ⚠️ It is a runaway brake and not a window, which is the opposite of `MaxPages` above. The log has
+ * more calls than anybody wants to read; the catalog is finite and small — 61 entries on this
+ * account — so the loop normally ends on the first short page and this number is never reached.
+ * What it guards against is an endpoint that answers a full page forever, and a loop inside a
+ * request nobody is watching.
+ */
+const ModelMaxPages = 10;
 /**
  * The gateway's log entry, read tolerantly.
  *
@@ -159,56 +169,138 @@ export function createCloudflareApi(deps) {
     }
     return {
         async gatewayCalls(query) {
-            const calls = [];
-            let partial = false;
-            for (let page = 1; page <= MaxPages; page += 1) {
-                const body = await get(`/accounts/${encodeURIComponent(deps.accountId)}/ai-gateway/gateways/${encodeURIComponent(deps.gatewayId)}/logs`, {
-                    page: String(page),
-                    per_page: String(PerPage),
-                    start_date: query.since.toISOString(),
-                    end_date: query.until.toISOString(),
-                    order_by: "created_at",
-                    order_by_direction: "desc",
-                    // ⚠️ Only documented scalar parameters travel. The endpoint also takes a `filters` array
-                    // whose query encoding Cloudflare documents nowhere — neither the reference nor the
-                    // curl example shows it — so a guess at it would either be ignored (a slow read) or
-                    // rejected (no read at all), and there is no way to tell those apart from the status.
-                    // The agent is therefore picked out below, from the metadata the runtime stamped.
-                });
-                const parsed = LogResponse.safeParse(body);
-                // A shape this reader cannot make sense of is a failure, not an empty window: an empty
-                // window reads as "this agent cost nothing".
-                if (!parsed.success) {
-                    throw new IntelError(502, "cloudflare_api_unreadable", "The Cloudflare API answered in a shape this version does not understand");
-                }
-                const entries = parsed.data.result ?? [];
-                for (const entry of entries) {
-                    const metadata = readMetadata(entry.metadata);
-                    if (metadata.agentId !== query.agentId)
-                        continue;
-                    calls.push({
-                        runId: typeof metadata.runId === "string" ? metadata.runId : null,
-                        model: entry.model ?? "",
-                        cost: entry.cost ?? 0,
-                        at: entry.created_at ?? query.until.toISOString(),
+            const logPath = `/accounts/${encodeURIComponent(deps.accountId)}/ai-gateway/gateways/${encodeURIComponent(deps.gatewayId)}/logs`;
+            /**
+             * One window of the log, optionally cut to this agent by the gateway itself.
+             *
+             * The encoding Cloudflare documents nowhere, measured against the live gateway (#274):
+             * `filters` is a URL-encoded JSON array, and `value` is an ARRAY even for a single value.
+             *
+             *   filters=[{"key":"metadata.value","operator":"eq","value":["<id>"]}]  → 200, filtered
+             *   value as a scalar string  → 400 `Expected array, received string`
+             *   filters as a JSON object  → 400 `Expected array, received object`
+             *   filters[0][key]=… (brackets) and filters.0.key=… (dots) → 200, SILENTLY IGNORED
+             *
+             * ⚠️ The last line is why this was never guessed at: two of the five spellings answer 200
+             * with the whole unfiltered window, which reads exactly like a filter that matched
+             * everything. Two filters combine with AND (measured with `metadata.key` plus `runId`).
+             */
+            async function read(pages, filtered) {
+                const calls = [];
+                let partial = false;
+                for (let index = 1; index <= pages; index += 1) {
+                    const body = await get(logPath, {
+                        page: String(index),
+                        per_page: String(PerPage),
+                        start_date: query.since.toISOString(),
+                        end_date: query.until.toISOString(),
+                        order_by: "created_at",
+                        order_by_direction: "desc",
+                        ...(filtered
+                            ? {
+                                filters: JSON.stringify([
+                                    { key: "metadata.value", operator: "eq", value: [query.agentId] },
+                                ]),
+                            }
+                            : {}),
                     });
+                    const parsed = LogResponse.safeParse(body);
+                    // A shape this reader cannot make sense of is a failure, not an empty window: an empty
+                    // window reads as "this agent cost nothing".
+                    if (!parsed.success) {
+                        throw new IntelError(502, "cloudflare_api_unreadable", "The Cloudflare API answered in a shape this version does not understand");
+                    }
+                    const entries = parsed.data.result ?? [];
+                    // ⚠️ The local check stays even under the server-side filter, and it is no longer belt
+                    // and braces: it is the only thing that could notice the filter matching the wrong rows.
+                    for (const entry of entries) {
+                        const metadata = readMetadata(entry.metadata);
+                        if (metadata.agentId !== query.agentId)
+                            continue;
+                        calls.push({
+                            runId: typeof metadata.runId === "string" ? metadata.runId : null,
+                            model: entry.model ?? "",
+                            cost: entry.cost ?? 0,
+                            at: entry.created_at ?? query.until.toISOString(),
+                        });
+                    }
+                    if (entries.length < PerPage)
+                        return { calls, partial: false };
+                    partial = index === pages;
                 }
-                if (entries.length < PerPage)
-                    return { calls, partial: false };
-                partial = page === MaxPages;
+                return { calls, partial };
             }
-            return { calls, partial };
+            const answer = await read(MaxPages, true);
+            /**
+             * ⚠️ Anything at all is taken at face value, and that is a decision with a hole in it. A
+             * filter that degraded PARTLY — matching some of this agent's rows and not others — returns
+             * here, and the under-count is then handed out as `partial: false`, which claims to be a
+             * total. The probe below cannot see that case, because the probe is only reached when the
+             * filtered read found nothing. It is the price of not reading the whole log twice on every
+             * request, and it is worth knowing before somebody reads `partial: false` as "complete".
+             */
+            if (answer.calls.length > 0)
+                return answer;
+            /**
+             * ⚠️ Zero is the ONE answer this reader may not take at face value, and the reason is the
+             * way `filters` fails. Measured: `cached` filtered to `["false"]` answers 200 with zero rows
+             * although every row in that window carries `cached: false` — a value the index does not
+             * match empties the page instead of being refused. So the day metadata stops being indexed
+             * the way it is today, this would report "cost nothing" for an agent that spent money, under
+             * `status: "read"`. That is precisely the sentence #251 exists for.
+             *
+             * One unfiltered page is the probe: if the newest calls contain any of this agent's, the
+             * filter is lying and the honest answer is that the log could not be read. It costs one
+             * request and only in the empty case, which is a fresh agent or a quiet window — and in the
+             * case it replaces, a quiet agent on a busy gateway, it costs 2 requests where reading the
+             * whole log unfiltered used to cost 20.
+             *
+             * ⚠️ It is a probe and not a proof: an agent whose only calls are older than the newest
+             * `PerPage` of the whole gateway is invisible to it, and that case still reports zero. What
+             * it buys is that a filter which stopped working ENTIRELY cannot pass as silence.
+             *
+             * ⚠️ A probe that cannot run leaves the answer standing, deliberately. The read this is
+             * checking SUCCEEDED and said "no calls"; letting a second opinion that never arrived turn
+             * that into `unreadable` would report an outage for the most ordinary state there is — a
+             * fresh agent — because one extra request met a 429. The guard is a second opinion, not the
+             * answer.
+             */
+            const probe = await read(1, false).catch(() => null);
+            if (probe === null || probe.calls.length === 0)
+                return answer;
+            throw new IntelError(502, "cloudflare_api_unreadable", "The Cloudflare API answered no calls for this agent while its own log holds some");
         },
         async workersAiModels() {
-            const body = await get(`/accounts/${encodeURIComponent(deps.accountId)}/ai/models/search`, {
-                per_page: String(ModelPerPage),
-                hide_experimental: "true",
-            });
-            const parsed = ModelResponse.safeParse(body);
-            if (!parsed.success) {
-                throw new IntelError(502, "cloudflare_api_unreadable", "The Cloudflare API answered in a shape this version does not understand");
+            const models = [];
+            for (let index = 1; index <= ModelMaxPages; index += 1) {
+                const body = await get(`/accounts/${encodeURIComponent(deps.accountId)}/ai/models/search`, {
+                    page: String(index),
+                    per_page: String(ModelPerPage),
+                    hide_experimental: "true",
+                });
+                const parsed = ModelResponse.safeParse(body);
+                if (!parsed.success) {
+                    throw new IntelError(502, "cloudflare_api_unreadable", "The Cloudflare API answered in a shape this version does not understand");
+                }
+                const entries = parsed.data.result ?? [];
+                models.push(...entries.map(readModel));
+                // ⚠️ A SHORT page is the end, and a full one is not a reason to believe the answer was
+                // complete (#330). Before this the reader took page one and stopped: a model past position
+                // 100 was simply absent from the select, `liveStatus` still said `read`, and nothing said
+                // the list was shorter than the account. A missing entry has no `source` to mark stale
+                // with, so the per-entry labelling that covers a fallback cannot cover this at all.
+                //
+                // ⚠️ `result_info.total_count` is NOT the test, which is why it is not parsed. Measured on
+                // the live account (#297): it reports 286 while page one returns 61 and page two is empty.
+                // A reader that paginated on that figure would loop over empty pages and call the result
+                // partial. The full page is the only honest signal.
+                if (entries.length < ModelPerPage)
+                    return models;
             }
-            return (parsed.data.result ?? []).map(readModel);
+            // Ten full pages is not a big account, it is an endpoint that stopped ending. Refusing is the
+            // honest answer: the catalog service falls back to its built-in table and the screen says the
+            // figures may be old — better than a list that is silently missing whatever came after.
+            throw new IntelError(502, "cloudflare_api_unreadable", "The Cloudflare API kept answering full pages of models past the read limit");
         },
     };
 }

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

@@ -1,3 +1,7 @@
+// 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;
 function mapTarget(row, contentKeys) {
     return {
         nodeId: row.node_id,
@@ -68,6 +72,81 @@ export function createNodeIndexRepository(db) {
                     .bind(target.versionId, target.nodeId, chunk.title, 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

package/dist/adapters/db/db.js

@@ -289,20 +289,17 @@ export function createNodeRepository(deps) {
          * ⚠️ `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.
-         *
-         * `context_policy` is the dead column migration 0009 explains; 'relevant' is the fixed value
-         * `insertNode` writes for the same reason.
          */
         async importTree(input) {
             const statements = [
                 deps.db
                     .prepare(`INSERT INTO nodes (
-            id, parent_id, kind, title, description, context_policy, owner_id,
+            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'), 'relevant',
+            json_extract(value, '$.description'),
             json_extract(value, '$.ownerId'), json_extract(value, '$.currentVersionId'),
             json_extract(value, '$.createdAt'), json_extract(value, '$.updatedAt'), NULL
           FROM json_each(?)`)
@@ -458,14 +455,10 @@ export function createNodeRepository(deps) {
             try {
                 await deps.db.batch([
                     deps.db
-                        // ⚠️ `context_policy` is dead and is written anyway (#76). The column is NOT NULL
-                        // without a DEFAULT and D1 will not let it be dropped — migration 0009 carries the
-                        // reason. The fixed value is the price; nothing reads it, and the contract no longer
-                        // knows the field. When the column goes (anchrd/intel#86), this line goes with it.
                         .prepare(`INSERT INTO nodes (
-            id, parent_id, kind, title, description, context_policy, owner_id,
+            id, parent_id, kind, title, description, owner_id,
             current_version_id, created_at, updated_at, archived_at
-          ) VALUES (?, ?, ?, ?, ?, 'relevant', ?, ?, ?, ?, ?)`)
+          ) 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 (
@@ -1144,32 +1137,46 @@ export function createNodeRepository(deps) {
                 match: "lexical",
             }));
         },
-        async hydrateVisibleCitations(actor, nodeIds, scopeId) {
-            const uniqueIds = [...new Set(nodeIds)].slice(0, 100);
-            if (uniqueIds.length === 0)
+        async hydrateVisibleCitations(actor, hits, scopeId) {
+            // One entry per node: the caller has already picked the best-scoring chunk of each, so a
+            // board that answered with four cards arrives as the one card that answered best.
+            const unique = [...new Map(hits.map((hit) => [hit.nodeId, hit])).values()].slice(0, 100);
+            if (unique.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(", ");
+            // 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)}
+                    .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,
-              substr(node_fts.content, 1, 480) AS passage,
+              -- ⚠️ 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 nodes n
+            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.id IN (${placeholders}) AND n.archived_at IS NULL`)
-                    .bind(...readBindings(actor), ...scopeBindings(scopeId), ...ids)
+            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(uniqueIds.map((id, index) => [id, index]));
-            // The same one-per-node rule as the lexical half above, for the same reason: a semantic hit
-            // is a hit on a NODE (the vector index is keyed by node id), so hydrating it must not turn one
-            // hit into one row per task.
+            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) => ({
@@ -1183,10 +1190,42 @@ export function createNodeRepository(deps) {
                 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 archived_at IS NULL
+          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)

package/dist/adapters/semantic-index/semantic-index.js

@@ -1,15 +1,48 @@
 const defaultModel = "@cf/baai/bge-m3";
 const maxEmbeddingCharacters = 24_000;
-function embedding(result) {
+// How much of one embedding request this adapter is willing to be: at most this many texts, and at
+// most this many characters across them. Both bounds are ours rather than a number Cloudflare
+// publishes — what the model documents is the shape of `text`, not a batch size — so they are set
+// well inside anything plausible. The point is that a board with three hundred cards costs a
+// handful of requests on its first pass instead of three hundred round trips.
+const maxBatchTexts = 25;
+const maxBatchCharacters = 96_000;
+// Vectorize takes at most 1000 vectors in one call from a Worker (platform limits). A board may
+// hold 5000 tasks, so the write is cut rather than sent whole and refused.
+const maxVectorsPerCall = 1000;
+/**
+ * How a chunk is named in the vector index (anchrd/intel#301).
+ *
+ * ⚠️ `""` keeps the bare node id, which is what every vector written before this was called. That
+ * is the whole reason the separator sits on the SUFFIX side: nothing an installation already holds
+ * changes its name, so this ships without re-embedding a tree.
+ *
+ * ⚠️ Reading it back splits at the FIRST separator, and that direction matters. A node id is minted
+ * here (`ulid`) and cannot contain a `#`; a task id can, because a bundle import carries the task
+ * ids written in the file. Splitting at the first `#` therefore always recovers the node id exactly
+ * and leaves the rest to the key — and even a key that never matched a card costs a hit that
+ * hydrates to nothing, never a citation for a node the searcher did not match.
+ */
+const chunkSeparator = "#";
+function vectorId(nodeId, key) {
+    return key === "" ? nodeId : `${nodeId}${chunkSeparator}${key}`;
+}
+function embeddings(result, expected) {
     if (typeof result !== "object" ||
         result === null ||
         !("data" in result) ||
         !Array.isArray(result.data) ||
-        !Array.isArray(result.data[0]) ||
-        !result.data[0].every((value) => typeof value === "number")) {
+        // ⚠️ The count is part of the check. The rows come back in the order the texts went out and
+        // nothing else identifies them, so a short answer would silently pair every embedding after the
+        // gap with the wrong card — a search that answers confidently with the neighbouring task.
+        result.data.length !== expected ||
+        // ⚠️ And every row has to hold something. An empty one passes "is an array of numbers" and would
+        // be upserted under a real card's name as a vector that matches nothing — indexed, recorded as
+        // fingerprinted, and never looked at again until somebody edits that card.
+        !result.data.every((row) => Array.isArray(row) && row.length > 0 && row.every((value) => typeof value === "number"))) {
         throw new Error("The embedding provider returned an invalid response");
     }
-    return result.data[0];
+    return result.data;
 }
 function matches(result) {
     if (typeof result !== "object" ||
@@ -27,27 +60,74 @@ function matches(result) {
             typeof match.score !== "number") {
             return [];
         }
-        return [{ nodeId: match.id, score: Math.max(0, Math.min(1, match.score)) }];
+        const separator = match.id.indexOf(chunkSeparator);
+        return [
+            {
+                nodeId: separator < 0 ? match.id : match.id.slice(0, separator),
+                chunkKey: separator < 0 ? "" : match.id.slice(separator + 1),
+                score: Math.max(0, Math.min(1, match.score)),
+            },
+        ];
     });
 }
+function batched(chunks) {
+    const batches = [];
+    let current = [];
+    let characters = 0;
+    for (const chunk of chunks) {
+        if (current.length > 0 &&
+            (current.length >= maxBatchTexts || characters >= maxBatchCharacters)) {
+            batches.push(current);
+            current = [];
+            characters = 0;
+        }
+        current.push(chunk);
+        characters += chunk.text.length;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}
 export function createSemanticIndex(deps) {
     const model = deps.model ?? defaultModel;
-    async function embed(text) {
-        return embedding(await deps.ai.run(model, { text: [text] }));
+    async function embed(texts) {
+        return embeddings(await deps.ai.run(model, { text: texts }), texts.length);
     }
     return {
-        async replace(target, content) {
-            const text = `${target.title}\n\n${content}`.slice(0, maxEmbeddingCharacters);
-            await deps.index.upsert([
-                {
-                    id: target.nodeId,
-                    values: await embed(text),
-                    metadata: { versionId: target.versionId },
-                },
-            ]);
+        async upsert(target, chunks) {
+            const vectors = [];
+            for (const batch of batched(chunks)) {
+                const values = await embed(batch.map((chunk) => chunk.text.slice(0, maxEmbeddingCharacters)));
+                batch.forEach((chunk, index) => {
+                    const embedded = values[index];
+                    // The index is what makes this reachable at all — `embeddings` has already refused a short
+                    // answer and an empty row, so this is the type system's question rather than the
+                    // provider's. It throws anyway rather than skipping: the alternative to a missing card is
+                    // never a shorter list, it is a card recorded as fingerprinted with no vector behind it.
+                    if (!embedded)
+                        throw new Error("The embedding provider returned an invalid response");
+                    vectors.push({
+                        id: vectorId(target.nodeId, chunk.key),
+                        values: embedded,
+                        metadata: { versionId: target.versionId },
+                    });
+                });
+            }
+            for (let offset = 0; offset < vectors.length; offset += maxVectorsPerCall) {
+                await deps.index.upsert(vectors.slice(offset, offset + maxVectorsPerCall));
+            }
+        },
+        async remove(nodeId, keys) {
+            const ids = keys.map((key) => vectorId(nodeId, key));
+            for (let offset = 0; offset < ids.length; offset += maxVectorsPerCall) {
+                await deps.index.deleteByIds(ids.slice(offset, offset + maxVectorsPerCall));
+            }
         },
         async search(query, limit) {
-            const result = await deps.index.query(await embed(query), {
+            const [vector] = await embed([query]);
+            if (!vector)
+                throw new Error("The embedding provider returned an invalid response");
+            const result = await deps.index.query(vector, {
                 topK: Math.max(1, Math.min(100, limit)),
                 returnMetadata: "none",
             });

package/dist/adapters/semantic-index/semantic-index.types.d.ts

@@ -12,17 +12,36 @@ export interface VectorizeBinding {
             versionId: string;
         };
     }>): Promise<unknown>;
+    deleteByIds(ids: string[]): Promise<unknown>;
     query(vector: number[], options: {
         topK: number;
         returnMetadata: "none";
     }): Promise<unknown>;
 }
+/**
+ * One vector's worth of a node (anchrd/intel#301).
+ *
+ * ⚠️ `key` is `""` for a node that carries exactly one vector — every kind but `board` — and the
+ * vector is then named by the bare node id it has always been named by. A board card carries its
+ * task id, and its vector is `<node id>#<task id>`.
+ *
+ * `text` is embedded verbatim. Composing it — the node's title in front of a document's body, the
+ * card's own title in front of a card — belongs to the indexing pass rather than here, because the
+ * same string has to be fingerprinted there to decide whether this vector needs making at all. A
+ * title prefixed on this side would sit outside that fingerprint and change nothing when it changed.
+ */
+export interface SemanticChunk {
+    key: string;
+    text: string;
+}
 export interface SemanticHit {
     nodeId: string;
+    chunkKey: string;
     score: number;
 }
 export interface SemanticIndex {
-    replace(target: NodeIndexTarget, content: string): Promise<void>;
+    upsert(target: NodeIndexTarget, chunks: SemanticChunk[]): Promise<void>;
+    remove(nodeId: string, keys: string[]): Promise<void>;
     search(query: string, limit: number): Promise<SemanticHit[]>;
 }
 export interface SemanticIndexDeps {