@anchrd/intel-api 0.13.0 → 0.14.0

package/dist/nodes/nodes.types.d.ts

@@ -1,4 +1,4 @@
-import type { AddBoardTaskInput, AgentKeyRotated, AgentList, AppendTableRowsInput, AppendTableRowsResult, ArchiveNodeInput, BoardTaskResult, ConfigureBoardInput, ConfigureBoardResult, CreateAgentInput, CreatedAgent, CreateNodeInput, DefineTableInput, DeleteBoardTaskInput, DeleteBoardTaskResult, DeleteTableRowsInput, DeleteTableRowsResult, Flow, FlowVersion, GetAgentInput, GetBoardInput, ListAgentsInput, ListNodesInput, MoveBoardTaskInput, Node, NodeAgent, NodeAttachment, NodeBoard, NodeCitation, NodeDocument, NodeGraph, NodeGraphInput, NodeLink, NodeTable, NodeVersion, RedefineTableInput, ResolveNodeLinksInput, ResolveNodeLinksResult, ResourceGrant, ResourceGrantList, ResourceVerb, RevokeGrantInput, RotateAgentKeyInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, ShareInput, ShareResult, UpdateBoardTaskInput, UpdateNodeInput, UpdateTableRowsInput, UpdateTableRowsResult } from "@anchrd/intel-contract";
+import type { AddBoardTaskInput, AgentKeyRotated, AgentList, AppendTableRowsInput, AppendTableRowsResult, ArchiveNodeInput, BoardTaskResult, ConfigureBoardInput, ConfigureBoardResult, CreateAgentInput, CreatedAgent, CreateNodeInput, DefineTableInput, DeleteBoardTaskInput, DeleteBoardTaskResult, DeleteTableRowsInput, DeleteTableRowsResult, Flow, FlowVersion, GetAgentInput, GetBoardInput, ListAgentsInput, ListNodesInput, MoveBoardTaskInput, Node, NodeAgent, NodeAttachment, NodeBoard, NodeCitation, NodeDocument, NodeGraph, NodeGraphInput, NodeLink, NodeTable, NodeVersion, RedefineTableInput, RepairBoardTaskIdsInput, RepairBoardTaskIdsResult, ResolveNodeLinksInput, ResolveNodeLinksResult, ResourceGrant, ResourceGrantList, ResourceVerb, RevokeGrantInput, RotateAgentKeyInput, SaveAgentDefinitionInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, ShareInput, ShareResult, UpdateBoardTaskInput, UpdateNodeInput, UpdateTableRowsInput, UpdateTableRowsResult } from "@anchrd/intel-contract";
 import type { SemanticIndex } from "../adapters/semantic-index/semantic-index.types.js";
 export interface Actor {
     id: string;
@@ -27,7 +27,7 @@ export interface NewTableVersion {
     idempotencyKey: string;
     auditId: string;
 }
-export type SnapshotOperation = "node.table_update" | "node.table_delete" | "node.table_redefine" | "node.board_configure" | "node.board_task_add" | "node.board_task_update" | "node.board_task_move" | "node.board_task_delete";
+export type SnapshotOperation = "node.table_update" | "node.table_delete" | "node.table_redefine" | "node.board_configure" | "node.board_task_add" | "node.board_task_update" | "node.board_task_move" | "node.board_task_delete" | "node.board_task_repair";
 /**
  * One version that replaces the readable state, written only against the state it replaces.
  *
@@ -145,7 +145,21 @@ export interface NodeRepository {
         occurredAt: string;
     }): Promise<boolean>;
     searchVisible(actor: Actor, input: SearchInput): Promise<NodeCitation[]>;
-    hydrateVisibleCitations(actor: Actor, nodeIds: string[], scopeId?: string): Promise<NodeCitation[]>;
+    /**
+     * `scopeId` cuts the candidates to one folder subtree, which is how the semantic half of a scoped
+     * search is narrowed (#126): the vector index answers over everything and this join is where the
+     * subtree — a relation in D1, not a value on a vector — is applied. The ACL still applies too.
+     *
+     * ⚠️ One entry per node, and it names WHICH chunk answered (anchrd/intel#301). The passage a
+     * searcher is shown is then that card rather than whichever one happens to be first in the board;
+     * a node whose winning chunk has no `node_vectors` row — every vector written before #301 — falls
+     * back on the first full-text passage, which is exactly what this returned before.
+     */
+    hydrateVisibleCitations(actor: Actor, hits: Array<{
+        nodeId: string;
+        chunkKey: string;
+    }>, scopeId?: string): Promise<NodeCitation[]>;
+    invalidateVectors(): Promise<void>;
     listCurrentVersionIds(input: {
         after: string | null;
         limit: number;
@@ -354,6 +368,15 @@ export interface NodeService {
     updateBoardTask(actor: Actor, input: UpdateBoardTaskInput): Promise<BoardTaskResult>;
     moveBoardTask(actor: Actor, input: MoveBoardTaskInput): Promise<BoardTaskResult>;
     deleteBoardTask(actor: Actor, input: DeleteBoardTaskInput): Promise<DeleteBoardTaskResult>;
+    /**
+     * The sixth, and the only one that is not about somebody's project (anchrd/intel#341).
+     *
+     * ⚠️ It names no task id, because a board that needs it holds two entries under one — the pair a
+     * bundle written before anchrd/intel#321 could carry in. Everything else here is unreachable for
+     * that second entry: the five operations above address a task by id and would take, write or
+     * remove both at once.
+     */
+    repairBoardTaskIds(actor: Actor, input: RepairBoardTaskIdsInput): Promise<RepairBoardTaskIdsResult>;
     getAgent(actor: Actor, input: GetAgentInput): Promise<NodeAgent>;
     /**
      * An agent node, its first definition, and the Gate Application it runs as (#182, D29).
@@ -435,12 +458,47 @@ export interface NodeIndexTarget {
  * task's own title, which is the text the FTS table weights highest.
  */
 export interface IndexChunk {
+    /**
+     * What this passage is called inside its node (anchrd/intel#301).
+     *
+     * `""` for a node that is one passage — every kind but `board` — and the task's own id for a card.
+     * The full-text index does not store it; the vector index is named by it, which is how a semantic
+     * hit can say WHICH card answered instead of only which board.
+     */
+    key: string;
     title: string;
     text: string;
 }
+/**
+ * What the vector index holds for one chunk of one node (anchrd/intel#301).
+ *
+ * `fingerprint` is over the exact text that was embedded, so the next pass can tell an untouched
+ * card from a changed one without asking Vectorize — whose writes are asynchronous and would answer
+ * about the save before last. `passage` is what a searcher is shown when this vector is the hit.
+ */
+export interface NodeVectorRecord {
+    chunkKey: string;
+    fingerprint: string;
+    passage: string;
+}
 export interface NodeIndexRepository {
     getTarget(versionId: string): Promise<NodeIndexTarget | null>;
+    /**
+     * The node behind this version when the reason `getTarget` refused it is that the node has been
+     * ARCHIVED — and null for every other reason (anchrd/intel#348).
+     *
+     * ⚠️ The distinction is the whole method. `getTarget` answers null for two very different
+     * situations: the node is archived, or this version has been superseded by a later save. The
+     * first one means "take this node out of the vector index"; the second is a queue message that
+     * arrived late — the ordinary case, because Cloudflare Queues deliver at least once — and acting
+     * on it would delete the vectors of a node that is perfectly alive. So this asks for the archived
+     * case by name and never infers it from an absence.
+     */
+    archivedNodeId(versionId: string): Promise<string | null>;
     replace(target: NodeIndexTarget, chunks: IndexChunk[]): Promise<void>;
+    listVectors(nodeId: string): Promise<NodeVectorRecord[]>;
+    replaceVectors(target: NodeIndexTarget, records: NodeVectorRecord[]): Promise<void>;
+    deleteVectors(nodeId: string): Promise<void>;
     markIndexed(versionId: string, occurredAt: string): Promise<void>;
     markError(versionId: string, message: string, occurredAt: string): Promise<void>;
 }

package/migrations/0009_no_context_policy.sql

@@ -1,5 +1,13 @@
 -- #76. `context_policy` leaves the contract, the UI and every MCP answer. The COLUMN stays.
 --
+-- ⚠️ HISTORY, and no longer an explanation of what is possible. The column was finally dropped by
+-- `0018_no_context_policy_at_last.sql` (#86), through an ordinary migration file — the very thing
+-- the conclusion at the bottom of this file says cannot be done. What changed is not D1 but the
+-- recipe: `0005`, `0013` and `0016` worked out that the new table has to be created under the FINAL
+-- name instead of renamed into place, and that `node_links` has to be carried out of the way
+-- because it is the one child declared ON DELETE CASCADE. Read on for the three failures that
+-- produced the lessons; read `0018` for the shape that works.
+--
 -- ⚠️ That is not the intent, it is what D1 permits. SQLite cannot drop a column a CHECK names, and
 -- this one names itself. The way around it is a table rebuild, and `knowledge_nodes` carries six
 -- foreign keys, one of them from itself.
@@ -22,6 +30,13 @@
 -- A table rebuild with foreign keys is therefore not possible inside a migration file. It needs a
 -- session that drives the transaction itself.
 --
+-- ⚠️ THAT CONCLUSION WAS WRONG, and the way it was wrong is worth more than the conclusion. The
+-- three lessons above are all correct; what they did not contain was the fourth — do not RENAME at
+-- all. Create the new table under the final name and insert the rows back under the name the
+-- children have referenced the whole time, and there is nothing left for a deferred check to
+-- complain about at COMMIT. `0005` found it, `0013` and `0016` repeated it, and `0018` used it to
+-- drop this column at last (#86).
+--
 -- What holds instead: the column sits in D1, nothing reads it, and `db.ts` writes a fixed value on
 -- insert because it is NOT NULL without a DEFAULT. The contract does not know it — for every
 -- consumer it is gone. What remains is one dead column, and that is the price of Intel running.

package/migrations/0017_a_vector_per_card.sql

@@ -0,0 +1,38 @@
+-- anchrd/intel#301: one vector per board card, and the record of which vectors a node has.
+--
+-- Vectorize is keyed by node id (`adapters/semantic-index`), so a board was ONE vector holding the
+-- whole document while the full-text half had held one row per card since #285. "Where do I stand
+-- with X" is the question a board exists to answer and it is an imprecise one: lexically it reaches
+-- a card only where the searched word is written on it verbatim. A vector id therefore becomes
+-- `<node id>#<task id>` for a board card and stays the bare node id for every other kind — no
+-- existing vector changes its name, so no installation re-embeds its whole tree to get this.
+--
+-- This table is the D1 side of that index and nothing more: which vectors a node has, what text
+-- each one was made from, and the passage a searcher is shown when that vector is the hit. It is
+-- DERIVED like `node_fts` beside it, and `reindex` empties it so that a rebuild really rebuilds.
+--
+-- ⚠️ `fingerprint` is what keeps a board of three hundred cards from costing three hundred
+-- embeddings per save. The indexing pass compares it against the text it is about to embed and
+-- upserts only what changed; a row is written ONLY AFTER the upsert it describes succeeded. That is
+-- why a fingerprint is stored rather than a timestamp: a pass that dies between the two leaves a
+-- row missing, never a row claiming a vector that was never written, so the next pass repairs
+-- itself instead of trusting a lie.
+--
+-- ⚠️ `chunk_key` is `''` for a node that has exactly one vector — every kind but `board`. NULL
+-- would be the honest spelling and is the wrong one: NULLs are distinct from one another inside a
+-- SQLite primary key, so two rows for the same node could both exist and neither would be found by
+-- the other's write.
+--
+-- ⚠️ No foreign key on `node_id`, deliberately, and for the same reason `node_fts` has none: a
+-- derived index must not be able to make a write to `nodes` fail, and every rebuild of `nodes`
+-- (0005, 0013, 0016, 0018) has to carry each declared child through the detour those files describe.
+-- A row that outlives its node is invisible anyway — hydration joins `nodes` and drops what is
+-- archived or gone, exactly as it does for `node_fts`.
+CREATE TABLE node_vectors (
+  node_id TEXT NOT NULL,
+  chunk_key TEXT NOT NULL,
+  version_id TEXT NOT NULL,
+  fingerprint TEXT NOT NULL,
+  passage TEXT NOT NULL,
+  PRIMARY KEY (node_id, chunk_key)
+);

package/migrations/0018_no_context_policy_at_last.sql

@@ -0,0 +1,90 @@
+-- #86: `context_policy` leaves `nodes` for good.
+--
+-- #76 removed it from the contract, the UI and every MCP answer — for every consumer it has been
+-- gone since. The COLUMN stayed because SQLite cannot drop one a CHECK names, and `db.ts` has been
+-- writing the fixed value `'relevant'` into it ever since so that inserting a node works at all.
+-- A dead column plus a line of code serving it: harmless, and ballast the next reader has to be
+-- told about.
+--
+-- ⚠️ THE reason this ticket sat open for weeks is that three earlier attempts failed against
+-- `--remote` while passing locally, and the file that recorded them (`0009_no_context_policy.sql`)
+-- concluded that a table rebuild with foreign keys needs "a session that runs the transaction
+-- itself, not a migration file". That conclusion is out of date, and the proof is in this
+-- directory: `0005`, `0013` and `0016` each rebuilt this very table through an ordinary migration
+-- file. `0016` did it against the live database on 2026-08-08 with 120 nodes, and every referencing
+-- table came out with the same count it went in with.
+--
+-- ⚠️ One thing about that run is worth knowing before it is quoted as a precedent: the installation
+-- held ZERO `node_links` rows, so the rescue below would have had nothing to rescue and the run
+-- would have passed without exercising it at all. The one row it did carry was created for the
+-- purpose, minutes before, by linking two throwaway documents. The proof was arranged, not found —
+-- and the next person rebuilding this table has to arrange it again, because the installation still
+-- has almost no links.
+--
+-- What the three of them worked out, and what this file copies rather than rediscovers:
+--
+--   1. `PRAGMA foreign_keys = OFF` is IGNORED by D1 over the HTTP API. Locally miniflare obeys it,
+--      so the integration test was green while the real database answered `FOREIGN KEY constraint
+--      failed`. That is why the proof of a migration here is a run against `--remote`.
+--   2. The new table is created under the FINAL name rather than built beside the old one and
+--      renamed over it. `ALTER TABLE ... RENAME` makes references FOLLOW the rename, so renaming
+--      the old table out of the way quietly re-points every other table at a table about to be
+--      dropped. Inserting the rows again under the name the children have referenced all along is
+--      what settles them.
+--   3. `DROP TABLE` on a parent runs an implicit `DELETE FROM` first, and `node_links` is the one
+--      child declared ON DELETE CASCADE — so that delete does not merely flag its rows, it REMOVES
+--      them. They are carried out of the way and put back. That is a rescue, not a decision about
+--      the data.
+--
+-- ⚠️ On an empty database neither detour is visible, because nothing points at anything. That is
+-- how `0005`'s first version passed a green suite and then failed against the first database with
+-- content in it, and why the proof for this file is a row count of every referencing table before
+-- and after rather than a migration that merely ran.
+PRAGMA defer_foreign_keys = TRUE;
+
+-- Plain holding tables on purpose: no keys, no CHECKs, no foreign keys, and the column set taken
+-- from whatever the live table has. Anything enforced here would only be enforced a second time on
+-- the way back in, and a holding table that can reject a row is a holding table that can lose one.
+CREATE TABLE nodes_carry AS SELECT * FROM nodes;
+CREATE TABLE node_links_carry AS SELECT * FROM node_links;
+
+DROP TABLE nodes;
+
+-- The same table as `0016` left it, minus one column. Nothing else about it changes: same keys,
+-- same CHECKs, same six kinds — a rebuild is the only way to drop the column, not an invitation to
+-- change anything else while the table is open.
+CREATE TABLE nodes (
+  id TEXT PRIMARY KEY NOT NULL,
+  parent_id TEXT REFERENCES nodes(id),
+  kind TEXT NOT NULL CHECK (kind IN ('folder', 'document', 'attachment', 'table', 'agent', 'board')),
+  title TEXT NOT NULL CHECK (length(title) BETWEEN 1 AND 240),
+  description TEXT CHECK (description IS NULL OR length(description) <= 2000),
+  owner_id TEXT NOT NULL,
+  current_version_id TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  archived_at TEXT
+);
+
+-- Columns named on both sides rather than `SELECT *`: the holding table still HAS `context_policy`,
+-- and a positional insert would either fail or, worse, shift every value one place to the left.
+INSERT INTO nodes (
+  id, parent_id, kind, title, description, owner_id,
+  current_version_id, created_at, updated_at, archived_at
+)
+SELECT
+  id, parent_id, kind, title, description, owner_id,
+  current_version_id, created_at, updated_at, archived_at
+FROM nodes_carry;
+
+-- `OR IGNORE` because whether the cascade above actually fired is SQLite's business, not this
+-- migration's: if it did, this puts the rows back; if it did not, each one is already present under
+-- the same primary key and this is a no-op. Either way `node_links` ends up holding exactly what it
+-- held before, which is the only outcome this statement is permitted to have.
+INSERT OR IGNORE INTO node_links SELECT * FROM node_links_carry;
+
+DROP TABLE nodes_carry;
+DROP TABLE node_links_carry;
+
+CREATE INDEX nodes_parent_idx ON nodes(parent_id, archived_at, title);
+CREATE INDEX nodes_owner_idx ON nodes(owner_id, archived_at);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@anchrd/gate-sdk": "^0.7.0",
-    "@anchrd/intel-contract": "^0.11.0",
+    "@anchrd/intel-contract": "^0.12.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "fflate": "^0.8.3",