@bongos/core 1.19.316 → 1.19.318

package/modules/lifecycle/db-deps-criteria.js

@@ -0,0 +1,441 @@
+// modules/lifecycle/db-deps-criteria.js — task/goal dependency edges, cycle detection + done-when criterion links.
+//
+// Carved out of modules/lifecycle/db.js by task 1003204 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original db.js lines 2133-2539 unchanged. db.js remains the facade that
+// re-exports every name, so every existing db call site is unchanged.
+//
+// THE BOUNDARY (ADR 0093 §1): this file reaches core ONLY through the published
+// doorway ../../src/module-api.js — never a core internal, never a sibling module.
+
+'use strict';
+
+const api = require('../../src/module-api');
+const { pool, withTx } = api;
+
+// -------------------------------------------------------------------------
+// Task dependencies (migration 020, task 309 / V3.R01b)
+// -------------------------------------------------------------------------
+// Forward edge: rows where task_id = X give X's dependencies.
+// Reverse edge: rows where depends_on_task_id = X give X's dependents.
+
+// Shared projection for both dep edges. Forward (dependencies): the tasks X
+// depends on. Reverse (dependents): the tasks that depend on X. Same SELECT;
+// the two differ only in which side of the dependencies edge is joined vs filtered.
+
+async function getTaskDepEdges(taskId, { reverse = false } = {}) {
+  // task->task edges only (the historical dependency arrays). Goal/criterion edges
+  // live in the same `dependencies` table but surface via the generic /dependencies
+  // endpoint, not these task-summary arrays — so consumers see an unchanged shape
+  // (task 1516). Forward: $1 is the from side; reverse: $1 is the to side.
+  const joinCol = reverse ? 'd.from_id' : 'd.to_id';
+  const whereCol = reverse ? 'd.to_id' : 'd.from_id';
+  const { rows } = await pool.query(
+    `SELECT t.id, t.title, t.status, t.version_id, t.kind, t.priority
+       FROM dependencies d
+       JOIN tasks t ON t.id = ${joinCol}
+      WHERE d.from_kind = 'task' AND d.to_kind = 'task'
+        AND ${whereCol} = $1
+      ORDER BY t.title`,
+    [taskId]
+  );
+  return rows;
+}
+
+
+async function getTaskDependencies(taskId) {
+  return getTaskDepEdges(taskId, { reverse: false });
+}
+
+
+async function getTaskDependents(taskId) {
+  return getTaskDepEdges(taskId, { reverse: true });
+}
+
+// attachTaskDepSummaries (hall redesign task 1002439) — enrich an already-fetched
+// task list with the two dependency numbers the Goals rollup + Tasks dependency
+// view need, WITHOUT an N+1 (two aggregate queries over the whole id set, not one
+// per task). For each task:
+//   blocked_by[] — the tasks THIS task waits on ({id,title,status,goal_id,satisfied}),
+//                  where satisfied === (target.status === 'shipped'), matching the
+//                  claim gate's DEPS_NOT_SHIPPED rule (ADR 0015). A `backlog` task
+//                  with any unsatisfied entry is what the UI paints "blocked".
+//   blocks         — how many tasks are waiting on THIS one (reverse edge count) —
+//                    the "clearing this unblocks N" signal.
+// task->task edges only (from_kind/to_kind='task'), same filter as getTaskDepEdges.
+// Mutates + returns the passed array so callers can `await db.attachTaskDepSummaries(tasks)`.
+async function attachTaskDepSummaries(tasks) {
+  if (!Array.isArray(tasks) || tasks.length === 0) return tasks;
+  const ids = tasks.map((t) => Number(t.id)).filter(Number.isFinite);
+  if (ids.length === 0) return tasks;
+  const [fwd, rev] = await Promise.all([
+    pool.query(
+      `SELECT d.from_id AS task_id,
+              json_agg(json_build_object(
+                'id', t2.id, 'title', t2.title, 'status', t2.status,
+                'goal_id', t2.goal_id, 'satisfied', (t2.status = 'shipped')
+              ) ORDER BY t2.id) AS blocked_by
+         FROM dependencies d
+         JOIN tasks t2 ON t2.id = d.to_id
+        WHERE d.from_kind = 'task' AND d.to_kind = 'task'
+          AND d.from_id = ANY($1::bigint[])
+        GROUP BY d.from_id`,
+      [ids]
+    ),
+    pool.query(
+      `SELECT d.to_id AS task_id, count(*)::int AS blocks
+         FROM dependencies d
+        WHERE d.from_kind = 'task' AND d.to_kind = 'task'
+          AND d.to_id = ANY($1::bigint[])
+        GROUP BY d.to_id`,
+      [ids]
+    ),
+  ]);
+  const blockedBy = new Map(fwd.rows.map((r) => [String(r.task_id), r.blocked_by]));
+  const blocks = new Map(rev.rows.map((r) => [String(r.task_id), r.blocks]));
+  for (const t of tasks) {
+    t.blocked_by = blockedBy.get(String(t.id)) || [];
+    t.blocks = blocks.get(String(t.id)) || 0;
+  }
+  return tasks;
+}
+
+// Generic cycle check over the polymorphic graph. Adding edge (from -> to) creates
+// a cycle iff `from` is already reachable FROM `to` along existing edges, so we seed
+// the walk at `to` and look for `from`. Nodes are (kind, id) pairs tokenized as
+// "kind:id"; returns the offending path of tokens, or null. Visited-set + depth cap
+// keep it terminating (task 1516, generalizes the task-only CTE from migration 020).
+
+async function findCycle(fromKind, fromId, toKind, toId, executor = pool) {
+  if (fromKind === toKind && Number(fromId) === Number(toId)) {
+    return [`${fromKind}:${fromId}`, `${toKind}:${toId}`];
+  }
+  const { rows } = await executor.query(
+    `WITH RECURSIVE walk(kind, id, depth, path) AS (
+       SELECT $1::text, $2::bigint, 1, ARRAY[$1 || ':' || $2::text]
+       UNION ALL
+       SELECT d.to_kind, d.to_id, w.depth + 1, w.path || (d.to_kind || ':' || d.to_id::text)
+         FROM dependencies d
+         JOIN walk w ON d.from_kind = w.kind AND d.from_id = w.id
+        WHERE NOT ((d.to_kind || ':' || d.to_id::text) = ANY(w.path))
+          AND w.depth < 100
+     )
+     SELECT path FROM walk WHERE kind = $3 AND id = $4::bigint LIMIT 1`,
+    [toKind, toId, fromKind, fromId]
+  );
+  return rows[0]?.path ?? null;
+}
+
+// Task-only wrapper preserving the historical bigint[] path shape for the task
+// dependency API. A pure task->task cycle maps cleanly to task ids; a cycle that
+// traverses a goal/criterion node (possible once cross-kind edges exist) keeps those
+// nodes as "kind:id" tokens rather than mislabeling them as task ids.
+
+async function findDependencyCycle(taskId, depTaskId, executor = pool) {
+  if (Number(taskId) === Number(depTaskId)) return [Number(taskId), Number(depTaskId)];
+  const path = await findCycle('task', taskId, 'task', depTaskId, executor);
+  if (!path) return null;
+  return path.map((tok) => {
+    const [kind, id] = String(tok).split(':');
+    return kind === 'task' ? Number(id) : tok;
+  });
+}
+
+
+async function addTaskDependency(taskId, depTaskId) {
+  if (taskId === depTaskId) {
+    throw { code: 'SELF_DEP' };
+  }
+  // Confirm both tasks exist
+  const { rows: existing } = await pool.query(
+    `SELECT id FROM tasks WHERE id = ANY($1::bigint[])`,
+    [[taskId, depTaskId]]
+  );
+  if (existing.length !== 2) {
+    throw { code: 'TASK_NOT_FOUND' };
+  }
+  const cyclePath = await findDependencyCycle(taskId, depTaskId);
+  if (cyclePath) {
+    throw { code: 'CYCLE', path: cyclePath };
+  }
+  await pool.query(
+    `INSERT INTO dependencies (from_kind, from_id, to_kind, to_id)
+     VALUES ('task', $1, 'task', $2)
+     ON CONFLICT DO NOTHING`,
+    [taskId, depTaskId]
+  );
+  return { task_id: taskId, depends_on_task_id: depTaskId };
+}
+
+
+async function removeTaskDependency(taskId, depTaskId) {
+  const { rowCount } = await pool.query(
+    `DELETE FROM dependencies
+      WHERE from_kind = 'task' AND from_id = $1
+        AND to_kind = 'task' AND to_id = $2`,
+    [taskId, depTaskId]
+  );
+  return rowCount > 0;
+}
+
+// Replace the full dependency set for a task. Used by bulk seeders.
+// Validates no cycles among the new set in one transaction. Order of the
+// list doesn't matter.
+
+async function setTaskDependencies(taskId, depTaskIds) {
+  const unique = [...new Set(depTaskIds.map(Number))];
+  if (unique.includes(Number(taskId))) {
+    throw { code: 'SELF_DEP' };
+  }
+  return withTx(async (client) => {
+    // Replace only this task's task->task edges; leave any task->goal/criterion
+    // edges (created via the generic /dependencies endpoint) untouched.
+    await client.query(
+      `DELETE FROM dependencies WHERE from_kind = 'task' AND from_id = $1 AND to_kind = 'task'`,
+      [taskId]
+    );
+    for (const dep of unique) {
+      // Re-check cycle for each insert (using the same txn connection so the
+      // previous inserts in this txn are visible). Reuses findDependencyCycle
+      // with the txn client as executor — task 1087, C3.
+      const cyclePath = await findDependencyCycle(taskId, dep, client);
+      if (cyclePath) {
+        throw { code: 'CYCLE', path: cyclePath };
+      }
+      await client.query(
+        `INSERT INTO dependencies (from_kind, from_id, to_kind, to_id)
+         VALUES ('task', $1, 'task', $2)`,
+        [taskId, dep]
+      );
+    }
+    return unique;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Generic polymorphic dependencies (migration 163 / ADR 0086 §5 / task 1516).
+// The task->task helpers above are the historical task API over this same table;
+// these add/remove/read edges of ANY kind ({task, goal, criterion}). A dependency
+// is a REFERENCE, not a grant — it never widens module scope, so cross-goal /
+// cross-version edges are allowed.
+// ---------------------------------------------------------------------------
+
+const DEP_KINDS = ['task', 'goal', 'criterion'];
+
+const DEP_KIND_TABLE = { task: 'tasks', goal: 'goals', criterion: 'done_when_criteria' };
+
+
+async function dependencyNodeExists(kind, id, executor = pool) {
+  const table = DEP_KIND_TABLE[kind];
+  if (!table) return false;
+  const { rows } = await executor.query(`SELECT 1 FROM ${table} WHERE id = $1`, [id]);
+  return rows.length > 0;
+}
+
+// Add a polymorphic edge "from is blocked until to is done". Throws BAD_KIND,
+// SELF_DEP, NODE_NOT_FOUND, or CYCLE (with the offending kind:id path).
+
+async function addDependency(fromKind, fromId, toKind, toId) {
+  if (!DEP_KINDS.includes(fromKind) || !DEP_KINDS.includes(toKind)) throw { code: 'BAD_KIND' };
+  if (fromKind === toKind && Number(fromId) === Number(toId)) throw { code: 'SELF_DEP' };
+  if (!(await dependencyNodeExists(fromKind, fromId)) || !(await dependencyNodeExists(toKind, toId))) {
+    throw { code: 'NODE_NOT_FOUND' };
+  }
+  const cyclePath = await findCycle(fromKind, fromId, toKind, toId);
+  if (cyclePath) throw { code: 'CYCLE', path: cyclePath };
+  await pool.query(
+    `INSERT INTO dependencies (from_kind, from_id, to_kind, to_id)
+     VALUES ($1, $2, $3, $4) ON CONFLICT DO NOTHING`,
+    [fromKind, fromId, toKind, toId]
+  );
+  return { from_kind: fromKind, from_id: Number(fromId), to_kind: toKind, to_id: Number(toId) };
+}
+
+
+async function removeDependency(fromKind, fromId, toKind, toId) {
+  const { rowCount } = await pool.query(
+    `DELETE FROM dependencies
+      WHERE from_kind = $1 AND from_id = $2 AND to_kind = $3 AND to_id = $4`,
+    [fromKind, fromId, toKind, toId]
+  );
+  return rowCount > 0;
+}
+
+// ---------------------------------------------------------------------------
+// Task ↔ criterion links (task_criteria, migration 055 / ADR 0025; populated on
+// task-create + manage endpoints by task 438). Mirrors the task_dependencies
+// CRUD above. A criterion "ref" is either a numeric done_when_criteria.id, a
+// positional "Cn" token (C1 = the version's first criterion by
+// (sort_order, criterion_id) — the SAME ordering the #435 backfill +
+// done-when.criterionProgress use), or a criterion_id slug. resolveCriterionIds
+// maps refs to numeric ids SCOPED to a version, so "C8" is unambiguous and a
+// numeric id from another version doesn't resolve.
+// ---------------------------------------------------------------------------
+
+// PURE: classify a single criterion ref. Returns { kind:'cnum', n } |
+// { kind:'id', id } | { kind:'slug', slug }. Exported for unit tests (no DB).
+// A leading C/c + digits is positional; bare digits are a numeric id; anything
+// else is treated as a criterion_id slug.
+
+function parseCriterionRef(raw) {
+  const ref = String(raw == null ? '' : raw).trim();
+  const cMatch = /^C(\d+)$/i.exec(ref);
+  if (cMatch) return { kind: 'cnum', n: Number(cMatch[1]) };
+  if (/^\d+$/.test(ref)) return { kind: 'id', id: Number(ref) };
+  return { kind: 'slug', slug: ref };
+}
+
+// Resolve an array of refs to done_when_criteria.id values within a version.
+// Returns { ids: [unique numeric ids, first-appearance order], unresolved: [refs] }.
+
+async function resolveCriterionIds(versionId, refs) {
+  const ids = [];
+  const unresolved = [];
+  if (!Array.isArray(refs) || refs.length === 0) return { ids, unresolved };
+  const { rows } = await pool.query(
+    `SELECT id, criterion_id,
+            ROW_NUMBER() OVER (ORDER BY sort_order, criterion_id) AS cnum
+       FROM done_when_criteria
+      WHERE version_id = $1`,
+    [versionId]
+  );
+  const byId = new Set(rows.map((r) => Number(r.id)));
+  const byCnum = new Map(rows.map((r) => [Number(r.cnum), Number(r.id)]));
+  const bySlug = new Map(rows.map((r) => [String(r.criterion_id), Number(r.id)]));
+  const seen = new Set();
+  for (const raw of refs) {
+    const p = parseCriterionRef(raw);
+    let id = null;
+    if (p.kind === 'cnum') id = byCnum.get(p.n) ?? null;
+    else if (p.kind === 'id') id = byId.has(p.id) ? p.id : null;
+    else id = bySlug.get(p.slug) ?? null;
+    if (id == null) { unresolved.push(String(raw).trim()); continue; }
+    if (!seen.has(id)) { seen.add(id); ids.push(id); }
+  }
+  return { ids, unresolved };
+}
+
+// Read the criteria linked to a task, with the live "Cn" position + link source.
+
+async function getTaskCriteria(taskId) {
+  const { rows } = await pool.query(
+    `WITH ranked AS (
+       SELECT id, version_id, criterion_id, criterion_md,
+              ROW_NUMBER() OVER (PARTITION BY version_id ORDER BY sort_order, criterion_id) AS cnum
+         FROM done_when_criteria
+     )
+     SELECT r.id, r.criterion_id, r.criterion_md, r.cnum, tc.source, tc.created_at
+       FROM task_criteria tc
+       JOIN ranked r ON r.id = tc.criterion_id
+      WHERE tc.task_id = $1
+      ORDER BY r.cnum`,
+    [taskId]
+  );
+  return rows;
+}
+
+// Link one task to one criterion. Validates both exist AND share a version (a
+// task can only gate its OWN version's criteria). Idempotent (ON CONFLICT DO
+// NOTHING). Throws { code } the route maps: TASK_NOT_FOUND | CRITERION_NOT_FOUND
+// | CRITERION_VERSION_MISMATCH.
+
+async function addTaskCriterion(taskId, criterionId, source = 'manual') {
+  const { rows: tRows } = await pool.query(`SELECT version_id FROM tasks WHERE id = $1`, [taskId]);
+  if (tRows.length === 0) throw { code: 'TASK_NOT_FOUND' };
+  const { rows: cRows } = await pool.query(`SELECT version_id FROM done_when_criteria WHERE id = $1`, [criterionId]);
+  if (cRows.length === 0) throw { code: 'CRITERION_NOT_FOUND' };
+  if (cRows[0].version_id !== tRows[0].version_id) {
+    throw { code: 'CRITERION_VERSION_MISMATCH', taskVersion: tRows[0].version_id, criterionVersion: cRows[0].version_id };
+  }
+  const safeSource = ['manual', 'planning', 'backfill'].includes(source) ? source : 'manual';
+  await pool.query(
+    `INSERT INTO task_criteria (task_id, criterion_id, source)
+     VALUES ($1, $2, $3)
+     ON CONFLICT DO NOTHING`,
+    [taskId, criterionId, safeSource]
+  );
+  return { task_id: taskId, criterion_id: criterionId, source: safeSource };
+}
+
+
+async function removeTaskCriterion(taskId, criterionId) {
+  const { rowCount } = await pool.query(
+    `DELETE FROM task_criteria WHERE task_id = $1 AND criterion_id = $2`,
+    [taskId, criterionId]
+  );
+  return rowCount > 0;
+}
+
+// Link many already-resolved criterion ids at create-time (default source
+// 'planning'). Assumes resolveCriterionIds already version-checked them, so this
+// is one idempotent batch insert. Returns the count inserted.
+
+async function linkTaskCriteria(taskId, criterionIds, source = 'planning') {
+  const ids = [...new Set((criterionIds || []).map(Number).filter(Number.isFinite))];
+  if (ids.length === 0) return 0;
+  const safeSource = ['manual', 'planning', 'backfill'].includes(source) ? source : 'planning';
+  const { rowCount } = await pool.query(
+    `INSERT INTO task_criteria (task_id, criterion_id, source)
+     SELECT $1, c, $3 FROM unnest($2::bigint[]) AS c
+     ON CONFLICT DO NOTHING`,
+    [taskId, ids, safeSource]
+  );
+  return rowCount;
+}
+
+// The claim gate's resolution point (task 1516 / ADR 0086 §5). Returns every
+// dependency of taskId that is NOT yet "done", resolving the task's OWN edges plus
+// edges INHERITED from its goal (tasks.goal_id) and the criteria it fulfils
+// (task_criteria). "Done": task shipped | criterion satisfied | goal achieved. Each
+// unmet row is { kind, id, title, state }. An orphaned `to` (no FK; row deleted)
+// yields no JOIN match and is silently absent — the promotion predicate treats such
+// an edge as un-done, so it can never accidentally unblock a task. A task with only
+// task->task edges resolves identically to the pre-1516 task-only gate.
+
+async function unsatisfiedDeps(taskId, client = pool) {
+  const { rows } = await client.query(
+    `WITH gating AS (
+       SELECT d.to_kind, d.to_id
+         FROM dependencies d
+         JOIN tasks t ON t.id = $1
+        WHERE (d.from_kind = 'task'      AND d.from_id = t.id)
+           OR (d.from_kind = 'goal'      AND d.from_id = t.goal_id)
+           OR (d.from_kind = 'criterion' AND d.from_id IN (
+                 SELECT tc.criterion_id FROM task_criteria tc WHERE tc.task_id = t.id))
+     )
+     SELECT 'task' AS kind, x.id, x.title, x.status::text AS state
+       FROM gating g JOIN tasks x ON g.to_kind = 'task' AND x.id = g.to_id
+      WHERE x.status <> 'shipped'
+     UNION ALL
+     SELECT 'criterion' AS kind, x.id, x.criterion_md AS title,
+            (CASE WHEN x.satisfied THEN 'satisfied' ELSE 'unsatisfied' END) AS state
+       FROM gating g JOIN done_when_criteria x ON g.to_kind = 'criterion' AND x.id = g.to_id
+      WHERE x.satisfied = false
+     UNION ALL
+     SELECT 'goal' AS kind, x.id, x.title, x.status::text AS state
+       FROM gating g JOIN goals x ON g.to_kind = 'goal' AND x.id = g.to_id
+      WHERE x.status <> 'achieved'`,
+    [taskId]
+  );
+  return rows;
+}
+
+module.exports = {
+  addDependency,
+  addTaskCriterion,
+  addTaskDependency,
+  attachTaskDepSummaries,
+  findCycle,
+  findDependencyCycle,
+  getTaskCriteria,
+  getTaskDependencies,
+  getTaskDependents,
+  linkTaskCriteria,
+  parseCriterionRef,
+  removeDependency,
+  removeTaskCriterion,
+  removeTaskDependency,
+  resolveCriterionIds,
+  setTaskDependencies,
+  unsatisfiedDeps,
+};