@anchrd/intel 0.59.0

package/migrations/0000_intel_foundation.sql

@@ -0,0 +1,203 @@
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE knowledge_nodes (
+  id TEXT PRIMARY KEY NOT NULL,
+  parent_id TEXT REFERENCES knowledge_nodes(id),
+  kind TEXT NOT NULL CHECK (kind IN ('folder', 'document', 'attachment')),
+  title TEXT NOT NULL CHECK (length(title) BETWEEN 1 AND 240),
+  description TEXT CHECK (description IS NULL OR length(description) <= 2000),
+  context_policy TEXT NOT NULL CHECK (context_policy IN ('pinned', 'relevant', 'explicit')),
+  owner_id TEXT NOT NULL,
+  current_version_id TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  archived_at TEXT
+);
+
+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);
+
+CREATE TABLE knowledge_versions (
+  id TEXT PRIMARY KEY NOT NULL,
+  node_id TEXT NOT NULL REFERENCES knowledge_nodes(id),
+  sequence INTEGER NOT NULL CHECK (sequence > 0),
+  content_key TEXT NOT NULL UNIQUE,
+  media_type TEXT NOT NULL,
+  content_hash TEXT NOT NULL CHECK (length(content_hash) = 64),
+  size INTEGER NOT NULL CHECK (size >= 0),
+  created_by TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  UNIQUE (node_id, sequence)
+);
+
+CREATE INDEX knowledge_versions_node_idx ON knowledge_versions(node_id, sequence DESC);
+
+CREATE TABLE knowledge_links (
+  id TEXT PRIMARY KEY NOT NULL,
+  source_node_id TEXT NOT NULL REFERENCES knowledge_nodes(id) ON DELETE CASCADE,
+  target_node_id TEXT NOT NULL REFERENCES knowledge_nodes(id) ON DELETE CASCADE,
+  relation TEXT NOT NULL CHECK (relation IN ('references', 'related', 'depends_on', 'implements')),
+  label TEXT CHECK (label IS NULL OR length(label) BETWEEN 1 AND 120),
+  created_by TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  CHECK (source_node_id <> target_node_id),
+  UNIQUE (source_node_id, target_node_id, relation)
+);
+
+CREATE INDEX knowledge_links_source_idx ON knowledge_links(source_node_id, created_at);
+CREATE INDEX knowledge_links_target_idx ON knowledge_links(target_node_id, created_at);
+
+CREATE TABLE knowledge_index_state (
+  version_id TEXT PRIMARY KEY NOT NULL REFERENCES knowledge_versions(id),
+  status TEXT NOT NULL CHECK (status IN ('pending', 'indexed', 'error')),
+  attempt_count INTEGER NOT NULL DEFAULT 0,
+  last_error TEXT,
+  updated_at TEXT NOT NULL
+);
+
+CREATE INDEX knowledge_index_state_status_idx ON knowledge_index_state(status, updated_at);
+
+CREATE TABLE resource_grants (
+  id TEXT PRIMARY KEY NOT NULL,
+  resource_type TEXT NOT NULL CHECK (resource_type IN ('knowledge', 'flow', 'tool-source')),
+  resource_id TEXT NOT NULL,
+  principal_type TEXT NOT NULL CHECK (principal_type IN ('user', 'email', 'organization')),
+  principal_id TEXT NOT NULL,
+  role TEXT NOT NULL CHECK (role IN ('viewer', 'commenter', 'editor', 'manager')),
+  expires_at TEXT,
+  created_by TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  UNIQUE (resource_type, resource_id, principal_type, principal_id)
+);
+
+CREATE INDEX resource_grants_principal_idx ON resource_grants(
+  principal_type,
+  principal_id,
+  resource_type,
+  expires_at
+);
+
+CREATE TABLE idempotency_keys (
+  actor_id TEXT NOT NULL,
+  operation TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL,
+  resource_id TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (actor_id, operation, idempotency_key)
+);
+
+CREATE INDEX idempotency_keys_created_idx ON idempotency_keys(created_at);
+
+CREATE TABLE audit_events (
+  id TEXT PRIMARY KEY NOT NULL,
+  actor_id TEXT NOT NULL,
+  action TEXT NOT NULL,
+  resource_type TEXT NOT NULL,
+  resource_id TEXT NOT NULL,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  occurred_at TEXT NOT NULL
+);
+
+CREATE INDEX audit_events_resource_idx ON audit_events(resource_type, resource_id, occurred_at DESC);
+CREATE INDEX audit_events_actor_idx ON audit_events(actor_id, occurred_at DESC);
+
+CREATE TABLE oauth_clients (
+  issuer TEXT NOT NULL,
+  redirect_uri TEXT NOT NULL,
+  client_id TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (issuer, redirect_uri)
+);
+
+CREATE TABLE tool_sources (
+  id TEXT PRIMARY KEY NOT NULL,
+  name TEXT NOT NULL,
+  url TEXT NOT NULL UNIQUE,
+  connection_handle TEXT NOT NULL,
+  enabled INTEGER NOT NULL DEFAULT 1 CHECK (enabled IN (0, 1)),
+  created_by TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  last_discovered_at TEXT
+);
+
+CREATE TABLE tool_catalog (
+  source_id TEXT NOT NULL REFERENCES tool_sources(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  title TEXT,
+  description TEXT,
+  input_schema_json TEXT NOT NULL,
+  output_schema_json TEXT,
+  annotations_json TEXT NOT NULL,
+  fingerprint TEXT NOT NULL,
+  discovered_at TEXT NOT NULL,
+  PRIMARY KEY (source_id, name)
+);
+
+CREATE INDEX tool_catalog_title_idx ON tool_catalog(source_id, title, name);
+
+CREATE TABLE flows (
+  id TEXT PRIMARY KEY NOT NULL,
+  title TEXT NOT NULL,
+  description TEXT,
+  owner_id TEXT NOT NULL,
+  current_version_id TEXT,
+  published_version_id TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  archived_at TEXT
+);
+
+CREATE INDEX flows_owner_idx ON flows(owner_id, archived_at, updated_at DESC);
+
+CREATE TABLE flow_versions (
+  id TEXT PRIMARY KEY NOT NULL,
+  flow_id TEXT NOT NULL REFERENCES flows(id),
+  sequence INTEGER NOT NULL CHECK (sequence > 0),
+  graph_json TEXT NOT NULL,
+  created_by TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  UNIQUE (flow_id, sequence)
+);
+
+CREATE INDEX flow_versions_flow_idx ON flow_versions(flow_id, sequence DESC);
+
+CREATE TABLE flow_runs (
+  id TEXT PRIMARY KEY NOT NULL,
+  flow_id TEXT NOT NULL REFERENCES flows(id),
+  version_id TEXT NOT NULL REFERENCES flow_versions(id),
+  status TEXT NOT NULL CHECK (status IN ('queued', 'running', 'waiting', 'completed', 'failed', 'cancelled')),
+  current_node_id TEXT,
+  input_json TEXT NOT NULL,
+  output_json TEXT,
+  error TEXT,
+  initiated_by TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  completed_at TEXT,
+  transition_id TEXT
+);
+
+CREATE INDEX flow_runs_flow_idx ON flow_runs(flow_id, created_at DESC);
+CREATE INDEX flow_runs_status_idx ON flow_runs(status, updated_at);
+
+CREATE TABLE flow_run_steps (
+  id TEXT PRIMARY KEY NOT NULL,
+  run_id TEXT NOT NULL REFERENCES flow_runs(id),
+  node_id TEXT NOT NULL,
+  outcome TEXT NOT NULL CHECK (outcome IN ('completed', 'failed')),
+  branch TEXT,
+  output_json TEXT,
+  error TEXT,
+  completed_by TEXT NOT NULL,
+  completed_at TEXT NOT NULL,
+  UNIQUE (run_id, node_id)
+);
+
+CREATE VIRTUAL TABLE knowledge_fts USING fts5(
+  version_id UNINDEXED,
+  node_id UNINDEXED,
+  title,
+  content,
+  tokenize = 'unicode61 remove_diacritics 2'
+);

package/migrations/0001_portal_native_tools.sql

@@ -0,0 +1,21 @@
+-- ADR-0003: the Cloudflare MCP portal owns tool discovery, tool permissions and provider
+-- credentials. Intel no longer registers sources, mirrors a catalog or grants access to tools.
+-- 0.1.x shipped these tables, so they are dropped explicitly rather than removed from 0000.
+
+DROP INDEX IF EXISTS tool_catalog_title_idx;
+DROP TABLE IF EXISTS tool_catalog;
+DROP TABLE IF EXISTS tool_sources;
+
+-- Grants for a resource type that no longer exists would otherwise linger and keep matching the
+-- ACL predicate shape used by knowledge and flows. The CHECK constraint still lists 'tool-source';
+-- rebuilding the table to drop one unused enum value is not worth the migration risk.
+DELETE FROM resource_grants WHERE resource_type = 'tool-source';
+
+-- The only tool-related secret Intel stores: the per-user access token for its own portal
+-- endpoint, sealed with the INTEL_SESSION_SECRET-derived key. No provider credential reaches D1.
+CREATE TABLE portal_tokens (
+  user_id TEXT PRIMARY KEY NOT NULL,
+  sealed TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);

package/migrations/0002_flows_in_the_knowledge_tree.sql

@@ -0,0 +1,34 @@
+-- ADR-0004: Knowledge and Flows share one folder tree. A flow gains `parent_id` into the existing
+-- `knowledge_nodes` tree; the contents stay two tables, because versions, the R2 body and the
+-- Vectorize entry belong to the document while the graph, runs and approvals belong to the flow.
+
+-- SQLite only accepts an added REFERENCES column when its default is NULL, which is exactly what an
+-- unfiled flow needs: `NULL` is the root of the same tree Knowledge uses.
+ALTER TABLE flows ADD COLUMN parent_id TEXT REFERENCES knowledge_nodes(id);
+
+CREATE INDEX flows_parent_idx ON flows(parent_id, archived_at, title);
+
+-- Existing flows land in a defined folder rather than scattered across the root. One folder per
+-- owner, with a derived ID so a re-run finds the same row: the narrow reading of an ambiguous case,
+-- as the ADR requires. A single shared folder would have to belong to someone, and its owner would
+-- gain sight of everyone else's flows — a migration must never widen access.
+INSERT INTO knowledge_nodes (
+  id, parent_id, kind, title, description, context_policy, owner_id,
+  current_version_id, created_at, updated_at, archived_at
+)
+SELECT
+  'folder-flows-' || flow.owner_id,
+  NULL,
+  'folder',
+  'Flows',
+  'Flows that existed before Knowledge and Flows shared one tree.',
+  'explicit',
+  flow.owner_id,
+  NULL,
+  '2026-08-01T00:00:00.000Z',
+  '2026-08-01T00:00:00.000Z',
+  NULL
+FROM flows flow
+GROUP BY flow.owner_id;
+
+UPDATE flows SET parent_id = 'folder-flows-' || owner_id WHERE parent_id IS NULL;

package/migrations/0003_folder_permissions.sql

@@ -0,0 +1,211 @@
+-- ADR-0004 §2: a grant sits on a node of the shared tree and applies to everything beneath it, and
+-- the verbs `read` / `write` / `execute` / `share` are granted independently. `role` could not carry
+-- that: it is a ladder (viewer < editor < manager), and the case the ADR is built around — /crm is
+-- readable for sales and executable only for billing — is not a rung on it.
+--
+-- `resource_grants` is deliberately left in place and untouched. The previous version of the Worker
+-- reads it and keeps answering correctly until it is replaced; nothing in this version reads it any
+-- more. Once no old Worker is left, the table holds only history and can be dropped.
+
+CREATE TABLE tree_grants (
+  id TEXT PRIMARY KEY NOT NULL,
+  -- Any node of the shared tree, not only a folder: a grant that was migrated from a document has
+  -- to stay exactly where it was. Moving it up to the parent folder would hand its principal the
+  -- folder's other contents as well, and a migration must never widen access. A grant on a leaf is
+  -- simply a subtree of one.
+  node_id TEXT NOT NULL REFERENCES knowledge_nodes(id),
+  principal_type TEXT NOT NULL CHECK (principal_type IN ('user', 'email', 'organization')),
+  principal_id TEXT NOT NULL,
+  verb TEXT NOT NULL CHECK (verb IN ('read', 'write', 'execute', 'share')),
+  expires_at TEXT,
+  created_by TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  -- The verb belongs in the key. Without it one principal could hold only one verb per node, which
+  -- is the ladder again under a new name.
+  UNIQUE (node_id, principal_type, principal_id, verb)
+);
+
+CREATE INDEX tree_grants_principal_idx ON tree_grants(
+  principal_type,
+  principal_id,
+  verb,
+  expires_at
+);
+
+CREATE INDEX tree_grants_node_idx ON tree_grants(node_id, verb);
+
+-- `principal_type` and `principal_id` are carried over verbatim, and that is a decision rather than
+-- laziness. Both resolvers read a principal the same way: a user by ID, an email folded to lower
+-- case on both sides, and the whole organization as the literal `*` that `setGrant` has always
+-- written. Rewriting any of them here would be a migration changing who a grant means.
+--
+-- The one case worth naming is an `organization` row whose `principal_id` is not `*`. Nothing in
+-- Intel writes such a row, but a repair or an import could have. It is copied as it stands, so it
+-- matches nobody and the access is gone; normalizing it to `*` would turn a row of unknown scope
+-- into a grant for everyone. Narrow is a lost grant somebody notices, wide is access nobody sees.
+
+-- A flow grant has no folder to move to that would be honest. Its own parent folder holds other
+-- things, so putting the grant there would show the principal everything else in that folder. The
+-- narrow reading is a folder that contains exactly this one flow: the flow moves into it, the grant
+-- lands on it, and nothing else is inside. The ID is derived from the flow so a re-run finds the
+-- same row, the same way 0002 derived one folder per owner.
+INSERT OR IGNORE INTO knowledge_nodes (
+  id, parent_id, kind, title, description, context_policy, owner_id,
+  current_version_id, created_at, updated_at, archived_at
+)
+SELECT
+  'folder-flow-' || flow.id,
+  flow.parent_id,
+  'folder',
+  flow.title,
+  'Holds one flow that was shared on its own before shares moved to the folder.',
+  'explicit',
+  flow.owner_id,
+  NULL,
+  '2026-08-01T00:00:00.000Z',
+  '2026-08-01T00:00:00.000Z',
+  NULL
+FROM flows flow
+WHERE EXISTS (
+  SELECT 1 FROM resource_grants grant_row
+  WHERE grant_row.resource_type = 'flow' AND grant_row.resource_id = flow.id
+)
+  AND flow.parent_id IS NOT 'folder-flow-' || flow.id;
+
+UPDATE flows SET parent_id = 'folder-flow-' || id
+WHERE EXISTS (
+  SELECT 1 FROM resource_grants grant_row
+  WHERE grant_row.resource_type = 'flow' AND grant_row.resource_id = flows.id
+)
+  AND EXISTS (SELECT 1 FROM knowledge_nodes node WHERE node.id = 'folder-flow-' || flows.id);
+
+-- Seeing a flow and starting it were the same permission until now: any flow grant plus the Gate
+-- `flows/run` capability could start a run. Splitting the two without carrying `execute` over would
+-- quietly take away something people have today, so every migrated flow grant keeps it.
+INSERT OR IGNORE INTO tree_grants (
+  id, node_id, principal_type, principal_id, verb, expires_at, created_by, created_at
+)
+SELECT
+  grant_row.id || ':read',
+  'folder-flow-' || grant_row.resource_id,
+  grant_row.principal_type,
+  grant_row.principal_id,
+  'read',
+  grant_row.expires_at,
+  grant_row.created_by,
+  grant_row.created_at
+FROM resource_grants grant_row
+WHERE grant_row.resource_type = 'flow'
+  AND EXISTS (
+    SELECT 1 FROM knowledge_nodes node WHERE node.id = 'folder-flow-' || grant_row.resource_id
+  );
+
+INSERT OR IGNORE INTO tree_grants (
+  id, node_id, principal_type, principal_id, verb, expires_at, created_by, created_at
+)
+SELECT
+  grant_row.id || ':execute',
+  'folder-flow-' || grant_row.resource_id,
+  grant_row.principal_type,
+  grant_row.principal_id,
+  'execute',
+  grant_row.expires_at,
+  grant_row.created_by,
+  grant_row.created_at
+FROM resource_grants grant_row
+WHERE grant_row.resource_type = 'flow'
+  AND EXISTS (
+    SELECT 1 FROM knowledge_nodes node WHERE node.id = 'folder-flow-' || grant_row.resource_id
+  );
+
+INSERT OR IGNORE INTO tree_grants (
+  id, node_id, principal_type, principal_id, verb, expires_at, created_by, created_at
+)
+SELECT
+  grant_row.id || ':write',
+  'folder-flow-' || grant_row.resource_id,
+  grant_row.principal_type,
+  grant_row.principal_id,
+  'write',
+  grant_row.expires_at,
+  grant_row.created_by,
+  grant_row.created_at
+FROM resource_grants grant_row
+WHERE grant_row.resource_type = 'flow'
+  AND grant_row.role IN ('editor', 'manager')
+  AND EXISTS (
+    SELECT 1 FROM knowledge_nodes node WHERE node.id = 'folder-flow-' || grant_row.resource_id
+  );
+
+INSERT OR IGNORE INTO tree_grants (
+  id, node_id, principal_type, principal_id, verb, expires_at, created_by, created_at
+)
+SELECT
+  grant_row.id || ':share',
+  'folder-flow-' || grant_row.resource_id,
+  grant_row.principal_type,
+  grant_row.principal_id,
+  'share',
+  grant_row.expires_at,
+  grant_row.created_by,
+  grant_row.created_at
+FROM resource_grants grant_row
+WHERE grant_row.resource_type = 'flow'
+  AND grant_row.role = 'manager'
+  AND EXISTS (
+    SELECT 1 FROM knowledge_nodes node WHERE node.id = 'folder-flow-' || grant_row.resource_id
+  );
+
+-- Knowledge grants stay on the node they were set on and keep exactly the verbs their role implied.
+-- `execute` is not among them for any role: a Knowledge grant never allowed anyone to start a run,
+-- and handing it out here would be the wide reading of an unambiguous case. `commenter` has no verb
+-- of its own yet, so it maps to `read` — the least it could have meant.
+INSERT OR IGNORE INTO tree_grants (
+  id, node_id, principal_type, principal_id, verb, expires_at, created_by, created_at
+)
+SELECT
+  grant_row.id || ':read',
+  grant_row.resource_id,
+  grant_row.principal_type,
+  grant_row.principal_id,
+  'read',
+  grant_row.expires_at,
+  grant_row.created_by,
+  grant_row.created_at
+FROM resource_grants grant_row
+WHERE grant_row.resource_type = 'knowledge'
+  AND EXISTS (SELECT 1 FROM knowledge_nodes node WHERE node.id = grant_row.resource_id);
+
+INSERT OR IGNORE INTO tree_grants (
+  id, node_id, principal_type, principal_id, verb, expires_at, created_by, created_at
+)
+SELECT
+  grant_row.id || ':write',
+  grant_row.resource_id,
+  grant_row.principal_type,
+  grant_row.principal_id,
+  'write',
+  grant_row.expires_at,
+  grant_row.created_by,
+  grant_row.created_at
+FROM resource_grants grant_row
+WHERE grant_row.resource_type = 'knowledge'
+  AND grant_row.role IN ('editor', 'manager')
+  AND EXISTS (SELECT 1 FROM knowledge_nodes node WHERE node.id = grant_row.resource_id);
+
+INSERT OR IGNORE INTO tree_grants (
+  id, node_id, principal_type, principal_id, verb, expires_at, created_by, created_at
+)
+SELECT
+  grant_row.id || ':share',
+  grant_row.resource_id,
+  grant_row.principal_type,
+  grant_row.principal_id,
+  'share',
+  grant_row.expires_at,
+  grant_row.created_by,
+  grant_row.created_at
+FROM resource_grants grant_row
+WHERE grant_row.resource_type = 'knowledge'
+  AND grant_row.role = 'manager'
+  AND EXISTS (SELECT 1 FROM knowledge_nodes node WHERE node.id = grant_row.resource_id);

package/migrations/0004_subflow_runs.sql

@@ -0,0 +1,14 @@
+-- ADR-0004 §3/§4: a flow may call another flow. The called flow gets a run of its own — its own
+-- immutable version, its own steps, its own authorization against the user — and these two columns
+-- are the only thing that ties it back to the step that called it.
+--
+-- A single run row that "descends into" the callee was the alternative. It would have had to carry
+-- two versions at once, and the step history would no longer say which graph a node belonged to.
+
+ALTER TABLE flow_runs ADD COLUMN parent_run_id TEXT REFERENCES flow_runs(id);
+ALTER TABLE flow_runs ADD COLUMN parent_node_id TEXT;
+
+-- One call site starts at most one run: the index is unique so a retried start cannot leave two
+-- results behind for the same step, with nothing to say which one flows back.
+CREATE UNIQUE INDEX flow_runs_call_site_idx ON flow_runs(parent_run_id, parent_node_id)
+  WHERE parent_run_id IS NOT NULL;

package/migrations/0005_flow_node_cleanup.sql

@@ -0,0 +1,28 @@
+-- #39. Two fields leave the flow graph, so the graphs already in the table are rewritten to match
+-- the contract that will read them. Both are removals of things that never did anything, which is
+-- why the rewrite can be unconditional rather than a decision per flow.
+--
+-- `description` on a node: a node has a title, and what it should do stands in the instruction. Two
+-- free texts beside each other were both kept half up to date.
+--
+-- A trigger's mode: `webhook` and `schedule` triggered nothing and, after the decision in #32, never
+-- will — a flow is carried out by an external agent that brings its own schedule. `manual` is the
+-- honest reading of every trigger that is stored today, because manual is what all of them did.
+--
+-- ⚠️ Written as one pass over the node array rather than a targeted UPDATE: `json_remove` is a no-op
+-- where the key is absent, so re-running this changes nothing. Only `flow_versions` holds a graph.
+UPDATE flow_versions
+SET graph_json = json_set(
+  graph_json,
+  '$.nodes',
+  (
+    SELECT json_group_array(
+      CASE
+        WHEN json_extract(node.value, '$.kind') = 'trigger'
+        THEN json_set(json_remove(node.value, '$.description'), '$.configuration', json_object('mode', 'manual'))
+        ELSE json_remove(node.value, '$.description')
+      END
+    )
+    FROM json_each(flow_versions.graph_json, '$.nodes') AS node
+  )
+);

package/migrations/0005_tables_in_the_knowledge_tree.sql

@@ -0,0 +1,68 @@
+-- #40: a fourth kind in the shared tree — `table`. It is a node like the other three: same
+-- `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. 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;
+
+-- 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(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),
+  context_policy TEXT NOT NULL CHECK (context_policy IN ('pinned', 'relevant', 'explicit')),
+  owner_id TEXT NOT NULL,
+  current_version_id TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  archived_at TEXT
+);
+
+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_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 `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;
+
+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/migrations/0006_links_are_written_in_the_text.sql

@@ -0,0 +1,20 @@
+-- #41: a relationship between two documents is written where it is meant — in the text — and the
+-- dialog that used to create one is gone. Saving a document now rewrites the links it contains.
+--
+-- That rewrite must not touch the links people made in the dialog before there was another way, so
+-- every link learns where it came from. Existing rows are `manual`: they are history, they stay
+-- readable as outgoing links and as backlinks, and nothing writes another one.
+--
+-- Deliberately not a migration of the data. Rewriting the old `relation` values into one kind, or
+-- deleting the rows outright, would throw away a distinction somebody chose on purpose; keeping the
+-- column costs nothing and keeps every existing relationship exactly as it was.
+--
+-- SQLite cannot add a CHECK with ALTER TABLE, so the constraint on this column lives in the
+-- contract (`KnowledgeLinkOrigin`) and in the one repository method that writes it. There is no
+-- table rebuild for it: `knowledge_links` is the target of no foreign key, but it is the source of
+-- two, and a rebuild would be a lot of risk for a constraint the only writer already enforces.
+ALTER TABLE knowledge_links ADD COLUMN origin TEXT NOT NULL DEFAULT 'manual';
+
+-- The reconciliation on save reads and deletes by source and origin, and the backlink list reads by
+-- target; both existing indexes stay useful, and this one keeps the delete off a table scan.
+CREATE INDEX knowledge_links_origin_idx ON knowledge_links(source_node_id, origin);

package/migrations/0007_no_node_waits.sql

@@ -0,0 +1,69 @@
+-- #73. The approval node leaves the contract, so the graphs already stored are rewritten to match
+-- the schema that will read them. Without this an `approval` node makes `FlowGraph.parse` throw in
+-- `db-flows.ts`, and the flow cannot be opened at all — not even to repair it. A removal that locks
+-- people out of their own flows is worse than the node it removes.
+--
+-- ⚠️ Rewritten to a `condition`, not deleted. The node has two outgoing branches, and deleting it
+-- would leave two edges pointing nowhere and a graph that fails `compileFlow` for a second reason.
+-- A condition is the honest replacement: it branches the same way, and the question the approval
+-- asked — "may this go ahead?" — is one the agent carrying out the run can answer. The prompt is
+-- carried over into the instruction rather than dropped, so the author still reads what was meant.
+-- `timeout` disappears with the waiting it configured (D24).
+--
+-- ⚠️ The branch handles are rewritten with it: an approval branched on `approved`/`rejected`, a
+-- condition on `yes`/`no`. Left alone, `completeStep` would look for a handle that no edge carries
+-- and every run through that node would answer 400.
+--
+-- ⚠️ One pass over the arrays rather than targeted updates, for the same reason as 0005: re-running
+-- must change nothing. A graph with no approval node is written back identical to itself.
+UPDATE flow_versions
+SET graph_json = json_set(
+  json_set(
+    graph_json,
+    '$.nodes',
+    (
+      SELECT json_group_array(
+        CASE
+          WHEN json_extract(node.value, '$.kind') = 'approval'
+          THEN json_set(
+            json_set(node.value, '$.kind', 'condition'),
+            '$.configuration',
+            json_object(
+              'mode', 'semantic',
+              'instruction', json_extract(node.value, '$.configuration.prompt')
+            )
+          )
+          ELSE node.value
+        END
+      )
+      FROM json_each(flow_versions.graph_json, '$.nodes') AS node
+    )
+  ),
+  '$.edges',
+  (
+    SELECT json_group_array(
+      CASE json_extract(edge.value, '$.sourceHandle')
+        WHEN 'approved' THEN json_set(edge.value, '$.sourceHandle', 'yes')
+        WHEN 'rejected' THEN json_set(edge.value, '$.sourceHandle', 'no')
+        ELSE edge.value
+      END
+    )
+    FROM json_each(flow_versions.graph_json, '$.edges') AS edge
+  )
+)
+WHERE EXISTS (
+  SELECT 1 FROM json_each(flow_versions.graph_json, '$.nodes') AS node
+  WHERE json_extract(node.value, '$.kind') = 'approval'
+);
+
+-- `waiting` was written for the approval node and never set by anything: the two places that tested
+-- for it only ever saw `running`. It leaves `FlowRunStatus`, so a row carrying it would become a
+-- status the contract cannot parse. There should be none — this makes that true rather than hoped.
+--
+-- The column's CHECK constraint still allows the value, deliberately: changing it means rebuilding
+-- the table in D1 for a value nothing writes.
+UPDATE flow_runs
+SET status = 'failed',
+    error = 'Flow run was waiting for an approval that no longer exists',
+    completed_at = COALESCE(completed_at, updated_at)
+WHERE status = 'waiting';