@anchrd/intel-api 0.3.1 → 0.3.2

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,39 @@
+-- #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. 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.
+PRAGMA defer_foreign_keys = TRUE;
+
+CREATE TABLE knowledge_nodes_next (
+  id TEXT PRIMARY KEY NOT NULL,
+  parent_id TEXT REFERENCES knowledge_nodes_next(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_next (
+  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;
+
+DROP TABLE knowledge_nodes;
+
+ALTER TABLE knowledge_nodes_next RENAME TO knowledge_nodes;
+
+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/package.json

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