@anchrd/intel-api 0.3.2 → 0.3.3

package/migrations/0005_tables_in_the_knowledge_tree.sql

@@ -2,15 +2,39 @@
 -- `parent_id`, same folder grants, same immutable `knowledge_versions` rows, same R2 body
 -- (ADR-0004 §1). Nothing here creates a second content model; only the CHECK has to learn the word.
 --
--- SQLite cannot alter a CHECK constraint, so the table is rebuilt. Dropping the old table would
--- otherwise trip the foreign keys of `knowledge_versions`, `knowledge_links`, `tree_grants` and
--- `flows`; deferring them to the end of the migration lets the rename put the same IDs back under
--- the same name before anything is checked.
+-- SQLite cannot alter a CHECK constraint, so the table is rebuilt. The rebuild is written the long
+-- way round, and both detours are here because the short way was tried and D1 rolled it back. The
+-- table this migration leaves behind is the same one either way — same columns, same constraints,
+-- same indexes — so an installation that already applied this file keeps exactly what it has.
+--
+-- ⚠️ First detour: the new table is created under the final name rather than built beside the old
+-- one and renamed over it. `DROP TABLE` on a parent runs an implicit `DELETE FROM` first, so the
+-- moment the old `knowledge_nodes` goes, every row of `knowledge_versions`, `tree_grants` and
+-- `flows` pointing at a node is a foreign-key violation. `defer_foreign_keys` postpones the
+-- complaint to COMMIT but does not withdraw it, and `ALTER TABLE ... RENAME` does not settle it
+-- either: a rename puts the name back, not the rows. Only inserting the nodes again, under the name
+-- the children have referenced all along, does. On an empty database none of this is visible —
+-- nothing points at anything — which is precisely how the first version passed a green test suite
+-- and then failed against the first database that had content in it.
+--
+-- ⚠️ Second detour: `knowledge_links` is the only child of `knowledge_nodes` declared ON DELETE
+-- CASCADE, so that same implicit delete does not merely flag its rows, it removes them — the
+-- migration would have committed with every relationship between two documents quietly gone. The
+-- rows are carried out of the way first and put back afterwards. That is a rescue, not a decision
+-- about the data: nothing is dropped, rewritten or reinterpreted here.
 PRAGMA defer_foreign_keys = TRUE;
 
-CREATE TABLE knowledge_nodes_next (
+-- 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 knowledge_nodes_carry AS SELECT * FROM knowledge_nodes;
+CREATE TABLE knowledge_links_carry AS SELECT * FROM knowledge_links;
+
+DROP TABLE knowledge_nodes;
+
+CREATE TABLE knowledge_nodes (
   id TEXT PRIMARY KEY NOT NULL,
-  parent_id TEXT REFERENCES knowledge_nodes_next(id),
+  parent_id TEXT REFERENCES knowledge_nodes(id),
   kind TEXT NOT NULL CHECK (kind IN ('folder', 'document', 'attachment', 'table')),
   title TEXT NOT NULL CHECK (length(title) BETWEEN 1 AND 240),
   description TEXT CHECK (description IS NULL OR length(description) <= 2000),
@@ -22,18 +46,23 @@ CREATE TABLE knowledge_nodes_next (
   archived_at TEXT
 );
 
-INSERT INTO knowledge_nodes_next (
+INSERT INTO knowledge_nodes (
   id, parent_id, kind, title, description, context_policy, owner_id,
   current_version_id, created_at, updated_at, archived_at
 )
 SELECT
   id, parent_id, kind, title, description, context_policy, owner_id,
   current_version_id, created_at, updated_at, archived_at
-FROM knowledge_nodes;
+FROM knowledge_nodes_carry;
 
-DROP TABLE knowledge_nodes;
+-- `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 `knowledge_links` ends up holding exactly
+-- what it held before, which is the only outcome this statement is permitted to have.
+INSERT OR IGNORE INTO knowledge_links SELECT * FROM knowledge_links_carry;
 
-ALTER TABLE knowledge_nodes_next RENAME TO knowledge_nodes;
+DROP TABLE knowledge_nodes_carry;
+DROP TABLE knowledge_links_carry;
 
 CREATE INDEX knowledge_nodes_parent_idx ON knowledge_nodes(parent_id, archived_at, title);
 CREATE INDEX knowledge_nodes_owner_idx ON knowledge_nodes(owner_id, archived_at);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {